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

When your UI says “To review” and your API says needs_review: vocabulary mismatches that break agents

Your users don't know your API. They say what they see on screen: “To review”, “Waiting on someone”, “Archived”. The agent has to turn that into your API's values. When the two don't match and nothing says how they map, agents guess, and some guesses look like answers.

Leonid Bugaev · Published 21 Oct 2026

What happened

A 99-tool production MCP server we tested has a web app with a tab called “To review”. Its API has no value called that. The list tool's stages are words like qualified and needs_review, and the per-group count the app shows as “To review” comes back under a count key called new, which isn't a stage value at all.

We asked, in a user's words: “Which of my groups is performing best? For each, give the number that are qualified and the number that need review.”

• Across the 8 jobs, 5 Claude Code answers called qualified items “To review”, the screen label, instead of the API stage qualified. Strict scoring: 32/40 (65–90%); accepting the label: 37/40.
• In 3 of 5 first-round runs of that job, Claude said the server didn't expose qualified vs needs-review counts. Wrong: the list tool returns a stage for every item.
• In an earlier live pass, Codex got the per-group “To review” counts right in 5 of 5 status runs; the mismatch hurt one app more than the other, which is why you test more than one.

None of these were errors. The answers looked confident.

Why agents guess

The mapping was buried. The list tool's description was 3,184 characters. The sentence explaining that one count key means the “To review” tab first appeared at character 1,515. Apps that show a short description, or search only names and the start, may never see it. See put the meaning in the first line.

The user's word was rejected noisily. Passing the label as the stage value returned a 15-line type tree that ended in Expected "qualified", actual "to_review", three times, and never said in one line which value meant “To review”.

How to map UI words to API values

1. First line of the description: name each value with its screen label, for example:

   Stages: qualified; needs_review (shown in the app as "To review"); disqualified.

2. Accept the label as an alias: to_review → needs_review. The agent passes what the user said and gets the right data.
3. If you reject it, say the mapping in one line:

   stage "to_review" is not valid; use needs_review ("To review" in the app).

4. Use one word per thing. If a count key isn't a stage, say which label and stages it covers.
5. Return labels with values where it helps: {"stage": "needs_review", "label": "To review"}, so the agent can answer in the user's words.

Error wording: error messages for AI agents. Other causes of wrong calls: why agents call the wrong tool.

Go deeper: Name tools the way users talk, When the agent doesn't recognise your server, Evaluate AI agents on your API.

How to find mismatches

• List every label your UI shows for a status, type or filter, next to the API value.
• Write test jobs that use the labels, not the values.
• Read answers by hand. Flag labels used as values, and any “that isn't available” that's false.
• Score strictly and leniently, and report both: here 32/40 vs 37/40.

How we measured

• Live: a 99-tool production MCP server, read-only through an allowlist proxy, 16 Oct 2026. Claude Code 2.1.301 and Codex CLI 0.161.0, 8 jobs × 5 runs per round; the group job over two Claude rounds (10 runs).
• Direct calls: the description position and the error text from tool listings and one invalid call, same day.
• Limits: one server; ranges are 95% Wilson intervals; job and group names are generalised.