/
← L4: Tool Distribution Across Agents L6: MCP Patterns for Real Workflows →
Module 3 — Designing Scalable Agentic Architecture

L5: Writing Tool Descriptions

L5: Writing Tool Descriptions

Writing Tool Descriptions That Work in Production

In traditional software development, writing a description or a docstring for a function is for the benefit of other human developers. In LLM architecture, the tool description is the prompt. Claude does not natively "know" what your backend functions do. It relies entirely on the natural language descriptions you provide in the JSON schema to decide if , when , and how to use a tool. A poorly written tool description is the leading cause of routing failures and hallucinations in agentic systems.

1. The Core Philosophy: Descriptions as Instructions

When you pass an array of tools to the Claude API, Claude reads the name and description of every single tool before it generates its first word.

An architect must treat a tool description not as a passive label, but as an active instruction manual. The description must answer four critical questions for the model:

  1. What does this do? (The core function)

  2. When should I use this? (The trigger condition)

  3. What should I NOT use this for? (The boundary/constraint)

  4. What will this return? (The expected outcome)

2. Anatomy of a Production-Grade Description

A production-ready tool description is usually a paragraph, not a single sentence. It uses explicit, directive language.

  • The "When" (Trigger Conditions): Use explicit triggers. Instead of saying "Gets user data," say, "Use this tool when the user asks for a specific customer's account balance, email, or physical address."

  • The "Do Not" (Negative Constraints): LLMs often try to use tools for tasks that sound similar. You must build fences. "Do NOT use this tool to search for companies or aggregate data; only use it for individual user IDs."

  • Return Expectations: Tell Claude what to expect so it knows how to plan its next step. "This tool will return a JSON object containing the user's transaction history. If the user is not found, it will return an empty array."

3. Good vs. Bad Tool Descriptions

Examining the difference between a developer-centric docstring and an LLM-centric tool description is critical for the exam.

The "Bad" Description (Fails in production):

"description": "Searches the knowledge base."

  • Why it fails: It is too vague. Claude doesn't know what is in the knowledge base, what parameters to search with, or when to choose this over another tool.

The "Production-Grade" Description:

"description": "Searches the internal IT wiki for troubleshooting guides and standard operating procedures (SOPs). Use this tool ONLY when the user is asking how to fix a hardware issue, reset a password, or configure VPN access. Do NOT use this tool for HR or payroll policies. The tool requires a highly specific keyword string and returns the top 3 matching document summaries."

4. Parameter-Level Descriptions

The overarching tool description is only half the battle. Inside your JSON schema, every single input property (parameter) must also have a robust description.

If a tool requires a parameter called status, you must explain the valid states:

  • Bad Parameter Description: "status": { "type": "string", "description": "The ticket status" }

  • Good Parameter Description: "status": { "type": "string", "description": "The exact string representing the current state of the Jira ticket. Must be exactly one of: 'OPEN', 'IN_PROGRESS', or 'RESOLVED'. Do not guess other statuses." }

Architectural Note: Using enum fields in your JSON schema mathematically forces the LLM to choose from an approved list, but providing a written description of what those enums mean ensures the LLM chooses the correct one for the context.

5. Overlapping Tools and Routing Confusion

As your agent scales, you will add more tools. A common architectural failure occurs when two tools sound similar (e.g., search_active_users and search_all_users).

If Claude cannot mathematically determine which tool is correct based on the prompt, it will randomly guess, leading to unpredictable software behavior.

  • The Fix: You must enforce mutual exclusivity in your descriptions.

  • Tool A: "Use this to search ONLY active, currently logged-in users."

  • Tool B: "Use this to search historical users. If you need currently active users, use the search_active_users tool instead."

By cross-referencing tools within their descriptions, you create a self-correcting routing matrix for the agent.