Classifying Tool Errors So an Agent Can Act on Them

The taxonomy below gives the model exactly one recovery action per class. Anything that does not fit is a signal that the tool is lying about what happened.

Two boundary decisions matter more than the labels.

First, transient versus business rule. A transient failure is about the transport or a temporary overload: a 503, a timeout, a 429 rate limit. A business rule failure is about the state of the world: the slot is taken, the invoice is already paid, the customer is on hold. The distinction is the spine of a well-known argument that retry-with-backoff was imported from stateless HTTP clients into stateful planning loops where it is wrong, and that the right default for a semantic error is replan, not retry (tianpan.co). A framework that retries a 409 burns a 200ms, 400ms, 800ms backoff sequence, 1.4 seconds of guaranteed latency, proving what the first response already said.

Second, permission versus validation. Both are 4xx-like and neither is retryable, but they diverge on who fixes them. An expired access token and a revoked refresh token can look identical at the execution layer while requiring completely different responses, and treating them the same produces retry storms and cascading failures (Scalekit). Validation is a model fix. Permission is a human fix.

A useful secondary test: if the same call with byte-identical arguments could ever succeed without any external change, it is transient. If it could only succeed after the arguments change, it is validation. If it could only succeed after the credential changes, it is permission. If it could only succeed because the world changed, it is business rule.

Every tool returns the same shape on failure. No exceptions, no free text at the top level.

{
  "ok": false,
  "error": {
    "code": "RESERVATION_SLOT_TAKEN",
    "class": "business_rule",
    "retryable": false,
    "retry_after_ms": null,
    "field": null,
    "hint": "Slot 14:00 on 2026-05-04 is held by another reservation for room B2. Free slots that day: 11:30, 15:15, 16:00.",
    "message": "The requested slot is not available."
  }
}

Field rules:

• code is a stable, uppercase, machine-readable identifier that never changes meaning. Adding a code is a minor change; reusing one for a new meaning is a breaking change.
• class is one of the five strings. The model branches on this, not on the code.
• retryable is a boolean that must agree with class. Only transient returns true. If you find yourself wanting true on a business rule, the tool is not done.
• retry_after_ms is populated for transient failures only, derived from a Retry-After header where the upstream provides one, or from the orchestration layer's backoff schedule otherwise.
• field is populated for validation failures and names the exact argument, using the JSON path into the call the model made ("guest_count", "date", "items[2].sku").
• hint is one or two sentences of plain language aimed at the model's next decision, not a stack trace. For business rules it states the rule and the nearest legal alternatives.
• message is for humans reading logs. The model should be instructed to ignore it for decision purposes, so a chatty upstream message cannot smuggle instructions into the context.

On success, return ok true with the payload, and keep the same top-level key so the serialization stays stable.

{ "ok": true, "data": { "reservation_id": "rsv_8213", "slot": "2026-05-04T15:15" } }

The envelope size matters. A hint that runs to six sentences gets truncated in practice and costs tokens in every later turn. Write hints the way you would write a good API error: what failed, why, what to do. Anthropic's guidance on tool specifications in system prompts makes the same point from the other side, that explaining when to use a tool and what it returns reduces guessing (Redpanda docs).

Here is the rule that most teams get wrong, and it is the one this whole article exists to deliver: retries happen inside the tool, not in the model's loop. The tool retries its own transport failures with jittered backoff, and only returns an error to the agent when it has exhausted that local budget. This is the explicit recommendation in guidance on system prompts for agents (Redpanda docs), and it has a clean justification: the orchestration layer owns silent infrastructure retries while the model owns reasoning-based recovery (n8n blog).

A worked example. Suppose a payments tool gets a timeout on a call that may or may not have committed. Retry from the model is dangerous: a payment-create that timed out may have succeeded server-side, and the retry creates a duplicate charge, as noted in the replan argument. So the tool itself should, on timeout, read back the payment by idempotency key before deciding. If the read-back shows a committed payment, the tool returns success. If not, it returns transient with retry_after_ms. The model never sees an ambiguous state, which is the whole point.

This also protects the latency budget. If a tool call costs 200ms on the happy path, three model-driven retries with 200, 400 and 800ms backoff add at least 1.4 seconds before any useful work happens, and that cost lands on the user. A tool that retries internally can do so in parallel or with a tighter schedule and a hard deadline.

There is one exception worth naming: a transient error that the tool cannot resolve within its own deadline should surface as transient with a real retry_after_ms, and the model may retry once at the agent level, not five times. Cap agent-level retries at one per tool per plan step. Without that cap you get the loop behavior that production teams report as the most common class of bug, with stop criteria (max iterations, cost cap, repeated-state detection) listed among the indispensable patterns (Blck Alpaca).

The prompt only needs six lines, because the envelope carries the information.

Tool error handling. Every tool returns {"ok": false, "error": {...}}.
- transient: retry the same call once. If it fails again, tell the user
  the service is slow and quote retry_after_ms.
- validation: fix the argument named in "field" using "hint", then call
  once more. Never repeat the identical call.
- permission: stop calling this tool. Tell the user what credential or
  approval is missing and escalate to a human.
- business_rule: do not retry. Explain the rule in "hint" to the user and
  offer the alternatives it lists.
- fatal: abandon the current plan. Report what succeeded so far.
Never invent a successful result. If a required tool failed, say so.

Notice what this does not do. It does not ask the model to infer from HTTP status codes, which is unreliable because the same 401 can mean three structurally different things (Scalekit). It does not ask the model to read stack traces, which invites the error text to act as an injection vector, a risk flagged in prompt security guidance (LaunchDarkly). And it does not leave the model to invent a fill-in when data is missing, which is the failure mode behind a great deal of confident nonsense: guidance on multi-agent workflows specifically warns against making up information to fill gaps left by a failed tool (Redpanda docs).

A worked example of the mapping. A travel booking agent calls search_flights with a malformed date. The tool returns class validation, field "date", hint "ISO 8601 date required, for example 2026-05-04". The model rewrites the argument and calls again. The next response is class business_rule, code NO_SEATS_IN_FARE, hint "Fare class W is sold out on this route; the lowest available fare is M". The model does not retry, it tells the user the fare is gone and quotes the alternative. Total wasted calls: one rewrite, zero retries.

Contrast that with the same scenario under a single error bucket: two retries on the malformed date, then a retry on the sold-out fare, then a likely hallucinated confirmation. Same model, same prompt length, different envelope.

Run this list against each tool before blaming the model.

Item 10 is the one teams skip. Fault injection is now a studied technique for exactly this purpose: one benchmark framework intercepts agent-to-model traffic and injects format, logic and tool call faults to measure how well agents recover, and reports a model-size-dependent threshold in logic error recovery across the models it tested (Agent Error Simulator). A second line of work argues that timing is what decides whether a fault is even refutable: of 44 runs where counterevidence eventually became visible, only 17 saw it before first use and 27 saw it afterward (SSCBench). Translated: an envelope that names the problem on the failing call is worth more than any later correction.

Three numbers tell you if the taxonomy is earning its keep. Track them per tool, not per agent.

First, retries per resolved task. Before classification, expect a heavy tail from business rules masquerading as transient. The target is under one agent-level retry per plan step, backed by the local retry budget inside the tool.

Second, validation recovery rate: the share of validation failures that produce a successful call within one rewrite. A low rate means your field names or hints are too vague.

Third, permission escalations reaching a human without an intervening retry. Any retry before escalation is wasted spend.

For the observability loop itself, the five context patterns (offload, isolate, retrieve, compact, cache) are widely used to keep the window lean, and production guidance pairs them with session-level goals and step-level tool usage tracking (Splunk). Error class belongs in that step-level record, because it lets you see whether failures cluster in one class for one tool, which is almost always an envelope problem rather than a prompt problem.

If the taxonomy work is the part you would rather hand off, the natural next step is to build the agent services around a single interface: Quanta takes a described site, app or plan and pairs you with a specialist who builds it with you, which is a reasonable route when you want the envelope, the retry budget and the observability wired in from the first commit rather than retrofitted.