Tool Description Design
Tool descriptions are the primary mechanism Claude uses to select which tool to call. They matter more than tool names.
What to include in a tool description:
- What the tool does (one sentence)
- Expected input formats and constraints
- What it returns (shape of the response)
- Boundary conditions (what it does NOT do)
- Example queries that would trigger this tool
Optimisation sequence: Enhance descriptions first → add few-shot examples → consolidate tools. Don't start by reducing the number of tools - start by making descriptions clearer.
Schema Design Rules
- 4–5 tools per agent maximum. More tools increase selection errors.
- Use descriptive parameter names -
customer_emailnotemail,order_date_rangenotrange. - Mark parameters as
requiredonly when truly mandatory. Optional parameters with defaults reduce friction. - Use
enumtypes for constrained choices - they guide the model better than freeform strings. - Expand descriptions before consolidating tools. If Claude misselects a tool, the first fix is a better description, not fewer tools.
tool_choice Modes
| Mode | Behaviour | Use When |
|---|---|---|
auto | Model decides whether to call a tool | Default for most agentic loops |
any | Model must call at least one tool (chooses which) | Guaranteed structured output when the input could match one of several schemas |
tool (forced) | Model must call a specific named tool | Guaranteed schema compliance for one known structure |
Key exam point: Use tool_choice: { type: "tool", name: "extract_data" } when you need one specific structure every time. When the document type is unknown and any of several extraction schemas could apply, tool_choice: "any" still guarantees structured output while letting the model pick the right tool.
auto is the correct default for agentic loops - the model needs freedom to decide when to call tools and when to respond with text.
MCP Architecture
Three-layer model: Host ⊃ Client ↔ Server (the host application contains the client; the client connects to servers)
| Layer | Role | Example |
|---|---|---|
| Client | Connects to servers, routes tool calls | Claude Desktop, IDE extension |
| Host | Application managing client lifecycle | The desktop app process itself |
| Server | Exposes tools, resources, prompts | A database connector, file system server |
Protocol: JSON-RPC 2.0 over stdio or streamable HTTP.
Configuration files:
.mcp.jsonin project root - project-level MCP servers (shared with team)~/.claude.json- personal/global MCP servers (not committed)
Key rule: Use community MCP servers first. Only build custom servers when no community server meets your requirements.
Tool Error Handling
Structured error metadata (the exam-tested pattern):
The four categories: transient (timeouts, service unavailability - isRetryable: true, resend as-is), validation (invalid input - false, correct the input and send a new call), business (policy violations - false, take an alternative path), permission (missing access - false, escalate to a principal with access). Only transient is retryable: the flag asks whether resending *this* call can work, and everything else needs something to change first. "Not found" is deliberately absent: a query that finds nothing is a valid empty result, not an error.
Critical distinction:
- Access failure (auth error, network timeout) → Retry or escalate. Something went wrong.
- Valid empty result (search returned 0 results) → Accept. The absence of data IS the answer.
Never treat a valid empty result as an error. Never silently swallow an access failure.
Tool Selection in Claude Code
| Tool | Purpose | Use When |
|---|---|---|
| Grep | Search file contents by pattern | Looking for code patterns, string occurrences |
| Glob | Find files by name/path pattern | Looking for files by extension or naming convention |
| Read | Read a specific file | You know the exact file path |
| Edit | Modify file contents | Making targeted changes to existing files |
| Bash | Run shell commands | Build, test, git operations, anything not covered above |
Selection principle: Use the most specific tool. Grep for content search, Glob for file discovery, Read for known files. Avoid Bash for tasks that specialised tools handle better.
Decision Rules for the Exam
| If the question says... | The answer is likely... |
|---|---|
| "Claude keeps picking the wrong tool" | Improve tool descriptions first |
| "guaranteed structured output" | Forced tool_choice for one known schema; tool_choice: any across multiple schemas |
| "model should decide which tool" | tool_choice: auto |
| "must call a tool but can choose which" | tool_choice: any |
| "search returned no results" | Valid empty result - accept it |
| "API returned 401/timeout" | Access failure - retry or escalate |
| "too many tools, selection errors" | Scope to 4–5 per agent, improve descriptions |
| "need a custom MCP server" | Check community servers first |
| "project-wide MCP config" | .mcp.json in project root |
| "personal MCP config" | ~/.claude.json |
Common Exam Traps
| Trap | Correct Answer |
|---|---|
| "Reduce tools to fix misselection" | Wrong first step - improve descriptions first |
| "tool_choice: any guarantees a specific tool" | Wrong - any forces *a* tool call, not a *specific* one |
| "MCP servers connect directly to each other" | Wrong - all communication goes through the client/host |
| "Empty search results mean the tool failed" | Wrong - absence of data is a valid result |
| "Return generic error string from tools" | Wrong - return structured metadata (category, retryable, suggestion) |
| "Build a custom MCP server for common integrations" | Wrong - check community servers first |
| "Tool name is the primary selection signal" | Wrong - tool description is the primary signal |
Previous
Domain 1: Agentic Architecture & Orchestration
Next
Domain 3: Claude Code Configuration & Workflows