Tool Error Recovery

Tool error recovery is what an agent does when a tool call fails. It matters more than it sounds, because in an agent the failure is not returned to a program that knows how to handle it — it is written back into the model's context as text, and the model decides what happens next. Whatever that text says is the entire basis for the decision. There are only three sensible responses, and they answer different failures. Retry suits a transient fault: a timeout, a rate limit, a service that was briefly unavailable. Re-plan suits a call that was wrong rather than unlucky — a missing argument, a record that does not exist, a permission the agent does not have — where repeating it will fail identically forever. Stopping suits everything else, and it is the response teams most often fail to implement, which is how a run spends its entire budget cycling between two broken options. Distinguishing the cases is the engineering. A model handed a bare stack trace, or the string "error", will usually guess, and its guess is biased towards trying again because trying again is what a helpful assistant does. Error messages returned to an agent are prompt surface: they should say what failed, whether it is worth retrying, and what a valid call would have looked like. That is a different message from the one you would log for an engineer, and it is worth writing separately. Retries are dangerous exactly where they are most tempting. If the failed call had already taken effect before the error — the payment went through and the response was lost — a retry does it twice, and the model has no way of knowing. Any tool that changes something needs to be safe to call again with the same arguments, and where that cannot be arranged, it needs to be excluded from automatic retry regardless of what the model proposes. The last piece is the cap. Recovery attempts consume steps, tokens and time exactly like productive work, and an agent that never gives up is indistinguishable in cost from one that has crashed. Fix a limit per tool and per run, and make what happens at the limit a real path — a partial result, a handover, a clear failure — rather than the run simply ending.