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.
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 | price" | the closest: answer |
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.
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:
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.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.
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.