Surfacing Tool Errors to an Agent Without Looping Forever

Make the error an instruction. Every message returned to a model should carry four parts, in this order:

1. Code and what failed, in a stable, machine-readable token such as trip_not_possible or invalid_argument.
2. Why it failed, in the terms the operation uses, not the terms your infrastructure uses.
3. The rejected arguments, echoed back exactly as the model sent them, so it can see its own mistake.
4. One next action: change a named parameter, call a named alternative tool, or stop and report.

The first three make the fourth credible. Compare, using a search tool that requires a bounded price range:

Bad:
Error: failed

Bad:
Traceback (most recent call last):
  File "/srv/tools/search.py", line 88, in search_flights
    assert max_price > 0
AssertionError

Good:
search_flights failed (code: invalid_argument).
Reason: max_price must be greater than 0.
Rejected arguments: {"origin": "SFO", "destination": "JFK", "max_price": -1}.
Next action: call search_flights again with max_price as a positive number,
or call search_flights_any_price if no budget constraint applies.

The good version costs perhaps sixty tokens. A single avoided retry on a mid-sized context usually pays for it several times over.

The four parts line up with longer-standing API conventions. A complete error object carries a status category, a short summary, a detailed message, an application-specific code, and a pointer to more information (errors best practices). Follow the same structure on the client side too: validate before the call where you can, and never hand the model a raw server error string without shaping it (API error handling). The failure to avoid, and guidance is explicit about it, is a catch-all that describes the category but not the fix.

Tool definitions deserve equal care, because the model's first mistake usually starts there. The description tells the model not just what a tool does but when to use it, and with several tools available, vague descriptions produce wrong selections before you ever reach the error path (function calling guide). The message-writing pattern below assumes your schema already states required fields, types and allowed values, mirroring the completeness expected of a published API reference (reference documentation).

That timeout row is where naive retries cause real damage. When a call times out after it was dispatched, the effect may have already landed, and a blind retry duplicates the action. A verification-aware wrapper that checks postcondition state before retrying cuts duplicate actions while keeping task success rates comparable, without changing the model (verified tool calls). Your error text should therefore distinguish three outcomes explicitly: no effect, effect unknown, effect applied.

Better messages reduce the retry rate. They will not reduce it to zero, and that is why you need a cap that does not depend on the model's cooperation. The pattern is small.

Fingerprint each call as the tuple of tool name and a canonical serialization of its arguments: sorted keys, normalized whitespace, no floats where an integer will do. Count consecutive failures per fingerprint for the turn. On the terminal failure, return a message that states retrying the same call is not allowed, names the alternatives, and tells the model to report the failure if no alternative applies.

import hashlib, json

RETRY_LIMIT = 3  # consecutive identical failures allowed per turn

def fingerprint(name, args):
    canonical = json.dumps(args, sort_keys=True, separators=(",", ":"))
    return hashlib.sha256(f"{name}:{canonical}".encode()).hexdigest()

def wrap(name, fn, counts):
    def call(args):
        fp = fingerprint(name, args)
        counts[fp] = counts.get(fp, 0) + 1
        try:
            result = fn(args)
            counts.pop(fp, None)
            return result
        except ToolError as e:
            if counts[fp] >= RETRY_LIMIT:
                return terminal(name, fp, e)
            return e.rendered_message  # the four-part text
    return call

Two decisions inside that snippet matter more than the code.

What counts as identical. Hash the arguments, not the intent. A model that slightly rewords a string argument has not changed its approach, and an exact-string hash will let it retry indefinitely with cosmetic edits. Normalize aggressively: lowercase where case is not meaningful, strip trailing slashes from paths, round numeric tolerances. When a retry does change the arguments meaningfully, let it through and reset the counter, because that is the behavior you want to reward.

Where the terminal message goes. It must be a tool result the model sees, not an exception your framework swallows. Counting duplicate calls before execution and returning a blocking message to the model is the mechanism; the debounce hook demonstration shows the same idea inside one agent framework, and its author notes the pattern applies to any framework with lifecycle hooks.

The terminal message itself should be short and imperative:

search_flights failed 3 times with identical arguments (code: invalid_argument).
Retrying the same call is not allowed.
You must now either call search_flights with a different max_price,
call search_flights_any_price, or stop and report this failure to the user.

From the model's point of view this is another observation, and observations shape the next action (function calling guide). The difference is that it names the only legal moves.

Two or three is the practical range, and the choice should follow the failure class rather than a global constant.

The distinction comes from treating agent failures in layers: rate limits and provider 5xx errors are transient, while tool failures from bad inputs are not, and a single retry policy for both wastes money or hides real bugs (retries in agents). Retry only what the error text says is retryable, and put that verdict in the message rather than leaving the model to infer it.

If your traces do not distinguish these classes, cap by budget as well. Set a per-turn ceiling on tool calls and a per-task ceiling on spend, and treat a cap hit as a reportable incident rather than a silent stop. Observability at this layer is worth wiring early. Splitting the response channel (what the model sees) from the effect channel (what actually happened) is the root of most duplicate-action bugs, and you cannot fix the gap you cannot see (verified tool calls).

Every tool error has two audiences: the model that reads it now and the engineer who reads your tool catalog later. Your processes should serve both. Industry surveys cited in a documentation guide report that developers overwhelmingly rely on the documentation bundled with APIs and SDKs to learn how to use them, which is why error documentation belongs in the reference rather than a wiki (documentation usage and practices). The UR sequence steps for writing and maintaining API descriptions, applied to agent tools, point the same way: reference, guides, and worked examples (API documentation guide).

Concretely, keep a table with one row per error code: code, which tool raises it, the argument constraints it reflects, whether retrying can help, and the alternative tool to name. Generate the message templates from that table so the text the model sees and the text in your docs cannot drift. This is the docs-as-code idea applied to prompts: documentation lives beside the code it describes, is reviewed with it, and deploys with it (docs as code). When a specification file drives generation, code examples and references stay synchronized as the tool evolves (single source of truth).

Two hygiene rules carry over directly. Do not leak secrets or internal identifiers into error text that gets sent to a model provider; the message should carry only what the problem requires (API error handling). And keep the format uniform across tools, because uniformity is what lets the model generalize what it learned from one failure in part to another tool (errors best practices). That generalization is the difference between an agent that recovers and one that loops.

One practical note on cost: errors that run to hundreds of tokens get appended to context and re-sent on every subsequent turn, so brevity compounds as much as verbosity does. Aim for a message under roughly a hundred tokens unless the alternative genuinely needs explaining, and put the long explanation behind a link referenced in the message.

Roll the pattern out in stages, and measure at each stage.

Step 5 is the one teams postpone and regret. The extreme cases are documented, including an agent that ran hundreds of reasoning steps without producing an answer (reasoning-loop experiment). A hard cap is the only defense that survives a model having a bad day.

If you are running these agents across several model providers, the wrapper layer is where the work concentrates, and keeping one client for every model type simplifies the plumbing. Quanta Inference (https://quantaintelligence.ai/inference) routes text, image, video, audio and embedding models through one OpenAI-compatible API with prepaid US-dollar pricing, which keeps the cost side of your caps easy to reason about. If you would rather hand the design to someone who has shipped these loops before, an expert engagement (https://quantaintelligence.ai/skills) puts a specialist on the tool boundary and its failure paths.

Once the caps and messages are in place, the remaining work is evidence: traces that show identical calls blocked, recovery calls succeeding, and cap hits reported. That evidence is what turns an agent that sometimes spins into one you can leave running.