# Tool descriptions, boundaries and naming

*Claude Certified Architect - Foundations Study Guide · Tool Design & MCP Integration · Last updated October 22, 2026 · https://www.certifyforce.com/study-guide/claude-certified-architect-foundations/tool-design-and-mcp-integration/tool-descriptions-boundaries-and-naming*

How Claude picks a tool from its name and description, and how to fix misrouting: descriptions that state what, when, inputs and limits; renaming and namespacing overlapping tools; splitting generic tools or consolidating endpoint wrappers; and removing system-prompt wording that overrides good descriptions.

- Certification: Claude Certified Architect - Foundations
- Exam section: Tool Design & MCP Integration
- Study guide: https://www.certifyforce.com/study-guide/claude-certified-architect-foundations

**Official exam objective:**

> Design effective tool interfaces with clear descriptions and boundaries

## What the exam expects

- Diagnose why Claude calls the wrong tool (or none): description, name, tool shape or system prompt.
- Write a tool description that states what the tool does and returns, when to use it and when not to, what each input means and its format, and the tool's limits.
- Remove functional overlap between similar tools by renaming them and rewriting their descriptions (for example `analyze_content` renamed to `extract_web_results`).
- Split a generic tool into purpose-specific tools with defined input and output contracts, and replace endpoint-per-tool wrappers with fewer workflow tools.
- Review a system prompt for keyword-triggered or aggressive tool instructions that override well-written descriptions.

Key terms: **tool description** (the plain-text `description` field Claude reads to decide when and how to call a tool); **misrouting** (tool A called when the request needed tool B); **namespacing** (a shared service or resource prefix such as `tracker_search`); **input contract** (the `input_schema` with named, described parameters); **overtriggering** (a tool called more than the task needs).

## Key facts

| Fact | Detail | Source |
|---|---|---|
| Most important factor in tool performance | Extremely detailed descriptions; at least 3-4 sentences per tool | [Define tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools) |
| What a description covers | What it does, when to use and not use it, each parameter's meaning, caveats and what it does not return | [Define tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools) |
| Fix for "calls tool A instead of B" | Differentiate tools by when to use them, not only what they do | [Troubleshooting tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use) |
| Cause of "never calls your tool" | Duplicate names across the tool list or an overly generic schema | [Troubleshooting tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use) |
| API tool name format | `^[a-zA-Z0-9_-]{1,128}$` | [Define tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools) |
| MCP name uniqueness | Scoped to one server; aggregating clients should prefix a server identifier | [MCP tools spec](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) |
| Parameter naming | `user_id`, not `user` | [Writing effective tools](https://www.anthropic.com/research/writing-tools-for-agents) |
| `input_examples` | Optional; each example must validate against `input_schema` or the request returns 400 | [Define tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools) |
| Aggressive tool wording | "CRITICAL: You MUST use this tool" and "If in doubt, use [tool]" cause overtriggering | [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) |

## Check yourself

- Why does adding when-to-use guidance fix routing when both descriptions are already accurate?
- When should you split a tool rather than rewrite its description?
- What should a parameter called `user` become, and why?
- Why can a well-described tool still lose to another tool?

## Sources

- [Define tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools)
- [Writing effective tools for AI agents](https://www.anthropic.com/research/writing-tools-for-agents)
- [Troubleshooting tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
- [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)
- [Tools (MCP specification 2026-07-28)](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
- [Claude Certified Architect – Foundations Exam Guide v1.0](https://everpath-course-content.s3-accelerate.amazonaws.com/instructor%2F6nizmqk8tpzpfjvt6qmmav7rh%2Fpublic%2F1783542750%2FClaude+Certified+Architect+%E2%80%93+Foundations+Exam+Guide.pdf)

## About the full unit

The "Core concepts", "Exam traps" and "Worked scenario" sections of this unit, its 11 linked practice questions, and unlimited timed mock exams are included with the Claude Certified Architect - Foundations pack (USD $19): https://www.certifyforce.com/practice-exams