Tool Description Best Practices
Write clear, effective tool descriptions that help Claude select and use tools correctly. Include input formats, examples, edge cases, and boundary conditions.
What makes a good tool description:
Include input format specifications with examples in the tool description
Specify edge cases and boundary conditions so the model handles them correctly
Clear parameter descriptions with expected types, ranges, and constraints
Tool descriptions act as documentation for the model — more detail is better
Anti-Patterns to Avoid
Vague tool descriptions that leave ambiguity about when or how to use the tool
Missing edge case documentation leading to unexpected tool behavior
Structured Error Responses
Design error responses that give the agent enough information to recover or escalate. Use structured fields like isError, errorCategory, and isRetryable.
Error response design patterns:
isError flag: explicitly signals tool failure to the agent
errorCategory: classifies errors (e.g., 'validation', 'auth', 'not_found', 'rate_limit')
isRetryable: tells the agent whether retrying the same call might succeed
Structured error context: include what was attempted and what failed
Anti-Patterns to Avoid
Generic error messages like 'Operation failed' that hide useful context
Silently suppressing errors by returning empty results as success
Not distinguishing between access failures and genuinely empty results
Tool Distribution & Selection
Distribute tools across agents effectively. Understand the impact of tool count on selection quality and how to scope tool access.
Tool distribution strategies:
4-5 tools per agent is optimal; too many tools (e.g., 18) degrades selection quality
Scoped tool access: each agent only gets tools relevant to its task
tool_choice options: 'auto' (model decides), 'any' (must use a tool), or forced specific tool
Tool grouping: organize related tools and assign them to specialized agents
Anti-Patterns to Avoid
Giving an agent 18+ tools when only 4-5 are relevant to its task
Not using tool_choice to constrain tool selection when the task is clear
MCP Server Configuration
Configure Model Context Protocol servers for project-level and user-level tool integration. Understand .mcp.json vs ~/.claude.json configuration.
MCP configuration essentials:
.mcp.json: project-level MCP server configuration (shared with team)
~/.claude.json: user-level MCP configuration (personal tools)
Environment variable expansion in MCP config for secrets management
MCP servers extend Claude's capabilities with custom tools and data sources
Anti-Patterns to Avoid
Hardcoding secrets in .mcp.json instead of using environment variable expansion
Mixing project-level and user-level configs without understanding precedence
Built-in Tools
Understand Claude's built-in tools: Read, Write, Edit, Bash, Grep, and Glob. Know when to use each tool for different tasks.
Built-in tools and their use cases:
Read: read file contents for understanding code or data
Write: create new files from scratch
Edit: modify existing files with targeted changes
Bash: execute shell commands for building, testing, and system operations
Grep: search for patterns across files in a codebase
Glob: find files matching patterns for discovery and navigation
Anti-Patterns to Avoid
Using Write when Edit would be more precise for modifying existing files
Using Bash for file operations when Read/Write/Edit are available
Exam Tips for Domain 2
Keep tools per agent to 4-5 for optimal selection quality
Structured error responses are critical — always include isError, errorCategory, isRetryable
Know the difference between .mcp.json (project) and ~/.claude.json (user)
Built-in tools: know when to use Grep vs Glob vs Read
Related Exam Scenarios
Customer Support Resolution Agent
Design an AI-powered customer support agent that handles inquiries, resolves issues, and escalates complex cases. Tests Agent SDK usage, MCP tools, and escalation logic.
Developer Productivity with Claude
Build developer tools using the Claude Agent SDK with built-in tools and MCP servers. Tests tool selection, codebase exploration, and code generation workflows.
Test Your Knowledge of Tool Design & MCP
Practice with scenario-based questions covering this domain.