Tool Definitions & Descriptions

Core

Design effective tool interfaces with clear descriptions and boundaries · Difficulty 2/5

toolsdefinitionsdescriptionsinterface-design

Tool definitions are the primary input Claude uses to decide which tool to call. Clear, comprehensive tool descriptions are the single highest-leverage improvement for tool selection reliability.

Anatomy of a Good Tool Definition

Name: Clear, action-oriented (e.g., lookup_order not data_fetch)

Description: What it does, when to use it, when NOT to use it

Input schema: JSON Schema with parameter descriptions

Examples: Input formats it accepts

Boundaries: How it differs from similar tools

Common Mistakes

Minimal descriptions: "Retrieves customer information" -- too vague

Overlapping names: analyze_content vs analyze_document -- ambiguous

Missing boundaries: Not explaining when to use this tool vs. similar alternatives

Fix: Rich Tool Descriptions

{
  "name": "lookup_order",
  "description": "Retrieves order details by order ID or tracking number. Use when the customer asks about order status, shipping, or delivery. Accepts formats: #12345, ORD-12345, or tracking numbers. Do NOT use for customer account lookups -- use get_customer instead."
}

Splitting Generic Tools

When a tool is too generic (e.g., analyze_document), split it into purpose-specific tools with clear contracts:

extract_data_points -- pulls structured data from documents

summarize_content -- generates concise summaries

verify_claim_against_source -- fact-checks claims against source material

Each specific tool has a narrower, clearer description that reduces selection ambiguity.

Key Takeaways

✓Tool descriptions are the #1 lever for tool selection accuracy
✓Include input formats, use cases, and boundaries vs similar tools
✓Rename ambiguous tools to clearly differentiate purpose
✓Split generic tools into purpose-specific tools with defined input/output contracts

Glossary Terms

tool_use

A content block type in Claude's response indicating the model wants to call a specific tool. Contains 'id', 'name', and 'input' fields. The agent must execute the tool and return results in a tool_result content block for the conversation to continue.

Model Context Protocol (MCP)

An open standard protocol for connecting Claude to external tools and data sources. Defines a client-server architecture where MCP servers expose tools, resources, and prompts that Claude clients can discover and use. Supports project-scoped (.mcp.json) and user-scoped configurations.

Related Concepts

Tool Selection Reliability & Debugging

Diagnose tool selection issues: descriptions first, then system prompt, then examples

Tool Distribution & Least Privilege

Each agent should have only the tools needed for its specific role (4-5 tools, not 18)

Test Yourself1 of 2

In testing, you notice the agent frequently calls get_customer when users ask about order status, even though lookup_order would be more appropriate. What should you examine first to address this issue?