CCA Domain 2: Tool Design & MCP Integration Explained

Domain 2 of the CCA-F exam, Tool Design & MCP Integration, is 18% of the score and tests whether you can design tools an agent will select correctly, return errors an agent can recover from, keep the tool count within reliable limits, and configure MCP servers at the right scope. The recurring idea is that a tool definition is an interface for the model, not documentation for a human.

This post covers what the domain includes, why it is weighted where it is, the concepts you must know cold, how the exam phrases them, a worked scenario, and the traps. It is built on our 21-article Domain 2 study guide, and every concept below links to the article that goes deeper.

What does CCA Domain 2 cover?

Five task areas. The table lists the anchor article for each.

Task	What it tests	Start here
2.1 Tool description and selection	How description quality drives routing accuracy; splitting overloaded tools	30% Misrouting with Minimal Descriptions, Near-Zero with Detailed Ones
2.2 Error handling and isError	Structured errors, error classification, access failure vs valid empty	Structured Errors: 78-95% Recovery vs 15% for Generic “Operation Failed”
2.3 Tool count and reliability	The accuracy curve, tool_choice modes, least-privilege tool sets	3 Tools = 97% Accuracy, 18 Tools = 51%: The Tool Count Curve
2.4 MCP server scope	.mcp.json vs ~/.claude.json, env-var expansion, resources vs tools	Project Scope in .mcp.json, User Scope in ~/.claude.json
2.5 Built-in tool responsibilities	Read, Grep, Glob, Edit, Write, Bash and when each applies	Each Built-in Tool Has One Job

If MCP itself is new to you, read the Foundations primer first: MCP: One Protocol to Connect Them All and Tools, Resources, and Prompts: MCP’s Three Primitives. Domain 2 assumes you know that layer.

Why is Domain 2 weighted at 18%?

Tools are where an agent touches the world, and most production agent failures we see are tool failures in disguise: the model called the wrong tool, retried an unrecoverable error five times, or told a customer their order does not exist because a timeout was returned as an empty result. Anthropic weights this at 18%, a little below the two 20% domains, because the concept count is smaller, but the questions are unusually concrete and therefore learnable. On a 60-question form that is roughly 11 questions (confirm the current weights on the official page before you register).

The concepts you must know cold

Descriptions are the routing signal. A description with purpose, input format, output format, example use cases, and a “do NOT use for X, use Y instead” line produces near-perfect selection. Five-word descriptions produce 30% misrouting between similar tools. When two tools keep getting confused, fix the specific pair rather than rewriting everything, as described in Data-Driven Description Fixing: Target the High-Misrouting Pairs. And a system prompt full of keyword rules (“if the user says ‘search’, use tool A”) often makes routing worse, see Removing Keyword Rules Improved Routing from 78% to 94%.

isError: true is the start, structure is the rest. A tool that fails should return isError: true plus enough metadata for the agent to decide what to do: an error category, whether it is retryable, a message that can be relayed to the user, and a suggested next action. Without classification, an agent burns retries on a permission error that will never succeed (Without Classification, the Agent Wastes 5 Retries on a Permission Error). The rule for local retry versus propagating upward is in Retry Locally First, Propagate with Context If Recovery Fails.

Access failure is not an empty result. A timeout must be isError: true. A successful query with zero rows is isError: false. Conflating them makes the agent tell a customer their confirmed order does not exist. This one shows up in Domain 2 and again in Domain 5, so learn it once from “Your Order Doesn’t Exist” — But It Does, the Database Was Just Down.

Tool count has a curve. Selection accuracy is near-perfect at three to five tools and drops steeply past eight. When an agent needs fifteen tools, split into specialists with four or five each and let a coordinator route. Give each role only its own tools (Least Privilege: Each Agent Gets Only Its Role’s Tools). Know the four tool_choice modes and what each guarantees (tool_choice: auto, any, tool, none).

MCP scope is a file location question. Team-shared servers go in .mcp.json at the project root, committed to git, with secrets referenced as ${ENV_VAR} (${ENV_VAR}: Keep Secrets Out of Version Control). Personal servers go in ~/.claude.json. Writing “use the GitHub server” in CLAUDE.md configures nothing. Resources let the model browse content without a tool call (MCP Resources: Browse Content Without Tool Calls), and all configured servers connect at startup (All MCP Servers Connect at Startup).

Built-in tools have single jobs. Grep searches content, Glob searches paths, Read before Edit, and Read plus Write is the fallback when Edit’s exact-match fails (When Edit Fails: Read + Write as Fallback).

How does the exam test Domain 2?

The scenarios are operational. Expect a described tool set or MCP setup, a measured symptom, and four fixes. Patterns we see repeatedly in practice questions:

• “Contracts keep being routed to the invoice-extraction tool.” (Descriptions differ by one word; add distinguishing document characteristics.)
• “The agent retries a 403 five times, then gives up.” (Return an error category and isRetryable: false, with a suggested action.)
• “A new engineer clones the repo and the Jira MCP server is missing.” (It was configured in ~/.claude.json; move it to .mcp.json with env-var secrets.)
• “The billing agent has 14 tools and picks the wrong one a third of the time.” (Split into role-scoped specialists.)
• “Which tool finds every file that imports auth.ts?” (Grep, because it searches content; Glob matches names.)
• “Should the team write a custom Slack server?” (No; use the community server for a standard integration, see Use Community Servers for Standard Integrations.)

Worked scenario: an order-lookup tool during an outage

Setup. A support agent has a lookup_order MCP tool. During a database incident, the tool’s handler catches the timeout and returns { isError: false, content: "No results found" }. The agent tells several customers their orders do not exist. Later, an engineer proposes returning { isError: true, content: "Operation failed" } for every exception.

Options.

A. Keep the empty result but add “the database may be down” to the system prompt. B. Return isError: true with a generic “Operation failed” message for all exceptions. C. Return isError: true with a structured payload: category transient, isRetryable: true, the attempted order_id, and a customer-safe message; keep isError: false for genuine zero-row results. D. Remove the tool and have the agent ask customers to call back.

Reasoning. A leaves the false-negative in place and hopes the prompt covers it. B fixes the silent swallow but reintroduces the uniform-error anti-pattern from “Operation Failed” × 5 Retries × 30 Seconds: the agent cannot tell a transient outage from a permission error, so it retries both identically. D throws away the capability. C distinguishes access failure from valid empty, tells the agent whether to retry, and includes the attempted query so the retry is exact. C is the least bad option, and it is the pattern the structured error article documents.

Common traps in Domain 2 questions

• Designing tools around the backend API. One manage_calendar tool with an action parameter mirrors the REST endpoint but forces the model to mode-switch, which produces parameter errors. Purpose-specific tools with tailored schemas win. See the three-field breakdown in Three Fields, All Critical: name, description, input_schema.
• Adding “just in case” tools. Seven extra tools drop a three-tool agent from near-perfect to about 80% selection accuracy. Every tool must earn its place.
• Confusing the Claude API and MCP definition formats. MCP uses inputSchema (camelCase); the Claude Messages API uses input_schema. The Foundations article The camelCase Trap is short and worth a re-read.
• Human-readable error text with no machine-readable fields. “Something went wrong, please try later” is fine for a user and useless for an agent deciding whether to retry.
• Choosing tool_choice: auto when a tool call must happen. Auto lets the model answer in text. any guarantees some tool is called; a named tool forces one schema.
• Putting credentials in .mcp.json. It is committed. Reference ${TOKEN} and let each developer set it locally.
• Answering with a custom server when a community one exists. The exam rewards using mature integrations for standard services and building custom servers only for proprietary systems.

Next step

Work through the five anchor articles above, then the Domain 2 practice set. Because Domain 2 questions are concrete, your accuracy should climb quickly; once you are steady, sit the free CCA-F mock exam to see the domain in proportion with the other four. The full list of Domain 2 articles is on the Domain 2 study guide page, and the study-plan version of this post is CCA Study Tips for Domain 2.