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.
| Approach | When to use it | Your responsibility |
|---|---|---|
| User-defined client tools | Custom business logic, internal APIs, proprietary data | Run the tool and drive the agentic loop |
| Anthropic-schema client tools | bash, file editing, desktop and browser control | Run the tool; Claude calls it reliably because the schema is trained-in |
| Server-executed tools | Web search, code sandbox, web fetch | Enable 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.
What matters is where the code runs. Both kinds of client tool run in your application, so you return a tool_result for each; with an Anthropic-schema tool, only the schema comes from Anthropic. Server tools run on Anthropic's side, so you only enable them and read the result.
“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.”Source: platform.claude.com
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.
{
"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?
The description has more effect on tool performance than anything else. Saying when to use the tool, and what it does not return, tells Claude to look elsewhere for earnings questions. Examples and enum constraints only shape how a valid call looks, not when to make one. A parameter that asks for step-by-step reasoning can trigger a reasoning_extraction refusal.
“Any important caveats or limitations, such as what information the tool does not return”Source: platform.claude.com
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.
| tool_choice type | Must Claude call a tool? | Who picks the tool |
|---|---|---|
| auto | No; Claude decides (default when tools are provided) | Claude |
| any | Yes, one of the provided tools | Claude |
| tool | Yes | You, by name |
| none | No; 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?
On models such as Claude Sonnet 5.5, both any and tool return a 400, so naming the tool does not help. Manual extended thinking also rejects forced tool use. The supported replacement is auto with strict tool use, which still guarantees schema-valid inputs. Parsing the fields out of prose is the regex warning sign from earlier in the lesson.
“auto with strict tool use to guarantee schema-valid tool inputs”Source: platform.claude.com
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?
Correct answer: C — any
- A.
autolets Claude decide whether to call a tool at all, so it may answer with plain text. That does not guarantee a call. - B.
noneprevents Claude from using any tool, which is the opposite of requiring a call. - C.
anyrequires Claude to use one of the provided tools but lets it pick which. It guarantees a call without naming a tool. - D.
toolforces one specific named tool, so Claude does not choose between tools. The stem asks for Claude to pick which.
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.
{
"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" /* ... */ }
]
}A tool_result block names its call in tool_use_id, and the value must match the id of the tool_use block. That field is how the API pairs each result with its call, including when several parallel results go back in one user message. The tool_use block itself uses id, but the result block does not.
Source: platform.claude.comCheckpoint 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?
Correct answer: C — Send one user message with three tool_result blocks, each carrying its matching tool_use_id, placed before any added text.
- A. Splitting results across messages breaks the required pairing, because every
tool_usemust be answered in the next user message. The API would reject the conversation shape. - B. Parallel tool calls are supported, and discarding two requests leaves unanswered
tool_useblocks. That produces an error and loses the data Claude asked for. - C. All results for one assistant turn go back together in a single user message, each matched by
tool_use_id. Any text belongs after thetool_resultblocks. - D. Tool results are sent in a user message, not an assistant message, and they are matched by id for client tools. Keying by tool name would fail with duplicate tools.
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.
{
"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
}
]
}For a client tool that fails while running, you still return a tool_result. You put the error message in content and set is_error: true, and Claude works the failure into its reply. stop_reason is a field Claude's response carries, not one you set in a tool_result. This applies only to client tools, because server tools handle their own errors.
Source: platform.claude.com6.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?
Claude needs a readable name to choose between matches and the stable id to pass into the next call. The other columns are bloat that wastes context, while a name alone leaves Claude unable to call send_message.
“include only the fields Claude needs to reason about its next step”Source: platform.claude.com
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?
Claude only sends a structured request, and a client tool runs only when your code runs it. That lets you gate the side-effecting refund, while the read-only lookups usually don't need a gate. If the user declines, a tool_result saying so lets Claude change course instead of stalling. Server tools run without your involvement, so you can't put an approval step in front of them.
“It emits a structured request, your code (or Anthropic’s servers) runs the operation”Source: platform.claude.com
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.
| Approach | What it reduces | When it fits |
|---|---|---|
| Tool search | Tool definitions loaded upfront | Many tools (10+), most of which aren't needed every turn |
| Programmatic tool calling | tool_result roundtrips | Chains of tool calls that can run as a single script |
| Prompt caching | Token cost of repeated tool definitions | Stable tool definitions across many requests |
| Context editing | Old tool_result blocks in history | Long 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.
Each fix works on a different source of context use. Tool search cuts the definitions loaded at the start. Programmatic tool calling cuts tool_result round trips. Prompt caching lowers what repeated definitions cost but leaves them in context. Context editing removes stale results from the history.
“Prompt caching doesn’t reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”Source: platform.claude.com
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?
Correct answer: D — Defer loading of most definitions and enable the tool search tool, so Claude loads only the few tools the task needs.
- A.
max_tokenslimits output length and does not shrink the input taken by tool definitions. Extra reasoning room does not make 220 overlapping tools easier to choose between. - B.
tool_choiceanyforces a call but does not help choose the right one, and it removes the option to answer without a tool. Definitions still fill the context. - C. A single dispatcher with a giant description keeps all the same tokens in context and removes the structured schemas that guide arguments. Selection quality would get worse.
- D. Tool search keeps the full catalogue out of context and loads definitions on demand. This cuts token cost and narrows the choices Claude sees, improving selection accuracy.
Sources
(9)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 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.
“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.
“Safety classifiers return this stop reason as a normal HTTP 200 response, not an error.”
↩︎ A schema and description that drive correct calls - 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.
“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.
“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.https://www.anthropic.com/engineering/writing-tools-for-agentsSecondary source
“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.https://code.claude.com/docs/en/agent-sdk/user-inputOfficial docs
“Deny: tool doesn't execute, Claude sees the message”
↩︎ Approval before side effects
Also cited
“Tool search keeps tool definitions out of the context window until Claude asks for them.”
↩︎ Exam trap 3“Prompt caching doesn’t reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”
↩︎ Checkpoint