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

2.1 Effective tool interfaces

Knowledge:
- Tool descriptions are the primary mechanism LLMs use for tool selection — minimal descriptions → unreliable selection among similar tools
- Descriptions should include: input formats, example queries, edge cases, boundary explanations
- Ambiguous/overlapping descriptions cause misrouting (e.g., analyze_content vs analyze_document)
- System prompt wording can create keyword-sensitive unintended tool associations

Skills:
- Write descriptions that differentiate purpose, inputs, outputs, and "when to use vs. alternatives" — Sample Q2's answer (cheapest, most direct fix beats few-shot/routing-layer/consolidation)
- Rename tools + update descriptions to eliminate overlap (analyze_content → extract_web_results)
- Split generic tools into purpose-specific ones with defined I/O contracts (analyze_document → extract_data_points, summarize_content, verify_claim_against_source)
- Review system prompts for keyword-sensitive instructions overriding good tool descriptions

2.2 Structured error responses for MCP tools

Knowledge:
- MCP isError flag pattern for tool failures
- Error taxonomy: transient (timeout/unavailable), validation (bad input), business (policy violation), permission
- Uniform "Operation failed" responses prevent good recovery decisions
- Retryable vs. non-retryable distinction avoids wasted retries

Skills:
- Return errorCategory, isRetryable boolean, human-readable description
- Include retriable: false + customer-friendly text for business-rule violations
- Local error recovery inside subagents for transient failures; propagate to coordinator only unrecoverable errors + partial results + what was attempted
- Distinguish access failures (need retry decision) from valid empty results (successful query, no matches)

2.3 Distributing tools across agents & tool_choice

Knowledge:
- Too many tools per agent (18 vs. 4-5) degrades selection reliability
- Agents with out-of-specialization tools tend to misuse them (e.g., synthesis agent doing web search)
- Scoped tool access: only what's needed for the role + limited cross-role tools for high-frequency needs
- tool_choice: "auto" / "any" / forced {"type":"tool","name":"..."}

Skills:
- Restrict each subagent's tool set to its role
- Replace generic tools with constrained alternatives (fetch_url → load_document that validates doc URLs)
- Provide scoped cross-role tools for high-frequency simple needs (e.g., verify_fact for synthesis agent) — Sample Q9's answer; route complex cases through coordinator
- Force a specific tool first (extract_metadata) before enrichment tools, using follow-up turns for later steps
- tool_choice: "any" to force a tool call rather than free text

2.4 MCP server integration into Claude Code / agents

Knowledge:
- Project-level .mcp.json (shared, team tooling) vs. user-level ~/.claude.json (personal/experimental)
- Env var expansion in .mcp.json (e.g., ${GITHUB_TOKEN}) for credentials without committing secrets
- All tools from all configured MCP servers are discovered at connection time and available simultaneously
- MCP resources expose content catalogs (issue summaries, doc hierarchies, DB schemas) to cut exploratory tool calls

Skills:
- Configure shared servers in project-scoped .mcp.json with env var expansion
- Configure personal/experimental servers in ~/.claude.json
- Enhance MCP tool descriptions in detail so the agent doesn't default to built-ins (e.g., prefers Grep over a more capable MCP tool)
- Prefer existing community MCP servers (e.g., Jira) over custom builds for standard integrations; reserve custom servers for team-specific workflows
- Expose content catalogs as MCP resources instead of requiring exploratory tool calls

2.5 Built-in tools (Read, Write, Edit, Bash, Grep, Glob)

Knowledge:
- Grep = content search (patterns, function names, error messages, imports)
- Glob = file path pattern matching (by name/extension)
- Read/Write = full file ops; Edit = targeted mod via unique text match
- When Edit fails (non-unique match) → fallback to Read + Write

Skills:
- Grep for finding callers of a function / error messages across a codebase
- Glob for naming-pattern file discovery (**/*.test.tsx)
- Read then Write when Edit can't find a unique anchor
- Build understanding incrementally: Grep for entry points → Read to follow imports/trace flow (not reading everything upfront)
- Trace function usage across wrapper modules: find all exported names first, then Grep each name codebase-wide

Discussion Prompts / Things to Drill