CONCEPT Overlap is the root cause of wrong-tool selection
When two tools have similar names and similar descriptions, Claude has to guess which one you meant — and
sometimes guesses wrong. As a tool library grows (multiple services, MCP servers, resource types), the odds of
a collision rise: a bare search from your CRM and a bare search from your docs system
are indistinguishable at selection time. Overlap — not model capability — is the usual cause of
wrong-tool selection. The primary fix is to make each tool's identity unambiguous.
CONCEPT Namespace tool names by service/resource
Anthropic's guidance: use meaningful namespacing in tool names. When your tools span
multiple services or resources, prefix the name with the service —
github_list_prs, slack_send_message, jira_create_ticket. The prefix makes
selection unambiguous as the library grows, and it's especially important when using the
tool search tool, where Claude discovers tools by matching names and descriptions against the
query rather than seeing all of them up front.
| Without namespacing | With namespacing |
|---|---|
search (CRM) vs search (docs) | crm_search · docs_search |
send — send what, where? | slack_send_message · email_send |
list, get, create | github_list_prs · github_get_pr |
CONCEPT Disambiguate with "when NOT to use"
Even with prefixes, two tools can be functionally close. Close the remaining gap in the
descriptions: state each tool's boundary and explicitly point to its sibling — "Use
crm_search for customer records; for product documentation use docs_search instead."
Cross-referencing the alternative in each description is the cheapest way to kill a lingering ambiguity.
DIAGRAM Three layers that prevent wrong-tool selection
(namespacing)"} L1 -->|"crm_search vs docs_search"| L2{"Non-overlapping scope?
(consolidation)"} L1 -->|"search vs search"| BAD["🔴 Collision →
wrong-tool selection"] L2 -->|"few, well-scoped tools"| L3{"Descriptions say
when NOT to use?"} L2 -->|"many lookalike tools"| BAD L3 -->|"yes: cross-reference sibling"| GOOD["🟢 Unambiguous
selection"] L3 -->|"no boundary stated"| BAD BAD -.->|"add prefix + boundary"| GOOD classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class GOOD ok; class BAD bad;
CODE Namespaced names + boundary-setting descriptions
Two search tools that used to collide. The service prefix disambiguates the name; the cross-reference in each description disambiguates the intent.
[
{
"name": "crm_search", // service prefix
"description": "Search the customer CRM for accounts, contacts, and "
"deals by name, email, or company. Use for questions about customers "
"or sales records. For product documentation, use docs_search "
"instead.", // ← points at the sibling
"input_schema": { "type": "object",
"properties": { "query": { "type": "string",
"description": "Customer name, email, or company" } },
"required": ["query"] }
},
{
"name": "docs_search",
"description": "Search internal product documentation and how-to guides. "
"Use for questions about how the product works. For customer or sales "
"records, use crm_search instead.",
"input_schema": { "type": "object",
"properties": { "query": { "type": "string",
"description": "Topic or feature to look up" } },
"required": ["query"] }
}
]
TRADE-OFFS Namespaced vs. bare names
✅ Namespaced, boundaried tools
- Selection stays unambiguous as the library grows
- Essential for tool search (name/description matching)
- Cross-references route Claude to the right sibling
⚠️ Bare, overlapping names
- Shorter, cleaner-looking in isolation
- But: collisions the moment a second service is added
- Wrong-tool selection Claude can't reason its way out of
EXAM TRAPS
search, get,
send). → Collisions are inevitable. Prefix with the service: github_list_prs,
slack_send_message.PRACTICE
Q1 · Two tools both named search from different systems. What's the fix?
Namespace the names by service — crm_search and docs_search — and add
a boundary line to each description pointing at the sibling. Anthropic recommends prefixing tool names with the
service when tools span multiple services or resources.
Q2 · Why does namespacing matter most with the tool search tool?
Tool search discovers tools by matching the query against names and descriptions rather than loading them all up front. Distinct, service-prefixed names make that matching unambiguous, so the right tool surfaces for the right query.
Q3 · Name the three complementary defenses against wrong-tool selection.
(1) Namespacing — distinct, service-prefixed names (2.4); (2) consolidation — fewer, well-scoped tools so there's less to overlap (2.3); (3) detailed descriptions stating when NOT to use a tool and which sibling to use instead (2.1).