Domain 2: Tool Design & MCP Integration

2.1 Tool Interface Design

Tool descriptions are the PRIMARY mechanism LLMs use for tool selection. This is not supplementary. It is THE mechanism.

What a Good Tool Description Includes

The Misrouting Problem

# BAD: Minimal descriptions cause misrouting
tools = [
    {"name": "get_customer", "description": "Retrieves customer information"},
    {"name": "lookup_order", "description": "Retrieves order information"}
]

# GOOD: Expanded descriptions with explicit boundaries
tools = [
    {
        "name": "get_customer",
        "description": "Retrieves customer profile: name, email, address, "
                       "account status, preferences. Use for account-level queries. "
                       "Do NOT use for order status — use lookup_order instead."
    },
    {
        "name": "lookup_order",
        "description": "Retrieves order details: status, items, shipping tracking, "
                       "payment method. Requires order_id (ORD-XXXXX) or customer email. "
                       "Use for order-related queries. Do NOT use for account info."
    }
]

Exam trap: The fix is better descriptions, NOT:

• Few-shot examples (token overhead, wrong root cause)
• Routing classifiers (over-engineered first step)
• Tool consolidation (too much effort)

Tool Splitting

Split generic tools into purpose-specific tools:

analyze_document → extract_data_points
                 → summarize_content
                 → verify_claim_against_source

System Prompt Interaction

Keyword-sensitive instructions in system prompts can create unintended tool associations that override well-written descriptions. Always review system prompts for conflicts after updating tool descriptions.

Practice Scenario

Scenario: An agent routes "check the status of order #12345" to get_customer instead of lookup_order. Both descriptions say "Retrieves [entity] information."

Options:

A) Add few-shot examples showing correct routing
B) Expand tool descriptions with explicit boundaries and example queries
C) Build a routing classifier to pre-select tools
D) Merge both tools into a single lookup tool

Reveal Answer

Correct: B. Low-effort, high-leverage. Fix the root cause (ambiguous descriptions) before adding complexity.

Check Questions

2.2 Structured Error Responses

Error Categories

MCP isError Flag

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "{\"errorCategory\": \"business\", \"isRetryable\": false, \"description\": \"Refund of $750 exceeds the $500 automatic refund limit. Requires manager approval.\"}"
  }]
}

Access Failure vs Valid Empty Result

This distinction is critical. The exam tests it.

Confusing these two breaks recovery logic.

Error Propagation in Multi-Agent Systems

• Subagents implement local recovery for transient failures
• Only propagate errors they cannot resolve locally
• Include partial results and what was attempted when propagating

Practice Scenario

Scenario: A tool returns an empty array after a customer lookup. The agent retries 3 times then escalates to a human. The actual issue: the customer's account does not exist.

Reveal Answer

Problem: Confusing a valid empty result with an access failure. The tool successfully queried the database — there simply is no matching account.

Fix: The tool should return structured metadata distinguishing "query succeeded, no results" from "query failed." The agent should treat empty results as a valid answer, not an error.

Check Questions

2.3 Tool Distribution and tool_choice

Tool Overload Problem

Giving an agent 18 tools degrades selection reliability. Optimal: 4-5 tools per agent, scoped to its role.

• A synthesis agent should NOT have web search tools
• A web search agent should NOT have document analysis tools

tool_choice Configuration

Scoped Cross-Role Tools

For high-frequency simple operations, give a constrained tool directly to the agent that needs it:

Synthesis agent gets: verify_fact (simple lookups only)
Complex verifications: route through coordinator

Result: 85% of verifications handled locally
         Eliminates 2-3 coordinator round trips per task
         40% latency reduction

The exam's Q9 tests this exact pattern.

Constrained Alternatives

Instead of giving a subagent fetch_url (can fetch anything), give it load_document that validates document URLs only.

Practice Scenario

Scenario: A synthesis agent frequently returns control to the coordinator for simple fact verification, adding 2-3 round trips per task and 40% latency. 85% of verifications are simple lookups.

Options:

A) Cache verification results in the coordinator
B) Give the synthesis agent a scoped verify_fact tool for simple lookups
C) Pre-compute all possible verifications before synthesis begins
D) Remove the verification step to reduce latency

Reveal Answer

Correct: B. A scoped tool handles the 85% simple case locally. Complex cases still route through the coordinator.

2.4 MCP Server Integration

Scoping Hierarchy

All tools from all configured servers are discovered at connection time and available simultaneously.

Environment Variable Expansion

// .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Keeps credentials out of version control. Each developer sets their own tokens locally.

MCP Resources

Expose content catalogues (issue summaries, documentation hierarchies, database schemas) as MCP resources. Gives agents visibility into available data without requiring exploratory tool calls.

Build vs Use Decision

Enhance MCP tool descriptions to prevent the agent from preferring built-in tools (like Grep) over more capable MCP tools.

2.5 Built-In Tools

Grep vs Glob

The exam deliberately presents scenarios where using the wrong one wastes time.

Read / Write / Edit

Incremental Codebase Understanding

1. Grep → find entry points (function definitions, imports)
2. Read → follow imports and trace flows from entry points
3. Do NOT read all files upfront (context-budget killer)

Practice Scenario

Task: Find all files that call a deprecated function oldValidator() and locate their test files.

Reveal Answer

Correct sequence:

1. Grep for oldValidator — finds caller files
2. Glob for test files matching caller filenames (**/*.test.tsx)

Domain 2 Practice Exam