The check catalog
Every grade Elva assigns comes from a fixed catalog of 30+ concrete checks, each with an id, a category, a severity, and a weight. This is the whole list, so you can see exactly what moves your score and why it matters when an agent is on the other end of the call.
Each check runs against your parsed OpenAPI spec and returns Pass, Partial, or Fail. That result is multiplied by the check weight and rolled into one of four categories: Design, Developer Experience, AI Readiness, and Security. The higher the weight, the harder that single check pulls your grade.
These are the exact same checks that drive MCP readiness. When Elva flags a tool as risky to expose to an agent, it is these checks talking. Fix them in the spec and both your catalog grade and your MCP readiness improve together.
You can pull this catalog live from the public API: GET https://api.getelva.ai/api/review/checks returns every entry below with its id, category, name, description, severity, and weight.
AI Readiness
These checks exist because an agent reads your spec the way a developer never would: literally, and at scale. Vague operationIds, undocumented enums, and missing formats are exactly what cause an LLM to hallucinate a call. This category is where “agent-ready” is earned.
id | Name | Severity | Weight |
| OperationId Quality | high | 9 |
| Semantic Operation Descriptions | medium | 6 |
| Schema Discoverability | medium | 6 |
| Schema Field Metadata | medium | 5 |
| Parameter Constraint Coverage | medium | 5 |
| Format Specification | medium | 5 |
| LLM Context Anchors | medium | 4 |
| Enum Documentation | medium | 4 |
Developer Experience
Humans still integrate your API, and their experience is a proxy for how legible the contract is. Missing examples, ad-hoc error shapes, and undescribed parameters make the spec harder for people and agents alike. spec-integrity sits here and carries the heaviest weight in the category.
id | Name | Severity | Weight |
| OpenAPI Integrity & Reuse | high | 9 |
| Executable Examples | high | 8 |
| Consistent Error Model | high | 8 |
| Operation Descriptions Present | medium | 7 |
| Parameter & Schema Descriptions | medium | 6 |
| Docs Accessibility Basics | low | 2 |
Design
The largest category by overall weight. This is where REST hygiene lives: nouns not verbs, correct method semantics, real status codes, pagination, and consistent identifiers. design-method-semantics is the single most influential check in the whole engine.
id | Name | Severity | Weight |
| HTTP Method Semantics & Idempotency | high | 9 |
| Status Codes in Spec | medium | 7 |
| Pagination Style & Docs | medium | 6 |
| Resource Identifier Consistency | medium | 6 |
| Resource URI Naming | medium | 5 |
| Content Types & Accept | medium | 5 |
| Response Schema Completeness | medium | 5 |
| URI or Spec Versioning | medium | 4 |
| Deprecation & Sunset | medium | 4 |
| Long-Running Operations | medium | 4 |
| Idempotency for Risky POSTs | medium | 4 |
| Webhook Contracts | medium | 4 |
| Consistent Casing & Separators | medium | 3 |
| Filtering, Sorting & Sparse Fieldsets | low | 3 |
Security
An agent you expose to the world is only as safe as the contract behind it. These checks confirm HTTPS, declared auth schemes, documented 401/403 and 429 responses, and no secrets leaking through examples.
id | Name | Severity | Weight |
| HTTPS Enforcement | high | 8 |
| Auth Schemes Declared | high | 8 |
| Secure Auth Methods | medium | 5 |
| Unauthorized/Forbidden Codes | medium | 5 |
| Secrets in Examples | medium | 4 |
| Rate Limit Documentation | medium | 3 |
What moves the score most
Weight is the lever. A handful of high-severity checks (weight 8 to 9) dominate every grade, so if you want the fastest lift, start here:
design-method-semantics(w9) andspec-integrity(w9)ai-op-ids(w9)dx-executable-examples(w8) anddx-error-schema(w8)sec-https-only(w8) andsec-auth-schemes-defined(w8)
Clearing these turns the biggest Fails into Passes and pulls the category percentages up hard. The lighter checks (weight 2 to 4) refine an already solid spec rather than rescue a broken one.
FAQ
Why does AI Readiness get its own category?
Why does AI Readiness get its own category?
Because agents fail differently than humans. A person can guess that POST /createUserV2 makes a user; an LLM planning a tool call needs a stable operationId, typed constraints, documented enums, and explicit formats to avoid inventing invalid arguments. Checks like ai-op-ids, ai-parameter-constraints, and ai-enum-documentation measure exactly that, so the tools you expose over MCP are ones agents can actually call correctly.
What does a Partial result mean?
What does a Partial result mean?
Each check scores Pass = 1.0, Partial = 0.5, or Fail = 0.0, then multiplies by its weight. Partial means you satisfy the check across most of your spec but not the threshold for a full pass. For example, a coverage check that wants descriptions on 90% of parameters returns Partial when you are close but short. Partials surface as warnings; Fails surface as errors.
Do these same checks drive MCP readiness?
Do these same checks drive MCP readiness?
Yes. The review engine is the single source of truth. The grade on your collection sidebar, the category bars on the Insights page, and the per-tool readiness shown when you generate a hosted MCP all come from this one catalog. Improve a check once and it lifts everywhere.
Can I see the full catalog programmatically?
Can I see the full catalog programmatically?
Call GET https://api.getelva.ai/api/review/checks with no auth. It returns the complete list with descriptions, so you can wire the catalog into your own CI or dashboards.
On this page
- The check catalog