D2 · Tool Design & MCP › Cluster 1 · Tool Use Fundamentals

1.2 · The Tool Definition (name · description · input_schema)

How Claude sees a tool

CONCEPT Three required fields

A tool is a JSON object you place in the tools array. Claude never sees your code — it sees only this object. Three fields are required:

FieldWhat it isNotes
nameThe tool's identifierMust match ^[a-zA-Z0-9_-]{1,64}$. Claude echoes it back in the tool_use block so you know which function to run.
descriptionPlain-text explanation of what the tool does, when to use it, and how it behavesBy far the biggest lever on tool-use quality. Aim for 3–4+ sentences.
input_schemaA JSON Schema object defining the tool's parametersTypes, properties, required, enum. Claude fills input to match this schema.
🔑 Because Claude sees only name, description, and input_schema, the description is the tool's real interface. A vague description is the #1 cause of a tool being ignored or mis-called.

CONCEPT The description carries the "when," the schema carries the "what"

Split responsibilities cleanly: the description tells Claude whether and when to reach for the tool; the input_schema tells it how to shape the arguments. Use required to mark truly-mandatory params and enum to fence values to a fixed set — both reduce malformed calls.

Optional extras exist too: input_examples (schema-valid sample inputs for complex tools), strict: true (guarantee the call matches the schema exactly), and cache_control. But name / description / input_schema are the only required three.
A one-line description like "Gets the stock price for a ticker." leaves Claude guessing what "ticker" means, what's returned, and when not to call it — expect wrong or missing calls.

DIAGRAM What the model actually sees

flowchart TD T["Your tool definition"] --> N["name
identifier Claude echoes back"] T --> D["description
WHAT it does · WHEN to use it"] T --> S["input_schema (JSON Schema)
properties · required · enum"] D --> DEC{"Claude: is this tool
relevant to the request?"} S --> DEC DEC -->|"yes"| USE["Emit tool_use
input matches the schema"] DEC -->|"no"| SKIP["Answer directly / pick another tool"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef info fill:#e7f1ff,stroke:#4a90d9,color:#1a3a5a; class USE ok; class N info; class D info; class S info;

CODE A well-described tool definition

Detailed description, typed schema, an enum-bounded optional param, and required listing only the mandatory field.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. "
                 "The symbol must be a valid ticker on a major US exchange "
                 "(NYSE or NASDAQ). Returns the latest trade price in USD. "
                 "Use this when the user asks for the current or most recent "
                 "price of a stock. It returns no other company data.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Stock ticker symbol, e.g. AAPL for Apple Inc."
      },
      "currency": {
        "type": "string",
        "enum": ["USD", "EUR"],   # fence values to a fixed set
        "description": "Currency for the returned price"
      }
    },
    "required": ["ticker"]    # currency is optional
  }
}

TRADE-OFFS Rich descriptions vs. many narrow tools

✅ Detailed descriptions, consolidated tools

  • Claude selects & fills the tool accurately
  • Group related ops (e.g. an action param) → fewer choices to disambiguate
  • Namespaced names (github_list_prs) stay unambiguous as the set grows

⚠️ Terse descriptions / a tool per micro-action

  • Selection ambiguity and malformed input
  • Larger tool surface → more tokens, more confusion
  • Every tool schema is billed as input tokens

EXAM TRAPS

Trap: Naming the fields wrong. → The three required fields are exactly name, description, and input_schema. It's input_schema (JSON Schema) — not "parameters," not "schema," not "arguments."
Trap: Treating the description as cosmetic. → It's the primary signal Claude uses to decide when and how to call the tool. Weak descriptions → skipped or mis-filled tools.
Trap: Illegal tool names. → name must match ^[a-zA-Z0-9_-]{1,64}$ — no spaces, no dots. "get weather" is invalid; "get_weather" is fine.
Trap: Confusing strict / input_examples with the required set. → Those are optional refinements. Only name / description / input_schema are required.

PRACTICE

Q1 · What are the three required fields of a tool definition?

name, description, and input_schema. The input_schema is a JSON Schema object describing the tool's parameters.

Q2 · Why is the description the most important field?

Claude never sees your implementation — only the definition. The description is what it reads to decide whether, when, and how to call the tool. Detailed descriptions (what it does, when to use it, what each param means, caveats) dramatically improve selection accuracy.

Q3 · How do you constrain a parameter to a fixed set of values, and mark it required?

Use enum inside the property's schema (e.g. "enum": ["celsius", "fahrenheit"]) to fence the allowed values, and list the mandatory parameters in the schema's required array. Params not in required are optional.