API Schema Quality for Agent Consumption

What this parameter measures

Beyond whether an OpenAPI specification exists, this parameter judges how usable it actually is for an AI agent. When friendly4AI has a prefetched spec, it parses the paths and measures four quality categories: the share of operations carrying a unique operationId, the share with typed 2xx response schemas (a $ref or type), the share with response examples, and whether the spec uses RFC 7807 application/problem+json error models. When no spec is parseable, it falls back to scanning the HTML for the same quality signals.

Why it matters for AI-readiness

An agent can only call your API reliably if the spec tells it exactly what to send and what to expect. Unique operationId values give the agent stable function names; typed request and response schemas let it build and validate payloads; examples teach it the shape of real calls; and a consistent error model, like RFC 7807 Problem Details, lets it recover from failures instead of crashing. A spec that exists but is untyped or inconsistent forces the agent to guess, which is where automated integrations break.

How we score it

This is a gradient AI-Specific Signals parameter, and the scanner refines the published rubric with concrete thresholds. With a parseable spec it counts quality categories — operationId coverage at least 70%, typed 2xx responses at least 70%, examples at least 30%, and RFC 7807 usage. Three or more categories pass (100), one or two score partial (50), and none falls through to the HTML-signal path. In that fallback, two or more strong signals pass, any single strong signal or supporting signal scores partial, and nothing detectable fails (0). This parameter is API-conditional: its weighted contribution counts only when an API is detected on the site (via api-discoverability); otherwise its effective weight is zero and it is excluded from the score.

How to fix common issues

• Add an operationId to every operation in your spec — aim well above the 70% threshold.
• Define typed request and response schemas with $ref components instead of free-form objects, so at least 70% of operations have typed 2xx responses.
• Include example payloads for your most common operations; even 30% coverage moves the needle.
• Adopt a consistent error format — RFC 7807 Problem Details (application/problem+json) — across all endpoints.
• Re-scan after tightening the spec; reaching three of the four categories earns the full score.