Chapter 2: Tools and tool_use

Documentation: Tool Use

2.1 What is tool_use

tool_use is a mechanism that allows Claude to call external functions. The model does not run code directly—it generates a structured tool call request; your code executes it and returns the result.

2.2 Tool Definition

Each tool is defined using a JSON schema:

{
  "name": "get_customer",
  "description": "Finds a customer by email or ID. Returns the customer profile, including name, email, order history, and account status. Use this tool BEFORE lookup_order to verify the customer's identity. Accepts an email (format: user@domain.com) or a numeric customer_id.",
  "input_schema": {
    "type": "object",
    "properties": {
      "email": {"type": "string", "description": "Customer email"},
      "customer_id": {"type": "integer", "description": "Numeric customer ID"}
    },
    "required": []
  }
}

Critically important aspects of a tool description:

1. The description is the primary selection mechanism. An LLM chooses tools based on their descriptions. Minimal descriptions (“Retrieves customer information”) lead to mistakes when tools overlap.

2. Include in the description:

   • What the tool does and returns
   • Input formats and example values
   • Edge cases and constraints
   • When to use this tool vs similar alternatives

3. Avoid identical or overlapping descriptions across tools. If analyze_content and analyze_document have nearly identical descriptions, the model will confuse them.

4. Built-in tools vs MCP tools: agents may prefer built-in tools (Read, Grep) over MCP tools with similar functionality. To prevent this, strengthen MCP tool descriptions—highlight concrete advantages, unique data, or context that built-in tools cannot provide.

2.3 The tool_choice Parameter

tool_choice controls how the model selects tools:

Value	Behavior	When to use
{"type": "auto"}	The model decides whether to call a tool or answer in text	Default for most cases
{"type": "any"}	The model must call some tool	When you need guaranteed structured output
{"type": "tool", "name": "extract_metadata"}	The model must call a specific tool	When you need a forced first step / execution order

Important scenarios:

• tool_choice: "any" + multiple extraction tools → the model picks the best one, but you still get structured output
• Forced selection → when you must guarantee a specific first action (e.g., extract_metadata before enrichment)

2.4 JSON Schemas for Structured Output

Using tool_use with JSON schemas is the most reliable way to obtain structured output from Claude. It:

• Guarantees syntactically valid JSON (no missing braces, no trailing commas)
• Enforces the required structure (required fields are present)
• Does not guarantee semantic correctness (values can still be wrong)

Schema design — key principles:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["bug", "feature", "docs", "unclear", "other"]
    },
    "category_detail": {
      "type": ["string", "null"],
      "description": "Details if category = 'other' or 'unclear'"
    },
    "severity": {
      "type": "string",
      "enum": ["critical", "high", "medium", "low"]
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "optional_field": {
      "type": ["string", "null"],
      "description": "Null if the information was not found in the source"
    }
  },
  "required": ["category", "severity"]
}

Schema design rules:

1. Required vs optional: mark fields as required only if the information is always available. Required fields push the model to fabricate values when data is missing.
2. Nullable fields: use "type": ["string", "null"] for information that may be absent. The model can return null instead of hallucinating.
3. Enums with "other": add "other" + a detail string to avoid losing data outside your predefined categories.
4. Enum "unclear": for cases where the model cannot confidently pick a category—honest "unclear" is better than a wrong category.

2.5 Syntax vs Semantic Errors

Error type	Example	Mitigation
Syntax	Invalid JSON, wrong field type	tool_use with a JSON schema (eliminates)
Semantic	Totals don't add up, value in wrong field, hallucination	Validation checks, retry with feedback, self-correction

---