The Ambiguous Tool Naming Trap
TRIGGER
Agents with access to dozens of MCP servers and hundreds of tools were calling wrong tools or getting confused when tools overlapped in function—a generic `search` tool could apply to files, users, or logs, and agents couldn't reliably pick the right one from ambiguous names.
APPROACH
Anthropic's team implemented systematic namespacing by service and resource. Tools like `search` became `asana_search` or `jira_search` at the service level, and `asana_projects_search` or `asana_users_search` at the resource level. They tested both prefix-based (`asana_projects_search`) and suffix-based (`projects_search_asana`) naming schemes, finding non-trivial performance differences that varied by LLM.
PATTERN
“Agent calls Slack search when you meant Notion search—the "ambiguous naming trap" where generic names like `search` apply to files, users, or logs. With 100+ tools, agents use names as first-pass filters before reading descriptions. Namespace by service and resource: `asana_projects_search` front-loads the disambiguation signal.”
✓ WORKS WHEN
- Agents have access to 20+ tools across multiple services or domains
- Multiple tools serve similar functions on different resources (search, list, create)
- Evaluation shows agents calling tools from the wrong service or resource type
- Tools come from multiple MCP servers that may use inconsistent naming
- Common verbs (search, get, create) appear across multiple tool categories
✗ FAILS WHEN
- Agent has fewer than 10 tools where names are already unambiguous
- All tools operate on a single resource type within one service
- Tool descriptions are sufficiently distinct that names don't matter for selection
- Namespacing would create tool names exceeding LLM's effective parsing length
- Tools are dynamically generated and can't follow a consistent naming scheme