The check catalog
The catalog below lists the 41 checks in the current scoring rubric. Each check has a stable identifier, category, severity, and weight. Use GET /api/review/checks to retrieve the catalog available on the service you are calling.
Checks report Pass, Partial, Fail, or NotApplicable. A returned fractional score takes precedence over the status's fallback credit. NotApplicable checks do not contribute evaluated weight and reduce coverage. See Spec quality & scoring for the complete formula.
The MCP readiness view uses AI Readiness findings from the collection's quality report. A collection-wide grade is not a separate safety certification for each selected tool.
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.
Check ID | Name | Severity | Weight |
ai-op-ids | OperationId Quality | high | 6 |
ai-op-semantics | Semantic Operation Descriptions | medium | 6 |
ai-context-anchors | LLM Context Anchors | medium | 3 |
ai-schema-richness | Schema Field Metadata | medium | 4 |
ai-schema-discoverability | Schema Discoverability | medium | 3 |
ai-parameter-constraints | Parameter Constraint Coverage | medium | 5 |
ai-enum-documentation | Enum Documentation | medium | 4 |
ai-implicit-enums | Implicit Enum Coverage | medium | 4 |
ai-format-specification | Format Specification | medium | 5 |
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.
Check ID | Name | Severity | Weight |
dx-op-descriptions | Operation Descriptions Present | medium | 7 |
dx-param-doc | Parameter Descriptions | medium | 6 |
dx-schema-doc | Schema Field Descriptions | medium | 6 |
dx-executable-examples | Authored Request & Response Examples | high | 8 |
dx-error-schema | Consistent Error Model | high | 8 |
dx-accessibility-docs | Documentation Clarity Basics | low | 2 |
spec-integrity | OpenAPI Structural Integrity | high | 9 |
dx-tags-navigation | Tag Navigation | medium | 6 |
dx-api-overview | API Overview & Contact Details | medium | 5 |
dx-auth-guidance | Authentication Guidance | high | 5 |
dx-example-validity | Example Correctness | high | 6 |
Design
Design and Developer Experience each contribute 30% of the overall score. Design checks cover API naming, methods, responses, pagination, temporal consistency, and lifecycle documentation.
Check ID | Name | Severity | Weight |
design-uri-naming | Resource URI Naming | medium | 6 |
design-consistent-naming | Consistent Naming | low | 3 |
design-http-methods | HTTP Method Semantics | medium | 4 |
design-status-codes | Status Code Coverage | medium | 6 |
design-versioning | API Versioning | medium | 3 |
design-pagination | Pagination | medium | 7 |
design-content-negotiation | Content Negotiation | low | 6 |
design-filtering-fields | Filtering & Field Selection | medium | 4 |
design-idempotency-key | Idempotency Key | medium | 2 |
design-async-lro | Async/LRO Documentation | medium | 2 |
design-webhooks | Webhook Documentation | medium | 2 |
ops-deprecation | Deprecation Guidance | low | 2 |
design-resource-identifier-consistency | Resource Identifier Consistency | medium | 3 |
design-response-schema-completeness | Response Schema Completeness | medium | 7 |
design-temporal-consistency | Date and Time Consistency | medium | 4 |
Security
Security checks evaluate what the specification declares about transport, authentication, errors, throttling, and credentials. They do not probe the running API or replace an authorization review.
Check ID | Name | Severity | Weight |
sec-https-only | HTTPS Server URLs | high | 3 |
sec-auth-schemes-defined | Auth Schemes Declared | high | 8 |
sec-strong-auth | Credentials Kept Out of URLs | medium | 5 |
sec-unauth-responses | Unauthorized/Forbidden Codes | medium | 5 |
sec-rate-limit-spec | Rate Limit Documentation | medium | 3 |
sec-secrets-hygiene | Secrets Hygiene | medium | 4 |
What moves the score most
Prioritize findings that affect consumers, then consider their weight and category. Structural integrity, useful examples, consistent errors, and complete authentication declarations are common high-impact improvements.
Check | Weight |
spec-integrity | 9 |
dx-executable-examples | 8 |
dx-error-schema | 8 |
sec-auth-schemes-defined | 8 |
ai-op-ids | 6 |
sec-https-only | 3 |
Review check comments before editing. A conditional feature such as pagination or webhooks can legitimately be NotApplicable; adding an irrelevant feature just to change a score does not improve the API.
FAQ
Why can Partial earn more or less than half credit? Many checks return a proportional score based on how much of the specification meets the requirement. Why is a category N/A? It has less than 70% rubric coverage. How do I retrieve full descriptions? Call the public check-catalog endpoint; its descriptions explain what each check evaluates.
On this page
- The check catalog