In 30 seconds
- Descriptions are prompts: say what the tool does, when to use it instead of a similar tool, and what comes back.
- Fewer, task-shaped tools beat dozens of narrow ones.
- Validate inputs in the handler every time; the schema guides but does not protect.
- Results should be bounded, and errors should say what happened and what to do next.
Anatomy of a good tool definition
{
"name": "find_customer",
"description": "Look up one customer by email or phone. Use this before
any order or refund tool. Returns id, name, plan and status.
Use search_customers for partial names instead.",
"input_schema": {
"type": "object",
"properties": {
"email": {"type": "string", "description": "Exact email, e.g. ana@example.com"},
"phone": {"type": "string", "description": "E.164 format, e.g. +84912345678"}
}
}
}
Claude picks tools from their names, descriptions and parameters, so write them like documentation for a new colleague. The most useful sentence is often the one that separates this tool from a similar one: "use this, not that, when…".
Fewer, better tools
Every definition costs context and adds a decision. Sixty tools that mirror database tables ask Claude to think like your schema. Five tools shaped around real tasks — find a customer, summarise an account, issue a refund — match how people ask. Overlapping tools should be merged, with an explicit parameter for the mode.
Inputs: guide with the schema, enforce in the handler
Use types, enums for fixed choices and per-field descriptions with formats and examples. Mark only truly required fields as required; forcing optional ones pushes the model to invent values. Then re-validate everything in the handler — type, range, business rules and permissions — because any model output, or injected text, can be wrong.
Outputs: small, labelled and honest
A tool that returns 5,000 rows floods the context window. Add filters and pagination with sensible defaults, and return counts or summaries for large results along with how to get more. Label units and keep them consistent.
Errors are part of the interface
"Error 0x8F2" tells an agent nothing, so it retries. Make the outcome explicit: not found (and what to try next), a transient failure that is safe to retry, or invalid input with the field that was wrong. That one distinction — retryable or not — prevents most agent loops.
Part of Domain 2: Tool Design & MCP Integration (18% of the exam). Explanations are our own, checked against Anthropic's documentation on November 22, 2026.