Claude’s tool use API lets you give the model a set of callable functions — web search, database queries, code execution, API calls — and have it decide when to call them, with what arguments, and how to use the results to complete a task. It is the foundational mechanism for building agents with Anthropic’s models: every tool-use agent, regardless of the framework it uses, ultimately sends tool definitions to Claude and receives tool-call requests in return. Understanding the raw API mechanics — what you send, what you receive, and how the multi-turn loop works — gives you precise control that framework abstractions sometimes obscure.
How Tool Use Works at the API Level
Tool use in Anthropic’s API is a structured conversation protocol. You send a message with two additions beyond a standard prompt: a tools array defining the callable functions, and (optionally) a tool_choice parameter controlling whether the model must use a tool, can choose freely, or must use a specific one. Claude examines the tools, decides whether calling one is appropriate, and returns either a standard text response or a tool_use content block requesting a specific tool call with arguments. You execute that tool call in your code, then send the result back to Claude in the next turn as a tool_result content block. Claude uses the result to continue its reasoning and either calls another tool or produces a final response. This loop repeats until Claude produces a text response without a tool call — the signal that the task is complete.
Defining Tools
Each tool definition requires three fields: name (a unique identifier), description (natural language explanation of what the tool does and when to use it — this is what Claude reads to decide whether to call the tool), and input_schema (a JSON Schema object defining the parameters the tool accepts). The description is the most important part: a vague description causes the model to call the tool at wrong times or not at all when it should. A good description is specific about the tool’s purpose, its limitations, and the cases where it should and should not be used. The input schema uses standard JSON Schema types and can include required fields, optional fields, enums, nested objects, and descriptions for each parameter — all of which the model uses when constructing its tool call arguments.
The Multi-Turn Loop
A complete tool-use interaction typically requires multiple API calls. The first call sends the user’s request with tool definitions and receives either a final answer or a tool-call request. If a tool call is requested, you execute it and send the result back in a second API call — the conversation history now includes the user message, Claude’s tool-call response, and your tool result. Claude then either calls another tool or produces its final answer. Each tool call adds two entries to the conversation history (the tool use and the tool result), so long tool-use chains accumulate context quickly. The loop terminates when Claude’s response contains no tool_use blocks — only text. Implementing a maximum iteration count (typically 10–20 steps) prevents infinite loops if Claude gets stuck repeatedly calling tools without progress.
Figure 1 — Anthropic tool use: the multi-turn API loop
Parallel Tool Use
Claude can request multiple tool calls in a single response — a feature called parallel tool use. When a task requires independent information from multiple sources (search for X and search for Y simultaneously), Claude returns multiple tool_use blocks in one response. Your application should execute these in parallel and return all results before the next API call. Parallel tool use significantly reduces total latency for tasks that decompose into independent subtasks: instead of four sequential tool calls (four round trips), you make one API call, execute four tools simultaneously, and make one more API call with all results. Implementing parallel execution requires your tool executor to handle concurrent calls — Python’s asyncio.gather or a thread pool are the standard approaches.
Error Handling in Tool Results
When a tool call fails — network error, invalid arguments, unexpected API response — you should return the error in the tool_result content block rather than raising an exception or retrying silently. Claude reads the error message and adjusts its approach: it may try different arguments, call a different tool, or inform the user that the operation failed. A tool result with a clear error message (“Error: the search API returned a 429 rate limit error — please try again in 60 seconds”) gives Claude the information it needs to handle the failure gracefully. A silent retry or exception can cause the conversation to stall or produce confusing results. The is_error field in the tool result content block signals to Claude that the result is an error rather than a successful outcome, allowing it to respond appropriately.
Tool Choice Control
The tool_choice parameter gives you control over how Claude selects tools. The default (auto) lets Claude decide whether to use a tool or respond directly — appropriate for most use cases. any forces Claude to use at least one tool from the available set — useful when you need Claude to always look up current information rather than answering from training data. tool with a specific tool name forces Claude to call that exact tool — useful for structured extraction tasks where you always want the output in a specific format. Forcing tool use with tool_choice: {type: "tool", name: "extract_data"} turns Claude into a structured extraction function: whatever it generates will always be a valid call to your extraction schema, which you parse into structured data. This is a lightweight alternative to dedicated structured output libraries for simple extraction tasks.
Extended Thinking with Tool Use
Claude’s extended thinking (available on Claude 3.7 Sonnet and later) works alongside tool use: the model can think through its reasoning before deciding which tool to call and how to use the results. When both are enabled, Claude may produce a thinking block before its tool call decision, giving you visibility into its reasoning process. For complex multi-step tasks, the combination of extended thinking and tool use is significantly more capable than either alone — the model reasons carefully about the current state of the task, what information is still needed, and which tool is most appropriate to obtain it. The thinking tokens add cost and latency, so this combination is best reserved for tasks where the quality improvement justifies the overhead: complex research, multi-step data analysis, or software engineering tasks with many interdependencies.
Token Efficiency and Best Practices
Tool definitions consume input tokens on every API call — a large set of tools with detailed schemas and descriptions can add 1,000–3,000 tokens per call. For agents with many tools, only include tools that are relevant to the current task rather than sending the full tool set every time. Tool results also consume tokens: if a tool returns a large document, truncate or summarise it before including it in the conversation. Structuring tool results as clean, concise text rather than raw API responses (which often contain metadata and nested objects that the model does not need) reduces token usage and keeps the model’s attention on the relevant content. For high-volume production agents, profiling token usage across the tool definition, the tool results, and the conversation history reveals where the largest optimisation opportunities lie.
Anthropic’s tool use API is a well-designed, low-abstraction interface that gives you direct control over the agent loop. The key design elements — tool descriptions that precisely define when to call each tool, clean structured tool results, explicit error propagation, and parallel execution for independent operations — determine most of the quality difference between a reliable production agent and a brittle prototype. Master the raw API mechanics first; framework abstractions are more useful once you understand what they are abstracting.
One pattern worth highlighting for production systems: use a separate system prompt section dedicated to tool use guidance — “when to search vs answer from memory,” “always verify numerical facts with the calculator tool,” “prefer the database tool over the search tool for internal company data.” This keeps tool routing logic out of the main task prompt and makes it easy to update as the tool set evolves. The quality of tool routing decisions is determined by the clarity of both the tool descriptions and this guidance section, and investing time in both pays dividends across every interaction the agent handles.