Design Effective Tool Interfaces with Clear Descriptions and Boundaries

📖 The Big Picture: A Real-World Analogy

This analogy maps directly to the exam scenario: a Customer Support Resolution Agent with tools get_customer, lookup_order, process_refund, and escalate_to_human. If get_customer and lookup_order both say "retrieves information," Claude may call either one for any query about customers or orders, with no reliable routing guarantee.

🔍 How Claude Selects Tools: The Description Dependency

Claude's tool selection is not based on function name alone, nor on code-level metadata. It is driven entirely by natural language understanding of the tool description field. When Claude receives a request, it performs this reasoning process:

1. Read the user's request in the context of the full conversation history.
2. Read all tool descriptions as natural language to understand each tool's purpose, accepted inputs, edge cases, and boundaries.
3. Determine which tool (or combination of tools) best matches the intent of this request.
4. Emit a tool_use block for the selected tool(s).

The Description is the Contract

Think of the tool description as a legal contract between the tool author and the model. It must specify:

• What the tool does (and only does)
• What format of inputs it accepts
• What it returns
• When to use it instead of a similar tool
• When not to use it, with an explicit pointer to the correct alternative

Minimal descriptions break this contract. A description of "Retrieves customer information" is unenforceable — Claude cannot reliably determine if "What is the status of my order?" falls within that scope or not.

🧬 Anatomy of a Production-Grade Tool Description

A production-grade tool description must contain four elements. Missing any one of them degrades reliability:

🏷️ The Naming-Description Alignment Problem

Claude reads both the function name and the description when making tool selection decisions. The name is the first signal Claude encounters. If the name is generic (e.g., analyze_content), Claude must rely entirely on the description for disambiguation. But when the name is misleading relative to the description, it creates cognitive friction — and LLMs fail under cognitive friction.

The solution is Name-Description Alignment: ensure the tool name itself communicates the precise purpose, so Claude can often make a correct initial guess before even finishing reading the description.

🎯 Single Responsibility & Constrained Tools

A tool that attempts to serve multiple different use cases creates decision paralysis. Consider a single analyze_document tool that: extracts structured data, summarizes content, AND verifies claims against source material. Claude must infer from user context which job to perform, and inference errors compound across multi-step workflows.

The principle of Single Responsibility from software engineering applies directly: each tool should do exactly one thing, expressed precisely in its name and description. This enables:

• Precise input schemas tailored to the single use case
• Output contracts that are always consistent (no conditional response shapes)
• Cleaner error messages when the tool is misused
• Easy testing of tool behavior in isolation

The Constrained Tool Pattern

For cases where you cannot decompose a tool (e.g., a general-purpose API you don't control), use a constrained wrapper tool. Instead of exposing fetch_url directly to the agent, expose load_internal_document that internally calls fetch_url but validates the URL against your document whitelist. The wrapper tool has a restricted, precise description. Claude sees the constrained tool, not the raw capability.

# Instead of exposing fetch_url directly:
# description: "Fetches content from any URL"  <-- TOO BROAD

# Expose a constrained wrapper:
tools = [{
    "name": "load_internal_document",
    "description": (
        "Loads the full text of an internal company document by its document URL. "
        "ONLY accepts URLs from the internal document store (docs.example.com). "
        "Returns the full document text. "
        "Do NOT use this for external web pages or APIs — use web_search for those. "
        "Document URL format: https://docs.example.com/<doc-id>"
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "document_url": {
                "type": "string",
                "description": "The internal document URL (must start with https://docs.example.com/)"
            }
        },
        "required": ["document_url"]
    }
}]

🠩 System Prompt Interference & Keyword Bias

Claude reads the system prompt and the tool descriptions together as a unified context. This creates a subtle but dangerous risk: keywords in the system prompt can create unintended associations with specific tool names, biasing Claude toward calling certain tools even when they are not appropriate.

The Keyword Association Problem

Consider this system prompt fragment:

Three Types of System Prompt Interference

📦 The Over-Provisioning Danger

A counterintuitive but exam-critical fact: providing an agent with more tools generally makes it LESS reliable. This violates the intuition that "more capability = more performance." Here is why it fails:

• Decision complexity: Selecting from 18 tools vs 4 tools is not 4.5x harder — it is exponentially harder because tool descriptions must now be differentiated across a much larger comparison space.
• Description dilution: With 18 tools, the descriptions of similar tools often begin to overlap, increasing misrouting even when each description is individually well-written.
• Specialization mismatch: A synthesis agent given web search tools will occasionally use them, even when its role is analysis. Tools outside an agent's specialization create behavioral noise.

The Scoped Tool Access Pattern

Instead of giving all agents all tools, implement scoped tool access:

The verify_fact cross-role tool is an example of a scoped cross-role tool: a shared utility needed frequently by multiple agents, exposed selectively rather than to all agents wholesale.

💻 Code Patterns: Minimal vs Production Tool Definitions

Below are side-by-side implementations of tool definitions — the minimal version that causes misrouting, and the production-grade version used in the customer support scenario.

# ❌ ANTI-PATTERN: Minimal descriptions with no boundaries
tools_minimal = [
    {
        "name": "get_customer",
        "description": "Retrieves customer information",  # TOO VAGUE
        "input_schema": {
            "type": "object",
            "properties": {
                "identifier": {"type": "string"}  # No format spec
            },
            "required": ["identifier"]
        }
    },
    {
        "name": "lookup_order",
        "description": "Retrieves order details",  # Near-identical to get_customer
        "input_schema": {
            "type": "object",
            "properties": {
                "identifier": {"type": "string"}  # Same schema name = maximum ambiguity
            },
            "required": ["identifier"]
        }
    }
]
# Result: Claude cannot reliably distinguish these tools for queries like
# "What is the status of my account?" — will misroute unpredictably.

# ✅ PRODUCTION PATTERN: Complete descriptions with boundary guidance
tools_production = [
    {
        "name": "get_customer",
        "description": (
            "Retrieves a customer's account profile from the CRM by their unique customer ID. "
            "Returns: name, email, phone, account status, and subscription tier. "
            "customer_id format: CUST-XXXXX (example: CUST-00123). "
            "Returns {found: false} if the customer ID does not exist — this is a VALID result, not an error. "
            "Use this tool ONLY for account-level queries (profile, status, contact info). "
            "Do NOT use for order status, refund history, or payment details — use lookup_order instead."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "customer_id": {  # Specific name, not generic "identifier"
                    "type": "string",
                    "description": "Customer ID in format CUST-XXXXX"
                }
            },
            "required": ["customer_id"]
        }
    },
    {
        "name": "lookup_order",
        "description": (
            "Retrieves a specific order record from the order management system by its order ID. "
            "Returns: line items, quantities, prices, shipment status, tracking number, and expected delivery date. "
            "order_id format: ORD-XXXXX (example: ORD-98765). "
            "Returns {found: false} for non-existent orders — this is a valid empty result, not an error. "
            "Use this tool ONLY for order-level queries (status, tracking, items, shipping). "
            "Do NOT use for customer account or profile queries — use get_customer for those."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {  # Distinct from customer_id — no overlap
                    "type": "string",
                    "description": "Order ID in format ORD-XXXXX"
                }
            },
            "required": ["order_id"]
        }
    },
    {
        "name": "process_refund",
        "description": (
            "Initiates a monetary refund for a specific order. Requires BOTH a verified customer ID AND order ID. "
            "PREREQUISITE: get_customer must succeed before this tool can be used — you must have a verified CUST-XXXXX. "
            "refund_amount must be a positive float in USD (e.g., 29.99). Do not include currency symbols. "
            "Returns: refund confirmation ID and estimated processing time. "
            "Do NOT use if the customer account is in suspended status — escalate instead."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "customer_id": {"type": "string", "description": "Verified CUST-XXXXX from get_customer"},
                "order_id": {"type": "string", "description": "Order ID from lookup_order (ORD-XXXXX)"},
                "refund_amount": {"type": "number", "description": "Amount in USD, e.g. 29.99"},
                "reason": {"type": "string", "description": "Brief reason for refund"}
            },
            "required": ["customer_id", "order_id", "refund_amount", "reason"]
        }
    }
]

⛔ Anti-Patterns to Avoid

✅ Exam Readiness & Key Takeaways