How to implement tool use

Choosing a model

We recommend using the latest Claude Sonnet (4.5) or Claude Opus (4.1) model for complex tools and ambiguous queries; they handle multiple tools better and seek clarification when needed.

Use Claude Haiku models for straightforward tools, but note they may infer missing parameters.

Specifying client tools

Client tools (both Anthropic-defined and user-defined) are specified in the tools top-level parameter of the API request. Each tool definition includes:

Tool use system prompt

When you call the Claude API with the tools parameter, we construct a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt. The constructed prompt is designed to instruct the model to use the specified tool(s) and provide the necessary context for the tool to operate properly:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

Best practices for tool definitions

To get the best performance out of Claude when using tools, follow these guidelines:

• Provide extremely detailed descriptions. This is by far the most important factor in tool performance. Your descriptions should explain every detail about the tool, including:
  • What the tool does
  • When it should be used (and when it shouldn't)
  • What each parameter means and how it affects the tool's behavior
  • Any important caveats or limitations, such as what information the tool does not return if the tool name is unclear. The more context you can give Claude about your tools, the better it will be at deciding when and how to use them. Aim for at least 3-4 sentences per tool description, more if the tool is complex.
• Prioritize descriptions, but consider using input_examples for complex tools. Clear descriptions are most important, but for tools with complex inputs, nested objects, or format-sensitive parameters, you can use the input_examples field (beta) to provide schema-validated examples. See Providing tool use examples for details.

The good description clearly explains what the tool does, when to use it, what data it returns, and what the ticker parameter means. The poor description is too brief and leaves Claude with many open questions about the tool's behavior and usage.

Providing tool use examples

You can provide concrete examples of valid tool inputs to help Claude understand how to use your tools more effectively. This is particularly useful for complex tools with nested objects, optional parameters, or format-sensitive inputs.

Basic usage

Add an optional input_examples field to your tool definition with an array of example input objects. Each example must be valid according to the tool's input_schema:

Examples are included in the prompt alongside your tool schema, showing Claude concrete patterns for well-formed tool calls. This helps Claude understand when to include optional parameters, what formats to use, and how to structure complex inputs.

Requirements and limitations

• Schema validation - Each example must be valid according to the tool's input_schema. Invalid examples return a 400 error
• Not supported for server-side tools - Only user-defined tools can have input examples
• Token cost - Examples add to prompt tokens: ~20-50 tokens for simple examples, ~100-200 tokens for complex nested objects

Tool runner (beta)

The tool runner provides an out-of-the-box solution for executing tools with Claude. Instead of manually handling tool calls, tool results, and conversation management, the tool runner automatically:

• Executes tools when Claude calls them
• Handles the request/response cycle
• Manages conversation state
• Provides type safety and validation

We recommend that you use the tool runner for most tool use implementations.

Controlling Claude's output

Forcing tool use

In some cases, you may want Claude to use a specific tool to answer the user's question, even if Claude thinks it can provide an answer without using a tool. You can do this by specifying the tool in the tool_choice field like so:

tool_choice = {"type": "tool", "name": "get_weather"}

When working with the tool_choice parameter, we have four possible options:

• auto allows Claude to decide whether to call any provided tools or not. This is the default value when tools are provided.
• any tells Claude that it must use one of the provided tools, but doesn't force a particular tool.
• tool allows us to force Claude to always use a particular tool.
• none prevents Claude from using any tools. This is the default value when no tools are provided.

This diagram illustrates how each option works:

Note that when you have tool_choice as any or tool, we will prefill the assistant message to force a tool to be used. This means that the models will not emit a natural language response or explanation before tool_use content blocks, even if explicitly asked to do so.

Our testing has shown that this should not reduce performance. If you would like the model to provide natural language context or explanations while still requesting that the model use a specific tool, you can use {"type": "auto"} for tool_choice (the default) and add explicit instructions in a user message. For example: What's the weather like in London? Use the get_weather tool in your response.

JSON output

Tools do not necessarily need to be client functions — you can use tools anytime you want the model to return JSON output that follows a provided schema. For example, you might use a record_summary tool with a particular schema. See Tool use with Claude for a full working example.

Model responses with tools

When using tools, Claude will often comment on what it's doing or respond naturally to the user before invoking tools.

For example, given the prompt "What's the weather like in San Francisco right now, and what time is it there?", Claude might respond with:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

This natural response style helps users understand what Claude is doing and creates a more conversational interaction. You can guide the style and content of these responses through your system prompts and by providing <examples> in your prompts.

It's important to note that Claude may use various phrasings and approaches when explaining its actions. Your code should treat these responses like any other assistant-generated text, and not rely on specific formatting conventions.

Parallel tool use

By default, Claude may use multiple tools to answer a user query. You can disable this behavior by:

• Setting disable_parallel_tool_use=true when tool_choice type is auto, which ensures that Claude uses at most one tool
• Setting disable_parallel_tool_use=true when tool_choice type is any or tool, which ensures that Claude uses exactly one tool

Maximizing parallel tool use

While Claude 4 models have excellent parallel tool use capabilities by default, you can increase the likelihood of parallel tool execution across all models with targeted prompting:

Handling tool use and tool result content blocks

Claude's response differs based on whether it uses a client or server tool.

Handling results from client tools

The response will have a stop_reason of tool_use and one or more tool_use content blocks that include:

• id: A unique identifier for this particular tool use block. This will be used to match up the tool results later.
• name: The name of the tool being used.
• input: An object containing the input being passed to the tool, conforming to the tool's input_schema.

When you receive a tool use response for a client tool, you should:

1. Extract the name, id, and input from the tool_use block.
2. Run the actual tool in your codebase corresponding to that tool name, passing in the tool input.
3. Continue the conversation by sending a new message with the role of user, and a content block containing the tool_result type and the following information:
   • tool_use_id: The id of the tool use request this is a result for.
   • content: The result of the tool, as a string (e.g. "content": "15 degrees"), a list of nested content blocks (e.g. ), or a list of document blocks (e.g. ). These content blocks can use the , , or types.

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

After receiving the tool result, Claude will use that information to continue generating a response to the original user prompt.

Handling results from server tools

Claude executes the tool internally and incorporates the results directly into its response without requiring additional user interaction.

Handling the max_tokens stop reason

If Claude's response is cut off due to hitting the max_tokens limit, and the truncated response contains an incomplete tool use block, you'll need to retry the request with a higher max_tokens value to get the full tool use.

Handling the pause_turn stop reason

When using server tools like web search, the API may return a pause_turn stop reason, indicating that the API has paused a long-running turn.

Here's how to handle the pause_turn stop reason:

When handling pause_turn:

• Continue the conversation: Pass the paused response back as-is in a subsequent request to let Claude continue its turn
• Modify if needed: You can optionally modify the content before continuing if you want to interrupt or redirect the conversation
• Preserve tool state: Include the same tools in the continuation request to maintain functionality

Troubleshooting errors

There are a few different types of errors that can occur when using tools with Claude:

This is correct:

If you receive an error like "tool_use ids were found without tool_result blocks immediately after", check that your tool results are formatted correctly.