CCAR-F MCP tool design: descriptions, scope and errors

In the guide's sample scenario, an agent calls get_customer for order questions because both tools have minimal descriptions. The fix it favors is better descriptions, not a routing layer.

01 What does CCAR-F test about tool design and MCP?

A question shows an agent picking the wrong tool, and three fixes sound reasonable. The guide's rule: descriptions are the primary mechanism LLMs use to select tools, so minimal ones leave similar tools indistinguishable.

Expect scenarios on misrouting, overlapping tools, tool count and error handling.

When an agent misroutes, fix the descriptions before adding routing layers or examples.

02 What belongs in a tool's interface?

A checklist for a tool interface

1. 01DescriptionPurpose, input formats, example queries and edge cases
2. 02BoundariesWhen to use it versus similar tools, with no overlapping names
3. 03ScopeA constrained tool, such as load_document instead of fetch_url
4. 04Error responsesError category, whether a retry helps, and a readable message

The guide's first fix for misrouting expands each description with input formats, example queries, edge cases and boundaries versus similar tools. It also splits generic tools, turning analyze_document into extract_data_points, summarize_content and verify_claim_against_source.

Keep the set small: giving an agent 18 tools instead of 4-5 degrades selection reliability.

A good tool says what it does, when not to use it, and what it accepts.

03 How should a tool report errors?

A generic status such as "search unavailable" hides context, and returning empty results as success silently suppresses the failure. The guide separates access failures, like timeouts that need a retry decision, from valid empty results.

Its exercise adds structured errors with errorCategory, an isRetryable boolean and a readable description. In the Messages API, you flag a failure by setting is_error to true on the tool result. In the Agent SDK, Claude can then retry, try a different tool or explain the failure.

Return errors the agent can act on: what failed, whether to retry, and why.

04 What does MCP add to tool design?

An MCP tool definition carries a unique name, a description, an inputSchema and an optional outputSchema. Tools are model-controlled, while resources such as files or database schemas are application-driven context.

With many servers connected, Claude still selects tools by name and description, and defer_loading with the tool search tool surfaces only the relevant ones.

Tools are actions the model chooses; resources are context the host provides.

Summary

1. Descriptions drive tool selection; minimal ones cause misrouting.
2. Rename, split or constrain tools that overlap, and keep the set small.
3. Structured errors beat generic failures and silent empty results.
4. MCP tools are model-controlled; resources are application-driven.

Sources and editorial status

Research checked Nov 3, 2026.

1. Claude Certified Architect – Foundations Exam Guide Version 1.0 · Effective July 2026 · Exam code: CCAR-F · This guide i
2. Handle tool calls - Claude Platform Docs
3. Give Claude custom tools - Claude Code Docs
4. Tools - Model Context Protocol
5. Resources - Model Context Protocol
6. MCP connector - Claude Platform Docs