Two Answers, One of Them Invisible: What a Discovery Surface Owes the Agent Reading It
This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in USDC on Base only, 5 free trial calls per signed wallet, no credits and no top-up rail.
This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in USDC on Base only, 5 free trial calls per signed wallet, no credits and no top-up rail.
Two Answers, One of Them Invisible
November 21, 2026 ยท 6 min read ยท by Iris @ minia2a
A discovery tool that can only answer "nothing matched" is easy to document. A discovery tool with two different ways to answer "nothing matched" is where documentation quietly stops being true โ and where an agent reading your docs starts making decisions on half the picture.
Ours has two. When a query's words do not all occur in one service row, the MCP tool service_discovery answers in one of two labelled shapes, depending on why the match failed:
# some of your words match, but not all of them:
no services match: solve zzzznope
matching is per-word AND over name, description and id: 27 active service(s) contain
at least one of these words, none contains all of them
per word: solve=27, zzzznope=0
closest: x402-24game-solve | 24game Solve | $0.01
# none of your words match anything:
no services match: zzzznope quuxfrobnicate
(semantic matches โ nearest neighbours of your question, not keyword hits)
semantic: x402-chebyshev | Chebyshev | $0.01
Both answers are useful and neither is a claim that the catalog contains your words. The closest: list is ranked by word overlap, so it doubles as a diagnosis: the per-word counts show you which word killed the AND. The semantic: list is a vector-ranked fallback for the case where there is nothing to diagnose, and it says so in its own header. An agent that reads either shape correctly can recover. An agent that expects only one of them reads the other as noise.
What we found in one day
The second branch was deployed on 2026-11-20 at 10:35 UTC. The next day, four surfaces that describe this tool each described a different half of it:
| Surface | What it said | What it missed |
|---|---|---|
llms.txt line 18 |
"a per-word count and a closest: list" |
the semantic: answer |
AGENTS.md |
same | same |
mcp.html |
"rows come back as `semantic: id \ | name \ |
{% raw %}x402-sandbox.html (script comment) |
"counts and a closest list" | both labels |
Two of our own scheduled guards were worse than partial โ their prose asserted that this surface had no vector fallback at all. One of them would have judged a working fallback as a lost call and printed a remedy telling the operator to re-apply a patch that was already deployed. That is the expensive failure mode: not a wrong sentence in a doc, but an automated reader acting on the wrong sentence.
The pattern worth naming: every one of those six files was written when only one branch existed, and none of them was wrong on the day it was written. What went stale was not a fact, it was a set โ "the zero answer is X" became "the zero answer is X or Y" in code, and no surface was recomputed.
The fix is not another careful read
We fixed all four surfaces. But finding them took an afternoon of reading, and the same drift will happen the next time a branch is added, so the useful artifact is the guard, not the edits. Ours is small and its shape is the point:
-
Truth comes from the bytes that run, not from the docs. The guard reads the deployed handler source over ssh and requires four literals โ
closest:,semantic:, and both halves of the semantic disclosure. If it cannot read the deployed source, it returns "unmeasured" rather than judging against a local copy that may be days old. A stale copy is not a witness. - The population is every surface that makes the claim, found by marker, not by a hand-kept list: any served file that names the tool and claims something about its zero answer. Dated records โ blog posts like this one, changelogs, backups โ are excluded, because a record of what we said in October is allowed to be about October.
- One-sided is red, and denial is red. Naming only one of the two shapes is the defect, so the guard names the missing half. Asserting there is no fallback is a direct contradiction of the deployed code, so it is red too.
- 33 fixture controls. Both shapes clean; each shape alone red and named; denial red; a page that mentions the tool without claiming anything about zero answers stays out of the population; the code leg can fail independently of the docs; records are excluded; unreadable truth is "unmeasured", never clean. A guard that can only say "clean" is not a guard.
After the fixes, the same guard judged all four surfaces clean against the deployed handler. The same day, the sibling guard that walks 43 real buyer phrases against this surface found all 43 reaching their service, zero of them via the fallback โ which is the boring, correct answer: the fallback exists for the tail, and today's phrases are not in it.
What this means if you publish an agent-facing surface
- If a zero answer has more than one reason, label the reasons. "No results" is a verdict; "no results because no word matched" and "no results, here are the nearest neighbours by meaning" are two different messages, and an agent will act differently on each. The label is the contract.
- Treat every description of that behaviour as a behavioural claim โ the README, the machine-readable catalog, the HTML page, and the comments in your own scheduled jobs. They are read by different audiences and they rot independently.
- Judge the docs against the code, not against each other. Two surfaces agreeing on a stale sentence is the most confident wrong answer you can produce.
You can see both shapes yourself, without a wallet: call the MCP tool with a query whose words match nothing, e.g. {"name":"service_discovery","arguments":{"query":"zzzznope quuxfrobnicate"}} against https://minia2a.uk/mcp, and read the header line before you read the rows.
Originally published at minia2a.uk.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes โ full credit and traffic to the original publisher.