What is Tool Error Recovery?
Also called error handling loop.
Tool error recovery is how an agent responds when a tool call fails, times out, returns unexpected data, or is rejected. It covers whether the failure is surfaced to the agent as an observation, how the agent is expected to react, and what limits prevent it from retrying the same failing call indefinitely.
The first design decision is whether the agent sees the error at all. Returning a clear error message as an observation lets the agent adapt, correcting a malformed argument or choosing a different tool. Swallowing the error and returning an empty result is worse than useless, because the agent interprets emptiness as a real finding and proceeds on a false premise.
Error messages are prompts in practice. A message stating which field was invalid and what values are accepted lets the model fix the call on the next attempt, while a generic failure produces blind retries of the same broken argument. Errors written for agents should name the problem, the offending field, and the valid alternative.
Failure classes call for different responses. Transient failures such as timeouts and rate limits justify a bounded retry with backoff. Argument errors justify one corrected retry. Permission denials and missing resources justify no retry at all, since the same call will always fail, and the agent should either take a different route or escalate.
Retries need hard limits regardless of class. Without them an agent can spend an entire step budget looping on one unavailable service, which appears in logs as a busy run that accomplished nothing. Counting consecutive failures per tool and forcing a different action or a stop after a threshold is the standard control.
Key points
- Surface errors as observations rather than empty results
- Error text should name the field and valid values
- Transient, argument, and permanent failures need different responses
- Cap consecutive retries per tool to prevent loops
- Silent failures cause the agent to reason from false premises
In practice
An agent calls a calendar tool with a date written as next Tuesday and receives an error stating that start_time must be an ISO 8601 timestamp. It converts the value and the second call succeeds. Later the same tool returns a permission denied error, which the recovery policy marks as non retryable, so the agent stops attempting it and escalates to a person instead.