tool-use-patterns

name	tool-use-patterns
description	Patterns for Claude tool use including tool definition schemas, multi-tool orchestration, parallel tool calls, error handling, and result formatting. Use when the user is defining tools for Claude, building agentic workflows with tool calling, handling tool errors, or implementing multi-step tool pipelines.

Tool Use Patterns

Patterns for defining, orchestrating, and handling Claude tool use. Covers schemas, multi-tool flows, parallel execution, error handling, and result formatting.

When to Use

• User is defining tools for the Claude API
• User is building agentic loops with tool calling
• User needs parallel tool execution
• User is handling tool errors or formatting results
• User is designing multi-step tool workflows

Core Patterns

Tool Definition Schema

Tools are defined with a name, description, and JSON Schema for input_schema. The description is critical -- Claude uses it to decide when to call the tool.

tools = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city. Use this when the user asks about weather, temperature, or forecast for a specific location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "City name, e.g. 'San Francisco, CA'"
                },
                "units": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature units. Default: fahrenheit."
                }
            },
            "required": ["city"]
        }
    }
]

message = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}]
)

Agentic Tool Loop

The core pattern: send a message, check if Claude wants to use tools, execute them, return results, and repeat until Claude produces a final text response.

def run_agent(user_message: str, tools: list, system: str = "") -> str:
    messages = [{"role": "user", "content": user_message}]

    while True:
        response = client.messages.create(
            model="claude-sonnet-4-6-20250514",
            max_tokens=4096,
            system=system,
            tools=tools,
            messages=messages,
        )

        # Collect tool use blocks and text
        tool_results = []
        final_text = ""

        for block in response.content:
            if block.type == "tool_use":
                # Execute the tool
                result = execute_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": json.dumps(result)
                })
            elif block.type == "text":
                final_text = block.text

        # If no tool calls, return the final text
        if response.stop_reason == "end_turn":
            return final_text

        # Append assistant response and tool results
        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": tool_results})

Parallel Tool Calls

Claude can call multiple tools simultaneously. Handle all tool results in a single user message to maintain correct conversation structure.

# Claude may return multiple tool_use blocks in one response
# Example: user asks "Compare weather in NYC and London"

for block in response.content:
    if block.type == "tool_use":
        # Execute each tool call
        result = execute_tool(block.name, block.input)
        tool_results.append({
            "type": "tool_result",
            "tool_use_id": block.id,  # Must match the specific tool_use block
            "content": json.dumps(result)
        })

# Return ALL results in a single user message
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})

Tool Error Handling

Return errors as tool results so Claude can reason about them and recover.

def execute_tool(name: str, inputs: dict) -> dict:
    try:
        if name == "get_weather":
            return get_weather(**inputs)
        elif name == "search_database":
            return search_database(**inputs)
        else:
            return {"error": f"Unknown tool: {name}"}
    except ValueError as e:
        return {"error": f"Invalid input: {str(e)}"}
    except TimeoutError:
        return {"error": "Request timed out. Try again or use a different query."}
    except Exception as e:
        return {"error": f"Tool execution failed: {str(e)}"}

# Alternatively, use the is_error flag for explicit error signaling
tool_results.append({
    "type": "tool_result",
    "tool_use_id": block.id,
    "content": "City not found. Please check the spelling.",
    "is_error": True  # Tells Claude this is an error, not a valid result
})

Forcing Tool Use

Control whether Claude must use a tool, can choose, or must not use tools.

# Force Claude to use a specific tool
message = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},  # Must use this tool
    messages=[{"role": "user", "content": "Tokyo forecast"}]
)

# Force Claude to use any tool (but must pick one)
tool_choice = {"type": "any"}

# Let Claude decide (default behavior)
tool_choice = {"type": "auto"}

Tool Result Formatting

Structure tool results so Claude can reason about them effectively.

# Good: structured, clear result
result = {
    "status": "success",
    "data": {
        "city": "Tokyo",
        "temperature": 22,
        "units": "celsius",
        "conditions": "partly cloudy",
        "humidity": 65
    }
}

# Good: include metadata for pagination or follow-up
result = {
    "status": "success",
    "results": items[:10],
    "total_count": 247,
    "has_more": True,
    "next_cursor": "abc123"
}

Anti-Patterns

• Writing vague tool descriptions that do not explain WHEN to use the tool
• Not including required fields in the input schema
• Returning raw exception tracebacks as tool results (expose internals, confuse Claude)
• Sending tool results with mismatched tool_use_id (causes API error)
• Not handling the case where Claude calls multiple tools in parallel
• Using tool_choice: {"type": "tool"} in a loop (causes infinite tool calling)
• Putting business logic in tool descriptions instead of the system prompt
• Returning excessively large tool results (summarize or paginate instead)

Quick Reference

Field	Purpose
name	Tool identifier, snake_case, max 64 chars
description	When and why to use -- be specific and directive
input_schema	JSON Schema object with properties and required
tool_use_id	Links tool result back to the specific tool call
is_error	Boolean flag signaling error in tool result
tool_choice	auto (default), any (must call one), {"type":"tool","name":"X"}

Conversation structure for tool use:

1. user message -> Claude responds with tool_use blocks
2. assistant message (Claude's response with tool_use) -> user message with tool_result blocks
3. Repeat until stop_reason is end_turn