tool-use-patterns

SKILL.md preview

---
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.

```python
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.

```python
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.

```python
# 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)
        })

# Re

…