--- title: UI Says 'To Review', API Says needs_review: Agents Get Lost description: Users say the screen label, the API wants another value. One label broke 5 Claude Code answers and a job passed 4 of 10 runs. How to map UI words to API values. canonical: https://spiritroom.app/blog/agent-vocabulary-mismatch/ published: 2026-10-21 updated: 2026-10-21 --- > Markdown version of https://spiritroom.app/blog/agent-vocabulary-mismatch/ 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/) # 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 **TL;DR** - **Screen label ≠ API value.** The app showed a “To review” tab; the API called that count `new` and its stages were different words. - **Wrong answers:** Claude Code used the label in 5 answers; the “which group is best?” job passed in 4 of 10 runs (17–69%). - **False “not available”:** in 3 of 5 runs Claude said the split wasn't exposed. It was, under the API's word. - **Buried mapping:** the description explained it at character 1,515 of 3,184; passing the label as a value returned a 15-line type dump. - **Fix:** map labels to values in the first line, accept the label as an alias, and say the mapping in errors. [What happened](#what)[Why agents guess](#why)[How to map UI words to API values](#fix)[How to find mismatches](#check)[How we measured](#how-we-measured)[FAQ](#faq) ## 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.” Claude Code: job passed *4/10 runs (17–69%)* Claude Code: said data not exposed *3/5 first-round runs* - 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](/blog/mcp-tool-descriptions-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”. **Find the words that trip agents on your API.** We run your users' requests, in their own words, through Claude Code, Codex and the other apps they use, and show where the vocabulary sends agents wrong. [Test your MCP →](/#contact) ## 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](/blog/error-messages-for-ai-agents/). Other causes of wrong calls: [why agents call the wrong tool](/blog/why-agents-call-the-wrong-tool/). **Go deeper:** [Name tools the way users talk](/blog/mcp-tool-naming-for-agent-search/), [When the agent doesn't recognise your server](/blog/agent-does-not-recognise-mcp-server/), [Evaluate AI agents on your API](/blog/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. ## FAQ ### Why does my agent use the wrong enum value? Often because the user used a screen label and nothing told the agent which API value it maps to. On the server we tested, the app's “To review” tab didn't match any API value, and the explanation was 1,515 characters into a tool description. ### Should an API accept UI labels as values? Accepting them as aliases is the cheapest fix: the agent passes the user's word and gets the right result. At least, reject them with a one-line error that names the value to use. ### Where should the label-to-value mapping go? In the first line of the tool description that takes or returns the value, because some apps and searches see only the start. Repeat it in the error for an invalid value. ### How do I find vocabulary mismatches? Write test jobs in your users' words, using the labels they see, and read the answers. Look for answers that use a label instead of a value, and for agents saying data isn't available. **Find the words that trip agents on your API.** We run your users' requests, in their own words, through Claude Code, Codex and the other apps they use, and show where the vocabulary sends agents wrong. [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[Why AI agents call the wrong tool: 7 causes we saw in recorded runs](/blog/why-agents-call-the-wrong-tool/) - Related[Write MCP tool descriptions agents actually see: put the meaning in the first line](/blog/mcp-tool-descriptions-first-line/) - Related[How to write error messages for AI agents: before and after, from a production MCP server](/blog/error-messages-for-ai-agents/)