Structured Error Context: How Claude Agents Recover From Tool Failures

What structured error context is

Structured error context is the discipline of returning useful information when a tool call fails, instead of a bare flag or a stack trace. When a subagent or an MCP tool cannot do its job, the model on the other side has to decide what to do next. It can only make that decision from what you hand back to it. If you hand back the word "failed", the most probable continuation is an apology to the user. If you hand back the failure type, the exact call that was attempted, whatever partial data you managed to gather, and a concrete alternative, the model has enough to retry, reroute, or escalate sensibly.

This knowledge point sits at the root of Task Statement 5.3, implement error propagation strategies across multi-agent systems, inside Domain 5 (Context Management and Reliability). Everything else in the task statement, the silent-suppression and workflow-termination anti-patterns, the access-failure distinction, coverage annotations, and full strategy design, assumes you already know what a good error payload contains. That payload is structured error context.

Why structured error context matters for the exam

The Claude Certified Architect exam tests judgement under realistic conditions, not memorisation. Two of its scenarios lean directly on this knowledge point: the Customer Support Resolution Agent (Scenario 1) and the Multi-Agent Research System (Scenario 3). In both, a tool reaches outside the model, a billing database, a web source, an internal knowledge base, and outside calls fail. The exam wants you to recognise that how a failure is reported decides whether the wider system degrades gracefully or collapses.

The key exam principle for Domain 5 is blunt: provide structured context for recovery. A well-designed agent does not treat an error as the end of the conversation. It treats the error as one more piece of evidence. That reframing is what separates an architect who designs resilient systems from a developer who wraps everything in a try/except that swallows the detail. The exam rewards the former.

How structured error context works: the four ingredients

Anthropic's own tooling guidance is explicit that a tool result should carry an is_error signal and an instructive message rather than a generic one. Building on the four error categories you met upstream, a complete error payload carries four things.

• Failure type. Classify the failure as transient (a timeout or a 500 that may succeed on retry), validation (the input was malformed), business (the operation is not allowed by a rule), or permission (the caller lacks access). The category tells the model whether retrying is even worth attempting.
• What was attempted. Record the specific call: the tool name, the parameters, the query string. "get_invoice(account=8842, month=May)" lets the model adjust the inputs; "lookup failed" does not.
• Partial results. If the tool gathered anything before it failed, three of five pages, a cached summary, the first half of a paginated result, hand it back. Discarding partial work is wasted token spend and lost progress.
• Alternative approaches. Suggest what to do instead: retry after a delay, try a narrower query, fall back to a secondary source, or ask the user for a missing identifier. This is the single most underused field, and the one that most reliably converts an apology into a recovery.

The mechanism in the Claude API is small and concrete. When a client tool throws, you continue the conversation with a tool_result block whose is_error field is true and whose content holds your descriptive message. Anthropic's documentation gives the canonical example of an instructive error, "Rate limit exceeded. Retry after 60 seconds.", precisely because that phrasing hands the model both the failure type and the alternative in one line.

Mapping each failure type to a recovery move

The four failure categories are not just labels; each one points the model toward a different next action, and that mapping is the real reason classification matters. A transient failure, a timeout, a brief network blip, an overloaded service returning a 500, is the only category where a plain retry is sensible, because the underlying request was well formed and conditions may improve within seconds. A validation failure is the opposite: retrying the identical call is pointless, because the input itself was malformed, so the right move is to correct the parameters before trying again. A business failure means the operation is forbidden by a rule, such as an account that is closed or a refund window that has passed, and no amount of retrying will change the verdict, so the agent should explain the constraint or pursue a different path entirely. A permission failure says the caller lacks the rights to perform the action, which usually means escalating to a human or to a more privileged process rather than knocking on the same locked door.

Seen this way, the failure category is a compact instruction for the loop. It collapses a vague sense that something went wrong into a specific decision: retry now, fix and retry, stop and explain, or escalate. That is why an architect who only ever returns a single generic error string is leaving most of the value on the table, because the category is doing the heavy lifting and omitting it forces the model to guess which of four very different responses is appropriate. A shared, consistent vocabulary of failure types across every tool in a system is therefore one of the highest-leverage design choices you can make, since it lets one coordinator reason uniformly about failures arriving from many different tools rather than learning each tool's idiosyncratic error dialect.

Turning a raw exception into a usable payload

The instinct most engineers carry from ordinary backend work is to catch an exception and either re-raise it or log it. Neither helps an agent. Re-raising aborts the loop; logging hides the detail from the only consumer that can act on it, the model. The architect's move is to translate the exception into the four ingredients before it ever reaches the conversation.

Consider a database timeout. The raw exception is a connection error with a stack trace. Translated, it becomes: failure type transient, attempted get_invoice(account=8842, month=May), partial results none, alternative retry after a short backoff. That translation is cheap to write and it changes the model's behaviour from "I am sorry, I could not retrieve your invoice" to "Let me try that again." The information was always there in the exception; this structured payload simply makes it legible to the model that has to decide what happens next.

How this becomes a propagation strategy

This payload is a per-call discipline, but its real value shows up across a whole pipeline. The downstream knowledge points in this task statement are all reactions to getting this wrong. If you return an empty result with no error flag you create the silent suppression anti-pattern. If you let one failure abort everything you fall into the workflow termination anti-pattern. And the capstone, error propagation strategy design, is essentially the art of returning structured error context at every node so the orchestrator can keep moving with partial results. Get the payload right at the leaf and the whole tree behaves.

Common misconceptions

How it shows up on the exam

Expect a scenario where a tool fails and you must choose what it should return. The wrong answers will be plausible: re-raise the exception, return an empty object, log the error and continue, or surface a generic message to the user. The correct answer is always the one that gives the model enough to recover, a typed failure with the attempted call and an alternative. If you can name the four ingredients and explain why each one changes the model's next move, you can answer every variant of this question, and you have the foundation the rest of Task Statement 5.3 builds on.

Watch and learn

Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.

Peace Of Code

Claude Certified Architect Ep 07: Agent Error Handling & tool_choice Explained

Why watch: Directly targets this exam and explains how to return errors to the agent with enough context for recovery rather than failing opaquely.

More videos for this concept

Claude Certified Architect Ep 07: Agent Error Handling & tool_choice Explained

Peace Of Code

How to Master Error Handling in Claude APIs

NextGen AI Explorer

Building more effective AI agents

Anthropic

Building Multi-Agent AI Research Systems at Anthropic

Steven Ge