Tool Use

0:00 Tool use, which other platforms call function calling, lets Claude call functions through the Claude API: you list tools in the tools parameter, each with a name, a description and a JSON Schema for its input; when Claude decides it needs one, it stops with stop_reason: "tool_use" and a tool_use block holding the arguments, your code runs the function, and you send the answer back in a tool_result block so Claude can continue (Tool use with Claude). Anthropic also runs some tools itself, the server tools, such as web search, so no code of yours is involved. Tool use is the base of every Claude agent, including Claude Code.

Quick facts

Sources: Tool use with Claude, Parallel tool use, Tool search tool, Release notes, Anthropic docs, read Nov 6, 2026.

Client tools and server tools

The difference is where the code runs (Tool use with Claude):

• Client tools run in your application. They are either your own functions or tools whose schema Anthropic wrote and trained Claude on: memory, bash, text editor, computer use and browser use. Claude returns the call; you execute it.
• Server tools run on Anthropic's machines and come back already finished in the same response: web search and web fetch, the code execution tool, the advisor tool, tool search and the MCP connector for remote Model Context Protocol servers. A long server-tool turn can stop with pause_turn, and you continue by sending the reply back.

How does the tool use loop work?

1. Send a request with tools and the user's message.
2. Claude answers with stop_reason: "tool_use" and one or more tool_use blocks, each with an id, a name and an input object.
3. Run each call in your code.
4. Append Claude's reply as an assistant message, then a user message holding one tool_result per call, matched by tool_use_id.
5. Send again. Repeat until stop_reason is end_turn.

Anthropic's own minimal example, trimmed, in Python:

tools = [{
    "name": "get_weather",
    "description": "Get the current weather for a given location.",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string",
                       "description": "City and state, e.g. San Francisco, CA"}},
        "required": ["location"],
    },
}]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

response = client.messages.create(model="claude-opus-5-5", max_tokens=1024,
                                  tools=tools, messages=messages)
tool_use = next(b for b in response.content if b.type == "tool_use")

weather = "15 degrees Celsius, partly cloudy"  # your lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": [{"type": "tool_result",
        "tool_use_id": tool_use.id, "content": weather}]},
]
followup = client.messages.create(model="claude-opus-5-5", max_tokens=1024,
                                  tools=tools, messages=messages)

If a tool fails, still return a tool_result for it, with is_error: true and a short explanation, so Claude can recover (Parallel tool use).

Writing good tool definitions

11:51 Claude chooses tools from their descriptions, so the description does most of the work: what the tool does, when to use it, what each parameter means. With tool_choice on auto, a line in the system prompt steers how eagerly Claude calls tools; Anthropic's docs give "Use the tools to investigate before responding." as an example that increases tool use. When a required value is missing from the user's message, Anthropic says Opus models are much more likely to ask for it, while Sonnet may guess one.

Forcing a tool, and why it fails on new models

tool_choice takes four types: auto (the default), none, any (some tool must be called) and tool (this named tool must be called). On Claude Opus 5.5, Sonnet 5.5, Fable 5.1 and Mythos 5.1, any and tool return a 400 error; Anthropic's advice is auto with strict tool use instead (Release notes). Older models and Haiku 5.5 still accept them.

Strict tool use

Without strict, Claude occasionally returns "2" where the schema says the number 2, or leaves out a required field. Adding "strict": true to a tool definition guarantees the input matches the schema, because sampling is constrained by a grammar compiled from it. It shares the schema rules of Structured Outputs: no recursive schemas, no numeric or string-length constraints, additionalProperties must be false, and at most 20 strict tools per request.

Parallel tool calls

Claude can call several tools in one reply, say three weather lookups at once. Your code may run them concurrently or in order; what matters is the reply: every tool_result goes in the next single user message, before any text in it (Parallel tool use). Splitting results across messages teaches Claude to stop calling in parallel. To allow at most one call per turn, set "disable_parallel_tool_use": true inside tool_choice.

The tool runner

The SDKs include a tool runner, in beta in all seven languages, that runs the loop for you: it calls your functions, sends the results and keeps the conversation until Claude is done (Tool runner). In Python a decorated function becomes a tool, its docstring the description:

from anthropic import Anthropic, beta_tool

@beta_tool
def get_weather(location: str) -> str:
    """Get the current weather in a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA
    """
    return "20°C, sunny"

runner = Anthropic().beta.messages.tool_runner(
    model="claude-opus-5-5", max_tokens=1024, tools=[get_weather],
    messages=[{"role": "user", "content": "Weather in Paris?"}],
)
print(runner.until_done().content[-1].text)

Anthropic recommends the manual loop instead when a person must approve calls, or for custom logging or conditional execution. For a full agent harness with files, permissions and subagents, see the Claude Agent SDK; for one Anthropic hosts, Managed Agents.

Many tools: tool search and programmatic calling

23:16 Large tool sets cost tokens and accuracy: Anthropic says a setup with GitHub, Slack, Sentry, Grafana and Splunk servers can spend about 55,000 tokens on definitions, and that tool choice degrades past 30 to 50 tools. The tool search tool marks tools defer_loading: true and lets Claude search for the 3 to 5 it needs (by regex or BM25), cutting definitions by over 85% in Anthropic's example, with up to 10,000 deferred tools per request.

25:05 Programmatic tool calling goes further: Claude writes a Python script that calls your tools inside the code execution sandbox, so checking 20 records takes one script instead of 20 model round trips (Programmatic tool calling). It needs code_execution_20260120 or later and is not eligible for zero data retention.

What tool use costs

Tools are billed as tokens: the definitions in tools, every tool_use and tool_result block, and a hidden system prompt Anthropic adds, 286 tokens on Opus 5.5, Sonnet 5.5 and Haiku 5.5 and up to 804 on Opus 4.7. Server tools can add a fee, such as $10 per 1,000 web searches. Tool definitions sit at the front of the prompt, so they cache well with Prompt Caching; changing any of them invalidates the whole cache. Prices are on Claude API Pricing.

Frequently asked questions

Does Claude support function calling? Yes. Claude calls this tool use: you define functions with a name, description and JSON Schema in the tools parameter, and Claude returns tool_use blocks with arguments for your code to run.

Why does tool_choice: any return a 400 error on Claude? Claude Opus 5.5, Sonnet 5.5, Fable 5.1 and Mythos 5.1 do not accept forced tool use (any or tool). Use auto with strict: true tools and, if needed, a system prompt telling Claude to call a tool first.

How do I return results for several Claude tool calls at once? Put one tool_result per tool_use block, each with its tool_use_id, all in the next single user message and before any text. Splitting them up makes Claude less likely to call tools in parallel.

Can Claude call tools on an MCP server? Yes. Claude can reach a remote MCP server from a single API request through the MCP connector, a beta server tool, or your code can act as the MCP client and pass the server's tools in as ordinary Claude tools.

How many tools can I give Claude? There is no small fixed cap, but Anthropic reports accuracy drops beyond 30 to 50 tools; the Claude tool search tool handles up to 10,000 deferred tools in one request by loading only the few Claude needs.

Sources

• Tool use with the Claude 3 model family, Anthropic, Apr 4, 2024 (video)
• Building with MCP and the Claude API, Anthropic, Oct 9, 2025 (video)
• Why we built-and donated-the Model Context Protocol (MCP), Anthropic, Dec 11, 2025 (video)
• Tool use with Claude, Anthropic docs, read Nov 6, 2026
• Parallel tool use, Anthropic docs, read Nov 6, 2026
• Strict tool use, Anthropic docs, read Nov 6, 2026
• Tool runner, Anthropic docs, read Nov 6, 2026
• Tool search tool, Anthropic docs, read Nov 6, 2026
• Programmatic tool calling, Anthropic docs, read Nov 6, 2026
• Structured outputs, Anthropic docs, read Nov 6, 2026
• Pricing, Anthropic docs, read Nov 6, 2026
• Release notes, Anthropic docs, read Nov 6, 2026