Domain 2: Tool Design and MCP Integration (18%)

2.1 Designing Tool Interfaces with Clear Descriptions

Key knowledge:

• Tool descriptions are the primary mechanism an LLM uses to select tools; minimal descriptions lead to unreliable selection
• The importance of including input formats, example queries, edge cases, and applicability boundaries
• Ambiguous or overlapping descriptions cause misrouting
• System prompt wording can create unintended associations with tools

Key skills:

• Write descriptions that clearly distinguish each tool from similar alternatives
• Rename tools to eliminate functional overlap (e.g., analyze_content -> extract_web_results)
• Split general-purpose tools into specialized ones with clear input/output contracts

2.2 Implementing Structured Error Responses for MCP Tools

Key knowledge:

• The isError flag in MCP tool responses
• The difference between transient errors (timeouts), validation errors (bad input), business errors (policy violations), and access/permission errors
• Generic errors ("Operation failed") prevent correct recovery decisions
• The difference between retryable and non-retryable errors

Key skills:

• Return structured metadata such as errorCategory (transient/validation/permission), isRetryable, and a human-readable message
• Use retryable: false for business-rule violations with clear user-facing explanations
• Do local recovery inside subagents for transient failures; propagate only errors they cannot resolve
• Distinguish access failures (retry decision) from valid empty results (no matches)

2.3 Allocating Tools Across Agents and Configuring tool_choice

Key knowledge:

• Too many tools per agent (e.g., 18 instead of 4–5) reduces tool selection reliability
• Agents with tools outside their specialization tend to misuse them
• Scoped tool access: only role-relevant tools plus a limited set of cross-role utilities
• tool_choice: "auto", "any", and forced tool selection ({"type": "tool", "name": "..."})

Key skills:

• Restrict each subagent’s toolset to what is relevant for its role
• Replace general tools with constrained alternatives (e.g., fetch_url -> load_document)
• Use tool_choice: "any" to guarantee a tool call instead of a text answer
• Force a specific tool to ensure execution order

2.4 Integrating MCP Servers into Claude Code and Agent Workflows

Key knowledge:

• MCP server scope: project (.mcp.json) for teams vs user (~/.claude.json) for experiments
• Environment variable substitution in .mcp.json (e.g., ${GITHUB_TOKEN}) for secret management
• Tools from all connected MCP servers are discovered on connection and are available simultaneously
• MCP resources as “content catalogs” (task summaries, database schemas) to reduce exploratory tool calls

Key skills:

• Configure shared MCP servers in project .mcp.json with env-var-based tokens
• Keep personal/experimental servers in ~/.claude.json
• Prefer community MCP servers over custom servers for standard integrations

2.5 Selecting and Applying Built-in Tools (Read, Write, Edit, Bash, Grep, Glob)

Key knowledge:

• Grep: search within file contents (function names, error messages, imports)
• Glob: find files by name/extension patterns
• Read/Write: full-file operations; Edit: precise changes via unique text matches
• If Edit fails due to non-unique matches, fall back to Read + Write

Key skills:

• Use Grep for content search and Glob for file discovery by patterns
• Build understanding incrementally: Grep entry points, then Read to trace flows
• Trace function usage through wrapper modules

---