Source: Anthropic Tool Use Docs
Claude API documentation on tool use: client vs server tools, tool definitions, tool_choice, parallel tool calls and token overhead.
Contents
- What: official API documentation (Tool use overview, Define tools, Parallel tool use pages)
- Author/publisher: Anthropic
- Date: living documents; read 2026-11-14
- Original: Tool use with Claude
Related pages: Define tools · Parallel tool use
Summary
Claude’s tool use is a request/response protocol: tools are declared with a name, description and JSON Schema input_schema; the model replies with stop_reason: "tool_use" and one or more tool_use blocks; the client runs them and returns tool_result blocks keyed by tool_use_id. Server tools (web search, web fetch, code execution, tool search) run on Anthropic’s side. The pages cover tool_choice, forced tool restrictions, parallel-call formatting rules, input examples and the hidden tool system prompt.
Key claims
- Tool names must match
^[a-zA-Z0-9_-]{1,128}$. Optional fields includeinput_examples,cache_control,strict,defer_loading. - The API builds a special system prompt from the tool definitions; this costs roughly 286–804 extra input tokens depending on model and
tool_choice(e.g. 286 on Opus 5.5 / Sonnet 5.5; 675 withauto/noneand 804 withany/toolon Opus 4.7). - Descriptions are the most important factor in tool performance; aim for at least 3–4 sentences. Consolidate related operations; namespace tool names by service.
tool_choice:auto(default with tools),any,tool(named),none.any/toolprefill the assistant turn, so no prose precedes the call and thinking is skipped; they are rejected with manual extended thinking and on Opus 5.5 / Sonnet 5.5 (useauto+ strict tools or structured outputs instead).- Changing
tool_choiceinvalidates cached message blocks. - Parallel calls are on by default. Return all
tool_resultblocks in one user message, before any text; splitting them across messages “teaches” the model to stop parallelising. Disable viadisable_parallel_tool_useinsidetool_choice(at most one call withauto, exactly one withany/tool). - Execution order of parallel calls is the client’s choice; skipped or failed calls still get a
tool_resultwithis_error: true. - When required parameters are missing, Opus is more likely to ask for them, while Sonnet may infer a plausible value (e.g. guess a location).
input_examplesmust validate against the schema and cost roughly 20–200 tokens each.- With
strict: true, tool inputs are grammar-constrained to the schema.