Domain 2: Tool Design & MCP Integration
18% of examDesign effective tool interfaces with clear descriptions and boundaries
Key Points
- Tool descriptions are the PRIMARY mechanism LLMs use for tool selection -- minimal descriptions lead to unreliable selection.
- Include input formats, example queries, edge cases, and boundaries explaining when to use a tool vs similar alternatives.
- Ambiguous or overlapping descriptions (e.g., analyze_content vs analyze_document) cause misrouting.
- Keyword-sensitive system prompt instructions can override well-written tool descriptions, creating unintended tool associations.
- Rename tools and update descriptions to eliminate functional overlap (e.g., analyze_content -> extract_web_results).
Decision Rules
When: Agent consistently selects the wrong tool among similar options
→Review and expand tool descriptions FIRST -- include input formats, example queries, and boundary explanations.
When: Two tools have near-identical names/descriptions causing misrouting
→Rename the tools and rewrite descriptions to clearly distinguish each tool's purpose.
When: Tool descriptions are clear but the agent still misroutes based on keywords like 'account'
→Review the system prompt for keyword-sensitive instructions that create unintended tool associations.
✗ Anti-Patterns to Reject
- Writing minimal descriptions like 'Retrieves customer information' without specifying inputs, outputs, or boundaries.
- Adding a routing layer or classifier as the first step instead of improving tool descriptions.
Implement structured error responses for MCP tools
Key Points
- Use the MCP isError flag to communicate tool failures back to the agent.
- Distinguish error categories: transient (timeouts), validation (bad input), business (policy violations), permission errors.
- Return structured metadata: errorCategory, isRetryable boolean, and human-readable descriptions.
- Uniform 'Operation failed' errors prevent the agent from making appropriate recovery decisions.
- Distinguish access failures (needing retries) from valid empty results (successful queries with no matches).
Decision Rules
When: A tool encounters a transient failure (timeout, service unavailable)
→Return isError: true with errorCategory: 'transient', isRetryable: true, and what was attempted.
When: A business rule is violated (e.g., refund exceeds policy limit)
→Return isError: true with errorCategory: 'business', isRetryable: false, and a customer-friendly explanation.
When: A query returns zero results but executed successfully
→Return a success response (isError: false) with empty results -- do NOT treat this as an error.
✗ Anti-Patterns to Reject
- Returning generic 'Operation failed' for all error types, preventing intelligent agent recovery decisions.
- Treating valid empty results (0 matches) the same as access failures (timeouts), causing unnecessary retries.
Distribute tools appropriately across agents and configure tool choice
Key Points
- Too many tools (e.g., 18 instead of 4-5) degrades tool selection reliability by increasing decision complexity.
- Agents with tools outside their specialization tend to misuse them (e.g., synthesis agent doing web searches).
- Apply principle of least privilege: give each agent only tools needed for its role, plus limited cross-role tools for high-frequency needs.
- tool_choice options: 'auto' (default), 'any' (must call a tool), forced selection ({'type': 'tool', 'name': '...'}).
Decision Rules
When: A specialized agent misuses tools outside its role (e.g., doc analysis agent doing web searches)
→Replace generic tools with purpose-specific constrained alternatives (e.g., fetch_url -> load_document).
When: 85% of a subagent's verification needs are simple fact-checks with 15% complex
→Give a scoped verify_fact tool for simple lookups; route complex cases through the coordinator.
When: You need to guarantee the model calls a specific tool first in a sequence
→Use tool_choice: {'type': 'tool', 'name': 'extract_metadata'} for the first turn, then switch to 'auto'.
✗ Anti-Patterns to Reject
- Giving all agents access to all tools, leading to cross-specialization misuse and unreliable selection.
- Giving the synthesis agent full web search tools when a scoped verify_fact tool handles 85% of its needs.
Integrate MCP servers into Claude Code and agent workflows
Key Points
- Project-scoped .mcp.json for shared team tooling; user-scoped ~/.claude.json for personal/experimental servers.
- Use environment variable expansion (${GITHUB_TOKEN}) in .mcp.json for credential management without committing secrets.
- Tools from all configured MCP servers are discovered at connection time and available simultaneously.
- MCP resources expose content catalogs (issue summaries, database schemas) to reduce exploratory tool calls.
- Prefer community MCP servers for standard integrations (Jira, GitHub); build custom servers only for team-specific workflows.
Decision Rules
When: Team needs shared MCP tooling with per-developer credentials
→Use project-scoped .mcp.json with ${ENV_VAR} expansion for tokens; document required vars in README.
When: A developer wants to experiment with a personal MCP server
→Configure it in user-scoped ~/.claude.json so it does not affect teammates.
When: A standard integration exists (GitHub, Jira) and you are considering a custom server
→Use the existing community MCP server; reserve custom implementations for team-specific workflows.
✗ Anti-Patterns to Reject
- Building custom MCP server wrappers when native env var expansion in .mcp.json already handles credential injection.
- Having each developer configure the MCP server in user scope instead of using a shared project-scoped .mcp.json.
Select and apply built-in tools (Read, Write, Edit, Bash, Grep, Glob) effectively
Key Points
- Grep for content search: finding function names, error messages, import statements within file contents.
- Glob for path pattern matching: finding files by name or extension (e.g., **/*.test.tsx).
- Read/Write for full file operations; Edit for targeted modifications using unique text matching.
- When Edit fails due to non-unique text matches, fall back to Read + Write for reliable file modifications.
- Build codebase understanding incrementally: Grep to find entry points, then Read to follow imports and trace flows.
Decision Rules
When: You need to find all callers of a specific function across the codebase
→Use Grep to search file contents for the function name.
When: You need to find all test files regardless of directory location
→Use Glob with pattern **/*.test.tsx to match by naming convention.
When: Edit fails because the anchor text appears multiple times in the file
→Use Read to load full contents, then Write the modified version as a fallback.
✗ Anti-Patterns to Reject
- Reading all files upfront to understand a codebase instead of incrementally tracing from entry points via Grep.
- Using Bash for file search/content operations when dedicated Grep and Glob tools are available.