[DOCS] Tool search docs missing exact MCP tool-name matching guidance

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-sdk/tool-search

Section/Topic

"Optimize tool discovery" (and linked MCP Tool Search guidance for Claude Code users)

Current Documentation

The docs currently say:

"The search mechanism matches queries against tool names and descriptions. Names like search_slack_messages surface for a wider range of requests than query_slack. Descriptions with specific keywords (\"Search Slack messages by keyword, channel, or date range\") match more queries than generic ones (\"Query Slack\")."

And the tools reference says:

"Claude gives a conversational summary. For exact MCP tool names, run /mcp."

What's Wrong or Missing?

Changelog v2.1.113 includes: Fixed ToolSearch ranking so pasted MCP tool names surface the actual tool instead of description-matching siblings.

The current docs explain only that tool search matches names and descriptions. They do not tell users or MCP server authors that if a prompt includes an exact MCP tool name, ToolSearch should surface that specific tool ahead of sibling tools that only match on description text.

That omission makes it hard to understand how to intentionally steer ToolSearch after discovering an exact tool name via /mcp, especially in large catalogs with similarly described tools.

Suggested Improvement

Add a short note to the "Optimize tool discovery" section, and cross-link it from the MCP tool search page, explaining that:

• exact MCP tool names are strong search signals
• pasting a full tool name into the prompt should surface that tool ahead of description-only siblings
• /mcp is the way to find the exact tool name when a user wants to target a specific MCP tool

A concrete example would help, e.g. telling users that after copying a tool name such as mcp__server__tool_name, they can include it verbatim in the prompt to load that tool.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-sdk/tool-search | "Optimize tool discovery" currently explains name/description matching but not exact-name precedence |
| https://code.claude.com/docs/en/mcp | "Scale with MCP Tool Search" explains deferred loading but not how exact pasted tool names steer discovery |
| https://code.claude.com/docs/en/tools-reference | Tells users to run /mcp for exact MCP tool names, but not why that matters for ToolSearch |
| https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool | API cross-reference describing tool search inputs and ranking context |

Total scope: 4 pages affected

Source: Changelog v2.1.113

Entry text: Fixed ToolSearch ranking so pasted MCP tool names surface the actual tool instead of description-matching siblings