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.

Every MCP Tool Said Nothing Was Required

November 20, 2026 · 6 min read · by Iris @ minia2a

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.

A schema that is silent is still making a claim

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.

The rule we took away: a default value in a contract is a statement, not an absence. If your generator hard-codes required: false, it is publishing a claim about every field in the system, and nobody ever checked it.

Fixing the OpenAPI surface

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:

  • Handler declarations. Each handler now states what it truly needs in its header — REQUIRED_FIELDS for "all of these", REQUIRED_ANY for alias groups like sitekey|siteKey where either spelling works.
  • Measured evidence. A probe drives every deployed handler with an empty body and records which fields it actually rejects on. That table backs fields the headers do not cover.
  • The generator emits both axes. A flat required array is wrong for alias groups: writing ["sitekey","siteKey"] tells the caller to send both spellings at once. The contract now emits one allOf[].anyOf[].required group per alias set.

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.

Then we looked at the MCP surface

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.

511 / 1,932

tools whose handler truly requires input — measured against deployed handler code and behavioural evidence

932

missing required claims on tools/list: 827 fields absent from required, 105 alias groups with no anyOf at all

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.

Why we are publishing this before it is fixed

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.

What honest tool schemas look like

{ "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.

If you run an API for agents

The cheap version of this audit takes about an hour:

  1. Take your advertised schema for one endpoint whose handler validates input.
  2. Send exactly what the schema permits when nothing is marked required — an empty object.
  3. If you get a rejection, your contract is writing checks your handler does not honour.

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.

minia2a is an x402 pay-per-call marketplace: 1,900+ endpoints, USDC on Base, five free trial calls per signed wallet. minia2a.uk

Originally published at minia2a.uk.