Domain 2 — Tool Design & MCP Integration

CCA Foundations course · Page 3 of 8 · ← Back to all courses · Weight: 18%. Mark complete at the bottom to advance.

2.1 — Tool Descriptions as the Routing Mechanism · Core

Descriptions are the primary signal the model uses to pick a tool.

• Include input format with examples and explicit boundaries ("do NOT use for…").
• Add ordering hints when tools are related.
• Grep = search file contents; Glob = match file paths.
• Fix misrouting by rewriting descriptions — not with few-shot examples or tool_choice.

2.2 — Structured Error Responses · Core

Return structured metadata so the coordinator can recover intelligently:

• isError, errorCategory (transient / validation / business / permission), isRetryable, attemptedQuery, partialResults.
• Generic "Operation failed" is an anti-pattern — it hides the context needed to recover.

2.4 — MCP Configuration · Core

• .mcp.json → team / version-controlled tooling. ~/.claude.json → personal / experimental.
• Environment-variable expansion for credentials (e.g. ${GITHUB_TOKEN}) — never commit secrets.
• MCP resources vs tools: resources expose readable content catalogs (reduce exploratory calls); tools perform actions.

2.x — Tool Distribution · Core

• 4–5 tools per agent is optimal; 18+ degrades selection reliability.
• Give each agent a scoped role; split big tool sets into multiple specialised agents.

⚠ Often-missed — Tool Distribution / Separation of Concerns · Gap

If an agent misuses a tool, the fix is to remove the tool and create a dedicated subagent for that job. NEVER patch it with instructions, few-shot examples, or tool_choice.

⚠ Often-missed — Built-in Tool Selection · Gap

• Edit = surgical change via a unique anchor (most efficient).
• Grep = file contents · Glob = file paths.
• Read + Write = full-file ops, only when needed.
• Bash = fallback.

⚠ Often-missed — Tool Batching to Reduce Round Trips · Gap

When several tools are needed together, prompt Claude to emit multiple tool_use blocks in one turn. Don't build a composite "do-everything" tool.

Exam reflexes for Domain 2

• "Tool misrouting" → fix tool descriptions (not few-shot, not tool_choice).
• "Agent misusing a tool" → remove it + dedicated subagent.
• "18+ tools per agent" → split into scoped agents (4–5 each).
• "Timeout returns empty success" → silent suppression anti-pattern → structured error with isError.
• "Multiple tools, different formats" → PostToolUse hook to normalise (Domain 1).