When Claude chooses which tool to call, it reads the tool descriptions you provided. Descriptions are a major input alongside the task, system instructions, schemas, tool availability, and any host routing policy. If your descriptions are vague, overlapping, or missing edge case guidance, the model will misroute — and it will do so silently, with full confidence.
This is the core subject of Domain 2 of the Claude Certified Architect – Foundations exam (Tool Design & MCP Integration, 18% weight). Domain 2 tests whether you can design tool boundaries that produce consistent, reliable selection behavior at scale.
Why minimal descriptions fail
Consider a tool registered with this description:
{
"name": "search",
"description": "Search for information.",
"input_schema": { ... }
}
The model has no basis for choosing search over any other tool. "Search for information" describes approximately 40% of possible tool actions. In a multi-tool environment, this produces random-looking selection behavior that is actually consistent — consistently based on nothing useful.
The minimum viable description answers four questions:
- What does this tool return? Not what it does — what it returns.
- What inputs does it expect? Format, type, any constraints.
- When should it be used over alternatives? Explicit comparison to similar tools.
- When should it NOT be used? Edge cases and out-of-scope inputs.
A rewritten version:
{
"name": "search_web",
"description": "Returns a ranked list of URLs and page excerpts from a live web index. Use when the user's question requires current information (published within the last 90 days) or when the answer is not available in internal documents. Do NOT use for queries about internal company policies, product catalog data, or historical records — use search_internal_docs for those.",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query in natural language or keyword form. Do not include URLs."
}
},
"required": ["query"]
}
}
The added boundary explanation (Do NOT use for...) is the highest-leverage addition. It disambiguates selection when two tools overlap in apparent purpose.
Naming tools to prevent overlap (Task Statement 2.1)
Tool names contribute to selection before descriptions are fully read. Names should be distinct enough that a partial match does not create ambiguity. Two problematic patterns:
Generic verbs: search, get, fetch, process — these names overlap across every tool in the set.
Symmetric names: analyze_content and extract_content sound different to a human but look nearly identical in embedding space. The model may call either when the task involves content.
Preferred naming convention: {verb}_{domain}_{specificity}
search_web_current— live web indexsearch_internal_docs— internal document storeextract_web_results— structured extraction from web outputanalyze_sentiment— sentiment analysis, not general analysis
The exam presents scenarios where tool name overlap causes selection failures and asks you to identify the fix. The fix is almost always renaming combined with description boundary language.
Scoping tool sets per agent role (Task Statement 2.2)
Giving an agent 18 tools degrades reliability in two ways:
- Distraction: The model considers irrelevant tools on every turn, increasing the chance of spurious selection.
- Ambiguity expansion: Each additional tool with overlapping semantics grows the decision boundary confusion region.
The reliable pattern is role-scoped tool sets: each agent receives only the tools needed for its specific function. A web research subagent gets search_web, fetch_page, extract_web_results. A document analysis subagent gets load_document, search_internal_docs, extract_document_section. Neither has access to the other's tools.
In the Claude Agent SDK, you implement this by passing different tools arrays to different agent instances. In MCP terms, you connect different MCP servers to different agents, or configure the same server with filtered tool exposure.
Starting heuristic: expose only the tools needed for the role, then measure selection and argument accuracy on representative requests. There is no universal safe tool count established here.
The exam tests this as a reliability question: "An agent with 15 tools is misrouting queries. What is the most effective architectural change?" The answer is decomposing into role-scoped subagents with smaller tool sets, not rewriting descriptions.
tool_choice: auto, any, and forced (Task Statement 2.3)
The tool_choice parameter controls whether Claude must call a tool and which:
| Setting | Behavior | Use case |
|---|---|---|
auto | Claude decides whether to call a tool or return text | Most agentic turns — default for open-ended tasks |
any | Claude must call at least one tool | Steps where a tool call is mandatory but the specific tool is flexible |
{ type: "tool", name: "X" } | Claude must call tool X | Forced completion steps, structured submission, testing specific tool behavior |
Choosing the wrong tool_choice is a common exam answer trap. any does not guarantee the right tool is called — it only guarantees some tool is called. If you need a specific tool (like submit_result at the end of a workflow), use forced tool_choice with the tool name.
When to use any: multi-step retrieval where the agent should gather information (any retrieval tool is acceptable) before synthesis.
When to use forced: the final extraction step where the output must conform to a specific schema via a specific tool call.
isError flag and structured error responses (Task Statement 2.4)
Tools that fail should not return empty results or generic strings. MCP CallToolResult uses an isError flag and a content array. Do not confuse that result with a provider-specific tool-result message. For example:
{
"content": [{
"type": "text",
"text": "External search is rate-limited; retry only within the configured budget."
}],
"isError": true
}
Four fields that matter in structured error responses:
errorCategory: Machine-readable type (RATE_LIMIT,NOT_FOUND,PERMISSION_DENIED,VALIDATION_ERROR). Enables coordinator-level routing logic.isRetryable: Boolean. Tells the coordinator whether retrying the same call makes sense.attemptedQuery: What was tried. Prevents the model from re-attempting the same failed query in different phrasing.suggestedAlternative: Which tool or approach to try instead. Enables intelligent recovery without coordinator-level hardcoding.
The isError: true flag is how the coordinator distinguishes an empty result (tool ran successfully, found nothing) from a failure (tool did not complete). Both can return content, but only failures set isError: true.
This distinction is tested directly in Domain 2 and Domain 5 questions: "A tool returns an empty array. Is this a success or failure?" Without isError, you cannot tell from the result alone.
MCP configuration: project vs user scope
The .mcp.json file controls which MCP servers are available in a given context. Two scopes matter:
Project scope (.mcp.json in the project root): Server definitions committed to the repository. Every team member working on the project gets the same tool set. Use for tools that are part of the project's defined workflow (internal APIs, project-specific data sources).
User scope (~/.claude/mcp.json or equivalent): Personal server definitions not shared with the team. Use for developer-local tools (local database connections, personal API keys, debugging tools that should not run in CI).
The exam tests this as a configuration question: "A team member adds a tool that should only run on their local machine during development. Which scope is correct?" Answer: user scope, not project scope. Committing development-only tools to .mcp.json exposes them in CI and to all team members.
Conflict resolution when the same server name appears in both scopes: user scope takes precedence. This matters when a developer needs a custom version of a project tool for local testing.
What the exam actually tests in Domain 2
Task Statements 2.1-2.4 map to concrete scenarios:
- 2.1 (Tool naming and descriptions): Given a scenario with selection failures, identify whether the fix is renaming, adding boundary language, or splitting into separate tools.
- 2.2 (Tool set scoping): Given an agent with too many tools, design the correct subagent decomposition.
- 2.3 (tool_choice): Select the correct
tool_choicevalue for a given workflow step. - 2.4 (Error handling): Design a structured error response that enables coordinator recovery, or identify why a generic error response fails.
The customer support resolution agent scenario is the primary frame for Domain 2: tools like get_customer, lookup_order, process_refund, and escalate_to_human have clear role boundaries but require careful description writing to prevent misrouting (for example, calling process_refund when lookup_order was the correct first step).
Key takeaways
- Tool descriptions are the selection mechanism. Vague descriptions produce vague selection.
- Add explicit boundary language: what this tool does NOT handle, and which tool handles those cases instead.
- Name tools with verb-domain-specificity to prevent name-level ambiguity.
- Scope tool sets to 4-5 tools per agent role. Decompose multi-purpose agents into role-specific subagents.
tool_choice: autofor open steps,anywhen a tool call is required but the specific tool is flexible, forced for specific tool requirements.- Use
isError: truewith structured error fields (errorCategory,isRetryable,suggestedAlternative) to enable intelligent recovery. - Project scope for team tools, user scope for developer-local tools.
This is a core topic in Domain 2 of the Claude Certified Architect – Foundations exam. Practice CCA scenario questions to test your ability to identify tool design failures in realistic agent architectures.
Test the boundary between adjacent tools
Write a small request set for every pair of tools that overlap. If one tool searches documents and another fetches a known document, include a request asking where a policy is documented and another naming the exact document identifier. The expected first action should differ, and your evaluation should make that distinction visible.
Record tool selection and argument correctness separately. The agent may choose the right tool while supplying a filename where an identifier is required. Tightening the description addresses a different problem from fixing the input schema or validating an argument server-side.
Include a no-result case and a permission-denied case. The first can justify a broader search; the second should not prompt the agent to bypass access controls. Error messages should explain the supported recovery path without exposing sensitive information.
Check the MCP tool specification when constructing responses. MCP result envelopes and a model provider's tool-result message are related but distinct interfaces. Keep the tool's return contract clear at the boundary where your host translates between them.
After a description change, rerun the same request set. One convincing demonstration is a start, but repeated adjacent-tool cases show whether the wording actually improved selection rather than simply making the example read better.
Related on explainx.ai
- Agent Seer: Apple's method for turning your MCP spec into an eval suite — new research confirming argument-value accuracy (not just tool selection) is the dominant agent failure mode
- The new MCP roadmap (Aug 22, 2026) — progressive tool discovery, the roadmap's answer to large tool catalogs, builds directly on the scoping discipline in this guide
- What is MCP? Model Context Protocol architecture guide
- MCP security guide 2026
Exam domain weights and task statements are based on the Claude Certified Architect – Foundations Certification Exam Guide published by Anthropic Academy. Verify current content on Anthropic Academy before your exam date.