Domain 2: Tool Design & MCP Integration

Before You Begin

Executive Summary

Highest-Leverage Principles

Tool descriptions are the primary mechanism Claude uses for tool selection. Vague or overlapping descriptions cause misrouting that is difficult to debug.

The correct fix for misrouting is better descriptions — not few-shot examples, not routing classifiers, not tool consolidation.

Optimal tool count per subagent: 4 to 5. Beyond this, selection reliability degrades measurably.

Prefer community MCP servers for standard integrations. Build custom only when community servers genuinely cannot meet the requirement.

TASK STATEMENT 2.1

Tool Interface Design

A tool description is not a one-liner. It is the specification the model uses to decide whether to call this tool or a similar one. Treat it accordingly.

What a Good Tool Description Includes

Primary purpose — what does this tool do?
Expected inputs — formats, types, and constraints.
Representative queries — example questions this tool answers well.
Edge cases and limitations — what this tool does not handle.
Explicit disambiguation — when to use this tool versus similar tools.

// ✗ Weak description — causes misrouting
get_customer: "Retrieves customer information"
lookup_order: "Retrieves order information"

// ✓ Strong descriptions — clear selection signals
get_customer: "Retrieves account profile, contact details, and account
  status for a customer. Use when the query is about WHO the customer is:
  their name, email, phone, account tier, or account standing.
  Do NOT use for order status, shipping, or purchase history."

lookup_order: "Retrieves the status, items, shipping details, and
  payment information for a specific order. Use when the query
  references an order number, shipment, or purchase. Do NOT use
  for customer account or profile information."

Tool Splitting

Split generic tools into purpose-specific tools with defined input and output contracts. Example: split analyze_document into three tools — extract_data_points, summarize_content, and verify_claim_against_source. Each tool's scope is now clear and unambiguous.

Practice Scenario 2.1

Persistent Misrouting

An agent routes "check the status of order #12345" to get_customer instead of lookup_order. Both descriptions say "Retrieves [entity] information." Options: A) better descriptions, B) few-shot examples, C) routing classifier, D) consolidate into one tool.

Answer: A — Better descriptions. This is the first step and addresses the root cause directly. Few-shot examples add token overhead without fixing the underlying ambiguity. A routing classifier is over-engineered for a description problem. Tool consolidation trades one problem for another.

TASK STATEMENT 2.2

Structured Error Responses

Category	Example	Retryable?	Action
Transient	Timeout, service unavailability	Yes	Retry with backoff.
Validation	Wrong format, missing required field	Yes (fix input first)	Fix input, then retry.
Business	Refund exceeds policy limit	No	Alternative workflow required.
Permission	Access denied	No	Escalate or use different credentials.

Critical Distinction — Tested Directly

Access failure: the tool could not reach the data source (timeout, auth failure). The agent should consider retrying.

Valid empty result: the tool successfully queried the source and found no matching records. The agent should not retry. The answer is "no results."

Confusing these two breaks recovery logic. An agent that retries a "no results" response is wasting compute on a known answer.

TASK STATEMENT 2.3

Tool Distribution and tool_choice

Tool Overload

Giving a single agent 18 tools degrades selection reliability. The optimal range is 4 to 5 tools per agent, scoped strictly to that agent's role. A synthesis agent should not have web search tools. A web search agent should not have document analysis tools.

Setting	Behaviour	Use When
`"auto"`	Model decides whether to call a tool or return text.	Default. General operation.
`"any"`	Model must call a tool, chooses which.	Guaranteed structured output from multiple schemas.
`{"type":"tool","name":"..."}`	Model must call this specific named tool.	Force mandatory first steps before enrichment.

TASK STATEMENT 2.4

MCP Server Integration

Level	Location	Shared?
Project-level	`.mcp.json` in the repository	Yes — version-controlled, shared with team
User-level	`~/.claude.json`	No — personal, not version-controlled

// .mcp.json — environment variable expansion for credentials
{
  "servers": {
    "github": {
      "url": "https://mcp.github.com",
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"  // keeps secrets out of version control
      }
    }
  }
}

Build vs Use Decision

Evaluate existing community MCP servers before building a custom one. Community servers exist for Jira, GitHub, Slack, and many other standard integrations. Build custom servers only for team-specific workflows that community servers genuinely cannot handle.

TASK STATEMENT 2.5

Built-In Tools

Tool	Searches	Use For
Grep	File contents	Finding function callers, locating error messages, searching import statements.
Glob	File paths	Finding files by extension (`*/.test.tsx`), locating configuration files.
Edit	—	Targeted modifications using unique text matching. Fast and precise.
Read + Write	—	Reliable fallback when Edit cannot find unique anchor text.

When exploring an unfamiliar codebase: start with Grep to find entry points, then use Read to follow imports. Do not read all files upfront — this exhausts the context budget before any useful work is done.

Hands-On Build Exercise

Build: MCP Tools with Intentional Ambiguity

Create three MCP tools — including one intentionally ambiguous pair with near-identical descriptions.
Observe how the model misroutes. Document the failure pattern.
Fix the descriptions and observe the improvement. Note what changed.
Write error responses for all four error categories with appropriate isRetryable flags.
Configure the tools in .mcp.json with environment variable expansion for credentials.
Test tool_choice forced selection to enforce a mandatory first step in a workflow.