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

Weight: 18% of scored content

This domain covers how to design clear tool interfaces, implement structured error responses, distribute tools across agents, integrate MCP servers, and effectively use Claude Code's built-in tools. The overarching theme: tool descriptions are the primary mechanism LLMs use for tool selection, so getting them right is critical.

Task Statement 2.1: Design effective tool interfaces with clear descriptions and boundaries

Why Tool Descriptions Matter

Tool descriptions are the primary mechanism Claude uses to decide which tool to call. When descriptions are minimal or ambiguous, the model can't distinguish between similar tools, leading to misrouting.

The Misrouting Problem

Consider two tools with near-identical descriptions:

# Bad: ambiguous, overlapping descriptions
analyze_content: "Retrieves customer information"
analyze_document: "Retrieves order details"

Both accept similar identifier formats. When a user says "check my order #12345," Claude may call analyze_content (the customer tool) instead of analyze_document (the order tool) because the descriptions don't clearly differentiate them.

What Good Tool Descriptions Include

A well-written tool description specifies: - Purpose — what this tool does and doesn't do - Input formats — what kind of identifiers/data it accepts, with examples - Edge cases — what happens with invalid input or empty results - Boundary conditions — when to use this tool vs. similar alternatives

{
  "name": "lookup_order",
  "description": "Retrieves order details by order ID (format: ORD-XXXXX) or tracking number. Use this when the customer asks about order status, shipping, delivery, or specific order details. Do NOT use for customer account information — use get_customer instead. Returns: order status, items, shipping info, payment summary.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Order ID (ORD-XXXXX format) or tracking number"
      }
    },
    "required": ["order_id"]
  }
}

Strategies for Fixing Tool Selection Issues

1. Expand descriptions — add input formats, example queries, and boundary explanations (low-effort, high-leverage)
2. Rename tools — eliminate ambiguity (e.g., rename analyze_content to extract_web_results with a web-specific description)
3. Split generic tools — break a generic analyze_document into purpose-specific tools: extract_data_points, summarize_content, verify_claim_against_source

System Prompt Interference

System prompt wording can create keyword-sensitive tool associations that override well-written descriptions. For example, if your system prompt says "always verify customer identity," Claude might call get_customer even when the user just wants order info. Review system prompts for instructions that might unintentionally bias tool selection.

Connection to Other Domains

• How agents decide which tools to call → see Agentic Architecture & Orchestration
• Few-shot examples for tool selection → see Prompt Engineering & Structured Output

Task Statement 2.2: Implement structured error responses for MCP tools

The isError Flag

In MCP, the isError flag on a tool response signals to the agent that the tool call failed. This is the standard pattern for communicating failures back to the model.

Why Uniform Errors Are Harmful

A generic "Operation failed" error tells the agent nothing useful. It can't decide whether to retry, try an alternative, or give up. Structured error metadata enables intelligent recovery.

Error Categories

Structured Error Response Format

{
  "isError": true,
  "content": "Unable to process refund",
  "errorCategory": "business",
  "isRetryable": false,
  "description": "Refund amount ($250) exceeds the per-transaction limit ($200) for automated processing.",
  "customer_message": "This refund needs manager approval. Let me connect you with a supervisor."
}

Key Design Decisions

• Include isRetryable: false and a customer-friendly explanation for business rule violations so the agent can communicate appropriately
• For transient errors, include isRetryable: true so the agent (or a hook) can implement automatic retry
• Distinguish access failures from valid empty results — a timeout (retry needed) is fundamentally different from a search that returned no matches (valid result, move on)

Local vs. Propagated Error Recovery

In multi-agent systems: - Subagents should attempt local recovery for transient failures (retry with backoff) - Only propagate to the coordinator errors that can't be resolved locally, along with: - What was attempted - Partial results (if any) - Potential alternatives

Connection to Other Domains

• Error propagation in multi-agent systems → see Context Management & Reliability
• Hook-based enforcement for error handling → see Agentic Architecture & Orchestration

Task Statement 2.3: Distribute tools appropriately across agents and configure tool choice

The Too-Many-Tools Problem

Giving an agent access to 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 — for example, a synthesis agent attempting web searches instead of focusing on combining existing findings.

Scoped Tool Access

Give each subagent only the tools needed for its role, with limited cross-role tools for specific high-frequency needs:

Web Search Agent:  [web_search, fetch_url]
Document Analysis: [read_document, extract_tables, summarize_section]
Synthesis Agent:   [verify_fact, format_report]  ← scoped cross-role tool
Coordinator:       [Task]  ← can spawn any subagent

Notice the synthesis agent gets a scoped verify_fact tool for simple lookups rather than full web search access. Complex verifications still route through the coordinator to the web search agent.

Replacing Generic Tools with Constrained Alternatives

Instead of giving an agent fetch_url (which can access anything), replace it with load_document that validates URLs against an allowed list. This prevents misuse without removing necessary functionality.

tool_choice Configuration

Forcing Tool Order with tool_choice

You can enforce a tool sequence across turns: 1. Turn 1: tool_choice: {"type": "tool", "name": "extract_metadata"} — force metadata extraction first 2. Turn 2+: tool_choice: "auto" — let the model decide subsequent steps

Setting tool_choice: "any" guarantees the model calls some tool rather than returning conversational text — useful when you always want structured output.

Connection to Other Domains

• Structured output enforcement → see Prompt Engineering & Structured Output
• Subagent configuration → see Agentic Architecture & Orchestration

Task Statement 2.4: Integrate MCP servers into Claude Code and agent workflows

MCP Server Scoping

Environment Variable Expansion

Use environment variables in .mcp.json for credential management without committing secrets:

{
  "mcpServers": {
    "github": {
      "command": "mcp-server-github",
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Tool Discovery

Tools from all configured MCP servers are discovered at connection time and made available simultaneously to the agent. You don't need to manually register tools — they're auto-discovered.

MCP Resources

MCP resources expose content catalogs (issue summaries, documentation hierarchies, database schemas) that give agents visibility into what data is available without requiring exploratory tool calls. This reduces unnecessary API calls and helps the agent plan its approach.

Best Practices

• Prefer existing community MCP servers for standard integrations (e.g., Jira, GitHub). Only build custom servers for team-specific workflows.
• Enhance MCP tool descriptions to explain capabilities and outputs in detail. Without good descriptions, the agent may prefer built-in tools (like Grep) over more capable MCP tools.
• Expose content catalogs as MCP resources so agents know what's available without trial-and-error exploration.

Connection to Other Domains

• MCP server configuration in Claude Code → see Claude Code Configuration & Workflows
• Tool description quality → see Task Statement 2.1

Task Statement 2.5: Select and apply built-in tools (Read, Write, Edit, Bash, Grep, Glob) effectively

Tool Selection Guide

Edit Failure Fallback

Edit requires a unique text match. When it fails due to non-unique text (the target string appears multiple times), fall back to Read + Write: read the full file, make modifications in memory, write the complete file back.

Incremental Codebase Exploration

Don't read all files upfront. Build understanding incrementally:

1. Start with Grep to find entry points (function definitions, error messages, imports)
2. Use Read to follow imports and trace execution flows
3. Use Glob to find related files (**/*.test.tsx for all test files)

Tracing Function Usage

To understand how a wrapper module is used across a codebase: 1. Read the module to identify all exported names 2. Grep for each exported name across the codebase 3. Read the most important callers to understand usage patterns

Connection to Other Domains

• Context management when reading many files → see Context Management & Reliability
• Plan mode for large codebase exploration → see Claude Code Configuration & Workflows