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

5 Task Statements / Lessons

2.1 Tool Interface Design

JSON Schema best practices for input_schema: clear names, descriptions that tell the model when to call the tool, required vs optional parameters, enums for constrained values.

2.2 Structured Error Responses

Return structured, model-readable errors so Claude can recover or ask clarifying questions instead of hallucinating success.

2.3 Tool Distribution & Tool Choice

How many tools to expose at once, progressive disclosure of tools, tool routing / selection strategies when the set is large.

2.4 MCP Server Integration

Model Context Protocol: writing MCP servers, exposing resources/tools/prompts, client-side integration patterns, authentication and scoping.

2.5 Built-in Tools

Claude’s built-in tools (computer use, code execution, web search, etc.) — when to prefer them over custom tools and how they interact with the agentic loop.

---

Exam mindset: Prefer the simplest tool surface that solves the problem. Overly complex schemas and monolithic tool sets are common distractors.

CCAR-F Domain 2 · Task 2.1

What You Need to Know

Tool descriptions are the primary mechanism LLMs use for tool selection. Minimal descriptions leave the model no way to tell overlapping tools apart.

What Makes a Good Tool Description (5 elements)

1. What the tool does — primary purpose, stated unambiguously
2. What inputs it expects — data types, formats, constraints, required vs optional
3. Example queries it handles well — concrete use cases
4. Edge cases and limitations — what it does not do
5. Explicit boundaries — when to use this tool versus similar tools

Minimal (causes misrouting):

get_customer: "Retrieves customer information"
lookup_order: "Retrieves order details"

Production-grade:

get_customer: "Looks up a customer account by email address, phone number, or customer ID. 
Returns customer profile (name, contact details, account status, loyalty tier). 
Use this when you need to verify who the customer is. 
Do NOT use for order-specific queries — use lookup_order for those."

Tool Splitting

Generic tools with broad responsibilities create ambiguity. Split them into purpose-specific tools with defined input/output contracts.

Tool Renaming for Clarity

When two tools have confusingly similar names, renaming fixes the overlap at the interface level.

System Prompt Interactions

Keyword-sensitive instructions in system prompts can create unintended tool associations that override well-written descriptions. After updating descriptions, reread the system prompt for conflicts.

In the exam

When weak descriptions cause misrouting, improving them is the first fix (low effort, large effect). Prefer better descriptions before routing classifiers or tool consolidation.

Key Concept: When weak descriptions cause misrouting, improving them is the first fix. Diagnose whether you face a description problem or a toolkit-size problem (Task 2.3).

Exam Traps

• Choosing few-shot examples to fix misrouting caused by minimal descriptions
• Implementing a routing classifier as the first step
• Consolidating similar tools as the first step
• Ignoring system prompt wording after updating tool descriptions

Practice Scenario

An agent frequently calls get_customer when users ask about orders. Both tools have minimal descriptions. What is the most effective first step?

Build Exercise: Design Tool Descriptions That Eliminate Misrouting (30 min)

CCAR-F Domain 2 · Task 2.2

What You Need to Know

A structured error response tells the agent the error's category, whether a retry can work, and how to recover. The MCP protocol provides the isError flag.

Two Error Layers

1. Protocol errors — JSON-RPC errors (malformed request, unknown tool, schema failure). The model never sees a tool result.
2. Tool execution errors — The tool ran but something went wrong. Returned with isError: true. The model reasons about recovery.

The Four Error Categories

Category	isRetryable	Recovery
Transient (timeouts, rate limits, unavailability)	true	Resend the same call after a delay
Validation (bad format, missing fields)	false	Correct the input, send a new call
Business (policy violations, limits)	false	Alternative path or escalate
Permission (access denied)	false	Escalate or use different credentials

isRetryable answers one narrow question: will resending this exact request work? Only transient errors get true.

Access Failure vs Valid Empty Result

• Access failure = tool could not reach the data source → may be retryable
• Valid empty result = tool queried successfully and found no matches → not an error, do not retry

Confusing the two causes wasted retries and incorrect escalations.

Error Propagation in Multi-Agent Systems

1. Subagents implement local recovery for transient failures.
2. Only propagate errors that cannot be resolved locally.
3. Include partial results and what was attempted.

Exam Traps

• Retrying when a tool returns an empty result from a successful query
• Using generic error messages without structured metadata
• Treating business errors as retryable
• Marking a validation error isRetryable: true
• Reading isRetryable: false as "abandon the task"
• Silently suppressing subagent errors by returning empty results as success

Practice Scenario

A tool returns an empty array after a customer lookup. The agent retries 3 times, then escalates. The customer's account simply does not exist. What is the root cause of this wasted effort?

Build Exercise: Implement Structured Error Responses

CCAR-F Domain 2 · Task 2.3

What You Need to Know

Tool distribution is the choice of which agent in a multi-agent system holds which tools. The number of tools an agent holds directly affects selection reliability.

The Tool Overload Problem

Giving a single agent ~18 tools degrades selection reliability. Keep each agent's set small and scoped to its role (guide example: 4–5 tools per agent).

Choosing the Right Fix

Situation	Fix
Few tools, two read alike	Sharpen the descriptions (2.1)
Different jobs (query, transform, export)	Split by role, small set each
Variations on one job, sharing a shape	Consolidate into one parameterised tool
Doing more than the agent should	Constrain them (least privilege)

Moving tools onto a second MCP server does not help — the client hands the model every tool from every connected server as one flat list.

Replacing Generic Tools with Constrained Alternatives

Prefer load_document (validates document URLs only) over a generic fetch_url. This is least privilege applied to tool design.

Scoped Cross-Role Tools

For high-frequency simple lookups that would otherwise go through the coordinator (adding 2–3 round trips), give the agent a scoped version of the capability. Complex cases still route through the coordinator.

The tool_choice Configuration

Setting	Behaviour	Use when
"auto" (default)	Model decides whether to call a tool	General conversation
"any"	Model must call a tool, chooses which	Guaranteed structured output from one of multiple schemas
Forced ({"type":"tool","name":"..."})	Model must call one specific tool	Enforce a mandatory first step

Exam Traps

• Routing all simple verification requests through the coordinator when 85% are simple lookups
• Using tool_choice 'auto' when structured output is required
• Giving an agent 18 tools and expecting reliable selection
• Giving a subagent a generic fetch_url tool for loading documents

Practice Scenario

A synthesis agent frequently returns control to the coordinator for simple fact verification, adding 2–3 round trips and 40% latency. 85% of verifications are simple lookups. What is the most effective solution?

Build Exercise: Configure Tool Distribution Across a Multi-Agent System

CCAR-F Domain 2 · Task 2.4

What You Need to Know

An MCP server extends Claude by connecting it to an external system (database, API, development tool, issue tracker).

The Scoping Hierarchy

Level	File	Scope
Project	.mcp.json (repo root)	Version-controlled, shared with whole team
User	~/.claude.json	Personal, not shared

All tools from all configured servers (project + user) are discovered at connection time and available simultaneously.

Environment Variable Expansion

.mcp.json supports ${VARIABLE_NAME} syntax so credentials stay out of version control:

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}",
    "DATABASE_URL": "${DATABASE_URL}"
  }
}

Also supports ${VAR:-default} fallback form.

MCP Resources

Resources expose a content catalogue to an agent upfront (issue lists, documentation hierarchies, database schemas). This reduces exploratory tool calls. Resources show agents what data is available; tools let them act on it.

The Build-vs-Use Decision

• Use community servers for standard integrations (Jira, GitHub, Slack, Linear, Notion).
• Build custom only for team-specific workflows, custom business logic, or proprietary internal systems with no community server.

Detailed MCP Tool Descriptions

When an MCP tool has a sparse description, the agent may prefer a built-in tool even when the MCP tool is more capable. Write detailed descriptions that explain capabilities and outputs.

Exam Traps

• Building a custom MCP server for a standard integration like Jira
• Putting team-wide MCP configuration in ~/.claude.json
• Pasting a token into .mcp.json
• Adding a system prompt rule or removing built-in tools to force use of an MCP tool

Practice Scenario

A team needs to integrate with Jira. A developer proposes building a custom MCP server. What is the correct first step?

Build Exercise: Configure MCP Servers with Scoping and Environment Variables (30 min)

CCAR-F Domain 2 · Task 2.5

What You Need to Know

Claude Code provides six built-in tools: Read, Write, Edit, Bash, Grep, Glob.

Grep vs Glob

Tool	Purpose
Grep	Searches file contents for patterns (function callers, error messages, imports)
Glob	Matches file paths by naming patterns (test files, config files, extensions)

Grep finds what is inside files. Glob finds files by their names.

Read, Write, and Edit

• Edit — targeted changes using unique text matching. Fast and precise. Default for modifications.
• When Edit cannot find a unique anchor → Read + Write (fallback). Do not default to Read + Write for every change (burns context tokens).

Real-work order:

1. Try Edit with shortest plausible unique anchor.
2. Widen old_string or use replace_all: true if needed.
3. Fall back to Read + Write only when neither works.

On the exam: answer Read + Write as the fallback.

Incremental Codebase Understanding

Never read every file upfront. Instead:

1. Grep to find entry points.
2. Read to follow imports and trace flows.
3. Grep again for wrapper / re-exported names.
4. Read only what you need.

Tracing Function Usage Across Wrappers

1. Grep for the function definition.
2. Read the defining file to identify exported names.
3. Grep for each exported name.
4. If re-exported through a barrel, Grep for the barrel module name too.

Finding Callers and Their Tests

1. Grep for the function name (finds callers and direct test imports).
2. Glob for sibling test files by naming convention.
3. Grep again for wrapper names if applicable.

Exam Traps

• Using Glob to find function callers
• Using Grep to find files by extension or naming pattern
• Reading all source files upfront
• Defaulting to Read + Write for every modification
• Wrong tool sequence for deprecation / caller+test discovery

Practice Scenario

Find all files that call a deprecated function and all test files for those callers. Repository is large; Bash is not allowed. Which tool sequence is correct?

Build Exercise: Trace and Refactor a Deprecated Function Using Built-in Tools (30 min)