claude-tool-use

Files (2)

• SKILL.md
• metadata.json

SKILL.md (first lines)

# Claude Tool Use

## When to Use
- Defining tools/functions for Claude to call
- Handling `ToolUseBlock` in API responses
- Sending tool results back to continue the conversation
- Building agentic loops that run until Claude stops using tools
- Implementing parallel tool calls
- Debugging tool use errors or unexpected stop reasons

## Core Rules
1. Always check `response.stop_reason == "tool_use"` — this is the signal to execute tools and continue.
2. Every `ToolUseBlock` needs a corresponding `ToolResultBlock` in the next user message.
3. Pass the entire `response.content` (including any `TextBlock`s) back as the assistant message in the loop.
4. Tool input schemas use JSON Schema — use `type: "object"` at root with `properties` and `required`.
5. A tool result with `is_error: true` tells Claude the tool failed — Claude will decide how to recover.
6. Use `tool_choice={"type": "any"}` to force Claude to call at least one tool.
7. Use `tool_choice={"type": "tool", "name": "specific_tool"}` to force a specific tool.
8. Parallel tool calls are native — Claude may call multiple tools in one response; handle all of them.
9. Set a max iteration limit on agentic loops to prevent runaway execution.
10. Tools with side effects (write, delete, send) should confirm with the user before executing in production.

## Tool Definition Schema

```python
tools = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city. Returns temperature and conditions.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "City name, e.g. 'San Francisco, CA'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature unit. Defaults to fahrenheit."
                }
            },
            "required": ["city"]
        }
    },
    {
        "name": "search_web",
        "description": "Search the web and return top results with snippets.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"},
                "num_results": {"type": "integer", "description": "Number of results, 1-10", "default": 3}
            },
            "required": ["query"]
        }
    }
]
```

## Basic Tool Use (Python)

```python
import anthropic
import json

client = anthropic.Anthropic()

def run_tool(tool_name: str, tool_input: dict) -> str:
    """Execute a tool and return the result as a string."""
    if tool_name == "get_weather":
        # Replace with real implementation
        return json.dumps({"temperature": 72, "conditions": "sunny", "city": tool_input["city"]})
    elif tool_name == "search_web":
        return json.dumps({"results": [{"title": "Example", "snippet": "..."}]})
    else:
        raise ValueError(f"Unknown tool: {tool_name}")

def chat_with_tools(user_message: str) -> str:
    messages = [{"role": "user", "content": user_message}]

    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )

    # Handle tool use in a loop
    while response.stop_reason == "tool_use":
        # Collect all tool calls from the response
        tool_use_blocks = [b for b in response.content if b.type == "tool_use"]

        # Add assistant's response (including TextBlocks) to messages
        messages.append({"role": "assistant", "content": response.content})

        # Execute all tool calls and collect results
        tool_results = []
        for tool_use in tool_use_blocks:
            try:
                result = run_tool(tool_use.name, tool_use.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": tool_use.id,
                    "content": result,
                })
            except Exception as e:
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": tool_use.id,
                    "content": str(e),
                    "is_error": True,
                })

        # Add tool results as user message
        messages.append({"role": "user", "content": tool_results})

        # Continue the conversation
        response = client.messages.create(

From UltronCore/claude-skill-vault, MIT.

More from UltronCore/claude-skill-vault