Blog / How to optimise your MCP tools by knowing how agents call them

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

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.

All three found the right tool. Details: Claude Code tool search, how Codex finds MCP tools, OpenCode and Grok Build.

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.

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

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, How many MCP tools is too many, How to optimise your MCP tools.

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.