Agents rarely fail because an API is hard; they fail at choosing the right tool and constructing valid arguments. Both are context problems, not model problems. The highest-leverage fix is almost always rewriting tool descriptions and schemas rather than upgrading the model.
When an agent misbehaves against an API, the instinct is to blame reasoning. Look at the traces and a different picture appears: the agent picked a plausible-but-wrong tool, or picked correctly and passed an argument that could never have worked.
Both failures are decided by what the agent was told about the tool, which is something you control completely.
| Failure mode | What it looks like | Primary fix |
|---|---|---|
| Wrong tool selected | A reasonable-looking call to the wrong endpoint | Sharper descriptions, fewer overlapping tools |
| Invalid arguments | Malformed IDs, wrong date formats, invented enum values | Strict schemas and enums, worked examples |
| Hallucinated identifiers | Plausible IDs that do not exist | Require a lookup tool before any action tool |
| Ignored errors | Agent proceeds as if a failed call succeeded | Error messages stating what to do next |
| Retry loops | Same failing call repeated until budget exhausts | Loop detection and a hard attempt cap |
Ranked by how often they appear in real traces, the top two account for most incidents, and neither requires touching the model to resolve.
Why does tool selection go wrong?
Because the agent chooses from descriptions, and descriptions are usually written as documentation rather than as decision criteria.
Figure 1 — The same tool, two descriptions
Written as documentation
“Searches customer records.”
Accurate and useless at decision time. It does not say what identifiers it accepts, how it differs from the three other search tools, or when it is the wrong choice.
Ambiguous
Written as decision criteria
“Find a customer by email address or account ID. Returns one record or none. Use when you have an exact identifier. Do not use for name searches — use customer_search_by_name instead.”
States the input it needs, what it returns, when to choose it, and what to choose instead.
Decidable
The negative clause does disproportionate work. Telling the agent when not to use a tool, and naming the alternative, resolves most confusion between overlapping tools at zero runtime cost.
How do you stop invalid arguments?
Constrain the space rather than describing it.
- Use enums wherever the value set is closed. A free-text status field invites invention; an enum makes invention impossible.
- Type dates and identifiers precisely, and state the expected format in the field description, not only in prose.
- Make optional arguments genuinely optional, since agents fill required fields with plausible guesses rather than leaving them empty.
- Include one worked example per tool, which does more than several paragraphs of description.
- Validate server-side regardless, because schema constraints reduce bad arguments without eliminating them.
Watch for this
Agents hallucinate identifiers with striking confidence, producing IDs that match your format exactly and refer to nothing. The structural fix is sequencing: never expose an action tool that takes an ID without also exposing the lookup tool that produces one, and say in the action tool’s description that the ID must come from that lookup.
What makes an error message useful to an agent?
An instruction, not a diagnosis.
A human reading “400 Bad Request: invalid parameter” can infer the next step. An agent frequently cannot, and will either retry identically or proceed as though nothing failed.
| Instead of | Return |
|---|---|
| 400 Bad Request | “Field ‘start_date’ must be YYYY-MM-DD. You sent ’12 March’. Retry with 2026-03-12.” |
| 404 Not Found | “No customer with ID 44718. Use customer_search_by_name to find the correct ID first.” |
| 403 Forbidden | “This action requires approval. Ask the user to confirm before retrying.” |
| 429 Too Many Requests | “Rate limited. Wait 30 seconds before retrying. Do not retry immediately.” |
| 500 Internal Error | “Server error, not caused by your request. Retry once, then report failure to the user.” |
Every message names the problem and the next action. That single change converts a large share of dead-end failures into successful recoveries, and it is work done once per tool.
How do you stop retry loops?
Detect repetition and cap attempts, because agents will not self-limit.
- Hash the tool name and arguments on every call, and count repeats within a run.
- Break at the second identical failure. A call that failed twice with identical arguments will fail again.
- Cap total tool calls per run as a hard budget, independent of loop detection.
- Escalate rather than fail silently, returning a message the agent can relay to the user.
Loop detection is cheap and catches the failure mode with the worst cost profile, since a loop burns budget until something stops it.
Where do teams go wrong?
Exposing the API surface as-is
An API designed for developers with documentation open is not an agent interface. Agents need fewer, coarser, more opinionated tools. Wrapping three related endpoints into one task-shaped tool usually outperforms exposing all three.
Debugging the model instead of the trace
Almost every tool failure is visible in the trace: which tool was chosen, with what arguments, and what came back. Teams that reach for a stronger model before reading traces frequently discover afterwards that a description was ambiguous.
Treating tool count as capability
More tools means more context consumed and more chances to choose wrongly. A focused set of well-described tools beats a comprehensive catalogue reliably.
What do experienced teams do differently?
They design tools around tasks rather than around endpoints.
An agent asked to “process a refund” performs better with one refund tool that internally does the lookup, validation and write than with five primitives it must sequence correctly. Every sequencing decision removed is a failure mode removed.
They also keep a regression set of real tool-use traces, including past failures. When a description changes or a model is swapped, replaying those traces catches selection regressions that no unit test would.
A short glossary
- Tool selection
- The agent’s choice of which available tool to invoke, decided from descriptions at runtime.
- Argument construction
- Producing valid input values for the chosen tool, constrained by its schema.
- Actionable error
- An error message stating both what went wrong and what the agent should do next.
- Loop detection
- Identifying repeated identical calls within a run and breaking before budget is exhausted.
- Task-shaped tool
- A tool designed around a complete user-level task rather than mirroring one API endpoint.
Key takeaways
- Most agent tool failures are selection and argument errors, both determined by what you told the agent.
- Tool descriptions are decision criteria read at runtime, not documentation for humans.
- Stating when not to use a tool, and naming the alternative, resolves most overlap confusion.
- Constrain arguments with enums and precise types rather than describing the rules in prose.
- Never expose an action tool taking an ID without the lookup tool that produces one.
- Error messages should name the problem and the next action, which converts dead ends into recoveries.
- Detect repeated identical calls and cap total attempts, because agents do not self-limit.
Frequently asked questions
Why do agents call the wrong tool?
Because they choose from descriptions, and most descriptions are written as documentation rather than decision criteria. A description that omits what inputs the tool needs, how it differs from similar tools, and when not to use it leaves the choice underdetermined.
How do I stop agents inventing IDs?
Sequence the tools. Never expose an action tool that accepts an identifier without also exposing the lookup tool that produces valid ones, and state in the action tool’s description that the ID must come from that lookup. Validate server-side as a backstop.
What makes a good tool description?
It states what the tool does, what inputs it requires, what it returns, when to choose it, and explicitly when not to, naming the alternative. The negative clause resolves most confusion between overlapping tools and costs nothing at runtime.
How should tool errors be worded?
As instructions rather than diagnoses. Instead of a status code, return what was wrong with the specific input and what the agent should do next, including whether to retry. This converts a large share of dead-end failures into successful recoveries.
How do I prevent infinite retry loops?
Hash the tool name and arguments on each call and count repeats within a run, breaking at the second identical failure. Add a hard cap on total tool calls per run as an independent safeguard, since agents will not limit themselves.
Should I expose my existing API directly to agents?
Usually not. APIs designed for developers with documentation open assume a reader who can sequence calls correctly. Agents do better with fewer, coarser, task-shaped tools that internally handle the sequencing, because every removed decision is a removed failure mode.
Does using a better model fix tool reliability?
Less than expected. Most failures trace to ambiguous descriptions and loose schemas, which a stronger model interprets slightly better but does not resolve. Read the traces first: the fix is usually a description rewrite, and it is far cheaper.
How many tools is too many?
Enough that selection accuracy starts falling, which happens sooner than teams expect. Each tool consumes context and adds a decision to get right. A focused set of well-described task-shaped tools consistently outperforms a comprehensive catalogue of endpoint wrappers.
References
- Anthropic. Model Context Protocol documentation, covering tool definitions and descriptions.
- Schick, T., et al. Toolformer: Language Models Can Teach Themselves to Use Tools. arXiv:2302.04761.
- Willard, B. T., and Louf, R. Efficient Guided Generation for Large Language Models. arXiv:2307.09702. Basis for constraining argument construction at decode time.
