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:
| Field | What it is | Notes |
|---|---|---|
name | The tool's identifier | Must match ^[a-zA-Z0-9_-]{1,64}$. Claude echoes it back in the tool_use block so you know which function to run. |
description | Plain-text explanation of what the tool does, when to use it, and how it behaves | By far the biggest lever on tool-use quality. Aim for 3–4+ sentences. |
input_schema | A JSON Schema object defining the tool's parameters | Types, properties, required, enum. Claude fills input to match this schema. |
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.
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."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
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
actionparam) → 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
name, description, and input_schema. It's
input_schema (JSON Schema) — not "parameters," not "schema," not "arguments."name must match
^[a-zA-Z0-9_-]{1,64}$ — no spaces, no dots. "get weather" is invalid;
"get_weather" is fine.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.