AI Tool Errors: Which Failures Need a Human Decision

An AI tool error should send work to the person or process that can resolve it. A malformed date may need a correction; a refused permission may need an owner’s decision. Treating both as “try again” wastes time and can turn a recoverable problem into an unauthorized action.

Route the response to repair, inspection, a decision or a bounded wait. The response supplies evidence; the task’s scope and the destination’s actual state determine what may happen next.

Start with the most specific trustworthy response available. The group names describe the next kind of work, not severity. A case can move from inspect to decide once the missing evidence is recovered. Apply the table only within the permissions and budget already granted.

RFC 9110 distinguishes access refusal, resource-state conflict and failed preconditions. A 403 response should not be automatically repeated with the same credentials. A 409 can require resolving a state conflict. Those meanings do not establish that every occurrence needs a human.

RFC 9457 provides a structured format for API problem details. Its type identifier and defined extensions are more suitable for machine routing than parsing the human-readable detail sentence. Our four routes are a synthesis layered above those protocol concepts.

An application may use a different error format or put domain failures inside an otherwise successful response. Inspect its documented contract. Do not infer the meaning of a vendor-specific code merely because its wording resembles an HTTP status.

Imagine an illustrative agent exporting a set of approved documents. The connection drops after the destination starts processing. The agent has evidence of a communication failure, but no evidence that the export failed. Its next useful action is a read-only lookup of the job or destination, not another export request.

Save the operation identifier, attempted target, last confirmed state and any completed item identifiers. If no lookup is possible, report the uncertainty plainly: the request may have completed, and repeating it may create another copy. The owner can then choose whether waiting or reconciliation is appropriate.

This is a different problem from choosing a backoff interval. Our long-running tool-call guide covers keeping track of an ongoing call; this table determines what its response means for the task.

A useful escalation names the blocked action, the relevant constraint and the available choices. “The approved spending ceiling is reached; the remaining files are untouched. Reduce the scope or approve a revised ceiling” is actionable. “The tool failed” leaves the owner to reconstruct the whole run.

Include evidence without copying secrets or a full diagnostic dump into the conversation. Preserve a reference to the restricted log if someone needs deeper investigation. The owner needs the reason and consequences, not every implementation detail.

Do not make the owner approve corrections already covered by the request. Reformatting an unambiguous date is ordinary execution. Choosing which of two clients the date belongs to changes the target. The distinction follows the ask-versus-guess decision rubric.

Choose a workflow with a clear destination and list its actual failure responses. Map each to the table, then record the evidence that permits recovery. Where the mapping is unknown, leave it unresolved until the tool contract or a controlled test supplies the missing information.

Give every recovery route an end condition: verified completion, a preserved partial result, an explicit decision request or a documented stop. “Keep trying” has no useful completion boundary. The background-work cancellation guide explains what to check when the run must end.

The table’s four routes exist because the reflex response to a tool error, try again, is the wrong one for three of the four groups. The illustrative cases below are each a plausible agent applying that reflex. They are patterns the rows describe, not observed incidents.

In each case the evidence needed to pick the right route was available or recoverable: the response itself, a job lookup or the item-level results. What was missing was a rule that read that evidence before acting.

Every route in the table depends on evidence the agent has to have saved before the error, which is why the recovery record is the practical heart of the reference. Seven fields cover the cases above: the operation identifier the tool returned, the attempted target, the last confirmed state, the identifiers of items already completed, the response class as the tool’s own contract defines it, the route chosen, and the end condition that closes the route.

An illustrative record for an interrupted export reads: job reference as returned by the destination; target folder and recipient; last confirmed state, processing started; completed items, none confirmed; response, transport timeout with no status body; route, inspect by read-only job lookup; end condition, lookup shows complete, or lookup unavailable and the owner is asked whether to wait or reconcile. The record is short, and it is the escalation message if one is needed: the owner reads what happened and what is being asked without a diagnostic dump.

The record also keeps secrets out of the conversation. It holds a reference to the restricted log rather than its contents, as the escalation section asks, and it names the tool’s documented contract for the response class rather than guessing from wording that resembles an HTTP status. Build it once for the workflow chosen in the apply section, and the recovery rules have somewhere to write their evidence.

Choose the workflow with the clearest destination, list the responses it can actually return, and write the seven-field record for one of them. Mapping that response to a route with an end condition is a small piece of work, and the mapping is reviewable in a way that a general instruction to persist is not.