A buying agent called one of our endpoints twelve times. It paid every time. It received nothing every time, and was refunded every time, and after the twelfth attempt it stopped calling us altogether โ 52 hours of silence, then nothing.
Its requests were well formed. The problem was ours: our machine-readable contract said the request body had no required fields, and the handler required one. The buyer built exactly what the document described and we answered 400 sitekey required, twelve times.
This is the least dramatic failure mode in an API business and one of the most expensive. Nothing crashed. No alert fired. The delivery ledger was consistent: charge, fail, refund. The only place it showed up was in a buyer that never came back.
The OpenAPI document for that endpoint had a requestBody schema with seven properties and no required array. Seven candidate aliases โ siteKey, sitekey, url, type, and so on โ all listed, all optional by default, because in JSON Schema a property is optional unless required says otherwise.
It is tempting to read that as "we did not say". A buyer cannot read it that way. A generated client reads the schema, and a schema with no required compiles into a method where every argument has a default of none. The document was not silent; it was asserting that nothing was needed.
We could not fix this by editing the generated file โ the next regeneration would put the lie back. The fix had to move into the generator and into the source of truth:
Current state: 130 services carry declarations, and 3,382 operations are checked against them. The endpoint from the story now says required: ["url","type"] and requiredAny: [["sitekey","siteKey"]] on both GET and POST.
MCP is the surface most agent buyers actually read. One tools/list call returns every tool with its inputSchema, and clients build their function signatures from it. So we measured it the same way.
Every tool's inputSchema carried properties and nothing else. The captcha endpoint above shows the pattern exactly: seven properties advertised, zero required claims, while the handler rejects the call unless sitekey or siteKey is present.
The 402 payment challenge has the same hole. Its bazaar block does include a required array, but only at the envelope level โ ["input"] โ so it tells a buyer that a request needs an input object, not which query parameters that object must contain.
The OpenAPI fix is live. The MCP fix is not: the tools/list schema is assembled inside our gateway binary, and the change is small but real โ the loader returns a list of field names per service, with no place to put a required set, and the builder emits only properties.
We could wait to write this until the number is zero. Publishing it now is more useful, for two reasons. First, a number that is measured and dated is a fact you can re-check; a promise is not. Second, the same defect is almost certainly in other people's MCP servers, and the failure is invisible from the seller's side โ the request arrives, the buyer pays, the handler rejects, the refund clears, and the only trace is a customer who stops calling.
{
"name": "x402-captcha-solve",
"inputSchema": {
"type": "object",
"properties": {
"url": { "type": "string" },
"type": { "type": "string" },
"siteKey":{ "type": "string" },
"sitekey":{ "type": "string" }
},
"required": ["url", "type"],
"anyOf": [
{ "required": ["sitekey"] },
{ "required": ["siteKey"] }
]
}
}
Two details in that snippet matter more than they look. The alias group belongs in anyOf, not in required โ flattening it turns "send either spelling" into "send both". And the envelope must not be trusted to describe the payload: a schema can be perfectly valid, pass every structural check, and still fail to tell a caller the one thing they need to know.
The cheap version of this audit takes about an hour:
Repeat it across your MCP tools/list. Tools that need input and advertise no required array are the ones most likely to have already lost a paying caller without ever showing up in an error budget.
The measurement, the guard, and a replayable snapshot of all 1,932 tool schemas are dated 2026-11-20. When the gateway change lands, we will re-run the same check and publish the new number โ that is the whole point of measuring it.