Tool Design and MCP Integration

Mechanism reference

This section documents every mechanism the task touches, at full depth, with exact field names, value spaces, ownership, and boundary conditions.

Mechanism reference: Tool definition anatomy

A tool is an object passed in the tools array of a POST /v1/messages request. The Messages API is the transport, and the tool definition is the contract that constrains what the model may emit inside a tool_use block. Three fields are required and always present. Every additional field is optional and layered on top without changing the core three.

name is a string that must be unique among the tools in the request and must use snake case. The API validates uniqueness. At runtime the model emits the same string in tool_use.name, and application code routes on it. The lesson set is explicit that a mismatch between the name declared in tools and the name forced via tool_choice produces a validation error before inference runs. A name such as get_customer versus lookup_order carries load-bearing information because the model uses both name and description together to decide relevance.

description is a free-form string with no length limit enforced by the schema, but with a token budget that matters in practice. Every token in every description is loaded into context on every turn. The lesson tool-definition-schemas quantifies a set of four to five well-described tools at roughly 17,000 to 18,000 tokens of context cost, which makes description verbosity a real constraint rather than a style preference. The guidance for what belongs in this string has been stable across documentation versions: state purpose unambiguously, state expected inputs with formats, give concrete example queries, enumerate edge cases and what the tool does not do, and state explicit boundaries versus sibling tools. The reference page lists exactly those five elements, and the lesson tool-definition-schemas covers them as the four jobs of a description plus boundary guidance, while agentic-eng-action-tools adds side effects as an explicit item to document.

input_schema is a JSON Schema object that must have type: "object". It is not a loose bag of hints. It is a schema that can be enforced by the API when strict mode is used, and it governs validation on every tool_use.input the model produces. The canonical shape is:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "City name with optional state or country, e.g. 'San Francisco, CA' or 'Tokyo, Japan'"
    },
    "units": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "description": "Temperature unit. Defaults to celsius if not specified."
    }
  },
  "required": ["location"]
}

Only type and properties are strictly required to form a valid schema, but a production schema also includes required and description per property, and often enum, additionalProperties, and type refinements. The sections below enumerate each subfield.

The reference page, the lesson, and the API documentation agree that name, description, and input_schema are the three load-bearing fields and that description dominates selection accuracy.

Mechanism reference: input_schema design at field-level depth

input_schema follows the JSON Schema object specification. The model treats it as a set of constraints on tool_use.input. The constraints listed here are the ones that exist in the API and that interact with strict mode.

type must be "object" at the top level. Individual properties use "string", "number", "integer", "boolean", "array", or "object". The distinction between integer and number is load bearing. The lesson tool-definition-schemas requires matching the schema type exactly to what the backend expects, because a schema that says integer but a backend that parses a string will accept the call and then fail on arrival. Where a value must be an integer identifier such as order_number, declare integer, not number. Where decimals are valid, use number.

properties is a map from parameter name to a schema fragment. Every property should include its own description that states format, constraints, and an example. The lesson explicitly shows "User ID in USR-XXXXX format, e.g. USR-48721" as the pattern. A property without a description leaves the model to infer format from the name alone, which is the same failure mode as a tool without a description, only at smaller scope.

required is an array of property names that must be present in tool_use.input. Only list a parameter here if the tool will fail without it. Optional parameters with sensible defaults must be omitted from required so the model can skip them when they are not relevant. An empty required array is valid and means every property is optional.

enum is an array of literal values that constrains a property to a closed set. Use it whenever a parameter has a fixed vocabulary. The lesson is explicit: do not rely on description alone for fixed values, because the model may still invent a value not in the allowed set. An enum of ["celsius", "fahrenheit"] prevents the model from emitting "metric" or "centigrade". The same pattern applies to status fields, action verbs, and tier names.

additionalProperties controls whether the model may emit properties not declared in properties. Setting it to false closes the object and forces the model to emit only declared keys. This is the recommended setting under strict mode, because open schemas leave a gap where unexpected keys can pass shape validation and then fail business validation downstream.

Nesting depth must be kept shallow. The lesson advises never exceeding two levels of nested objects, because deeper nesting reduces invocation reliability. Flatten complex structures where possible. If a tool logically needs a nested object, consider splitting the tool instead.

description per property is where identifier format belongs. A property named order_number with description "Order number in #NNNNN format, e.g. #12345" prevents the model from passing a raw integer or a tracking ID into the wrong field. The description is also where defaults are documented: "Temperature unit. Defaults to celsius if not specified."

Validation boundary: when strict mode is off, the model is guided by the schema but not constrained by it, so a required field can still be omitted or a value can arrive as string "2" instead of integer 2. When strict mode is on, the API constrains sampling so that only schema-valid outputs are possible, using grammar-constrained sampling. Strict mode guarantees shape, not business validity. A well-typed customer_id that references an account the caller cannot access still passes shape validation and must be rejected by application authorization code.

Mechanism reference: Optional top-level tool fields

Beyond name, description, and input_schema, the API defines a set of optional fields that layer capabilities onto the same definition without changing the core contract. The prompt for this task enumerates type, strict, defer_loading, input_examples, allowed_callers, cache_control, and eager_input_streaming as the fields to account for. Each is documented here with its exact semantics.

type identifies the tool kind. Most tools submitted by applications are custom tools (the default when omitted). Built-in server tools carry their own type values, such as web_search or code_execution, and are not declared with a full input_schema by the caller in the same way. For a custom tool, omitting type or setting it to "custom" is equivalent and has no effect on selection. Specifying a server-tool type without the corresponding beta or capability flags produces a validation error.

strict is a boolean flag set at the same level as name and description. When true, the API enforces the input_schema with grammar-constrained sampling so that tool_use.input is guaranteed to match the schema and the emitted tool_use.name is guaranteed to be one of the tools provided. The constrained schema subset in strict mode is the same subset used for structured outputs. Schemas that use unsupported constructs (deeply nested conditionals, some anyOf or oneOf patterns, or recursive references) must be simplified before strict mode accepts them. Strict mode does not replace server-side business validation.

defer_loading is a boolean that marks a tool as deferred. A deferred tool is not loaded into the model's context at the start of the turn. Only non-deferred tools and a lightweight tool_search capability are visible initially. When a task needs a deferred capability, the model searches by name or intent and only then is the matching definition expanded into context. This addresses context bloat when an application exposes many tools. An application can expose 50 or more tools while the model only pays the token cost for the ones it actually searches for and uses on a given turn. defer_loading is a beta capability and requires the corresponding beta header as of this writing.

input_examples is an array of 1 to 5 realistic sample invocations showing minimal, partial, and fully specified parameter combinations. These examples are attached to the tool definition and teach the model conventions that a JSON Schema cannot express, such as date formats, identifier prefixes, and which optional fields travel together. An input_examples entry is a complete input object that would be valid according to the input_schema. The lesson emphasizes that this field is distinct from few-shot prompting in the system prompt. Few-shot in the prompt adds tokens on every turn and does not fix why the model is confused, while input_examples on the tool definition adds targeted format guidance that travels with the schema and is consulted during selection.

allowed_callers controls whether a tool may be called from code execution sandboxes. The current documented value is ["code_execution_20250825"], which opts a tool into programmatic calling from Claude-written code running in the sandbox. When opted in, multi-step orchestration and filtering can happen inside code rather than as a chain of individual tool_use and tool_result round trips, which keeps bulky intermediate results out of the context. Without this flag the tool is only callable as a normal tool_use block. The flag interacts with the code execution tool family.

cache_control marks a tool definition for prompt caching. Setting cache_control: { "type": "ephemeral" } on a tool allows its prefix in the request (typically the tools array and system prompt) to be cached across turns so that repeated calls pay only for the uncached suffix. Tool definitions are a natural fit for caching because they are large, stable, and repeated verbatim. The token savings are most visible when the tool set is large and descriptions are detailed. Caching does not change selection semantics. It changes billing and latency.

eager_input_streaming is an optimization that allows the model to begin streaming tool_use.input field values before the full block is complete. The flag is only meaningful when streaming responses are consumed incrementally and the application can act on partial inputs (for example to pre-validate or prefetch). It does not change the final validation of the input against input_schema. When absent or false, the input is delivered atomically at the end of the tool_use block.

Mechanism reference: tool_use and tool_result shapes

The tool definition governs what the model may produce. The tool_use block is what the model actually produces, and tool_result is what the application returns. These three objects form a matched triple and share identifiers that must align exactly.

tool_use block. The model emits this inside the content array of an assistant message when stop_reason is tool_use. The shape is fixed:

{
  "type": "tool_use",
  "id": "toolu_01ABC123",
  "name": "get_weather",
  "input": {
    "location": "Tokyo, Japan",
    "units": "celsius"
  }
}

Three fields are always present. id is a unique identifier prefixed with toolu_. It is generated by the API and is the correlation key for the round trip. name is the tool name from the definition, and with strict mode enabled it is guaranteed to be one of the tools provided. input is the parameter object constructed according to input_schema, with the same type coercions and enum constraints the schema declared. When strict is true the input is guaranteed to match input_schema, otherwise it is best effort and application code must validate. Multiple tool_use blocks may appear in a single assistant message, and they may be interleaved with text blocks that contain a brief explanation such as "Let me check the weather for you".

The id prefix is load bearing. The application must not invent an identifier or reuse one across blocks. Each tool_use has its own id, and each result must echo that exact string.

tool_result block. The application emits this inside the content array of a user message that follows the assistant message containing tool_use. The ordering requirement is strict: the assistant message with tool_use blocks must be appended to the message history before the user message with tool_result blocks, otherwise the API rejects the request. The shape is:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01ABC123",
  "content": "Tokyo: 22C, Sunny, 55% humidity, Wind 15 km/h",
  "is_error": false
}

tool_use_id must match the originating id character for character. content carries the tool output. It may be a string or an array of content blocks. The API does not prescribe a schema for the output, the application chooses what to return, but lesson tool-definition-schemas and agentic-eng-action-tools both require that the description of the tool already told the model what the output will look like so it can interpret the result and decide what to do next. is_error is optional. When true it marks the result as an error and the lesson tool-choice-deep-dive recommends handling it by switching tool_choice to none to force a textual explanation rather than retrying the same failing tool.

Matching contract for parallel calls. If the model emits three tool_use blocks in one turn, the application must return three tool_result blocks in one user message, each with its own tool_use_id. A common bug is to return a single result for multiple calls or to split results across multiple user messages before re-querying the model. The loop must collect all results and send them together.

stop_reason values. The response's top-level stop_reason tells the application what to do next. The four values seen in a basic tool-use loop are end_turn (model finished, no pending calls, display text), tool_use (model wants to call tools before continuing, extract blocks and execute), max_tokens (response was cut off at the max_tokens limit, any tool_use at the tail may have an incomplete input and must be validated before execution), and stop_sequence (a custom stop string was hit, verify completeness). Three additional values apply to agents that use server tools or run near limits: pause_turn when a server-side tool hits its iteration cap and the correct action is to send the assistant content back as is to let it continue, refusal when the model declines for safety reasons with stop_details indicating the policy and the mitigation being a retry on a fallback model, and model_context_window_exceeded when the model runs out of context mid-generation, distinct from the client-side max_tokens cap. Ignoring stop_reason and assuming every turn contains tool calls, or assuming every turn ends the conversation, are both common loop bugs.

Mechanism reference: tool_choice interaction with schema design

tool_choice does not live inside the tool definition. It lives at the request level alongside tools and messages, but it directly governs how the model consults the definitions. Four values exist and each fundamentally changes termination behavior.

auto lets the model decide whether to use a tool. Either tool_use or end_turn is possible. This is the correct default for general-purpose assistants where some requests are purely conversational. The lesson set is consistent that auto also preserves the model's ability to emit a short explanatory sentence before a tool call, while forced modes do not. Leaving tool_choice unspecified is equivalent to auto.

any forces the model to use one of the available tools on every turn. No text-only response is allowed, and stop_reason will always be tool_use. This is correct for classifiers and routers that must act on every input, but it requires a maximum turn guard in any loop, because the loop will never terminate on its own if any is held constant.

none suppresses all tools. The model responds with text only and stop_reason is always end_turn. This is correct for greeting turns, confirmation prompts before destructive actions, and error explanations after a failed tool result.

Specific tool, expressed as {"type": "tool", "name": "get_weather"}, forces the model to call exactly that tool. The named tool must exist in tools or the request fails validation. This is correct for pipeline steps where the caller must guarantee which function runs.

Forcing via any or a specific name prefills the assistant turn to guarantee a tool call, which suppresses leading text and reasoning that would otherwise appear before the tool_use block. The lesson notes that this is observable and that applications which need a sentence of reasoning before a forced call should capture reasoning via the extended thinking channel or switch to auto with a strong nudge. The ordering implication for schema design is that descriptions must do their work without relying on free-form reasoning that only appears under auto.

Mechanism reference: Misrouting taxonomy

With the field-level mechanics in place, the failure modes the reference page describes can be named precisely.

Ambiguity misrouting occurs when two descriptions lack boundary statements. The model sees get_customer: "Retrieves customer information" and lookup_order: "Retrieves order details" and treats them as near synonyms. A user request containing both a customer signal ("check my order") and an order identifier ("#12345") provides no disambiguation through the description alone, so the model picks arbitrarily. The fix is to add accepted identifier formats, returned fields, and an explicit do-not-use clause to each description.

Granularity misrouting occurs when a single tool handles multiple distinct intents. analyze_document: "Analyses a document and returns results" conflates extraction, summarization, and verification. Even with a perfect description it remains one tool with one name, so the model cannot express which intent the caller actually wants. Splitting into three tools with distinct names and narrow schemas removes the ambiguity.

Name-collision misrouting occurs when the name alone is confusing. analyze_content tells the model nothing about whether the tool operates on web results, local files, or conversation history. Renaming to extract_web_results disambiguates at the name layer without changing implementation, because name and description are consulted together.

Prompt-override misrouting occurs when a system prompt contains a keyword that implicitly favors one tool. A prompt that says "always check customer details before proceeding" creates an association between any mention of a customer and the get_customer tool, even when the user intent is order tracking. Updating descriptions without auditing the prompt leaves this override in place.

Cardinality misrouting occurs when the tool count itself is the problem. The reference page and the lesson set agree that four to five tools is the sweet spot, six to eight is manageable only with carefully differentiated descriptions, and beyond that reliability drops. At very large counts the model's decision space is too wide for description quality to rescue, and the correct remedy is architectural, such as introducing a router tool that dispatches inside the application. Task 2.3 addresses that threshold and response.

Mechanism reference: Batch endpoints and parallel variants

The lesson tool-definition-schemas adds two scale patterns that are directly relevant to schema design because they determine whether the caller needs a new tool, a new parameter, or no change at all.

Batch parameter execution replaces N sequential calls that differ only by a parameter value with one call that accepts an array of values and returns an array of results. Three calls to run_analysis at two minutes each cost six minutes wall-clock when serialized, while one call to run_analysis_batch with scenarios: ["A", "B", "C"] completes in roughly two minutes by running server-side concurrently. The schema change is to replace a singular parameter with an array type and to declare the return as an array of corresponding results. Batch endpoints also require input size limits at the API layer so that an oversized batch is rejected or paginated rather than timing out.

Parallel variant over boolean switches. When a lightweight version of an existing tool is needed, adding a new tool such as search_orders_summary alongside search_orders_full is clearer to the model than adding a boolean includeDetails switch to one tool. Each variant gets its own description, input_schema, and usage guidance, the summary variant keeps the model from pulling heavyweight fields it does not need, and existing callers retain backward compatibility because no signature changed.

Mechanism reference: Output specifications and context hygiene

Tool outputs are not declared in input_schema. Whatever the application returns in tool_result.content is the output. The discipline is to describe the output in the description so the model knows what to expect and what to do next, and to keep the output itself concise and structured. The lesson advises returning summaries or paginated results rather than dumping full documents into the context window, and enforcing input size limits so that wide queries do not flood the window on the way in either. Error outputs deserve the same discipline, with a clear statement of what went wrong, why, and what to try next, rather than a raw stack trace.

Ownership map

Each layer in the stack owns a distinct set of guarantees. Mixing ownership causes bugs where the model is blamed for a backend validation failure or the application is blamed for a sampling constraint the API should have enforced.

The ordering of tool_use and tool_result is worth calling out separately because it is a common source of "API error on the second turn" reports. The history must read assistant message containing tool_use blocks, then user message containing tool_result blocks, then the next assistant message. Swapping the two or appending a tool_result without first preserving the assistant message breaks the required alternation.

Version and terminology currency

The reference page, the lessons, and the current Anthropic documentation use nearly identical vocabulary for the core triple, but surrounding terminology has moved. Candidates should know both forms to avoid hesitation on phrasing.

Tool versus function. The exam guide and early documentation sometimes say "function calling" while current docs say "tool use." These refer to the same mechanism. Tool definitions in the Messages API are functions the model may call. The field tools on the request and the block tool_use in the response are the current names, with function persisting only in informal description.

strict and grammar-constrained sampling. The reference page does not use the word strict, but the lesson tool-definition-schemas covers strict: true as a top-level tool property that places the sampling path under a schema-constrained decoder. This capability postdates the original tool-use launch which described input_schema as guidance rather than a guarantee. The currency note is that older writing says the model "should produce valid input according to the schema" while current writing with strict says the model "will produce only schema-valid input." The two statements describe the same system before and after the flag is enabled.

Advanced tool use additions. Three capabilities described in lesson tool-definition-schemas under the heading Advanced Tool Use: Search, Examples, and Programmatic Calling are beta additions that layer on top of the core contract. They map to the optional fields documented above: defer_loading for the Tool Search Tool, input_examples for Tool Use Examples, and allowed_callers for Programmatic Tool Calling. The lesson notes they are opt-in behind a beta header as of its writing, and that they are not prerequisites for correct basic definitions. Candidates who read only the reference page will not have seen these fields by name. The correct exam interpretation is that they are scaling solutions for large tool libraries, not prerequisites for fixing misrouting among a small set.

Tool Search Tool naming. The documentation heading "Tool Search Tool" and the flag defer_loading: true describe the same feature. An older informal description might say "deferred tools" while newer docs say "Tool Search." Both mean tools that are searchable rather than eagerly loaded.

cache_control and prompt caching. Prompt caching is documented as a distinct optimization from schema design, but it is included in the tool enumeration for this task because detailed descriptions are expensive. Lesson tool-definition-schemas lists cache_control alongside strict and defer_loading as part of the production surface, and Anthropic docs describe caching as applicable to tool definitions that are repeated verbatim.

Exam-guide versus current product names. The exam guide may refer to the tool set in terms of "functions" or describe batching and routing in prose, while the product surfaces concrete flags and tool kinds. The candidate should answer with the documented behavior, using whichever term the question stem uses, and should not treat a term mismatch as a trick.

Official versus community divergence

Where community material contradicts Anthropic documentation on this task, the documentation governs the answer. The divergences below are the ones relevant to tool schema design.

Few-shot as a first fix. Community explanations sometimes recommend adding five to eight few-shot examples to the system prompt as the primary remedy for misrouting. The official documentation and the lesson material both treat few-shot as symptom treatment that adds token overhead without fixing why the model is confused. The correct first step for the reference scenario is to expand descriptions. The community recommendation is not wrong in isolation, but the reference page explicitly marks it as the exam trap for this scenario.

Routing classifier as a first step. Community patterns sometimes jump to a dedicated routing layer that parses input before each turn and pre-selects a tool. Anthropic guidance and the lesson set both characterize this as over-engineered as a first step because it bypasses the model's natural language understanding and adds infrastructure the scenario did not require. The router tool pattern inside the application is endorsed as a cardinality solution, not as a misrouting fix for two ambiguous descriptions.

Tool consolidation versus splitting. Some community write-ups advocate consolidating get_customer and lookup_order into a single lookup_entity tool that dispatches internally. The reference page states this is valid as long-term architecture but wrong as a first step in front of a misrouting test where expanding descriptions costs far less. Lesson tool-definition-schemas reinforces that a new parallel tool is often preferable to a boolean switch on an existing one, but only when the need is for a lightweight variant, not as a way to paper over ambiguous descriptions.

Tool count thresholds. Community material sometimes quotes a single magic number for when selection breaks. The official-adjacent lesson material gives a graduated scale rather than a cliff: one to three tools is highest reliability, four to five is the sweet spot at moderate token cost, six to eight is manageable only with carefully differentiated descriptions, and nine or more is where selection errors increase significantly, with 18 stated as the hard ceiling where the model reliably fails. The exam tests the four to five ideal and the deferred routing response for large sets, not a single hard threshold in isolation.

Strict versus description quality. A community misconception holds that strict: true fixes misrouting. Strict guarantees that the emitted input matches input_schema in shape. It does not fix which tool the model chooses. That choice is driven by name and description. A strict schema with vague descriptions still misroutes reliably, it just misroutes with well-formed arguments.

Prompt wording as neutral. Community material often treats the system prompt as orthogonal to tool selection. Both the reference page and the lesson on tool_choice emphasize that keyword-sensitive instructions can silently override descriptions, and that only auto preserves explanatory text before a tool call. Leaving the prompt untouched after a description rewrite is explicitly identified as a trap.

The candidate's decision rule is simple. When a choice in a practice or exam scenario has one answer grounded in Anthropic docs or lesson guidance and another grounded only in a community pattern, pick the documented behavior and note the divergence.

Beyond the task statement

The reference page keeps focus narrow: descriptions fix misrouting among a workable number of tools, and system prompts can override them. The lesson set covers adjacent material that the reference page omits entirely, and each of these is relevant to how a candidate reasons about schema design in production.

JSON Schema depth and strict guarantees. The lesson tool-definition-schemas devotes a full subsection to per-property description, enum, required, additionalProperties, and shallow nesting. This is the vocabulary the exam uses to test whether a schema will actually constrain the model or merely hint at what it should do. Knowing the strict subset and that it uses the same constrained decoding as structured outputs matters for any scenario where a malformed call would throw at runtime.

The full stop_reason enum and tool_choice interplay. Lesson tool-use-blocks enumerates seven stop reasons, not just end_turn and tool_use, and lesson tool-choice-deep-dive shows how each tool_choice value maps to which reasons can appear and whether the loop can terminate naturally. A candidate who only knows end_turn versus tool_use will misdiagnose pause_turn as an error and will not understand why any loops forever without a max turn guard.

Forcing suppresses reasoning. The detail that any and specific-tool forcing prefill the assistant turn and suppress explanatory text, even when the prompt says "explain first," is omitted from the reference page but documented in tool-choice-deep-dive and tied to the extended thinking channel. This is the mechanism behind the prompt-override trap.

Batch and parallel variant patterns. Lesson tool-definition-schemas covers batch endpoints and parallel lightweight variants as scale responses. These are schema design decisions that determine whether the correct remediation is a schema edit, a new tool, or a new parameter. The reference page's splitting advice is a special case of this broader set.

4 to 5 tool rule and router pattern. The token cost table and the recommendation to use a router tool when the set exceeds the sweet spot appear in tool-definition-schemas but not on the reference page's core path. This is flagged as Task 2.3 territory, but the vocabulary is needed here to understand when expanding descriptions is and is not the remedy.

Action-perception loop and result design. Lesson agentic-eng-action-tools frames tools as the agent's action space and tool results as perception that drives the next reasoning cycle. The signal-to-noise principle there, returning relevance-scored paths and pass/fail summaries rather than raw dumps, is the production counterpart to the description guidance. A well-described tool that returns 500 lines of raw output still leaves the loop open and wastes tokens.

Risk-tiered permissions. The same lesson classifies tools into read-only, write, destructive, and external, with progressively stricter approval expectations. Schema design interacts with this classification because a tool's side effects must be documented in its description so the model, and a human reviewer, know that calling it mutates state.

Granularity guidance. Read operations should be fine-grained for context control, writes should be coarse-grained for safety, and search should be medium-grained. This is omitted from the reference page but sets the default for whether splitting is appropriate in a given domain.

Worked production examples

Two end-to-end walkthroughs show how the mechanisms combine in a system that could ship. Each names the failure mode it avoids, the reasoning chain that leads to the remedy, and the observable outcome.

Worked production examples: Example 1: Customer support copilot that stopped misrouting order queries

Context. A retail copilot exposes two tools to handle the most frequent intents. Observability showed that roughly one in three order-tracking utterances such as "check my order #12345" was routed to get_customer instead of lookup_order, while customer-identity utterances such as "is my account still active under [email protected]" were rarely misrouted the other way. The tools array at the time carried minimal descriptions.

Step 1: Capture the failure. Production logs sampled ten real user utterances covering both intents and recorded the selected tool per turn. Three of ten order queries hit get_customer, confirming an ambiguity problem rather than random noise. The sampling excluded any prompt-forced or routing-layer behavior so the measurement reflected pure description-driven selection.

Step 2: Diagnose the root cause. The definitions at the time looked like this, stripped to the load-bearing lines:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const weakTools: Anthropic.Tool[] = [
  {
    name: "get_customer",
    description: "Retrieves customer information",
    input_schema: {
      type: "object",
      properties: {
        identifier: {
          type: "string",
          description: "Customer identifier",
        },
      },
      required: ["identifier"],
    },
  },
  {
    name: "lookup_order",
    description: "Retrieves order details",
    input_schema: {
      type: "object",
      properties: {
        identifier: {
          type: "string",
          description: "Order identifier",
        },
      },
      required: ["identifier"],
    },
  },
];

Both tools share the same identifier property name, the same type, and near identical descriptions. No format tells the model that get_customer expects email, phone, or customer_id while lookup_order expects #NNNNN or a tracking ID. No boundary tells it what not to use each tool for. The model therefore treats the two as synonymous and picks on surface keyword overlap.

Step 3: Expand descriptions and tighten schemas. The remedy is low effort and high leverage. Each tool keeps its name but receives a production-grade description that states purpose, accepted formats, returned fields, and an explicit do-not-use clause. Each input_schema gains per-property description with format examples, and additionalProperties: false closes the object.

const strongTools: Anthropic.Tool[] = [
  {
    name: "get_customer",
    description:
      "Looks up a customer account by email address, phone number, or customer ID. "
      + "Returns customer profile fields: name, contact details, account status, and loyalty tier. "
      + "Use this when you need to verify who the customer is. "
      + "Do NOT use for order-specific queries such as status or shipping, use lookup_order for those.",
    input_schema: {
      type: "object",
      properties: {
        identifier: {
          type: "string",
          description:
            "Customer identifier. One of: email address (e.g. '[email protected]'), "
            + "phone number in E.164 format (e.g. '+14155552671'), or customer ID in CUST-XXXX format (e.g. 'CUST-4831').",
        },
        include_loyalty: {
          type: "boolean",
          description:
            "When true, include loyalty tier and points balance. Defaults to false if omitted.",
        },
      },
      required: ["identifier"],
      additionalProperties: false,
    },
  },
  {
    name: "lookup_order",
    description:
      "Retrieves order details by order number in #NNNNN format or by tracking ID. "
      + "Returns order status, item lines, shipping details, and refund eligibility. "
      + "Use this when a customer asks about a specific order. "
      + "Do NOT use for customer identity verification or account lookups, use get_customer for those.",
    input_schema: {
      type: "object",
      properties: {
        identifier: {
          type: "string",
          description:
            "Order identifier. One of: order number in #NNNNN format (e.g. '#12345') "
            + "or carrier tracking ID (e.g. '1Z999AA10123456784').",
        },
        include_items: {
          type: "boolean",
          description:
            "When true, include full item lines with SKU, quantity, and price. Defaults to true if omitted.",
        },
      },
      required: ["identifier"],
      additionalProperties: false,
    },
  },
];

What this block proves: the name, description, and input_schema are the full selection surface, and each property description teaches format in a way that enum alone cannot for open-ended identifiers. The failure boundary it addresses is ambiguous overlap between tools that accept similar-shaped strings. Its observable output is that the same ten sampled utterances, when replayed against strongTools, route correctly on nine or ten of ten turns without any change to model, prompt, or infrastructure.

Step 4: Audit the system prompt. The team found the prompt contained "Always check customer details before handling any request." That sentence creates a keyword association between any mention of a customer and get_customer, even for order flows. It was rewritten to "Verify customer identity only when the request requires identity-sensitive action such as profile changes or payment updates. For order tracking, use the order identifier directly." After the rewrite the last remaining misroutes disappeared.

Step 5: Guard with strict and server-side checks. The team set strict: false during iteration and then enabled strict: true once the schema stabilized, which guarantees that tool_use.input matches input_schema in shape, not in business authority. A server-side check still verifies that the caller is entitled to view the returned customer or order, because a well-shaped identifier can still reference a record outside the session's scope.

Step 6: Verify the loop contract. A minimal harness shows the tool_use and tool_result shapes and the required ordering:

async function handleTurn(userText: string) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    tools: strongTools,
    tool_choice: { type: "auto" },
    messages: [{ role: "user", content: userText }],
  });

  if (response.stop_reason === "tool_use") {
    const toolUses = response.content.filter((b) => b.type === "tool_use");

    const toolResults = await Promise.all(
      toolUses.map(async (block) => {
        if (block.type !== "tool_use") throw new Error("unexpected block type");
        const result = await dispatchTool(block.name, block.input);
        return {
          type: "tool_result" as const,
          tool_use_id: block.id,
          content: result,
        };
      })
    );

    const second = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 1024,
      tools: strongTools,
      messages: [
        { role: "user", content: userText },
        { role: "assistant", content: response.content },
        { role: "user", content: toolResults },
      ],
    });
    return second;
  }

  return response;
}

async function dispatchTool(name: string, input: unknown): Promise<string> {
  if (name === "get_customer") return JSON.stringify(await lookupCustomer(input));
  if (name === "lookup_order") return JSON.stringify(await lookupOrder(input));
  throw new Error(`unknown tool ${name}`);
}

What this block proves: the id to tool_use_id correlation, the requirement to preserve the assistant message before appending tool_result blocks, and the handling of parallel tool_use blocks in one turn. Its failure boundary is a single missing or mismatched tool_use_id or an omitted assistant message, either of which causes the follow-on POST /v1/messages to fail validation. Its observable output is a second response with stop_reason: "end_turn" containing the final answer that synthesizes the tool output.

Worked production examples: Example 2: Splitting a monolithic document tool and adding a batch variant

Context. An operations agent started with a single tool called analyze_document: "Analyses a document and returns results" whose input_schema accepted a document_id and a task string. The agent was asked to extract invoice amounts one turn, summarize a contract the next, and verify a compliance claim the turn after. The single tool forced the model to encode intent in the task parameter free text, which the backend then parsed heuristically. Accuracy was low because two distinct capabilities hid behind one name and one vague description.

Step 1: Split by intent. The team replaced the monolith with three narrowly scoped tools, each with its own description and narrow input_schema. A batch variant was added for the extraction case where runs are long and repeated:

const documentTools: Anthropic.Tool[] = [
  {
    name: "extract_data_points",
    description:
      "Extracts structured data fields (dates, amounts, names, SKUs) from a document. "
      + "Returns an array of field objects with value, page, and confidence. "
      + "Use for extraction only. Do NOT use for summarization or claim verification.",
    input_schema: {
      type: "object",
      properties: {
        document_id: {
          type: "string",
          description: "Document ID in DOC-XXXXXXXX format, e.g. 'DOC-9F3A21C0'",
        },
        fields: {
          type: "array",
          items: { type: "string", enum: ["date", "amount", "name", "sku", "total"] },
          description: "Field types to extract. At least one required.",
        },
        page_range: {
          type: "string",
          description: "Optional page range, e.g. '1-3' or '2,5'. Defaults to all pages if omitted.",
        },
      },
      required: ["document_id", "fields"],
      additionalProperties: false,
    },
  },
  {
    name: "extract_data_points_batch",
    description:
      "Batch variant of extract_data_points. Accepts an array of document field requests "
      + "and returns an array of results in the same order. Use when extracting the same fields "
      + "from multiple documents or multiple field sets from one document. One batch call replaces N sequential calls.",
    input_schema: {
      type: "object",
      properties: {
        requests: {
          type: "array",
          description: "Array of extraction requests, 1 to 20 items per batch",
          items: {
            type: "object",
            properties: {
              document_id: { type: "string", description: "Document ID in DOC-XXXXXXXX format" },
              fields: {
                type: "array",
                items: { type: "string", enum: ["date", "amount", "name", "sku", "total"] },
                description: "Fields to extract for this request",
              },
            },
            required: ["document_id", "fields"],
            additionalProperties: false,
          },
        },
      },
      required: ["requests"],
      additionalProperties: false,
    },
  },
  {
    name: "summarize_content",
    description:
      "Produces a concise summary of a document's key arguments and conclusions. "
      + "Returns a summary string plus the three most cited sections. "
      + "Use only when the user asks for a summary or overview. Do NOT use for field extraction.",
    input_schema: {
      type: "object",
      properties: {
        document_id: {
          type: "string",
          description: "Document ID in DOC-XXXXXXXX format",
        },
        max_sentences: {
          type: "integer",
          description: "Maximum sentences in the summary. Defaults to 8 if omitted. Range 3 to 12.",
        },
      },
      required: ["document_id"],
      additionalProperties: false,
    },
  },
  {
    name: "verify_claim_against_source",
    description:
      "Checks whether a specific claim is supported by the source document. "
      + "Returns an object with verdict (supported, contradicted, not_enough_evidence) and cited evidence spans. "
      + "Use only for claim verification against a named source document.",
    input_schema: {
      type: "object",
      properties: {
        document_id: {
          type: "string",
          description: "Document ID in DOC-XXXXXXXX format",
        },
        claim: {
          type: "string",
          description: "The claim to verify, as a single declarative sentence, e.g. 'Invoice total is $4,200'",
        },
      },
      required: ["document_id", "claim"],
      additionalProperties: false,
    },
  },
];

Step 2: Prefer parallel variants over boolean switches. The extraction pair follows the lesson guidance to add a new tool rather than a boolean is_batch switch on the existing one. Each tool has its own description and schema, the batch variant constrains batch size at the schema layer, and existing callers of extract_data_points require no migration. The summary tool uses integer for max_sentences rather than number because the backend expects a whole number.

Step 3: Wire the batch path to real parallelism. The backend executes extract_data_points_batch concurrently across its requests and returns an array in matching order, so one round trip replaces N serialized turns. Input size limits are enforced at the API layer so that an oversized batch is rejected with a structured error rather than timing out. The model's ability to call extract_data_points_batch with an array is governed entirely by its input_schema, with items and enum constraining each entry.

Step 4: Design for caching and loading. Because four detailed tool definitions raise the per-turn token cost, the application marks the stable prefix with cache_control: { type: "ephemeral" } so repeated turns reuse the cached prefix. If the agent's repertoire grows further, the team can mark the batch tool with defer_loading: true and keep only the single-document extractor eager, so the model searches for the batch capability only when it needs it. For code-execution orchestration, allowed_callers: ["code_execution_20250825"] can be added to the extraction tool so that bulk filtering happens inside sandbox code without returning bulky intermediates to the context.

Observable outcome. After the split, intent accuracy on the same utterance set moved from frequent conflation of extraction and summarization to reliable selection on each variant, because each name and description now corresponds to exactly one user intent. The batch variant reduced wall-clock time for three-document extraction jobs from the sum of three serialized calls to roughly the duration of one, observable as fewer tool_use round trips and lower output token cost per job.

Worked production examples: Validation code that catches what strict cannot

Even with strict: true, application code must validate business shape and handle the truncation case. The block below sits in the dispatch layer, between the model output and the domain handler, and is deliberately language tagged and complete so its failure modes can be named.

type ToolUseBlock = {
  type: "tool_use";
  id: string;
  name: string;
  input: unknown;
};

function validateToolUse(block: ToolUseBlock, stopReason: string | null): void {
  if (!block.id.startsWith("toolu_")) {
    throw new Error(`invalid tool_use id prefix: ${block.id}`);
  }
  if (!["get_customer", "lookup_order"].includes(block.name)) {
    throw new Error(`unknown tool name ${block.name}`);
  }
  if (stopReason === "max_tokens") {
    throw new Error(
      "response truncated at max_tokens, input may be incomplete, do not execute"
    );
  }
  const input = block.input as Record<string, unknown>;
  if (typeof input.identifier !== "string" || input.identifier.length === 0) {
    throw new Error("identifier must be a non-empty string");
  }
  if (!/^CUST-|@|\+1/.test(input.identifier) && block.name === "get_customer") {
    console.warn(`get_customer received non-customer identifier ${input.identifier}`);
  }
  if (!/^#\d{5}$/.test(input.identifier as string) && block.name === "lookup_order") {
    const looksLikeEmail = (input.identifier as string).includes("@");
    if (looksLikeEmail) {
      throw new Error(`lookup_order received an email ${input.identifier}, likely misroute`);
    }
  }
}

What this block proves: strict guarantees schema shape but not business correctness, max_tokens truncation must be treated as incomplete and not executed, and heuristic format checks in the handler catch the residual case where the model's best-effort input leaks a category mismatch. Its failure boundary is intentionally visible. The get_customer branch warns rather than throws on a loose pattern because legitimate phone formats vary, while the lookup_order branch throws on an email because that always signals a misroute worth surfacing before a backend round trip. Its observable output is either a dispatched call with validated arguments or a logged error that returns a tool_result with is_error: true and a human readable message the model can act on.

Build exercise material

Each step below is verifiable. No step asks the learner to guess at success. The observable outcome at the end of each step proves that the step worked.

Step 1: Register two ambiguous tools. In a throwaway MCP server or a local Messages API harness, define get_customer and lookup_order with single-sentence descriptions and a shared identifier string property, as shown in the weak-tools block above. Start the server and list the registered tools. You should see exactly two tools, each with a description under ten words and no boundary clause, and a single call to list tools returns both names.

Step 2: Replay ten queries and log selection. Send the same ten user utterances used in the walkthrough, five that mention customer identity (email or phone or customer ID) and five that mention orders (order number or tracking ID). For each turn log the emitted tool_use.name and tool_use.input. You should see at least two to three cases where an order-bearing utterance is routed to get_customer or vice versa, with stop_reason: "tool_use" on every turn where the model chose a tool.

Step 3: Rewrite descriptions to production grade and tighten schemas. Replace each one-line description with a three to five sentence description that states purpose, accepted identifier formats with examples, what the tool returns, and an explicit do-not-use boundary against the sibling tool. In each input_schema, expand the identifier description to name formats such as CUST-XXXX or #NNNNN, and add additionalProperties: false. Keep the name identifiers unchanged. Reload the tools and verify that get_tools or the equivalent listing shows the longer strings and the stricter schema.

Step 4: Re-run the same ten queries. Send the identical utterances in the same order without changing the system prompt. You should see selection correct on nine or ten of ten cases, with the previously misrouted order utterances now hitting lookup_order and carrying a correctly formatted #NNNNN identifier in tool_use.input.

Step 5: Audit the system prompt. Open the system prompt and search for keyword-sensitive phrases such as "always check customer details", "always use customer data first", or any instruction that links any mention of a customer to a single tool. Replace each found phrase with a scoped version such as "Verify customer identity only when the task requires identity-sensitive action, otherwise use the identifier the user provided directly." Re-send any order query that still contained the word "customer" and confirm that tool_use.name no longer flips to get_customer.

Step 6: Add the loop guards. In the loop harness, add handling for stop_reason: "max_tokens" that treats any trailing tool_use as incomplete and does not execute it, handling for tool_result with is_error: true that surfaces a readable message, and a branch that sends an assistant message's content first before appending the tool_result user message on the next turn. You should see that a deliberately low max_tokens: 10 request produces the truncation path without a dispatch, and that swapping the assistant and user message order produces a validation error from the API that disappears when the correct ordering is restored.

Step 7: Observe caching and cost. With strongTools installed and a system prompt of at least a few hundred tokens, set cache_control: { type: "ephemeral" } on the prompt and on the tools prefix, then make two consecutive calls with the same tool set. You should see the second response report cache reuse in the usage or billing metadata and a lower input token bill for the repeated prefix, even though the description content and selection behavior are unchanged.

Mechanism reference: The protocol-level tool_result block

The Messages API defines tool_result as a content block type that appears in a user message following an assistant tool_use block. The protocol fields are, in full:

• type - the literal string "tool_result".
• tool_use_id - a string that must match the id of the tool_use block this result answers. Mismatches break the conversation.
• content - optional. The result of the tool, as a string, as a list of nested content blocks (text, image, document, search_result), or as a list of document blocks. Most tool results serialize a JSON string here.
• is_error - optional boolean. Set to true when the tool execution resulted in an error. When omitted it defaults to false.

Two structural ordering rules are protocol-enforced and produce a hard HTTP 400, not a soft failure. First, every tool_result block must immediately follow the assistant's tool_use message; you cannot insert any other message between them. Second, inside the user message that carries results, every tool_result block must come first in the content array; any plain text block must come after all tool results. A user message that leads with text before a tool_result is rejected.

The is_error boolean is the only failure signal the protocol gives Claude. It is deliberately minimal. It tells Claude "this tool call did not succeed" but carries no category, no retry hint, and no recovery instruction. That is by design: Anthropic leaves the content shape open so you can tailor it to your domain. The lesson is explicit that is_error is the one part the API standardizes, and "everything else in this lesson, the errorCategory taxonomy, the isRetryable flag, the backoff parameters, is application-layer convention that you design, not an Anthropic-mandated schema."

Mechanism reference: Full value space of the content field and ordering boundary conditions

The content field is the most misunderstood part of the protocol because its accepted type is unusually permissive. The Messages API accepts four distinct shapes for content on a tool_result block, and the chosen shape changes how Claude parses the result. First, a plain string, which is the common case where your application serializes a JSON object or a human-readable message. Second, a list of nested content blocks, where each element is one of text, image, or document. Third, a list of document blocks only. Fourth, when the result is an error, the same string or block list carries the error envelope; is_error: true is orthogonal to whether content is a string or a block list. A tool that returns a screenshot of a failed render can therefore set is_error: true and still pass an image block as visual evidence, and the model reads both the failure flag and the picture.

The boundary condition that breaks real integrations is the request-size ceiling. The documented hard limit is a 32 MB total request size for the Messages API, enforced as a 413 request_too_large error, not a 400. This is a request-wide limit, not a per-block cap, so a single enormous tool_result can fail the whole call even when every individual block is well formed. In practice the model context window is the tighter bound: large results degrade reasoning long before they approach 32 MB, so the production guidance is to summarize, paginate, or truncate well under any byte ceiling. The 413 is the protocol's last-resort guard; the application layer owns the discipline of never reaching it.

The two ordering rules are protocol-enforced and fail hard, but their exact boundaries matter. Rule one: a tool_result block must appear in a user message that directly follows the assistant tool_use message, with no intervening assistant or user turn. You cannot, for example, place a thinking block or a plain text message between the tool_use and its result. Rule two: inside one user message, every tool_result block must precede any text block. The sharp boundary is that a text block placed before even a single tool_result invalidates the entire message with a 400, even if every tool_result is otherwise correct. The SDK agent loop handles this automatically when results are returned as one user turn, but hand-built message arrays in raw API calls are where the 400 surfaces.

The wire example below shows the protocol surface at full extent: two tool results in one user turn, one a successful lookup rendered as a nested document block, the other a failure rendered as a text envelope plus an image block. Both respect the ordering rules, and the failure sets is_error at the block level rather than burying it inside the content.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01renderOk",
      "content": [
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "application/json",
            "data": "{\"customerId\":\"CUST-48721\",\"tier\":\"premium\",\"status\":\"active\"}"
          }
        }
      ]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01renderFail",
      "is_error": true,
      "content": [
        {
          "type": "text",
          "text": "{\"isError\":true,\"errorCategory\":\"transient\",\"isRetryable\":true,\"message\":\"Render service unreachable.\"}"
        },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M8AAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
          }
        }
      ]
    }
  ]
}

What it proves: a failure is a block-level is_error: true regardless of whether content is a string, a nested block list, or a mix of text and image. The protocol failure signal travels independently of the result payload shape. The single user turn carries both results in the required order, tool results first, so no 400 is raised.

Mechanism reference: Backoff, idempotency, and the write-timeout boundary

The transient category with isRetryable: true is correct for read timeouts, but a timeout during a write is a different boundary. A read-only query that times out left no side effect, so a blind retry is safe. A write that times out halfway through may have partially committed on the upstream, so retrying the same call risks duplication: a double charge, a duplicate order, a second notification. The lesson material flags this read-versus-write distinction as exam-relevant, and the safe pattern is an idempotency key the upstream uses to detect and collapse repeats. The key must be supplied by your tool wrapper, never inferred by the model, because the model has no durable record of which calls it already issued.

The code below shows a tool wrapper that combines exponential backoff with jitter, the same shape the lessons recommend, and stamps an idempotency key on every mutating call. A read timeout retries under backoff. A write timeout retries only because the idempotency key lets the upstream treat the second attempt as a replay of the first, returning the original outcome instead of creating a duplicate. A non-transient error escapes the loop and becomes a structured tool_result error for the model.

interface IdempotentRetryConfig {
  maxAttempts: number
  baseDelayMs: number
  maxDelayMs: number
  useJitter: boolean
}

function backoffWithJitter(attempt: number, config: IdempotentRetryConfig): number {
  const exponential = Math.min(config.baseDelayMs * Math.pow(2, attempt - 1), config.maxDelayMs)
  return config.useJitter ? Math.random() * exponential : exponential
}

async function withIdempotentRetry<T>(
  fn: (idempotencyKey: string) => Promise<T>,
  isTransient: (error: unknown) => boolean,
  config: IdempotentRetryConfig = { maxAttempts: 3, baseDelayMs: 300, maxDelayMs: 4000, useJitter: true }
): Promise<T> {
  const idempotencyKey = crypto.randomUUID()
  let lastError: unknown
  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
    try {
      return await fn(idempotencyKey)
    } catch (error) {
      lastError = error
      if (!isTransient(error) || attempt === config.maxAttempts) break
      await new Promise(r => setTimeout(r, backoffWithJitter(attempt, config)))
    }
  }
  throw lastError
}

async function chargeCustomer(customerId: string, amountCents: number) {
  return withIdempotentRetry(
    (key) => paymentsApi.charge({ customerId, amountCents, idempotencyKey: key }),
    (error) => error instanceof TransientError,
    { maxAttempts: 3, baseDelayMs: 300, maxDelayMs: 4000, useJitter: true }
  )
}

What it proves: backoff and idempotency are separate concerns that must be combined for mutating tools. Backoff alone prevents thundering-herd retries; idempotency alone prevents duplicate side effects when a retried write reaches an upstream that already acted. Together they make isRetryable: true safe for the write-timeout boundary the exam tests. The idempotencyKey is stable across the retries of one logical call but unique per call, which is exactly the contract an upstream needs.

Mechanism reference: Application-layer error envelope

Because is_error alone is insufficient for intelligent recovery, production tool code wraps structured metadata inside the content string. This is the "structured error envelope" the reference page shows. The envelope is a JSON object whose keys are your convention, not protocol fields. A representative envelope, matching the reference page and our tool-error-handling lesson, carries:

• isError - a redundant in-content boolean mirroring is_error so downstream parsers that read the content string (not the block) still see the failure.
• errorCategory - one of the taxonomy values (transient, validation, business, permission, and in the wider model rate-limit, auth, not-found, permanent).
• isRetryable - boolean answering "will resending this exact request work?" Only transient (and rate-limit after a wait) get true.
• message - a human-readable description Claude can include in its response to the user.
• description (reference page) or context / technicalDetail (our lesson) - optional fields carrying the recovery hint, the affected resource, the sanitized input, the attempt number, or a suggestion for what to try instead.

The critical rule: these envelope keys live inside content, which is a stringified JSON object. They are NOT keys of the tool_result block. The block itself still needs type, tool_use_id, content, and is_error. A correct structured error therefore sets is_error: true on the block AND embeds the envelope in content. Setting only the envelope inside content while leaving is_error absent (defaulting to false) is the silent-failure anti-pattern: Claude reads a successful block whose content describes an error, and reasons as if the call worked.

Mechanism reference: The four required categories and their value space

The reference page specifies four categories. Each maps to a recovery strategy and to a fixed isRetryable value. The full set, including the wider lesson taxonomy, is:

The exam guide v1.0 frames the four reference categories. The wider taxonomy is the production reality and refines them: rate-limit is a transient variant that must include a wait time because Claude has no internal clock; auth overlaps permission (both need a different principal or credential, neither is retryable with the same call); not-found is the boundary case between error and empty result and is treated as an error distinct from a valid empty result.

The single most-tested nuance is the meaning of isRetryable: false. It does NOT mean "abandon the task." It means "resending this exact request is pointless because something must change first." For validation the change is the input (the agent fixes it unaided). For business and permission the change is a policy exception or a different principal (escalation). Three categories are non-retryable, but only two are dead ends.

Mechanism reference: Category deep dives

Each category has behaviour the exam probes beyond the boolean. The details below are the full value space.

Rate-limit errors are uniquely identifiable by a Retry-After header or a retryAfterSeconds field in the upstream response. They are retryable but only after waiting the indicated duration. Claude has no internal clock, so it cannot independently know when to retry; you must either include the wait time in the error description or handle the backoff inside your tool wrapper. Retrying before the window expires wastes a call and may extend the cooldown. In the wider taxonomy rate-limit is isRetryable: true but qualified "after wait"; in the four-category exam model it folds into transient. Either way the wait time must be communicated.

Timeout errors require a sub-distinction the lessons call out: client-side versus upstream. A client-side timeout means your tool imposed a deadline on an upstream call and gave up; the upstream may or may not have partially executed. An upstream timeout (for example an HTTP 504) means the service responded that it could not complete. A timeout on a read-only query is safe to retry; a timeout halfway through a write may have partially committed, so blind retry risks duplication. The category transient with isRetryable: true is correct for read timeouts, but idempotency keys or check-status calls are needed for writes. The exam tests the read-versus-write distinction.

Validation errors are never retryable with the same input. The recovery is a reformulated call with corrected parameters. A validation error that says only "invalid input" forces Claude to guess what failed; the envelope must state exactly which field violated which rule and what the expected format is. The lessons warn that marking a validation error isRetryable: true causes Claude to retry with the same invalid input indefinitely, the purest form of the retry anti-pattern. The context.input field should carry the sanitized bad value (never credentials) and context.suggestion should state the fix.

Authentication and permission errors are never retryable from Claude's perspective. A missing API key, expired token, or insufficient role will not be fixed by resending the same call. These errors must be logged server-side with full detail and returned sanitized: the message explains the issue without exposing the key, token, or internal scope string that an attacker could abuse. The permission category in the four-category model maps onto auth in the wider taxonomy; both require escalation or a different principal. Credential material must never appear in content or in context.

The three-layer error model is the conceptual frame that ties protocol, convention, and presentation together. Layer one is the tool implementation, where your code sees raw error objects, stack traces, and HTTP status codes as native exceptions. Layer two is the tool_result block, where Claude sees a sanitized, categorized error (the envelope). Layer three is Claude's natural-language response to the end user, which may include only as much of the error as is helpful. The rule is never to mix layers: raw stack traces and internal addresses stay in layer one and are logged, not returned. This is why the envelope separates message (shown to Claude and the user) from technicalDetail / context (logged, optionally shown to Claude for debugging but never to end users).

Graceful degradation is the pattern for tools that depend on multiple upstream services. When one service fails, the tool should still return what it can, marking each section ok, degraded, or unavailable. This is distinct from partial results in a batch (where some items fail), but both communicate mixed outcomes so Claude can report accurately rather than hiding failure. A degraded section tells Claude "here is stale or fallback data, label it as such"; an unavailable section tells Claude "this part genuinely failed." Serving fallback data without indicating its source is itself an anti-pattern: it creates false confidence.

Fallback chains operate at two levels. A tool-level fallback tries an alternative implementation (for example a premium weather API, then a free one, then an estimate). An agent-level fallback lets Claude choose a different tool. Either way the chosen source must be labelled in the result so Claude and the user know they are seeing fallback data. When all fallbacks are exhausted, the tool returns a structured permanent error rather than a silent empty result. The exam tests whether a candidate designs fallbacks that are transparent and orders them from best to worst quality.

Mechanism reference: Access failure versus valid empty result

This is the distinction the reference page flags as "the distinction to nail" and the exam tests directly. It deserves the deepest treatment because it is where protocol, convention, and reasoning interact.

A tool query has three outcomes, not two: success with data, success with no data, and failure to reach the data. The failure mode that breaks recovery is collapsing the last two into one shape.

A valid empty result means the tool successfully executed, reached the data source, ran the query, and found zero matches. The operation is a normal, expected outcome. The agent should report "no results found" and move on. There is nothing to retry because the query was correct and the answer is genuinely "nothing matches."

An access failure means the tool could not reach or query the data source at all. A timeout occurred, authentication failed, the service was down, or the network dropped. The data might exist, but the tool never got to check. The agent should decide whether to retry, escalate, or degrade, because the question "does anything match?" is genuinely unanswered.

The trap is structural. If a tool returns the same shape for both, an empty array [] whether it found nothing or reached nothing, then Claude cannot tell them apart. It will treat a successful empty result as a failure worth retrying, or treat an access failure as a benign empty result and confidently report "the customer does not exist" when the truth is "the database was unreachable."

The fix is to make the two outcomes look nothing alike at the protocol boundary. A valid empty result is a success block: is_error absent or false, with an explicit empty-state marker such as resultCount: 0 and a message stating the query ran and matched nothing. An access failure is an error block: is_error: true, errorCategory: "transient" (or auth/not-found as appropriate), isRetryable: true for transient, with a description stating the query did not execute.

The lesson material makes this the central anti-pattern. A queryDatabase function that catches an exception and returns [] silently is explicitly labelled DANGEROUS: Claude concludes there are no results and proceeds with "no orders found" reasoning when the real problem is a broken connection. The safe version returns a structured error object with isError: true, errorCategory: "transient", isRetryable: true.

The reference page's practice scenario grounds this precisely: a tool returns an empty array after a customer lookup, the agent retries three times, then escalates to a human, and analysis shows the customer's account simply does not exist. The root cause is that the tool does not distinguish access failures from valid empty results, so the agent treats no-matches as a retriable failure. The correct answer to that scenario is "the tool does not distinguish between access failures and valid empty results."

A subtler boundary is not-found as an error versus empty as a success. A search that returns zero rows for a valid query is a success with empty data. A lookup by a specific identifier that expects exactly one record, where that record does not exist, is usually modelled as a not-found error (or as an empty success, depending on the tool's contract). The distinguishing question is whether "no match" is a normal outcome of the query or a sign that the requested resource is absent. Our lessons handle both: tool-error-handling returns errorCategory: "not-found" from a database lookup that expects a row, while tool-result-handling returns items: [], count: 0, message: "No orders found for this customer." for a search where empty is expected. The contract must be explicit and consistent across a tool suite.

Mechanism reference: Error propagation in multi-agent systems

In multi-agent architectures the reference page states a principle of local recovery with selective propagation. This is consistent with our lessons and with the agent-sdk guidance on building effective agents. The mechanism has three rules.

Rule one: subagents implement local recovery for transient failures. If a web-search subagent times out, it retries internally before bothering the coordinator. The coordinator should not see a transient blip; it should see either a result or a genuinely unrecoverable failure.

Rule two: only propagate errors that cannot be resolved locally. If all internal retries fail, the subagent reports the failure upward. This avoids two anti-patterns the reference page names. The first is silently suppressing errors by returning empty results as success, which hides failure from the coordinator and leaves it making decisions blind. The second is terminating an entire workflow on a single failure, which throws away all the partial progress from sibling steps.

Rule three: include partial results and what was attempted. The coordinator needs context: "I searched 3 of 5 sources successfully. Sources 4 and 5 timed out. Here are partial results from the 3 successful sources." This is the multi-agent analogue of the partial-result pattern in tool-result-handling, where a batch that processes 8 of 10 records returns status: "partial" with both successes and errors rather than failing the whole batch or hiding the failures.

The ownership of this boundary is shared. The subagent's own code owns local retry and the decision to propagate. The coordinator's code owns interpreting the propagated error, choosing escalation or alternative workflow, and folding partial results into its synthesis. The protocol owns only that the propagated failure arrives as a tool_result block with is_error: true (if the subagent is itself invoked as a tool) or as a message describing the failure (if the subagent communicates by message). The category and partial-result metadata are once again application convention, agreed between subagent and coordinator.

Ownership map

Which layer owns which guarantee matters because the exam repeatedly tests whether a candidate knows what the protocol does versus what application code must do. The table below is the authoritative allocation.

The single sentence to remember: the protocol tells Claude a tool failed; your code tells Claude why and what to do. If your code fails to set is_error and fails to embed a category, the protocol cannot compensate, and Claude will treat the result as success.

Ownership map: Ownership boundary conditions in practice

The ownership table is easy to read as a partition, but the exam probes the seams where two layers touch. The first seam is the tool_use_id match. The protocol validates only that the string on the tool_result block equals some prior tool_use id; it does not validate that the right result reached the right call, nor that the content matches what that call would produce. Your application code owns that correctness. A mismatched id returns a 400, but a matched-yet-wrong id is a silent logic bug the protocol cannot see.

The second seam is the MCP translation. When a tool is served through the Model Context Protocol, the server returns CallToolResult with a camelCase isError. The MCP client is responsible for translating that into the Anthropic tool_result block, setting the snake_case is_error and carrying the content across. The protocol layer owns the block shape; the MCP client owns the field-name translation; your server code owns the meaning of the error inside the content. If the client mis-translates, the failure flag can be dropped, recreating the silent-failure anti-pattern at the transport boundary rather than in your code.

The third seam is the SDK agent loop. The loop owns matching results to calls and appending them as a user turn in the correct order, but it does not own the error taxonomy. A loop that adds its own retry-with-backoff wrapper is exercising application-level discretion, not protocol behaviour; the protocol neither requires nor forbids it. The exam expects a candidate to name the loop as the owner of ordering and matching, and your code as the owner of category and retryability, never the reverse.

The fourth seam is upstream infrastructure. A 429 with Retry-After is produced by the upstream, not by your tool, but your code owns the decision to surface the wait time inside the error description or context because the model has no internal clock. The infrastructure owns the transient behaviour; your envelope owns making that behaviour actionable to the model.

Version and terminology currency

This task spans terminology from two eras of the certification and two layers of the stack. The candidate must keep them straight.

The credential itself was renamed. The exam guide Version 1.0, effective July 2026, brands the credential "Claude Certified Architect - Foundations" with exam code CCAR-F. The older "CCA-F" short name still circulates in community material and in the reference page's footer, but the authoritative code is CCAR-F, and the domain blueprint (27 / 20 / 20 / 18 / 15) has been constant across guide versions v0.1, v0.2, and v1.0. Task 2.2 sits in Domain 2, Tool Design and MCP Integration, weighted at 18 percent.

The field name itself shifted between the two stacks a candidate touches. The reference page says "the MCP protocol provides the isError flag." That is accurate for the Model Context Protocol: CallToolResult carries a camelCase isError. But the Anthropic Messages API, which is what a candidate actually writes against when calling Claude, uses a snake_case is_error on the tool_result content block. The concept is identical; only the casing differs. A candidate who codes a tool_result block must use is_error, while a candidate who writes an MCP server returns isError that the MCP client then translates into the tool_result content. Both forms appear on the exam, and the reference page's MCP framing should be read as "the flag exists in the protocol; in the Anthropic API it is is_error."

The category vocabulary has also widened over time. The exam guide v1.0 frames four categories: transient, validation, business, permission. Our lesson material, written for current production practice, documents a fuller taxonomy that adds rate-limit, auth, not-found, and permanent. The four-category model remains the exam-facing vocabulary; the wider model is how a real tool suite is built. A candidate answers exam items with the four named categories and understands the wider model as refinement.

The isRetryable semantics align with industry conventions the reference page cites explicitly: gRPC treats INVALID_ARGUMENT as non-retryable, and AWS-style retry metadata does the same. The reference page applies that well-established convention to the validation gap the exam guide leaves open. A candidate who reasons "will resending this exact call work?" lands on false for validation every time, matching both the community convention and the gRPC/AWS precedent.

One currency note on the description field: the reference page uses description for the human-readable recovery hint, while our tool-error-handling lesson splits that role across message (always required, shown to Claude and the user) and optional context / technicalDetail (for debugging, never shown to users). Both are valid application conventions; the reference page's description is the lesson's message plus a recovery suggestion. The principle, not the exact key name, is what the exam tests.

Version and terminology currency: Version drift details that affect this task

Three layers each carry their own version story, and the exam expects a candidate to separate them. The protocol layer is the most stable: the tool_result block, its type, tool_use_id, content, and is_error fields, and the two ordering rules have not changed across the current documentation set, so a candidate coding against is_error today is coding against the same field the exam guide assumes. The MCP layer introduced the isError camelCase naming on CallToolResult as part of the protocol specification, and the divergence between isError and is_error is a naming convention, not a behaviour change; both signal the same failure.

The credential layer changed most recently. The exam guide Version 1.0, effective July 2026, brands the credential "Claude Certified Architect - Foundations" with exam code CCAR-F, while the older "CCA-F" short name still appears in community material and in the reference page footer. The authoritative code is CCAR-F, and the domain blueprint weighting (27 / 20 / 20 / 18 / 15) is documented as constant across the rename. A candidate who writes CCAR-F on the exam and reasons about the four-category model framed by that guide is aligned with the current documentation.

The error-reference layer also drifts. The HTTP error codes documented for the API (400, 401, 402, 403, 404, 413, 429, 500, 504) are the API-level mirror of the tool-level category model, and the 429 rate_limit_error carries the Retry-After convention that the rate-limits documentation describes as current. The agent-sdk guidance on local recovery and selective propagation is current and matches our lesson framing of multi-agent error handling. Where a community source uses an older term or an older credential code, documentation wins, and the candidate answers with the current term while recognizing what the older material meant.

Official versus community divergence

Our gap analysis compares the official exam guide against a large community prep bank. For structured errors the finding is reassuring rather than divergent in substance: the community family is strong, not a blind spot. The probe counts (isError 139, errorCategory or category 129, retryable 176, structured-error 225) show the community bank drills exactly the four-category model with retryable metadata. There is no community material contradicting the official framing.

The one genuine divergence is a gap, not a contradiction. The exam guide v1.0 states retriable: false for business rule violations and never assigns a value to validation. The community convention fills that gap by assigning false to validation, reasoning from "will resending this exact call work." Because the guide is silent, a candidate facing a validation-boolean question should reason from first principles and land on false, exactly as the reference page instructs. Documentation does not contradict the community here; the community simply completes an underspecified row.

A second, more dangerous divergence is an exam trap the reference page calls out directly: some material presents validation as isRetryable: true because the agent can recover from it. That is wrong, and the reference page rebuts it at length. The boolean answers whether resending the same call works, not whether the agent can recover. A malformed order ID fails the same format check every time, so validation is false; the agent recovers by correcting the input and issuing a new call, but errorCategory carries that instruction, not the boolean. A candidate who answers "validation is retryable because the agent can fix it" is choosing the trap.

A third divergence is vocabulary scope. Community and older prep material sometimes collapse auth and permission into one bucket, or omit rate-limit and not-found entirely. Our lessons keep them distinct, and the documentation position is that rate-limit is a transient variant requiring a wait, auth is a credential problem needing escalation, not-found is an error distinct from valid empty. The candidate should answer with the fuller, documentation-aligned taxonomy while recognizing the exam's four-category framing.

Where documentation and community material conflict, documentation wins, and the candidate answers with the documentation position. Here the conflict is mild and the guidance is consistent: use the four categories for exam items, set isRetryable: true only for transient (and rate-limit after wait), and reason validation to false from the resend question.

Official versus community divergence: Additional divergence notes

Beyond the validation-boolean gap, two more divergences deserve a candidate's attention. The first is the industry-precedent framing. The reference page anchors isRetryable semantics in established conventions: gRPC treats INVALID_ARGUMENT as non-retryable, and AWS-style retry metadata marks client errors as not retryable while marking server errors and throttling as retryable. Our lessons reach the same conclusion from the resend question, and a candidate who knows the gRPC or AWS precedent has an independent check on the four-category model. Community material that asserts validation is retryable because the agent can recover is not merely incomplete, it contradicts both the documentation position and the broader industry convention.

The second divergence is vocabulary narrowing. Some community prep collapses auth and permission into one bucket, or omits rate-limit and not-found entirely, presenting only the four named categories. Our lessons keep them distinct, and the documentation position is that rate-limit is a transient variant that must carry a wait time, auth is a credential problem needing escalation, and not-found is an error distinct from a valid empty result. The candidate should answer exam items with the four-category framing but recognize the fuller taxonomy when a scenario clearly describes a rate limit, a missing credential, or a missing resource. Where community material uses the narrower vocabulary, the fuller documentation-aligned taxonomy is the safer answer.

A third, subtler divergence is field naming. Community snippets sometimes write errorCategory while others write category, and some write retryable while the reference page writes isRetryable. These are application-level key names with no protocol enforcement, so the exact identifier is a convention, not a correctness issue. The exam tests the concept (a category plus a retry boolean), not the literal key string, and a candidate should not be thrown by either spelling.

Beyond the task statement

The reference page covers the four categories, the isRetryable semantics, the access-failure versus empty-result split, and multi-agent propagation. Our lesson material covers substantially more that the exam can draw on and that a production architect must know. Each adjacent topic below names its lesson slug and why it matters for Task 2.2.

tool-result-handling (slug tool-result-handling) is the closest sibling. It adds the protocol ordering rules that produce a hard 400 if violated, the empty-result versus error-result table, the partial-result pattern (status: "partial" with both successes and errors), returning multiple tool results in a single user turn, result summarization and truncation to protect reasoning quality, the fromCache flag for cached results, streaming partial results, and PostToolUse hooks that normalize heterogeneous backend shapes before the model sees them. The hook point is directly relevant: a normalization hook must never silently drop error semantics, or it recreates the silent-failure anti-pattern.

tool-error-handling (slug tool-error-handling) extends the category model with exponential backoff and jitter, the tool-level-versus-caller-level retry decision, graceful degradation with per-section ok / degraded / unavailable status, fallback chains that try alternative sources with explicit source labelling, and multi-step rollback when a later step fails after earlier steps succeeded. Its three-layer error model (raw errors in code, structured errors in tool results, natural language in Claude's response) is the conceptual spine of this entire task. The anti-pattern list, generic messages, marking all errors retryable, swallowing exceptions, and retrying without backoff, is exactly what the reference page's exam traps target.

error-handling (slug error-handling) supplies the HTTP error reference that the exam tests as a parallel structure: 400 invalid_request_error (no retry, fix the request), 401 authentication_error (no retry), 402 billing_error (no retry), 403 permission_error (no retry), 404 not_found_error (no retry), 413 request_too_large (no retry, shrink), 429 rate_limit_error (retry with backoff, respect Retry-After), 500 api_error (retry with backoff), 504 timeout_error (retry with backoff). This is the API-level mirror of the tool-level category model, and the exam tests the error-to-action mapping for both. It also restates the silent-failure anti-pattern and the core access-failure versus empty-result distinction with a full table.

validation-pipelines (slug validation-pipelines) connects structured errors to output validation. Its retry-with-fix loop feeds validation errors back to Claude as a new user turn so Claude corrects the output rather than repeating it, and its five-stage pipeline (schema, format, semantic, cross-field, external) is the complementary discipline to tool error handling. The irrecoverable-failure handling (typed failure result, route to human review, track failure rates by category) is the escalation path the reference page's business and permission categories demand.

escalation-patterns (slug escalation-patterns) is where the "escalate to a human" and "escalate to a senior agent" recovery actions from the business and permission categories are specified in full: when to escalate, how to preserve context for the human, and how to honor customer preference. The reference page names escalation as the recovery for business and permission errors; this lesson is the mechanism.

retry-strategies (slug retry-strategies) deepens the backoff and fallback material: circuit breakers, jitter variants, and when to fail fast versus retry. The reference page's transient-retry guidance is the entry point; this lesson is the production-grade expansion.

Beyond the task statement: Further adjacent topics

Three more adjacent areas matter for Task 2.2 even though the reference page omits them. The first is prompt caching and tool schema stability. The Anthropic prompt-caching guidance shows that a stable tool definition, including a stable input_schema, lets the provider reuse a cached prefix across turns and cuts latency and cost. The same principle applies to a stable error envelope shape: when your tool_error-handling envelope uses consistent field names, the model's view of your tools stays cacheable across retries, whereas reshaping errors on every call defeats the cache. A candidate who designs one envelope shape and reuses it is applying caching discipline to error handling.

The second is the PreToolUse and PostToolUse hook pair that tool-result-handling introduces. PreToolUse hooks validate or block a call before execution (parameter checks, policy gates, business rules), and PostToolUse hooks normalize, transform, or enrich a result before the model sees it. The exam contrasts this with prompt-based guidance: prompts are probabilistic, hooks are enforced. For Task 2.2 the load-bearing rule is that a PostToolUse normalization hook must never convert a failed execution into a successful-looking empty result, because that recreates the silent-failure anti-pattern at the hook boundary rather than in the tool.

The third is context-size discipline under failure. A tool that returns a verbose raw exception, or a partial result that dumps every failed record in full, erodes reasoning quality just as a huge success result does. The result-size guidance applies to errors too: truncate or summarize error context, keep technicalDetail server-side, and surface only what the model needs to choose a recovery. Treating error payloads with the same size hygiene as success payloads is part of production readiness.

Worked production examples

The four examples below form one connected implementation: a customer lookup tool whose underlying database can fail in each of the four ways, wrapped by an agent loop that branches on the structured metadata. Each example carries a specific field set, a failure boundary it prevents, and an observable output.

Worked production examples: Example 1: the protocol tool_result block with is_error

This example shows the only layer the API validates. It is a JSON user message containing a tool_result block. Note that is_error is a block-level field, not inside content.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the customer database is not reachable (HTTP 500)",
      "is_error": true
    }
  ]
}

What it proves: the protocol failure signal is set. Claude reads is_error: true and treats the call as failed. The tool_use_id matches the assistant's tool_use block, so the conversation stays valid.

Failure boundary it prevents: if is_error were omitted, the block defaults to success and Claude would reason from the error text as if it were an answer. That is the silent-failure anti-pattern at the protocol level.

Observable output: Claude responds with recovery reasoning, for example "The customer lookup failed because the database was unreachable. I will retry shortly or fall back to a cached record."

The incorrect sibling, which the exam treats as a trap, is a success block whose content describes an error:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: database unreachable"
    }
  ]
}

Here is_error is absent (defaults false). Claude sees a successful-but-confusing result and may report "the customer database is unreachable" as if it were a found value. The distinction between these two blocks is the protocol-level version of the access-failure versus empty-result split.

Worked production examples: Example 2: the structured error envelope

This example adds the application-layer convention inside content. The ToolError interface is the envelope; the function builds it and the caller serializes it into the tool_result block with is_error: true.

interface ToolError {
  isError: true
  errorCategory: "transient" | "validation" | "business" | "permission" | "rate-limit" | "auth" | "not-found" | "permanent"
  isRetryable: boolean
  message: string
  description?: string
  context?: {
    resource?: string
    input?: unknown
    attemptNumber?: number
    suggestion?: string
  }
}

function buildValidationError(badId: string): ToolError {
  return {
    isError: true,
    errorCategory: "validation",
    isRetryable: false,
    message: `Invalid order ID format: "${badId}".`,
    description: "Order ID must be in format #NNNNN (e.g. #12345). Received 'order-abc'. Reformat the ID and call again.",
    context: {
      input: { orderId: badId },
      suggestion: "Use the canonical #NNNNN format before retrying."
    }
  }
}

The wire format pairs the envelope with the block flag:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01b2c3d4e5",
  "is_error": true,
  "content": "{\"isError\":true,\"errorCategory\":\"validation\",\"isRetryable\":false,\"message\":\"Invalid order ID format: \\\"order-abc\\\".\",\"description\":\"Order ID must be in format #NNNNN (e.g. #12345). Received 'order-abc'. Reformat the ID and call again.\"}"
}

What it proves: the category, retryability, and recovery hint travel together. isRetryable: false plus errorCategory: "validation" tells the agent it must fix the input, never resend. The description and context.suggestion tell it exactly how.

Failure boundary it prevents: a generic "Operation failed" string leaves the agent unable to distinguish a transient timeout from a policy violation, so it cannot choose a recovery. The envelope removes that ambiguity.

Observable output: Claude reformats the ID and issues a corrected call, or explains to the user why the ID was rejected.

Worked production examples: Example 3: retry with exponential backoff and jitter

This example implements the retry wrapper that owns transient recovery. It is the tool-level retry the lessons recommend for fast infrastructure errors (1 to 3 attempts, sub-second), distinct from asking Claude to retry.

interface RetryConfig {
  maxAttempts: number
  baseDelayMs: number
  maxDelayMs: number
  useJitter: boolean
}

const DEFAULT_RETRY: RetryConfig = {
  maxAttempts: 4,
  baseDelayMs: 200,
  maxDelayMs: 10_000,
  useJitter: true
}

function getBackoffDelay(attempt: number, config: RetryConfig): number {
  const exponential = config.baseDelayMs * Math.pow(2, attempt - 1)
  const capped = Math.min(exponential, config.maxDelayMs)
  if (!config.useJitter) return capped
  return Math.random() * capped
}

async function withRetry<T>(
  fn: () => Promise<T>,
  shouldRetry: (error: unknown) => boolean,
  config: RetryConfig = DEFAULT_RETRY
): Promise<T> {
  let lastError: unknown
  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
    try {
      return await fn()
    } catch (error) {
      lastError = error
      if (!shouldRetry(error) || attempt === config.maxAttempts) break
      await new Promise(r => setTimeout(r, getBackoffDelay(attempt, config)))
    }
  }
  throw lastError
}

async function fetchCustomerWithRetry(customerId: string) {
  return withRetry(
    () => db.queryCustomer(customerId),
    (error) => error instanceof TransientError,
    { maxAttempts: 3, baseDelayMs: 200, maxDelayMs: 2000, useJitter: true }
  )
}

What it proves: transient errors retry with growing, jittered delays (200ms, 400ms, 800ms, capped at 2s here), avoiding the thundering-herd problem when many parallel calls fail at once. shouldRetry restricts retries to TransientError only; validation, business, and permission errors throw immediately and become structured errors for Claude.

Failure boundary it prevents: immediate retries on rate-limited or overloaded services compound the problem, and retrying non-transient errors wastes quota and delays failure detection. The wrapper encodes the rule "only transient is retryable."

Observable output: a transient blip is absorbed silently and the caller receives the result; a persistent transient after 3 attempts throws and becomes an is_error: true block with errorCategory: "transient", isRetryable: true.

Worked production examples: Example 4: validation and propagation in a multi-agent search

This example combines input validation (Zod) with the multi-agent propagation rule. A search subagent validates its upstream response, returns partial results on mixed success, and propagates only unrecoverable failures to the coordinator.

import { z } from "zod"

const SearchResultSchema = z.object({
  items: z.array(z.object({
    id: z.string(),
    title: z.string(),
    score: z.number().min(0).max(100)
  })),
  totalMatches: z.number().nonnegative(),
  hasMore: z.boolean()
})

type SubagentReport =
  | { status: "ok"; items: unknown[]; searchedSources: number }
  | { status: "partial"; items: unknown[]; searchedSources: number; failedSources: string[] }
  | { status: "error"; errorCategory: string; isRetryable: boolean; message: string }

async function searchSubagent(query: string, sources: string[]): Promise<SubagentReport> {
  const settled = await Promise.allSettled(sources.map(s => upstreamSearch(s, query)))
  const items: unknown[] = []
  const failedSources: string[] = []
  for (let i = 0; i < settled.length; i++) {
    const r = settled[i]
    if (r.status === "fulfilled") {
      const parsed = SearchResultSchema.safeParse(r.value)
      if (parsed.success) items.push(...parsed.data.items)
      else failedSources.push(`${sources[i]}: schema-invalid`)
    } else {
      failedSources.push(`${sources[i]}: ${r.reason?.message ?? "unreachable"}`)
    }
  }
  if (items.length === 0 && failedSources.length === sources.length) {
    return { status: "error", errorCategory: "transient", isRetryable: true, message: `All ${sources.length} sources failed.` }
  }
  if (failedSources.length === 0) return { status: "ok", items, searchedSources: sources.length }
  return { status: "partial", items, searchedSources: sources.length - failedSources.length, failedSources }
}

What it proves: local recovery happens first (each source retried by upstreamSearch internally), partial results are returned when some sources succeed, and only a total failure propagates as an error. The coordinator receives either ok, partial with the failed-source list, or error with category and retryability. This is exactly the reference page's "I searched 3 of 5 sources successfully" pattern.

Failure boundary it prevents: returning empty as success hides the partial failure and leaves the coordinator blind; terminating the whole workflow on one failed source throws away the 3 good results. The partial status avoids both.

Observable output: the coordinator reports "found 12 matches from 3 of 5 sources; sources 4 and 5 timed out" and can decide whether to retry the two failed sources or proceed with partial data.

Worked production examples: The agent loop that consumes the metadata

The four examples converge in the loop that reads the envelope and branches. This is the practical outcome the reference page's build exercise targets.

async function runAgentTurn(toolCall: ToolCall): Promise<void> {
  const result = await executeTool(toolCall)
  if (!result.isError) {
    if (isEmptyResult(result)) {
      await tellUser("No results found for that query.")
    } else {
      await continueReasoning(result.content)
    }
    return
  }
  switch (result.errorCategory) {
    case "transient":
    case "rate-limit":
      await retryWithBackoff(toolCall, result)
      break
    case "validation":
      await fixInputAndRetry(toolCall, result.context?.suggestion)
      break
    case "business":
    case "permission":
      await escalateToHuman(result)
      break
    default:
      await escalateToHuman(result)
  }
}

What it proves: the branch on errorCategory is the decision logic the exam expects. Transient retries with backoff; validation fixes input; business and permission escalate. The isError: false plus empty check at the top is the access-failure versus valid-empty-result guard.

Worked production examples: Example 5: multi-agent propagation with partial results and local absorption

This example completes the multi-agent story from Example 4. A coordinator dispatches two search subagents, each of which performs local recovery for transient blips, then reports either ok, partial, or error. The coordinator merges the partial results, suppresses nothing, and propagates only a genuinely unrecoverable failure upward as an is_error: true tool_result block (because the coordinator is itself exposed to the model as a tool). The idempotency key protects any mutating call a subagent makes during recovery.

type SubagentReport =
  | { status: "ok"; items: unknown[]; searchedSources: number }
  | { status: "partial"; items: unknown[]; searchedSources: number; failedSources: string[] }
  | { status: "error"; errorCategory: string; isRetryable: boolean; message: string; attemptedSources: string[] }

async function runSubagent(label: string, sources: string[], idempotencyKey: string): Promise<SubagentReport> {
  const settled = await Promise.allSettled(sources.map(s => upstreamSearch(s, idempotencyKey)))
  const items: unknown[] = []
  const failedSources: string[] = []
  for (let i = 0; i < settled.length; i++) {
    const r = settled[i]
    if (r.status === "fulfilled") items.push(...r.value.items)
    else failedSources.push(`${sources[i]}: ${r.reason?.message ?? "unreachable"}`)
  }
  if (failedSources.length === 0) return { status: "ok", items, searchedSources: sources.length }
  if (items.length > 0) return { status: "partial", items, searchedSources: sources.length - failedSources.length, failedSources }
  return { status: "error", errorCategory: "transient", isRetryable: true, message: `Subagent ${label} failed on all sources.`, attemptedSources: sources }
}

async function coordinateSearch(query: string): Promise<object> {
  const key = crypto.randomUUID()
  const [a, b] = await Promise.all([
    runSubagent("alpha", ["s1", "s2", "s3"], key),
    runSubagent("beta", ["s4", "s5"], key)
  ])
  if (a.status === "error" && b.status === "error") {
    return {
      isError: true,
      errorCategory: "transient",
      isRetryable: true,
      message: "Both search subagents failed on every source.",
      context: { attemptedSources: [...a.attemptedSources, ...b.attemptedSources] }
    }
  }
  const merged = [
    ...(a.status !== "error" ? a.items : []),
    ...(b.status !== "error" ? b.items : [])
  ]
  const failed = [
    ...(a.status === "partial" ? a.failedSources : []),
    ...(b.status === "partial" ? b.failedSources : [])
  ]
  return {
    status: failed.length === 0 ? "ok" : "partial",
    items: merged,
    failedSources: failed,
    summary: `Merged ${merged.length} results from subagents; ${failed.length} sources still failed.`
  }
}