Tool Use

What Is Tool Use?

Every response you have seen so far has Claude working from what it already knows. Tool use changes that fundamentally. Tool use lets you define functions — tools — that Claude can call when it needs information it does not have or actions it cannot perform itself. Claude does not execute the function. It identifies which tool to call, extracts the right arguments from the user’s message, and tells your application to run it. Your application executes the function, passes the result back, and Claude incorporates it into a final response. This is how AI applications connect to the real world.

Without Tool Use	With Tool Use
Claude works from training data only	Claude accesses live data
Cannot answer real-time questions	Can query APIs, databases, services
Static knowledge cutoff	Always current information
General purpose responses	Precise, data-driven responses

A Real Example

User: “What is the current price of Bitcoin?” Without tool use:

“I don’t have access to real-time data, so I cannot tell you the current price of Bitcoin.”

With tool use:

“The current price of Bitcoin (BTC) is $97,432.18 USD.”

The difference is a get_crypto_price tool that Claude called, your application executed, and Claude used to answer accurately.

The Two-Request Lifecycle

Tool use always takes two requests:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

REQUEST 1
You send: tool definitions + user message
Claude returns: tool_use block (which tool + what arguments)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

YOUR APPLICATION
Executes the function with Claude's arguments
Gets the result

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

REQUEST 2
You send: full history + tool result
Claude returns: final text response

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Claude reasons. You execute. Claude responds.

Request 1 — Define Your Tools

Pass tool definitions in the tools array alongside the user message:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_crypto_price",
      "description": "Get the current price of a cryptocurrency in USD. Use this when the user asks about current crypto prices.",
      "input_schema": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string",
            "description": "The cryptocurrency symbol, e.g. BTC, ETH, SOL"
          }
        },
        "required": ["symbol"]
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "What is the current price of Bitcoin?"
    }
  ]
}

Anatomy of a Tool Definition

Each tool has three required fields:

name

The function identifier. Use snake_case. Claude uses this to identify which tool it is calling.

"name": "get_crypto_price"

description

The most important field. Claude reads this to decide whether and how to use the tool. Write it as if explaining the function to a junior developer — be specific about what it does and when to use it.

"description": "Get the current price of a cryptocurrency in USD. Use this when the user asks about current crypto prices."

Vague Description	Specific Description
`"Gets prices."`	`"Get the current price of a cryptocurrency in USD. Use this when the user asks about current crypto prices."`
`"Searches things."`	`"Search for recent news articles on a given topic. Use this when the user asks about current events or recent developments."`
`"Does weather."`	`"Get the current weather conditions for a city. Use this when the user asks about weather in a specific location."`

A vague description leads to missed or incorrect tool calls. Claude cannot use a tool well if it does not understand what the tool does. The description is where most tool use failures originate.

input_schema

A JSON Schema object defining the tool’s parameters — their names, types, descriptions, and which are required:

"input_schema": {
  "type": "object",
  "properties": {
    "symbol": {
      "type": "string",
      "description": "The cryptocurrency symbol, e.g. BTC, ETH, SOL"
    }
  },
  "required": ["symbol"]
}

Always include descriptions for each parameter — Claude uses them to extract the right values from the user’s message.

Response 1 — The Tool Use Block

When Claude decides a tool is needed it stops generating text and returns a tool_use content block:

{
  "id": "msg_011Cd8...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01AXtTKvmkaPzQ75JP3o9R4X",
      "name": "get_crypto_price",
      "input": {
        "symbol": "BTC"
      }
    }
  ],
  "stop_reason": "tool_use"
}

Notice three things: stop_reason: "tool_use" — generation stopped because a tool call is needed. This is your signal to execute the function. content[0].type: "tool_use" — the response contains a tool call, not text. Your application should never try to display this as a user-facing response. content[0].input — Claude extracted "BTC" from “What is the current price of Bitcoin?” automatically based on your tool description and schema. You did not parse the user’s message — Claude did.

Save the content[0].id value — toolu_01.... You need it in Request 2 in two places. The IDs must match exactly or the request will fail.

Your Application Executes the Function

Between Request 1 and Request 2, your application runs the actual function:

Claude said: call get_crypto_price with symbol "BTC"
Your app: fetches live price from a crypto API
Your app: gets back "$97,432.18"
Your app: passes this to Claude in Request 2

The function can do anything — query a database, call a third-party API, read from a file, check inventory, send a request to your backend. Claude does not care how you get the result, only that you pass it back correctly.

Request 2 — Pass the Tool Result

Send the full conversation history including Claude’s tool call and your result:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [...same tool definition as Request 1...],
  "messages": [
    {
      "role": "user",
      "content": "What is the current price of Bitcoin?"
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "id": "toolu_01AXtTKvmkaPzQ75JP3o9R4X",
          "name": "get_crypto_price",
          "input": {"symbol": "BTC"}
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01AXtTKvmkaPzQ75JP3o9R4X",
          "content": "The current price of BTC is $97,432.18 USD"
        }
      ]
    }
  ]
}

Three things to notice in this request: The tool definition is included again — it must be present in both requests. Claude’s tool call is in the messages array — as an assistant turn with structured content, not plain text. The tool result is a user turn — with type: "tool_result" and the matching tool_use_id.

Response 2 — Final Answer

Claude reads the tool result and generates a natural language response:

{
  "content": [
    {
      "type": "text",
      "text": "The current price of Bitcoin (BTC) is $97,432.18 USD. Keep in mind that cryptocurrency prices are highly volatile and can change rapidly. Would you like to check the price of any other cryptocurrencies?"
    }
  ],
  "stop_reason": "end_turn"
}

stop_reason returns to end_turn — the tool use cycle is complete. Claude incorporated the real data into a natural, helpful response.

Multiple Tools

Define multiple tools in a single request. Claude selects the right one automatically:

{
  "tools": [
    {
      "name": "get_crypto_price",
      "description": "Get the current price of a cryptocurrency in USD.",
      "input_schema": {...}
    },
    {
      "name": "get_weather",
      "description": "Get the current weather for a city.",
      "input_schema": {...}
    },
    {
      "name": "search_news",
      "description": "Search for recent news articles on a topic.",
      "input_schema": {...}
    }
  ]
}

If the user’s message requires more than one tool, Claude returns multiple tool_use blocks in a single response. Your application executes each function and passes all results back in Request 2.

Token Cost of Tool Use

Tool definitions are included in input tokens on every request — whether Claude uses the tool or not:

Request	Input Tokens	Why
Basic message	17	Message only
Tool use Request 1	407	Message + tool definition
Tool use Request 2	687	Full history + tool definition + tool result

Tool use is significantly more token-intensive than standard messaging. Keep tool definitions concise — especially the description and parameter descriptions. Every unnecessary word costs tokens on every request.

Controlling Tool Selection

Use tool_choice to control when and how Claude uses tools:

Value	Behavior
`auto`	Claude decides whether to use a tool. Default.
`any`	Claude must use at least one of the provided tools.
`tool`	Claude must use a specific named tool.

{
  "tool_choice": {"type": "auto"},
  "tools": [...],
  "messages": [...]
}

Use any or tool when you need guaranteed tool usage — for example, when your application requires structured output that only comes from a specific tool.

Common Use Cases

Use Case	Tool Example
Live data	`get_stock_price`, `get_weather`, `get_exchange_rate`
Database queries	`search_products`, `get_user_account`, `check_inventory`
External APIs	`send_email`, `create_ticket`, `post_to_slack`
Internal services	`get_order_status`, `calculate_shipping`, `verify_payment`
File operations	`read_document`, `search_knowledge_base`, `get_policy`

Tool Use API Reference

Interactive playground for testing tool use requests

Streaming

Combine streaming and tool use for real-time agent applications

System Prompts

Use system prompts to control when and how Claude uses tools

Error Handling

Handle tool use errors and failed tool calls gracefully

Getting Started

Core Concepts

Guides

What Is Tool Use?

A Real Example

The Two-Request Lifecycle

Request 1 — Define Your Tools

Anatomy of a Tool Definition

name

description

input_schema

Response 1 — The Tool Use Block

Your Application Executes the Function

Request 2 — Pass the Tool Result

Response 2 — Final Answer

Multiple Tools

Token Cost of Tool Use

Controlling Tool Selection

Common Use Cases

Further Reading

Tool Use API Reference

Streaming

System Prompts

Error Handling

​What Is Tool Use?

​A Real Example

​The Two-Request Lifecycle

​Request 1 — Define Your Tools

​Anatomy of a Tool Definition

​name

​description

​input_schema

​Response 1 — The Tool Use Block

​Your Application Executes the Function

​Request 2 — Pass the Tool Result

​Response 2 — Final Answer

​Multiple Tools

​Token Cost of Tool Use

​Controlling Tool Selection

​Common Use Cases

​Further Reading

Tool Use API Reference

Streaming

System Prompts

Error Handling

What Is Tool Use?

A Real Example

The Two-Request Lifecycle

Request 1 — Define Your Tools

Anatomy of a Tool Definition

name

description

input_schema

Response 1 — The Tool Use Block

Your Application Executes the Function

Request 2 — Pass the Tool Result

Response 2 — Final Answer

Multiple Tools

Token Cost of Tool Use

Controlling Tool Selection

Common Use Cases

Further Reading