02.04 · Concept
When a tool fails
Return an error the model can act on instead of one that ends the run.
Tool failures should be returned as structured, actionable responses that let the model recover, retry, correct arguments, ask the user, or stop cleanly. Raw exceptions and vague status codes remove useful context, while concise failure shapes make invalid input, permissions, rate limits, timeouts and missing data part of normal agent control flow.
What this lesson answers
- how should agents handle tool call failures
- what error should a failed tool return
- when should an agent retry a tool call
Notes
A tool call is just a request from the model to run some external code: query a database, call an API, search files, or invoke a service. When that code fails, the worst response is often to crash the whole run or return a vague exception like “500” or “ValueError.” The better pattern is to return a structured, meaningful error message that the model can read and use for its next decision.
Think of the model as a junior developer driving your tool interface. If the tool says “failed,” the model has no useful move.
Common questions
- Should a failed tool call crash the whole agent run?
- Usually no. Many tool failures are expected control-flow events, such as invalid arguments, missing records, rate limits or temporary service problems. Return a structured error the model can interpret, then let it decide whether to retry, ask for more information, change arguments, use another tool or explain that it cannot proceed.
- What makes a tool error useful to a model?
- A useful tool error says what went wrong, whether recovery is possible, and what kind of action makes sense next. For example, it can identify a missing required field, an invalid date format, a permission problem, a timeout, or an unavailable record. It should avoid raw stack traces and vague failure labels.
- How do I decide whether a tool error is retryable?
- Retry is appropriate for transient failures such as timeouts, temporary network problems or rate limits where waiting may help. It is not appropriate for errors that require changed input, missing user information, denied permissions or an absent resource. Classifying failures this way helps the model choose a sensible next step.