# Readiness rules

Every version you push is scored from 0 to 100 by these rules, version 1.0.3. The version's report lists each rule's findings.

## The score

Each rule applies to some of your operations or parameters, and its share is the part of those that pass. A rule with nothing to apply to passes. The score is the sum of each rule's weight times its share, divided by the total weight (88), times 100, rounded to a whole number.

## The rules

| Rule | What it checks | Weight | How to fix it |
| --- | --- | ---: | --- |
| `operation-ids` | Every operation has a clear operationId | 10 | Give each operation an operationId that says what it does (listOrders, refundOrder). It becomes the tool name. |
| `descriptions` | Descriptions say what the operation does, when to use it, and what it returns | 10 | Write a description of at least 40 characters per operation, different from the others: models pick tools by it. |
| `summaries` | Every operation has a summary | 8 | Add a short summary (under 80 characters): clients show it as the tool's title. |
| `parameter-descriptions` | Parameters are described | 8 | Describe each parameter: its meaning, format and allowed values. |
| `response-schemas` | Success responses have a JSON schema | 8 | Describe what a 2xx response contains with a JSON schema, so agents know what they'll get back. |
| `security` | How to authenticate is described | 8 | Describe your auth in components.securitySchemes and apply it with security. |
| `examples` | Operations have an example | 6 | Add an example for each operation (a parameter, request or response example): models copy examples. |
| `error-responses` | Errors are described | 6 | Document the errors an operation returns (400, 404, 409…) so agents can recover instead of retrying blindly. |
| `pagination` | List endpoints are paginated | 6 | Give list operations a limit and a cursor (or page) parameter: an agent can't read ten thousand rows. |
| `json-bodies` | Request bodies are JSON | 5 | Accept application/json for request bodies agents send (form and multipart bodies can't be tool calls). |
| `idempotency` | Writes have an idempotency story | 5 | Accept an Idempotency-Key header on POST/PATCH (Agentify honours it for agents), so a retry doesn't do the work twice. |
| `enums` | Parameters with a fixed set of values list them | 4 | Give status/sort/type-like parameters an enum (or list the values in the description). |
| `tool-count` | A manageable number of tools, with distinct names | 4 | Keep enabled tools to about 40 per server (models choose worse from long lists), and give operations distinct operationIds. |

## Run them yourself

The same rules are public as [openapi-agent-check](https://www.npmjs.com/package/openapi-agent-check) (MIT), so you can score a document on your machine or in CI before you push it.

## Where this comes from

- `app/api/readiness/_lib/agentify/rules.ts`
- `app/api/readiness/_lib/report.ts`
- `app/registry/_lib/store.ts`
- `app/_lib/entity.ts`