Three Fields, All Critical: name, description, input_schema

The Claude Messages API tool definition has three fields. Each matters: name identifies, description selects, input_schema parameterizes. Weak descriptions produce 52% accuracy. Ambiguous schema field names produce validation errors. All three need attention.

The three fields

name — unique identifier. Used in tool_use blocks. Keep it descriptive: get_order_status > tool_1.

description — the primary selection mechanism. When a model decides which tool to call, it reads and evaluates the description. This is the most important field for routing reliability.

input_schema — JSON Schema defining parameters. Types, required fields, constraints. Tells the model what data to provide.

Description quality → accuracy data

Detailed descriptions consistently produce 93%+ accuracy. Minimal descriptions hover around 50-60% — barely better than random for multi-tool agents.

input_schema field descriptions matter

A tool with {query: {type: "string"}} and description “Look up an order” gets called with {query: "John Smith"} instead of {query: "ORD-12345"}. The model can’t tell that query means order number.

Fix: rename field to order_id with description: “Order number (e.g., ORD-12345)”. Field names and descriptions in the schema guide the model’s parameter construction.

“Field names are self-explanatory” — wrong. file could mean file path, file content, or filename. options is meaningless without specifying what options are available. The small token cost of field descriptions is far outweighed by reduced validation errors.

The comprehensive definition template

For each tool within ~50 words:

1. Purpose: what the tool does specifically
2. Input: what it accepts (with format guidance)
3. Output: what it returns
4. When to use: specific use cases
5. When NOT to use: disambiguation with redirect to correct tool

Plus schema field names with descriptions and examples.

Common confusions

• “prompt” instead of “description”: the description is a selection guide, not system instructions
• “parameters” instead of “input_schema”: uses JSON Schema format, not a simple list
• Implementation details in the definition: endpoints, handlers, runtime config are backend concerns. The definition is model-facing.
• MCP naming: inputSchema (camelCase) in MCP vs input_schema (snake_case) in Claude API

One-liner: Tool definitions need descriptive names, detailed descriptions (40+ words with purpose, I/O, and disambiguation produce 93%+ accuracy), and input_schema with field-level descriptions and examples — minimal descriptions (5-8 words) produce only 52-61% accuracy.