Claude Tool Use Guide for Developers

Claude tool use lets you give Claude access to external functions, APIs, and databases through a structured calling mechanism. Instead of returning unstructured text, Claude signals exactly which function to call and with what parameters — your application executes it and returns the result. This guide covers the current API for defining tools, handling the request/response cycle, and controlling tool-calling behavior with tool_choice.

What is Claude Tool Use?

Tool use (also referred to as function calling) is a feature of the Claude Messages API that lets Claude interact with external systems in a structured way. When you include tool definitions in your API request, Claude can return a tool_use content block instead of plain text. Your application executes the referenced function and sends the result back as a tool_result message — Claude then incorporates that data into its final reply.

Two categories of tools exist in the Claude API:

• Client tools — Defined by you in the tools parameter. Claude returns a structured call; your code runs the logic and returns the result.
• Server tools — Provided by Anthropic (web search, code execution, web fetch). Anthropic handles execution on their infrastructure; you see results without running anything yourself.

This guide focuses on client tools and the developer workflow for integrating them into applications and agent pipelines.

Supported Models

All current Claude 4 models support tool use via the Messages API:

Model	API ID	Best for
Claude Opus 4.8	claude-opus-4-8	Complex multi-tool workflows; ambiguous queries where clarification matters
Claude Sonnet 4.6	claude-sonnet-4-6	General-purpose tool integration with balanced speed and accuracy
Claude Haiku 4.5	claude-haiku-4-5-20251001	High-volume, straightforward tools where cost and latency are priorities

Anthropic recommends Claude Opus 4.8 when your workflow involves multiple tools or ambiguous user inputs. Opus is more likely to ask for missing parameters rather than guessing. Haiku and Sonnet may infer reasonable values for unspecified optional parameters instead.

How to Define a Tool

Each tool in the tools array of your API request requires three fields:

Field	Type	Required	Description
name	string	Yes	Alphanumeric identifier; must match ^[a-zA-Z0-9_-]{1,64}$
description	string	Yes	What the tool does, when to call it, and what it returns
input_schema	object	Yes	JSON Schema object defining expected parameters and types
input_examples	array	No	Example input objects that help Claude understand optional parameters and formats

Writing Effective Tool Descriptions

According to Anthropic’s official documentation, tool descriptions are the single most important factor in tool performance. A thorough description should explain what the tool does, when it should (and should not) be called, what each parameter means, and what the tool returns. Aim for at least 3–4 sentences for any non-trivial tool. Example:

{
  "name": "get_weather",
  "description": "Returns the current weather for a given city. Use this when the user asks about current conditions, temperature, humidity, or weather in a specific location. Returns temperature, conditions, humidity, and wind speed. Does not provide historical data or multi-day forecasts.",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and country, e.g. 'Paris, France'"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature unit. Defaults to celsius if not specified."
      }
    },
    "required": ["location"]
  }
}

The Request/Response Cycle

Tool use follows a multi-turn conversation pattern. Your application is responsible for executing tools and passing results back to Claude:

1. Send a request with the tools array and a user message
2. Claude returns a tool_use content block with stop_reason: "tool_use"
3. Your code extracts the tool name and input from the block, then runs the function
4. You send a new request appending a tool_result block with the function output
5. Claude returns its final response with stop_reason: "end_turn"

Here is a complete Python example using the Anthropic SDK:

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Returns current weather for a city. Use when the user asks about weather or temperature in a specific location. Returns temperature and conditions. Does not provide forecasts.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and country, e.g. 'London, UK'"
                }
            },
            "required": ["location"]
        }
    }
]

# Step 1: Initial request with tools
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What is the weather in Tokyo?"}]
)

# Step 2: Claude responds with a tool_use block
if response.stop_reason == "tool_use":
    tool_block = next(b for b in response.content if b.type == "tool_use")

    # Step 3: Execute the tool in your application
    result = {"temperature": "22 C", "conditions": "Partly cloudy"}

    # Step 4: Return the result to Claude
    final = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        tools=tools,
        messages=[
            {"role": "user", "content": "What is the weather in Tokyo?"},
            {"role": "assistant", "content": response.content},
            {
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": tool_block.id,
                        "content": str(result)
                    }
                ]
            }
        ]
    )
    # Step 5: Claude returns its final answer
    print(final.content)

Controlling Tool Calls with tool_choice

The tool_choice parameter controls whether and how Claude uses tools in a given request:

Value	Behavior
{"type": "auto"}	Default. Claude decides whether to call a tool or respond in plain text.
{"type": "any"}	Claude must call at least one tool from the provided list.
{"type": "tool", "name": "..."}	Claude must call the specifically named tool.
{"type": "none"}	Claude cannot call any tools. Same behavior as omitting the tools parameter.

Use "any" or "tool" when your workflow requires structured output — for example, a data extraction pipeline where a plain-text response is not useful. Note that "any" and "tool" are not compatible with extended thinking mode; use "auto" when combining tool use with thinking budgets.

Parallel Tool Calls

Claude can return multiple tool_use blocks in a single response. When this happens, your response.content contains two or more tool calls. Execute each independently, then return all results as separate tool_result blocks within a single user message before sending back to Claude. Parallel tool calls are especially useful in agent workflows that need to gather data from multiple sources — weather, calendar, and inventory, for example — before composing a single response.

Best Practices

• Write detailed descriptions. Aim for 3–4 sentences per tool. Explain what the tool does, when to call it, what it returns, and what it explicitly does not return.
• Use specific JSON Schema constraints. Use enum for constrained string values, mark truly required fields in required, and add field-level descriptions for every property.
• Keep tool responses lean. Return only the data Claude needs for its next reasoning step. Bloated tool responses waste context window tokens and can slow multi-turn workflows.
• Choose the right model. Use Opus 4.8 for complex multi-tool orchestration. Use Haiku 4.5 for high-volume, simple tools where cost and latency are priorities.
• Use strict mode in production. Adding "strict": true to a tool definition ensures Claude’s calls always match your schema exactly, preventing malformed inputs from reaching your application logic.

Tool Use and Pricing

Tool definitions contribute to your input token count alongside the messages array. The API also adds a system prompt when tools are present — approximately 346 tokens for auto or none tool_choice, and approximately 313 tokens for any or tool tool_choice. These are added to your normal input token count. Client tools are billed at standard API rates. Server tools (web search, code execution) carry additional usage-based charges. For current per-model pricing, see the official Anthropic pricing page or use the Claude API Cost Estimator on this site.

For a broader Claude API introduction, see the Claude API Guide. To estimate costs for tool-heavy workflows, use the Claude API Cost Estimator.

Frequently Asked Questions