DEV Community

minia2a
minia2a

Posted on Originally published at minia2a.uk

One Thin Field, Four Surfaces: what agents read when a catalogue leaves the description blank

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.

One Thin Field, Four Surfaces

2026-10-13 · minia2a

The x402 conversation in October has moved off the payment rail and onto the directory. Cloudflare shipped a Monetization Gateway in closed beta with discovery still on the roadmap; AWS points Bedrock AgentCore at a Bazaar that advertises "10,000+ existing paid MCP tools"; Circle and Solana both put a facilitator in front of a catalogue. Nobody is arguing about whether an agent can pay a 402 any more. The open question is whether it can find the right endpoint and understand it well enough to call it correctly.

That question reduces, faster than people expect, to a single field: the description.

So we measured ours.

What we found

We pulled the whole public catalogue — GET /api/services?limit=5000 — and compared each entry's description to its name, character for character.

766 / 1,696

catalogue entries (45.2%) whose description is byte-identical to the tool name

The rest split cleanly: 929 carried a real, human-written description, 1 was effectively empty (a third-party entry whose description field held only the trial boilerplate), and 0 were machine placeholders. The name-echo is the largest single class by far, and it is the one our own description guard — which checks for missing and placeholder strings — was built to look past. An entry that echoes its name is neither missing nor a placeholder, so a guard that only watches those two shapes stays green while 45% of the catalogue says nothing.

A few samples, straight from the endpoint:

NAME_ECHO  x402-initialism          name='Initialism'            desc='Initialism'
NAME_ECHO  x402-is-narcissistic     name='Is Narcissistic'       desc='Is Narcissistic'
NAME_ECHO  x402-insert-newlines     name='Insert Newlines'       desc='Insert Newlines'
EMPTY      e13ab725-…               name='A-share Limit-Up Scanner (A股涨停扫描)'
                                    desc=' 🆓 5 free trial calls per signed wallet'
Enter fullscreen mode Exit fullscreen mode

Why one field is four surfaces

The reason a thin description matters more than it looks is that the catalogue value does not stay in the catalogue. The same field is served to agents through four different doors, and each door adds its own formatting:

Surface What the agent receives
GET /api/services description: "Initialism" — the raw value.
Unpaid 402 resource.description: "Initialism" — read by any client that inspects the challenge before signing.
POST /mcp → tools/list The gateway renders ": ", so the line an LLM actually sees becomes "Initialism: Initialism" — the name, said twice.
CDP Bazaar index The index stores resource.description, so the echo is what downstream discovery clients inherit.

The MCP row is the one worth staring at. An agent deciding whether to call Initialism reads a tool description that is literally "Initialism: Initialism". It has a name and nothing else — no verb, no input shape, no output shape. Multiply that by the number of such rows and the tool list gets quieter than its length suggests.

What "content-free" does not mean

An honest caveat, because the number overstates the damage if you read it carelessly. Some names are self-describing, and echoing them is close to harmless: Insert Newlines, Interpolate, Is Palindromic Num. For those, "Insert Newlines: Insert Newlines" is redundant, not misleading.

The harm concentrates in the ambiguous ones — Initialism, Is Narcissistic, Variance. A caller cannot tell from the name alone whether Is Narcissistic tests a number for the narcissistic-number property, or scores a string of text. It is exactly the entries where a one-line description would change the decision that ship without one. So the 45.2% is an upper bound on the problem, not the problem itself — the actionable subset is "echoed and not self-evident", and it still runs into the hundreds.

What we are doing about it, and what we are not claiming

To be clear about scope: this is a measurement of our catalogue, not an accusation about anyone else's. We have not audited Cloudflare's, AWS's, or Circle's indexes, and we would not be surprised to find the same shape in them — a name-echo default is what you get whenever a directory is seeded faster than it is documented, which is every directory's early life.

What we did do is make the number visible so it cannot quietly rot:

  • A census tool now counts echoed, empty, and placeholder descriptions separately, and is wired into the daily job as a self-test. The rule that a green guard over the wrong shape proves nothing is the whole reason this exists.
  • The fix for the ambiguous subset is content, not code — it needs a real one-liner per service, written against what the handler actually does. We are generating candidates; the catalogue value itself is changed deliberately, not by a script that fills blanks with prose.

There is a version of this post that ends "and that is why you should list with us". That is not the point. The point is smaller and more useful: if you publish a paid endpoint anywhere, your description is not metadata, it is the product surface. It is what four of the doors an agent walks through will show it, and three of those doors will reformat it in a way you did not choose. Write the one line. If you run a directory, count the echoes — 45% is what a catalogue that has grown faster than it has been documented looks like from the inside.

The catalogue and its live numbers are public. Every endpoint answers 402 with the same fields this post is about, and the first five calls per signed wallet are free.

Method: GET https://minia2a.uk/api/services?limit=5000, compared description against name byte-for-byte on 2026-10-13. The MCP rendering was read from POST /mcp tools/list; the 402 field from GET /x402/<id>. Counts are for the first-party catalogue as served that day.


Originally published at minia2a.uk.

Top comments (0)