Notes
🔍

Tool Error Handling

Tools fail. An API returns a 500, a token expires, a query times out, or the model fills in an argument the endpoint will not accept. Tool error handling is what the runtime does next, and the choice matters more than it looks: the error is not a crash to be logged somewhere, it is the next thing the model reads.

Handling a failure well
The pattern that works keeps the loop alive and gives the model something to act on:

  • Return, do not raise — the failure goes back as an observation through the same channel a successful result would use;
  • Make the message actionable — a validation message naming the offending field repairs the next call; a bare status code does not;
  • Separate transient from semantic — a timeout or rate limit is retried with backoff by the runtime, invisibly; a wrong argument needs the model to try something different;
  • Bound the attempts — a retry cap, so a permanently broken tool cannot consume the run;
  • Have a fallback — another tool, a degraded answer, or an escalation to a person.

Why it matters
A model handed a clear error usually repairs its own call on the second attempt, which is the cheapest reliability gain available in agent engineering. The failure modes sit either side of that. Swallow the error and return an empty result, and the agent builds the rest of its plan on a step it believes succeeded. Surface it with no limit, and you get the classic stuck run: the same failing call, re-argued and re-sent until the budget is gone.

Tool error handling is how an agent runtime responds when a tool call fails — returning the failure to the model as an observation rather than raising it, with a message specific enough to repair the next attempt, while retrying transient faults with backoff and capping total attempts. Done well, the model corrects its own call within a step or two; done badly, errors are either swallowed into a confidently wrong plan or retried until the budget is gone.

A good assistant who finds a locked door tells you which door, and that it was locked. A poor one either says it did not work, or stands there rattling the handle all afternoon.

Tool error handling is the design of that moment for AI agents. Things an agent tries will fail — a website is down, a form rejects a date, a password has expired. What matters is what the agent is told. Given a clear, specific message, it usually fixes the problem itself on the next try. Given a vague one, or none at all, it either carries on as though everything worked or repeats the same failed attempt until someone stops it.