Nine in ten sites have no agent manifest, and most of them should not

Ninety per cent of the sites we scan have no /.well-known/agent.json. For a while we took points off all of them. That was a mistake, and correcting it changed how we think about what a check is for.

What went wrong

Our actionability category was four checks: an agent manifest, reachable API documentation, form semantics, and whether documentation sat behind a wall. Sensible enough if you are a software company. We ran a 44-site sweep of local businesses — dentists, plumbers, a bakery, two law firms — and 38 of the 44 scored exactly zero on the category.

Zero, on 15 points out of 100, for every one of them. And there was nothing any of them could do about it. A dentist does not have an API. Publishing an agent manifest describing the API they do not have would be worse than not having one.

The two wrong fixes

The obvious move is to exempt local businesses from the API checks. We already have that machinery — a sector profile names the checks a sector is not measured on, and an exemption is a skip, which leaves the denominator rather than counting as a zero. But applied here it would have been a fudge, for a reason worth stating:

We only ever select a profile from what a site declares about itself, in JSON-LD, using schema.org's own vocabulary. Never from the absence of the thing being exempted. "No API docs, therefore exempt from API docs" makes the score a tautology — every site passes everything it does not have. A site that declares nothing recognised is measured on everything, because silence is not a claim.

The second wrong fix is to reweight the category down to near nothing. That fails differently: it says the question does not matter, when for a plumber the question "can an agent find out how to contact you and book you" matters more than almost anything else we check.

What we did instead

We kept the category and its weight, and changed what is inside it. Scoring version 1.4 added three checks that any business can pass and most can fix in an afternoon:

• —Contact reachable — is there a phone number, an email address or a postal address a machine can extract? A tel: link, a mailto:, or telephone in JSON-LD all count.
• —Action declared — does the site say, in structured form, what you can do here? A potentialAction, a ReserveAction, an OrderAction. Booking a table is an action. So is requesting a quote.
• —Action not JavaScript-only — if the primary way to act is a booking widget that only exists after a script runs, a client that does not execute scripts sees a page with no way to do anything.

The category went from 15 catalog points to 26, and the weight stayed at 15, because points inside a category are normalised against the category weight. Every one of the 44 businesses now has something in that category they can pass, and something concrete to do about the ones they fail.

The agent manifest check is still there

It is worth fewer points and it is still worth having, because for a site with an API it is a real answer to a real question. The 90% failure rate is not evidence that the check is wrong. It is evidence that a check most sites fail should not be most of a category.

Why any of this is public

Changing a weight changes every score, so it is a versioned event rather than a tweak. Every score row records the version that produced it, 1.2 and 1.3 are archived and still scorable, and the current catalog and every weight is published. You cannot argue with a score you cannot see the arithmetic of, and a score nobody can argue with is a number we made up.