D2 · Tool Design & MCP › Cluster 2 · Designing Great Tools

2.4 · Namespacing & Avoiding Tool Overlap

Stop Claude picking the wrong tool

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 namespacingWith namespacing
search (CRM) vs search (docs)crm_search · docs_search
send — send what, where?slack_send_message · email_send
list, get, creategithub_list_prs · github_get_pr
🔑 Namespacing is the naming-level defense against overlap; consolidation (2.3) is the granularity-level defense. Detailed descriptions (2.1) that state "when NOT to use" are the semantic defense. Use all three together.

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

flowchart TD REQ["User request"] --> L1{"Distinct names?
(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

Trap: "Claude picked the wrong tool → it's a model problem." → Usually it's a design problem: overlapping tools. Fix with namespacing, consolidation, and boundary-setting descriptions before blaming the model.
Trap: Reusing generic verbs across services (search, get, send). → Collisions are inevitable. Prefix with the service: github_list_prs, slack_send_message.
Trap: Ignoring namespacing "because there are only a few tools." → Libraries grow, and namespacing is especially important with tool search, which selects by matching names/descriptions.
Trap: Prefixing names but leaving descriptions overlapping. → Add a "when NOT to use, use X instead" boundary in each description to close the remaining ambiguity.

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).