Claude Tool Use: How Function Calling Works

Claude tool use (also called function calling) lets the model invoke code you define. You declare each tool with a name, description, and JSON Schema for its parameters; Claude decides when to call it and emits a tool_use block; your application runs the function and returns a tool_result; the loop continues until Claude produces its final text response.

What is Claude tool use?

Tool use bridges Claude and the real world. Without it, the model is limited to training-time knowledge. With it, Claude can fetch live data, run calculations, query databases, send messages, or trigger any action your application exposes.

The model never executes code directly. Claude decides which tool to call and what arguments to pass; your application handles execution. That separation is intentional: you control the side effects, the security boundary, and what gets returned.

How do you define a tool?

Every tool definition has three required fields:

• name — a concise identifier (get_weather, not weather)
• description — what Claude reads to decide when to call the tool
• input_schema — a JSON Schema object describing the parameters

{
  "name": "get_weather",
  "description": "Get current weather for a location. Call this when the user asks about current conditions, not historical data.",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and state, e.g., San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["location"]
  }
}

The description is the most important field. Claude uses it to decide when to call the tool, so a description that states the trigger condition — "Call this when the user asks about current conditions, not historical data" — outperforms one that only states what the tool does.

What happens when Claude calls a tool?

The lifecycle has four steps:

1. Call messages.create() with your tool definitions in tools[]
2. Detect stop_reason: "tool_use" — Claude has decided to call one or more tools
3. Execute the tool(s) in your application and collect results
4. Append the assistant turn (including tool_use blocks) and a new user message containing tool_result blocks, then call the API again

import anthropic

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "What's the weather in Paris?"}]

while True:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        tools=tools,
        messages=messages
    )
    if response.stop_reason == "end_turn":
        break

    messages.append({"role": "assistant", "content": response.content})

    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            result = run_your_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result
            })

    messages.append({"role": "user", "content": tool_results})

When a tool fails, include "is_error": True alongside content. Claude acknowledges the error and decides how to proceed — typically by trying a different approach or asking a clarifying question.

What are the tool_choice options?

By default, Claude decides whether to use any tool at all. You can override this with the tool_choice parameter:

Value	Behavior
{"type": "auto"}	Claude decides (default)
{"type": "any"}	Claude must call at least one tool
{"type": "tool", "name": "get_weather"}	Claude must call this specific tool
{"type": "none"}	Claude cannot call any tools

Any of these options also accepts "disable_parallel_tool_use": true, which forces Claude to use at most one tool per response — useful when tool calls have ordering dependencies.

Can Claude call multiple tools at once?

Yes. In a single response, Claude can emit multiple tool_use blocks, effectively fanning out across independent actions in parallel. When you see more than one tool_use block in response.content, handle all of them before sending back results — send all tool_result blocks together in a single user message.

tool_results = []
for block in response.content:
    if block.type == "tool_use":
        result = run_your_tool(block.name, block.input)
        tool_results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": result
        })
# All results go back in one message
messages.append({"role": "user", "content": tool_results})

Tool runner versus manual loop

The manual loop above gives full control but requires wiring the iteration yourself. All major Anthropic SDKs include a tool runner (currently in beta) that handles the loop automatically.

Python uses the @beta_tool decorator:

from anthropic import beta_tool

@beta_tool
def get_weather(location: str) -> str:
    """Get current weather for a location."""
    return f"72°F and sunny in {location}"

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[get_weather],
    messages=[{"role": "user", "content": "Weather in Paris?"}],
)
for message in runner:
    print(message)

TypeScript uses Zod schemas via betaZodTool. Java, Go, Ruby, and PHP each have language-native equivalents. Use the tool runner for straightforward pipelines. Reach for the manual loop when you need approval gates, custom logging, or conditional branching between calls.

What are server-side tools?

User-defined tools run in your application. Server-side tools run on Anthropic's infrastructure — you declare them in tools[] and Claude handles the rest. The most commonly tested for the exam:

• Web search (web_search_20260209) — live internet queries with citations
• Code execution (code_execution_20260120) — sandboxed Python runtime with data science libraries pre-installed
• Bash and text editor — part of the agent toolset used in Claude Code and Managed Agents

When server-side tools reach their default iteration limit of ten rounds, the stop reason becomes "pause_turn" rather than "tool_use" or "end_turn". Re-send the conversation to resume — no extra user message needed.

What does the CCA-F exam test about tool use?

The Claude Certified Architect — Foundations exam treats tool use as a core competency. Candidates should be comfortable with:

• The structure of a tool definition and the role of each field, especially description
• Reading the tool use lifecycle — stop reasons, block types, the order of operations
• Choosing between auto, any, tool, and none for different scenarios
• Handling parallel tool calls correctly (all results in one user message)
• The distinction between user-defined and server-side tools
• When to use the tool runner versus a hand-written agentic loop
• What "pause_turn" signals and how to resume from it

Exam questions reward understanding the why behind each design decision — why descriptions matter more than names, why all tool results must return in a single message, why pause_turn is distinct from tool_use. Candidates who can explain these trade-offs, not just recite the API shape, score consistently higher on this domain.