--- title: How to Name MCP Tools So Agents Find Them description: Claude Code picks MCP tools from names alone, Codex regex-filters names and descriptions, Grok Build runs BM25. Captured on the wire, and how to name tools. canonical: https://spiritroom.app/blog/mcp-tool-naming-for-agent-search/ published: 2026-10-21 updated: 2026-10-21 --- > Markdown version of https://spiritroom.app/blog/mcp-tool-naming-for-agent-search/ for agents. Index: /llms.txt [Blog](/blog/) / [How to optimise your MCP tools by knowing how agents call them](/blog/optimise-mcp-tools-for-agents/) # Name MCP tools the way users talk: how names-only, regex and BM25 search pick tools Before an agent calls your tool, it has to find it among dozens or hundreds. Each agent app searches differently, but in all three we captured, your tool's name did most of the work. Leonid Bugaev · Published 21 Oct 2026 **TL;DR** - **Claude Code:** saw 113 names, picked 3 by exact name with `select:`. No keyword search ran. - **Codex:** wrote JavaScript regex filters over tool names and descriptions, starting with the server's name. - **Grok Build:** ran BM25 with the user's words plus the server name, default top 5. - **Naming rules:** user's nouns and verbs, a consistent prefix, one obvious tool per job, no internal codenames. - **When users don't name your product,** search can miss: Codex missed the tools in 8 of 80 live runs. [Three ways apps find tools](#three)[What names do in each](#names)[Naming rules](#rules)[Examples](#examples)[How we measured](#how-we-measured)[FAQ](#faq) ## Three ways apps find tools We captured the traffic of three agent apps with the same 99-tool MCP server attached and the same request. | App | What the model gets | How it searched | | --- | --- | --- | | Claude Code 2.1.301 | 113 tool names, no descriptions | `ToolSearch` with `select:` and 3 exact names | | Codex 0.161.0 | No tool names at all; a code tool with `ALL_TOOLS` | JS regex over name and description: server name first, then narrower filters | | Grok Build 1.0.60 | Server names and tool counts | `search_tool` with the user's words plus the server name; client-side BM25 | All three found the right tool. Details: [Claude Code tool search](/blog/claude-code-tool-search-explained/), [how Codex finds MCP tools](/blog/how-codex-finds-mcp-tools/), [OpenCode and Grok Build](/blog/opencode-mcp-tool-loading/). **Find out whether agents find your tools.** We run your users' requests, in their words, through the agent apps they use and show which tools get found, missed or confused. [Test your MCP →](/#contact) ## What names do in each - **Names-only (Claude Code):** the name is the only signal before the model loads definitions. A vague name like `process` or an internal one like `ar_docs_query` loses. - **Regex (Codex):** the model guesses words and filters. Its first filter, on the server name, matched everything and printed 56,619 tokens, cut to 11,244. Narrower filters followed (1,777 and 3,030 tokens). Words in names and descriptions are what it can match. - **BM25 (Grok Build):** word overlap between the query and your tool text decides the top 5. User words in names and first lines rank. When the user doesn't name your product, all three rely on guessed words. In live runs Codex missed the server's tools in 8 of 80 (5–19%). See [when the agent doesn't recognise your server](/blog/agent-does-not-recognise-mcp-server/). ## Naming rules 1. **Use the user's nouns:** if the screen says “tasks”, don't call them `items`. If you must, say “tasks are called items in the API” in the description. 2. **Verb + object:** `list_tasks`, `get_task`, `count_tasks_by_status`. The action matters to the model's choice. 3. **One obvious tool per job.** Two tools that both look like the answer split the choice. See [why agents call the wrong tool](/blog/why-agents-call-the-wrong-tool/). 4. **Consistent prefix** for a domain (`billing_`, `projects_`) so a filter or select can grab the set. 5. **A server name users would type,** because apps prefix it and searches start from it. 6. **Repeat the key words in the first line** of the description for regex and BM25. See [put the meaning in the first line](/blog/mcp-tool-descriptions-first-line/). ## Examples ``` Weak Better stats get_task_counts workspace get_workspace_overview ar_docs_query list_invoices do_action start_export (destructive, say so) ``` **Go deeper:** [UI words vs API values](/blog/agent-vocabulary-mismatch/), [How many MCP tools is too many](/blog/how-many-mcp-tools-is-too-many/), [How to optimise your MCP tools](/blog/optimise-mcp-tools-for-agents/). ## How we measured - **Captures:** one request per app against a local stub of a 99-tool production server, 16 Oct 2026, traffic recorded through a temporary, process-scoped proxy with secrets redacted. - **Live misses:** Codex CLI 0.161.0, two rounds of 8 jobs × 5 runs on the production server through a read-only proxy. - **Limits:** one capture per app; naming effects weren't tested as a controlled experiment. Ranges are 95% Wilson intervals. ## FAQ ### How should I name MCP tools so agents find them? Use the words your users use for the object and the action (list\_invoices, get\_invoice), keep a consistent prefix or namespace, and avoid internal codenames. In our captures Claude Code picked tools from names alone, and Codex and Grok Build matched names and descriptions against words. ### Does the tool description matter for discovery? In Codex and Grok Build, yes: their search covers descriptions too. In Claude Code, the model chose from names before seeing any description. Put the key words in both. ### Should tool names include the product name? Agent apps already prefix MCP tools with the server name (for example mcp\_\_server\_\_tool), and Codex's first filter in our capture was the server name. Pick a server name users would type. ### What's BM25 tool search? A keyword-ranking method: tools whose names and descriptions share more of the query's words rank higher. Grok Build runs it on the client with a default limit of 5. **Find out whether agents find your tools.** We run your users' requests, in their words, through the agent apps they use and show which tools get found, missed or confused. [Test your MCP →](/#contact) ## Keep reading - Up[How to optimise your MCP tools by knowing how agents call them](/blog/optimise-mcp-tools-for-agents/) - Related[Write MCP tool descriptions agents actually see: put the meaning in the first line](/blog/mcp-tool-descriptions-first-line/) - Related[Why AI agents call the wrong tool: 7 causes we saw in recorded runs](/blog/why-agents-call-the-wrong-tool/) - Related[Claude Code tool search, seen from the wire: the model picks your tool from its name](/blog/claude-code-tool-search-explained/) - Related[How Codex finds MCP tools: code mode and ALL\_TOOLS](/blog/how-codex-finds-mcp-tools/)