--- title: MCP Tool Descriptions Agents See: Put the Meaning First description: Agent apps see names, ~120-character snippets or the start of your tool description. Better first lines took Claude from 1/6 to 6/6 on the right tool. Template. canonical: https://spiritroom.app/blog/mcp-tool-descriptions-first-line/ published: 2026-10-21 updated: 2026-10-21 --- > Markdown version of https://spiritroom.app/blog/mcp-tool-descriptions-first-line/ 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/) # Write MCP tool descriptions agents actually see: put the meaning in the first line You wrote a careful 3,000-character description. The agent may see the name, a snippet, or the first part. Whatever matters most has to be at the start. Leonid Bugaev · Published 21 Oct 2026 **TL;DR** - **Apps see different amounts:** Claude Code shows names until a tool is loaded; OpenCode 2 showed ~120-character snippets; search may not read the end of long descriptions. - **Buried meaning costs answers:** on a production server, the key field was first explained at character 1,515 of 3,184, and Claude got that job right in 4 of 10 runs. - **First lines move tool choice:** on a mock, better descriptions took Claude from 1/6 to 6/6 runs on the right counting tool, and a small model from 0/6 to 4/6. - **Template:** what it returns, when to use it (and what instead), then the key values. Details after. [What agents see of a description](#see)[What buried meaning costs](#cost)[First lines change tool choice](#mock)[A first-line template](#template)[Before and after](#examples)[How we measured](#how-we-measured)[FAQ](#faq) ## What agents see of a description | App | Before choosing | | --- | --- | | Claude Code 2.1.301 (tool search on) | Names only; full definitions after the model loads them | | OpenCode 2.0.31 | 16 of 99 tools, descriptions shortened to roughly 120 characters | | Codex 0.161 (code mode) | Searches names and descriptions with code filters | | Grok Build 1.0.60 | BM25 search over tools, top 5 by default | | OpenCode 1.18 | Everything, every request | In our marker tests, a word near the end of a long description wasn't found by Claude Code's search. There's no universal “first N characters”, but every app sees the start. More: [Claude Code tool search, seen from the wire](/blog/claude-code-tool-search-explained/). ## What buried meaning costs On a 99-tool production MCP server, the list tool's description was 3,184 characters. The sentence explaining which count matched the app's “To review” tab first appeared at **character 1,515**. Claude Code: “which group is best?” *4/10 runs (17–69%)* In 3 of 5 first-round runs Claude said the data wasn't exposed. It was. See [UI words vs API values](/blog/agent-vocabulary-mismatch/). **See which of your descriptions agents miss.** We run your users' jobs through the agent apps they use and show where a description sent the agent to the wrong tool or past a key field. [Test your MCP →](/#contact) ## First lines change tool choice On a made-up task-tracker MCP server we compared one-word descriptions (“Stats.”) with descriptions whose first sentence said what the tool returns and when to use it. Same tools, same data. The three count questions, 6 runs per app: Claude Code, one-word *1/6 used the count tool (3–56%)* Claude Code, first-line *6/6 (61–100%)* Small model, one-word *0/6 (0–39%)* Small model, first-line *4/6 (30–90%)* Codex, one-word *5/6 (44–97%)* Codex, first-line *6/6 (61–100%)* Answers were right in every run either way: on a small, clean server agents get there. The better lines changed the route. Claude's list calls on those questions dropped from 12 to 2. The descriptions added 361 tokens to the tool list (1,369 → 1,730). ## A first-line template ``` [What it returns] for [scope]. Use for [user's job]; for [common wrong case] use [other tool]. Values: [api_value] ("[screen label]"), ... [Details, limits, examples...] ``` - Lead with the noun the user says, not your internal term. - Say when *not* to use it, and what to use instead. - Put value-to-label mapping in the first lines, not at character 1,515. - Keep the first sentence under ~120 characters if you can. ## Before and after ``` Before: Stats. After: Task counts per status for one project (or all projects if project_id is omitted), plus open tasks per person. ... Use this for "how many" questions. Before: Workspace. After: Workspace overview: projects with task counts per status. For exact counts in one project use get_stats. ``` Naming matters even more where only names are shown: [name tools the way users talk](/blog/mcp-tool-naming-for-agent-search/). Wrong-tool causes: [why agents call the wrong tool](/blog/why-agents-call-the-wrong-tool/). Check first-line length on your list with the [MCP scorecard](/tools/mcp-scorecard/). **Go deeper:** [How to optimise your MCP tools](/blog/optimise-mcp-tools-for-agents/), [Tool annotations](/blog/mcp-tool-annotations-destructive-hint/), [OpenCode 1 vs 2](/blog/opencode-mcp-tool-loading/). ## How we measured - **What apps see:** captured first requests of each app with a 99-tool server attached, 16 Oct 2026; marker words in descriptions for search tests. - **Production:** description lengths from the live tool list; job results from Claude Code 2.1.301 over two rounds of 5 runs. - **Mock:** a made-up task tracker, one-word vs first-line descriptions, Claude Code, Codex and a small free model in OpenCode; 3 count questions × 2 runs per app per variant, 21 Oct 2026. Ranges are 95% Wilson intervals; samples are small. ## FAQ ### How do I optimise MCP tool descriptions for AI agents? Put what the tool returns and when to use it in the first sentence, name the alternative for the common wrong case, and list key values with the user's words. Keep details after that. Different agent apps show different amounts of the description, but all of them see the start. ### How long should an MCP tool description be? There's no universal limit. What matters is that the first sentence works alone: some apps show only names or a short snippet before the model chooses. ### Do agents read the whole tool description? Once a tool is loaded, the model gets the full description. Before that, it may see only the name (Claude Code), a ~120-character snippet (OpenCode 2), or a search result that may not reach the end of a long description. ### Should I repeat information across tool descriptions? Repeat what decides the choice, such as “for counts use get\_stats instead”. In our mock test that line moved agents to the right tool. **See which of your descriptions agents miss.** We run your users' jobs through the agent apps they use and show where a description sent the agent to the wrong tool or past a key field. [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[Name MCP tools the way users talk: how names-only, regex and BM25 search pick tools](/blog/mcp-tool-naming-for-agent-search/) - Related[Claude Code tool search, seen from the wire: the model picks your tool from its name](/blog/claude-code-tool-search-explained/) - Related[When your UI says “To review” and your API says needs\_review: vocabulary mismatches that break agents](/blog/agent-vocabulary-mismatch/)