tool-use

SKILL.md preview

---
name: tool-use
description: Tool use patterns for Claude including schema design, tool_choice modes, result handling, parallel execution, error recovery, and extended thinking integration.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
---

# Tool Use Skill

Comprehensive guide to implementing tool use with Claude, covering schema design, tool choice modes, multi-turn conversations, error handling patterns, and advanced features like extended thinking and strict schema conformance.

## When to Use This Skill

Activate this skill when:
- Defining custom tools with JSON schemas
- Building agentic workflows with tool use
- Implementing tool result handling
- Building parallel vs sequential tool orchestration
- Requiring guaranteed schema conformance
- Implementing error recovery patterns
- Combining tools with extended thinking

## Core Concepts

### Tool Definition Schema

Every tool requires a JSON Schema input definition with:
- **name**: Tool identifier (regex: `^[a-zA-Z0-9_-]{1,64}$`)
- **description**: Detailed explanation of purpose, when to use, behavior (3-4+ sentences)
- **input_schema**: JSON Schema defining parameters
- **input_examples** (optional, beta): Concrete examples of valid inputs

#### Best Practices for Tool Definitions

```json
{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. Use this when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company beyond the price.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc. Must be uppercase."
      },
      "include_historical": {
        "type": "boolean",
        "description": "Optional. Whether to include 52-week high/low prices.",
        "default": false
      }
    },
    "required": ["ticker"],
    "additionalProperties": false
  },
  "input_examples": [
    {"ticker": "AAPL"},
    {"ticker": "MSFT", "include_historical": true},
    {"ticker": "GOOGL"}
  ]
}
```

**Key Guidelines:**
- Descriptions should be 3-4+ sentences minimum
- Explain what the tool does, when to use it, what it returns, limitations
- Use `input_examples` for complex nested objects or format-sensitive parameters
- Set `additionalProperties: false` for strict validation
- Use enums for constrained parameters

### Tool Choice Modes

Control how Claude decides whether and how to use tools:

| Mode | Behavior | Use Case |
|------|----------|----------|
| `"auto"` | Claude decides to use tools or not (default) | General tool use, letting Claude decide |
| `"any"` | Claude must use one tool but can choose which | Forcing tool use without specific tool |
| `"tool"` | Force specific tool (e.g., `{"type": "tool", "name": "get_weather"}`) | Structured JSON output, specific tool required |
| `"none"` | Prevent all tool use | Normal text-only responses |

```python
# Allow Claude to decide
# tool_choice="auto" (default)

# Force any tool to be used
tool_choice={"type": "any"}

# Force specific tool (useful for JSON output)
tool_choice={"type": "tool", "name": "record_summary"}

# Prevent tool use
tool_choice={"type": "none"}
```

**Important Constraints with Extended Thinking:**
- Extended thinking only supports `tool_choice: {"type": "auto"}` or `{"type": "none"}`
- Cannot use `{"type": "any"}` or `{"type": "tool"}` with extended thinking
- Use the separate "think" tool instead for complex reasoning with tool use

### Strict Schema Conformance (Beta)

Enable guaranteed schema validation with `strict: true`:

```python
tools=[{
    "name": "search_flights",
    "strict": True,  # Enable strict mode
    "input_schema": {
        "t

…