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

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

What agents see of a description

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.

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.

In 3 of 5 first-round runs Claude said the data wasn't exposed. It was. See UI words vs API values.

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:

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. Wrong-tool causes: why agents call the wrong tool. Check first-line length on your list with the MCP scorecard.

Go deeper: How to optimise your MCP tools, Tool annotations, OpenCode 1 vs 2.

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.