CertSafari
    Anthropic Claude Certified Developer – Foundations (CCDV-F) - December 7 onwards· Lessons

    Domain 8 · Lesson 22/24

    Tool design: schemas, results, errors and tool sets

    Tool Design and Response Shaping

    21 min read
    3.33% of exam
    9 sources
    Published 18 Nov 2026
    Docs as of 11 Nov 2026

    What you will be able to do

    • Write a tool definition whose name, description and input_schema lead Claude to call it correctly
    • Choose the right tool_choice mode and decide whether a tool runs client-side or server-side
    • Return tool results correctly, including parallel results and errors marked with is_error
    • Shape tool responses so they are minimal, high-signal and actionable
    • Add an approval step for actions with side effects and keep a large tool set accurate with tool search and defer_loading

    Key concept

    Tool as a contract — A tool is a typed interface between your application and Claude. Claude sees only the schema and description you provide and the result you send back. It decides when to call the tool, and something outside the model runs it. Every design choice changes what Claude can see or what it gets back.

    1.Where a tool runs decides what you build

    Tools differ most in where their code runs. Claude never executes anything itself. It emits a structured request, and then either your application or Anthropic's servers carry it out. That location determines your application's job. With a user-defined client tool, you write the schema, run the operation (a database query, an HTTP call, a file write) and send the output back in a tool_result block on the next request. Most tool-use traffic is this kind: custom tools that call into application-specific logic.

    Anthropic-schema client tools (memory, bash, text_editor, computer, browser) still run in your code, but Anthropic publishes their schemas. Claude was trained on thousands of trajectories that use those exact signatures, so it calls them more reliably than a home-made equivalent and recovers from errors more gracefully. If you need shell or file-editing access, use the trained-in schema instead of writing your own. Server tools (web_search, web_fetch, code_execution, tool_search) run on Anthropic's side. You enable them, you never build a tool_result for them, and you read the answer that comes back. A server loop can hit its iteration cap and return stop_reason: "pause_turn". When that happens, re-send the conversation so Claude can continue.

    Three execution buckets and what each one asks of your application
    ApproachWhen to use itYour responsibility
    User-defined client toolsCustom business logic, internal APIs, proprietary dataRun the tool and drive the agentic loop
    Anthropic-schema client toolsbash, file editing, desktop and browser controlRun the tool; Claude calls it reliably because the schema is trained-in
    Server-executed toolsWeb search, code sandbox, web fetchEnable it and read the results; Anthropic runs it

    A tool is the right choice when the task needs something text alone can't provide: a side effect such as sending an email, fresh external data, a guaranteed output shape, or a call into an existing system. If you find yourself writing a regex to pull a decision out of Claude's prose, that decision should have been a tool call. Summarization, translation and one-shot Q&A don't need a tool round trip. The loop that drives client tools (keep going while stop_reason is tool_use) is covered in Messages API mechanics.

    Checkpoint 1 of 11· Match them up

    Match each kind of tool to what your application has to do when Claude calls it.

    Tap a term, then the definition that fits it.

    Sources1

    2.A schema and description that drive correct calls

    A user-defined tool has three required fields. name must match ^[a-zA-Z0-9_-]{1,128}$. description is plain text explaining what the tool does, when to use it and how it behaves. input_schema is a JSON Schema object for the parameters. Claude sees the schema, so constraints such as enum and required tell it what a valid call looks like.

    A complete tool definition: one required string and an optional unit restricted by enumjson
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
          }
        },
        "required": ["location"]
      }
    }

    The description matters more than any other factor in tool performance. Aim for at least three or four sentences that cover what the tool does, when to use it and when not to, what each parameter means, and what the tool does not return. Compare two descriptions for the same tool. "Gets the stock price for a ticker." leaves Claude guessing. The better version says the ticker must belong to a company on NYSE or NASDAQ, that the tool returns the latest trade price in USD, when to use it, and that it provides no other information about the company. The second version tells Claude both when to call the tool and when to look elsewhere.

    For tools with nested objects or format-sensitive parameters, an optional input_examples array shows Claude what well-formed calls look like. Each example must validate against input_schema, and an invalid one returns a 400. Examples add roughly 20–50 prompt tokens for a simple case and 100–200 for a complex nested one. They work on user-defined and Anthropic-schema client tools, but not on server tools. If a parameter asks Claude why it is making the call, ask for a short explanation or the supporting evidence. A parameter that asks for the model's thinking or step-by-step reasoning can trigger a reasoning_extraction refusal. A refusal is not an API error: it comes back as a normal HTTP 200 response with stop_reason: "refusal" and no usable answer, so your tool-call loop ends instead of continuing. Reasoning belongs in thinking blocks, not in a tool parameter, so keep parameters to short explanations or evidence.

    Checkpoint 2 of 11· Check yourself

    An agent has a get_stock_price tool whose description reads only "Gets the stock price for a ticker." Users ask about a company's earnings, and Claude keeps calling this tool to answer them. Which change targets the cause most directly?

    Sources23

    3.Controlling whether Claude calls a tool

    tool_choice has four modes, and they differ in two ways: whether a tool call is required, and who picks the tool. The easy mistake is to treat any and tool as the same thing. Both force a call. Only tool also fixes which tool gets called.

    The four tool_choice modes
    tool_choice typeMust Claude call a tool?Who picks the tool
    autoNo; Claude decides (default when tools are provided)Claude
    anyYes, one of the provided toolsClaude
    toolYesYou, by name
    noneNo; tools are blocked (default when no tools are provided)Nobody

    Forcing a call doesn't work everywhere. With manual extended thinking (thinking: {type: "enabled"}), any and tool return an error, and models including Claude Opus 5.5 and Claude Sonnet 5.5 return a 400 for both modes. On those models, use auto with strict tool use when you need schema-valid inputs. Strict tool use is an optional strict property on a tool definition. It puts the API into strict mode, where a grammar built from your tool schemas constrains what Claude emits as tool-call output, so the input of a call always matches the input_schema you declared. It guarantees the shape of the arguments, not that Claude calls the tool: with auto, prompting and descriptions still influence which tool Claude picks.

    Checkpoint 3 of 11· Check yourself

    A pipeline on Claude Sonnet 5.5 sends tool_choice {"type": "any"} so that Claude always calls an extraction tool with valid arguments, and every request comes back with a 400. What should the request use instead?

    Checkpoint 4 of 11· Exam question

    Which tool_choice setting makes Claude call one of the supplied tools in its next turn, while leaving the choice of which tool to Claude?

    Sources24

    4.Returning results, including parallel calls

    A client-tool call arrives as a response with stop_reason: "tool_use" and one or more tool_use blocks. Each block carries an id, the tool name, and an input object that conforms to the schema. Your reply is a user-role message containing a tool_result block. Its tool_use_id must match that id, and its content can be a string or a list of text, image, document or search_result blocks.

    When Claude emits several tool_use blocks at once, for example three independent weather lookups, run all of them and return every result in one user message, each with its own tool_use_id. Sending a separate user message per result is the most common formatting mistake. It also teaches Claude to stop making parallel calls. Inside that message, the tool_result blocks come first. Text placed before them is rejected, while text after them is allowed. Results never go in an assistant message, and tool_use_id is how the API pairs each result with its call, for every client tool.

    This user message is rejected with a 400 because text comes before the tool_resultjson
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
        { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
      ]
    }

    Checkpoint 5 of 11· Fill the gap

    The documentation uses this user message as an example of one the API rejects with a 400, because text comes before the tool_result. Even after you fix that, the result still has to be linked to the call Claude made. Which field name fills the blank?

    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
        { "type": "tool_result", " ? ": "toolu_01" /* ... */ }
      ]
    }

    Checkpoint 6 of 11· Exam question

    Claude responds with stop_reason of tool_use and three tool_use blocks (ids toolu_01, toolu_02, toolu_03) for three independent weather lookups. How should the application send the results back?

    Sources56

    5.Errors Claude can act on

    A tool that fails while running should still return a result. Put the error message in content and set is_error: true. Claude then works the failure into its reply, for example telling the user the weather service is down and suggesting they try later. An unhandled failure leaves Claude with nothing to work with. A message that names the cause gives it something to act on.

    An execution failure reported back with is_errorjson
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
          "content": "ConnectionError: the weather service API is not available (HTTP 500)",
          "is_error": true
        }
      ]
    }

    An invalid call, such as one missing a required parameter, is a different failure. It usually means Claude lacked the information to use the tool correctly. At runtime you can return "Error: Missing required 'location' parameter" with is_error: true, and Claude retries 2–3 times with corrections before apologizing to the user. During development, though, a pattern of these errors means the description needs more detail. Tool-call metrics point the same way: many invalid-parameter errors suggest clearer descriptions or better examples. Server tools handle their own errors, so you never handle is_error for them.

    Checkpoint 7 of 11· Fill the gap

    Your weather tool's HTTP call fails with a 500. You still want to send a result so Claude can tell the user the service is down and suggest trying later. Which field marks this tool_result as a failure?

    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
          "content": "ConnectionError: the weather service API is not available (HTTP 500)",
          " ? ": true
        }
      ]
    }

    Sources57

    6.Shaping responses to be minimal and actionable

    Every byte a tool returns ends up in Claude's context, so return only the fields Claude needs for its next step. Bloated responses waste context and bury the useful part. Return semantic, stable identifiers such as slugs or UUIDs instead of opaque internal references, because Claude has to pass those identifiers into the next call. For example, search_user returns an id that send_message then needs.

    Sometimes Claude needs only content and sometimes it needs ids too. A response_format enum parameter with concise and detailed values lets Claude choose. In a Slack example, the detailed response includes thread_ts, channel_id and user_id so Claude can make follow-up calls. The concise response returns only the thread content and uses about a third of the tokens. Even the structure of a response (XML, JSON or Markdown) can affect results, and no single format wins everywhere, so measure it.

    Checkpoint 8 of 11· Check yourself

    A search_user tool currently returns the full 40-column database row for each match. On its next step, Claude passes the chosen user to send_message. How should you reshape what search_user returns?

    Sources27

    7.Approval before side effects

    A client tool runs only when your code runs it, so you can put an approval step between Claude's request and the action. Claude emits a structured request, and your application decides whether to carry it out. This matters most for tools with side effects, such as sending email, writing files or updating records, where a wrong call can't be undone. Read-only lookups usually don't need the step.

    In the Agent SDK, a canUseTool callback shows the user the tool name and input and asks "Allow this action?". It returns behavior: "allow" with the input, which can be modified, or behavior: "deny" with a message. When the call is denied, the tool doesn't run and Claude reads the message, so it can change course instead of stalling. Without the SDK, the same pattern is to return a tool_result that says the user declined, so the conversation can continue. Permission modes and hooks are covered in Agent SDK hooks, and restricting what a tool can do at all is covered in least privilege.

    Checkpoint 9 of 11· Check yourself

    A support agent has three client tools: lookup_order, search_faq and issue_refund. You want a person to confirm before anything irreversible happens, and you are not using the Agent SDK. Which design fits?

    Sources18

    8.Assembling a tool set that stays accurate

    Tool count has a cost of its own. Claude's ability to pick the right tool drops once more than 30–50 are available. A typical setup connected to GitHub, Slack, Sentry, Grafana and Splunk can spend about 55k tokens on definitions before doing any work. Start by trimming the surface. Group related operations into one tool with an action parameter: one tool instead of create_pr, review_pr and merge_pr. Then prefix names with their service, as in github_list_prs and slack_send_message, so tools from different services don't collide. Grouping by action keeps a typed schema. Collapsing every tool into one free-text command does not, and it brings back the ambiguity you were trying to remove.

    Beyond about ten tools, add the tool search tool. It comes in two variants: tool_search_tool_regex_20251119 and tool_search_tool_bm25_20251119. Mark the rest with defer_loading: true. You still send every full definition on every request, but deferred tools stay out of context until a search matches them by name, description or argument names. The API returns up to 5 by default as tool_reference blocks and expands them into full definitions. Never defer the search tool itself, and keep your 3–5 most-used tools loaded so Claude can call them without searching first. The other fixes don't help here. Raising max_tokens adds output room, not input room. Setting tool_choice to any forces a call but does nothing to improve which tool Claude picks.

    Matching the context fix to where the tokens go
    ApproachWhat it reducesWhen it fits
    Tool searchTool definitions loaded upfrontMany tools (10+), most of which aren't needed every turn
    Programmatic tool callingtool_result roundtripsChains of tool calls that can run as a single script
    Prompt cachingToken cost of repeated tool definitionsStable tool definitions across many requests
    Context editingOld tool_result blocks in historyLong conversations where early results are no longer relevant

    Checkpoint 10 of 11· Match them up

    Each agent below is running short on context for a different reason. Match each fix to the agent it helps.

    Tap a term, then the definition that fits it.

    Checkpoint 11 of 11· Exam question

    An agent connects to eight MCP servers that together expose about 220 tool definitions. The definitions consume a large share of the context window before the user says anything, and Claude increasingly picks the wrong tool. What is the best change?

    Sources24

    Sources

    (9)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “The primary axis along which tools differ is where the code runs.”
      ↩︎ Where a tool runs decides what you build
      “You never construct a tool_result block for these tools.”
      ↩︎ Where a tool runs decides what you build
      “The reason to use an Anthropic-schema tool instead of defining your own equivalent is that these schemas are trained-in.”
      ↩︎ Where a tool runs decides what you build
      “The model never runs anything on its own.”
      ↩︎ Approval before side effects
      “Claude never receives your implementation; it only receives the schema you provided and the result you returned.”
      ↩︎ Key concept
      “For web_search, web_fetch, code_execution, and tool_search, Anthropic runs the code. You enable the tool in your request and the server handles everything else.”
      ↩︎ Checkpoint
      “It emits a structured request, your code (or Anthropic’s servers) runs the operation”
      ↩︎ Checkpoint
    2. 2.
      “Provide extremely detailed descriptions. This is by far the most important factor in tool performance.”
      ↩︎ A schema and description that drive correct calls
      “Aim for at least 3–4 sentences for each tool description, more if the tool is complex.”
      ↩︎ A schema and description that drive correct calls
      “Invalid examples return a 400 error.”
      ↩︎ A schema and description that drive correct calls
      “A parameter that asks for the model’s thinking or step-by-step reasoning might lead to a reasoning_extraction refusal.”
      ↩︎ A schema and description that drive correct calls
      “tool forces Claude to always use a particular tool.”
      ↩︎ Controlling whether Claude calls a tool
      “none prevents Claude from using any tools. This is the default value when no tools are provided.”
      ↩︎ Controlling whether Claude calls a tool
      “Return semantic, stable identifiers (for example, slugs or UUIDs) rather than opaque internal references”
      ↩︎ Shaping responses to be minimal and actionable
      “include only the fields Claude needs to reason about its next step”
      ↩︎ Shaping responses to be minimal and actionable
      “Rather than creating a separate tool for every action (create_pr, review_pr, merge_pr), group them into a single tool with an action parameter.”
      ↩︎ Assembling a tool set that stays accurate
      “tool forces Claude to always use a particular tool.”
      ↩︎ Exam trap 1
      “Any important caveats or limitations, such as what information the tool does not return”
      ↩︎ Checkpoint
      “auto with strict tool use to guarantee schema-valid tool inputs”
      ↩︎ Checkpoint
    3. 3.
      “Safety classifiers return this stop reason as a normal HTTP 200 response, not an error.”
      ↩︎ A schema and description that drive correct calls
    4. 4.
      “The grammar for strict mode (the rules that constrain tool-call output to match your schemas)”
      ↩︎ Controlling whether Claude calls a tool
      “Never set defer_loading: true on the tool search tool itself.”
      ↩︎ Assembling a tool set that stays accurate
      “Keep your 3–5 most frequently used tools non-deferred so Claude can call them without searching first.”
      ↩︎ Assembling a tool set that stays accurate
      “Tool search typically reduces this by over 85 percent, loading only the 3–5 tools Claude needs for a given request.”
      ↩︎ Prediction
    5. 5.
      “id: A unique identifier for this particular tool use block. This is used to match up the tool results later.”
      ↩︎ Returning results, including parallel calls
      “If a tool request is invalid or missing parameters, Claude will retry 2–3 times with corrections before apologizing to the user.”
      ↩︎ Errors Claude can act on
      “The best approach during development is to try the request again with more-detailed description values in your tool definitions.”
      ↩︎ Errors Claude can act on
      “Unlike client tools, you do not need to handle is_error results for server tools.”
      ↩︎ Exam trap 4
    6. 6.
      “Correct: all tool results together in a single user message”
      ↩︎ Returning results, including parallel calls
      “Wrong: a separate user message for each tool result”
      ↩︎ Returning results, including parallel calls
      “Correct: all tool results together in a single user message”
      ↩︎ Exam trap 2
    7. 7.
      “lots of tool errors for invalid parameters might suggest tools could use clearer descriptions or better examples”
      ↩︎ Errors Claude can act on
      “exposing a simple response_format enum parameter in your tool”
      ↩︎ Shaping responses to be minimal and actionable
    8. 8.
      “Deny: tool doesn't execute, Claude sees the message”
      ↩︎ Approval before side effects

    Also cited

    Ready to test yourself?

    Practise Anthropic Claude Certified Developer – Foundations (CCDV-F) - December 7 onwards in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.