Tool & Error Anti-Patterns

Most agent failures aren't dramatic crashes. They're quiet misroutes: the model picks the wrong tool, or a tool fails with a vague message the model can't recover from. The agent then improvises, fabricates, or silently abandons the task.

This lesson dissects three anti-patterns that ship constantly in production:

• Minimal tool descriptions that leave the model guessing
• Too many tools per agent, which degrades selection reliability
• Generic error statuses that block intelligent recovery

Each one is a frequent wrong answer on the exam. Learn to spot and fix them.

A common misconception: the model routes by tool name. It does not. The tool description is the primary selection mechanism. Names are labels; descriptions are where the model decides whether a tool fits the situation.

A minimal description like "Looks up an order" tells the model almost nothing. When two tools have thin, overlapping descriptions, the model misroutes — it calls lookup_order when it needed get_customer, and the whole agentic loop drifts.

A good tool description carries five things:

• Purpose — what it does and when to use it
• Return values — the shape of what comes back
• Input formats with examples — concrete, not abstract
• Edge cases — empty results, ambiguity, multiple matches
• Applicability boundaries — when NOT to use it

That last point is what disambiguates overlapping tools. Below is the weak version most teams ship.

Now the strong version. Notice how the description states the input format with an example, the return shape, the empty-result case, and an explicit boundary that prevents collision with get_customer.

This is the single highest-leverage fix for misrouting: you change the description, not the model.

The second anti-pattern: handing one agent a giant toolbox. Selection reliability isn't constant — it degrades as the tool count grows.

• 4-5 tools per agent is the optimal range
• 18+ tools measurably degrades selection reliability

More tools mean more chances for overlapping descriptions, more surface area for ambiguity, and a longer list the model must reason over every turn. Breadth is not a feature here — it's a liability.

The fix is architectural: scope tools to the role instead of giving every agent every capability. In a hub-and-spoke multi-agent system, the coordinator decomposes work and delegates to subagents — each subagent gets only the handful of tools its job needs, following least privilege.

A focused 4-tool support agent outperforms a 20-tool generalist because each tool is unambiguous within its small, role-scoped set.

When a workflow genuinely needs many capabilities, the answer is not one bloated agent — it's decomposition. Split responsibilities across role-scoped subagents and let the coordinator route between them.

Remember the multi-agent rule: subagents do not inherit the coordinator's conversation history. So when you delegate, pass all needed context explicitly in the subagent prompt. A clean split keeps each agent's tool set small AND keeps its context focused.

The third anti-pattern lives in the error path. A tool that fails with "Operation failed" or a bare isError: true gives the model nothing to act on. It can't tell a transient network blip from a validation mistake from an empty result — so it either retries blindly, gives up, or fabricates an answer.

Generic error statuses block intelligent routing. Structured errors enable it.

A recoverable error carries structure. The MCP convention bundles the fields the model needs to decide what to do next:

• isError: true plus an errorCategory: transient / validation / business / permission
• isRetryable — should the model try again at all?
• message, attempted_query, and partial_results

With these, the model routes intelligently: retry a transient fault, fix a validation error, escalate a permission denial, or surface partial results instead of nothing.

One subtle distinction the exam loves: an access FAILURE (the tool couldn't run — timeout, permission) is not the same as a valid EMPTY result (the query ran fine and matched nothing).

Collapsing both into a generic error is a recovery-killer. A failure may be worth a retry; an empty result means "no matches" and should be reported as fact, not retried forever. Your lookup_order earlier got this right: no match returns an empty result, not an error.

Put it together into an error-propagation strategy:

• Recover transient faults locally in the subagent — retry the timeout, don't bubble it up
• Escalate non-recoverable failures with structured context: failure type, attempted query, partial results, and alternatives
• Never silently suppress errors, and never abort the whole workflow because one subagent failed

The coordinator can then route around a single failed branch and still aggregate a useful answer — which is exactly what generic errors make impossible.

Apply the lesson to a concrete failure.

You can now spot and fix the tool-and-error anti-patterns that show up as wrong answers on the exam:

• Minimal descriptions cause misrouting. Fix: descriptions are the selection mechanism — state purpose, return values, input formats with examples, edge cases, and applicability boundaries.
• Too many tools degrade selection. Fix: 4-5 tools per agent is optimal, 18+ degrades reliability — scope tools to the role and split across subagents under least privilege.
• Generic errors block recovery. Fix: structured errors with errorCategory (transient/validation/business/permission), isRetryable, attempted_query, and partial_results — distinguish access failure from a valid empty result, recover transient faults locally, escalate the rest with context, and never silently suppress or abort the whole workflow.