Error Messages as Prompts
An error message is a prompt: its reader is the model's next step, so it must say what to do next — and it only works if it reaches the model at all.
When a tool call fails, the error string goes back into the model's context and becomes the most influential input to its very next decision. That makes the audience of every tool error precise: not the engineer reading logs tomorrow, but the model choosing its next call a second from now. Two consequences follow, and this essay is built on both. First, an error that only says what went wrong leaves the model to guess the fix; a useful one says what to do next. Second, an error delivered on a channel the model never reads — a protocol-level error the client swallows — teaches it nothing, however well it is written.
Step 1The model's next call is conditioned almost entirely on the last error.
A human who hits an error opens docs, reads source, asks a colleague. The model has exactly one artifact to learn from: the text you returned. It will not go and re-read the schema; it will pattern-match its retry against your error string. That makes the error message the highest-leverage sentence in the whole tool — functionally a just-in-time prompt, injected at the exact moment the model is deciding what to do differently.
And the budget for that prompt is small. Anthropic's tool-use docs state that if a tool request is invalid or missing parameters, Claude "will retry 2-3 times with corrections before apologizing to the user." Two or three shots is the whole recovery window. An error that spends one of them on "invalid input" has burned a third of the run's chance to succeed.
Step 2An error the model cannot see teaches it nothing: put it on the right channel.
Before wording, routing. Every major tool interface has a channel that lands in the model's context and a channel that does not, and an error written for the model but sent on the second one is wasted.
- Anthropic Messages API. A failed client tool is returned as an ordinary
tool_resultblock with"is_error": trueand the message incontent. The model reads it like any other result. The docs add the instruction this page is about: instead of generic errors like"failed", "include what went wrong and what Claude should try next." - OpenAI function calling. There is no error flag. The
function_call_outputitem carries anoutputstring whose "format is up to you (JSON, error codes, plain text, etc.)", and "the model will interpret that string as needed." The error is the string — so the string has to carry everything, including whether to retry. - MCP. The spec defines two mechanisms, and only one of them is aimed at the model. Protocol errors are JSON-RPC
errorobjects for unknown tools, malformed requests and server errors; clients "MAY" pass them to the model, "though these are less likely to result in successful recovery." Tool execution errors — API failures, input validation errors, business-logic errors — are returned inside a normalresultwithisError: true, and clients "SHOULD provide tool execution errors to language models to enable self-correction." The current revision, 2026-07-28, keeps that split unchanged.
# Protocol error: caught by the client; the model may never see it { "jsonrpc": "2.0", "id": 3, "error": { "code": -32602, "message": "Invalid params" } } # Tool execution error: an ordinary result, delivered into context { "jsonrpc": "2.0", "id": 4, "result": { "content": [{ "type": "text", "text": "Dates must be in the future. Current date is 08/08/2025" }], "isError": true } }
The protocol learned this the hard way. MCP's 2025-06-18 spec was ambiguous — "invalid arguments" were listed as a protocol error, "invalid input data" as a tool execution error — so many servers returned validation failures as JSON-RPC -32602. SEP-1303 (“Input Validation Errors as Tool Execution Errors”) states the consequence directly: "Protocol Errors are catch at the application level by the MCP Client. Only Tool Execution Errors are forwarded back to the model," so "models cannot see these error messages and thus cannot self-correct." Its worked case is a flight-booking tool whose "date must be in the future" rule cannot be expressed in JSON Schema: the SEP reports that Cursor "typically consistently sends dates in 2024" and "repeats the same tools/call request 3 times without getting any information as to why the tools call fails." The fix moved all input validation into tool execution errors, and the 2025-11-25 and 2026-07-28 specs both list input validation errors under isError: true.
The trap is that the framework does the wrong thing by default. A validator that throws, an SDK that maps exceptions to JSON-RPC errors, a gateway that turns a 4xx into a transport failure — each can silently move a carefully worded message onto the channel the model does not read. Test the path end to end: make the tool fail and look at what actually lands in the transcript, as MCP testing describes.
Step 3The shape: what failed, what you sent, why, what to do next, and whether to try again.
"Name the cause" is necessary and not sufficient. An error that diagnoses perfectly but stops there leaves the model to derive the remedy, and derivation is where the 2–3 retries go. The minimum useful error has five parts, and the fourth is the one most often missing.
# Minimal tool-error template (plain text; the same fields work as JSON) <tool> failed: <what was rejected, in one clause> You sent: <the offending value, echoed back> Because: <the rule it broke, or the state that blocked it> Next: <the corrected call, or the tool to call first> Retry: <yes, as corrected | yes, after N s | no — stop and tell the user>
- Echo the offending value. "You sent
39.99" lets the model see its own mistake instead of re-reasoning about what it might have done. - Prescribe, don't just diagnose. The
Nextline is a concrete call or a named tool. Anthropic's "Writing effective tools for agents" makes the same point: prompt-engineer error responses to "clearly communicate specific and actionable improvements, rather than opaque error codes or tracebacks." - State retryability in words. Don't make the model infer it from an HTTP code it half-understands. An ambiguous error on a side-effecting tool is how runaway loops start: the model can't tell "already done, stop" from "transient, try again," picks try-again, and re-fires — the pattern retry amplification describes.
- Supply the missing context. The MCP spec's own example says "Current date is 08/08/2025" — a fact the model did not have and needed to fix the call. If the rule depends on state, include the state.
Step 4Before and after: five failure classes, each rewritten to say what to do next.
The template is easy to agree with and easy to skip. These are the rewrites that matter in practice.
Validation. The model sent a well-typed value that breaks a rule the schema cannot express.
# Before: the model guesses, retries, fails the same way ValidationError: field 'amount' invalid # After create_refund failed: 'amount' must be a positive integer in cents. You sent 39.99 (dollars). Retry with amount=3999.
Not found / ambiguous. The model passed a name where an ID was needed, or a reference that matches several things. The good error routes to the tool that produces the missing input — it turns a dead end into a plan.
# Before 404: user not found # After delete_user failed: 'user_id' expects an ID like usr_8f3a; you sent "Dana Lee". Two users match that name: usr_8f3a (dana@acme.com), usr_c901 (dana.lee@acme.com). Ask the user which one, then retry with that user_id. Do not guess.
Permission. Nothing about the next call can fix this, and the model needs to be told so — otherwise it will try neighbouring tools or argument variations looking for a way around the denial.
# Before 403 Forbidden # After merge_pr failed: this agent's token has read-only access to repo acme/billing. Not retryable, and no other tool can merge here. Stop, tell the user the PR is ready for review, and include its URL.
Rate limit / transient. Retryable — but say when, and say how many attempts remain, so the model neither hammers nor gives up.
# Before Error: 429 # After search_tickets failed: rate limit exceeded (upstream allows 10 requests/min). Retry after 60 seconds. Meanwhile, narrow the query: one call with status="open" and since="2026-10-01" replaces the per-day calls you were making.
Too large. The call succeeded but the result would flood the window. Treat it as an error with a narrowing prescription, not as a silent truncation. Anthropic's tool-writing guidance says that if you truncate, "be sure to steer agents with helpful instructions"; the same post notes that Claude Code restricts tool responses to 25,000 tokens by default. The budget mechanics are covered in shaping tool results; the error's job is the next-step sentence.
# Before: 40,000 tokens of JSON, cut mid-object [{"id": "LOG-1", ... <truncated> # After read_logs: 14,212 lines match; returning none (limit 500). Add level="error" (312 lines) or a time window via since/until, or call read_logs with page=1 to page through 500 at a time.
Step 5Which errors go to the model, and which go to the harness or a human.
The channel split in Step 2 is a protocol fact; underneath it is a design rule. Return an error to the model when the model can change something about its next action. Handle it in the harness when only code can, and escalate to a human when only a person can.
- To the model (as
is_error/isError): validation failures, not-found and ambiguity, business-rule rejections ("order already refunded"), oversized results, and rate limits the model can work around by narrowing or waiting. Each one has a better next call. - To the harness: transient blips that a plain retry with backoff will fix — a dropped connection, one 503. Spending a model turn to decide "try again" is waste; the harness retries silently and only surfaces the error, now marked terminal, once its own budget is spent. The layering is in tool-use loops & error recovery.
- To a human: expired credentials that need re-consent, denials that only an owner can lift, an exhausted spend cap. The model still gets a short terminal result — "not retryable; ask the user to reconnect GitHub" — so it stops cleanly instead of looping, but the decision belongs to a person (human in the loop).
- To no one in the model's context: stack traces, internal hostnames, SQL, secrets. They cost tokens, help no next step, and leak your internals into a transcript that may be logged or shown to users. Log them; give the model the one sentence it can act on.
A quick test for any error string: cover everything except the Next and Retry lines. If what remains would not tell a competent stranger what to do, the model will not know either.
Step 6Never let a tool fail silently or lie about success.
The worst error is the one that wasn't returned. A tool that swallows a failure and returns an empty result, or returns success when nothing happened, makes the model proceed confidently on a false premise — and the failure surfaces three steps later as behaviour no trace can localise (the silent-failure anti-pattern). Partial success is the same trap: "refund issued, but the confirmation email failed — do not refund again; tell the user to expect no email" must be reported as exactly that, or the agent reports a falsehood to the user, or refunds twice.
Step 7When a terse error is the right call.
Instructive is not the same as long. Errors are re-sent on every later turn like any other result, and an error that dumps the whole valid schema or a 500-line trace poisons the window worse than a curt one. Where strict schema enforcement already makes a class of error impossible — Anthropic's strict: true guarantees tool inputs match the schema — spend no words on it. Anthropic's guidance also points the other way: "lots of tool errors for invalid parameters might suggest tools could use clearer descriptions or better examples." A recurring error is a description bug, not a wording problem. Make errors instructive, not encyclopaedic: one clause of cause, the echoed value, the next call, and the retry verdict — delivered as a result the model can read, because an error that never reaches its context is one it cannot act on.