`score`

Introduction

The score command analyzes an OpenAPI description and produces a composite Agent Readiness score (0–100) that measures how easy the API is to integrate and how usable it is by AI agents and LLM-based tooling. Higher is better.

In addition to the top-level score, the command reports normalized subscores, raw metrics for every operation, and a list of hotspot operations — the endpoints most likely to cause integration friction — along with human-readable explanations.

Important

The score command is considered an experimental feature. This means it's still a work in progress and may go through major changes.

The score command supports OpenAPI 3.x descriptions only.

Metrics

The following raw metrics are collected per operation and aggregated across the document:

Metric	Description
Parameter count	Total parameters (path, query, header, cookie) per operation.
Required parameter count	How many of those parameters are required.
Request body presence	Whether the operation defines a request body.
Top-level writable field count	Number of non-`readOnly` top-level properties in request schemas.
Max request/response schema depth	Deepest nesting level in request and response schemas.
Polymorphism count	Number of `oneOf`, `anyOf`, and `allOf` usages. `anyOf` is penalized more heavily because it allows ambiguous combinations of schemas, making it harder for consumers and AI agents to determine the correct shape.
Property count	Total schema properties across request and response.
Description coverage	Fraction of operations, parameters, and schema properties that have descriptions.
Ambiguous identifier count	Parameters with generic names (e.g. `id`, `name`, `type`) and no description.
Constraint coverage	Count of constraining keywords (`enum`, `format`, `pattern`, `minimum`, `maximum`, `minLength`, `maxLength`, `discriminator`, etc.).
Request/response example coverage	Whether request and response media types include `example` or `examples`.
Structured error response coverage	How many 4xx/5xx responses include a content schema or meaningful description.
Security scheme coverage	Whether operations reference documented security schemes with descriptions.
Cross-operation dependency depth	Inferred from shared `$ref` usage across operations. Operations that share many schemas form a dependency graph; deeper graphs indicate tightly coupled multi-step interactions.

Subscores

The following subscores are normalized to 0–1 and combined into the composite Agent Readiness score:

parameterSimplicity, schemaSimplicity, documentationQuality, constraintClarity, exampleCoverage, errorClarity, dependencyClarity, identifierClarity, polymorphismClarity, discoverability.

The discoverability subscore reflects the total number of operations in the API. Larger APIs (approaching 1,000+ operations) receive a lower discoverability score because finding the right endpoint becomes harder for both humans and AI agents.

Hotspots

The command identifies the operations with the lowest scores and provides reasons such as:

"High parameter count (N)"
"Deep schema nesting (depth M)"
"Polymorphism (anyOf) without discriminator"
"Missing request and response examples"
"No structured error responses (4xx/5xx)"
"Missing operation description"

Usage

redocly score <api>
redocly score <api> [--format=<option>]

Options

Option	Type	Description
api	string	REQUIRED. Path to the API description filename or alias that you want to score. Refer to the API section for more details.
--config	string	Specify path to the configuration file.
--format	string	Format for the output. Possible values: `stylish`, `json`. Default value is `stylish`.
--operation-details	boolean	Print a per-operation metrics table sorted by property count.
--debug-operation-id	string	Print a detailed schema breakdown for a specific operation (by `operationId` or `METHOD /path`).
--help	boolean	Show help.
--lint-config	string	Specify the severity level for the configuration file. Possible values: `warn`, `error`, `off`. Default value is `warn`.
--version	boolean	Show version number.

Examples

Specify API

Pass an API directly

redocly score openapi/openapi.yaml

Specify output format

Stylish output (default)

The default output format shows a human-readable summary in your terminal:

  Scores

  Agent Readiness:  68.3/100

  Subscores

  Parameter Simplicity     [████████████████░░░░] 80%
  Schema Simplicity        [██████████████░░░░░░] 70%
  Documentation Quality    [████████████░░░░░░░░] 60%
  Constraint Clarity       [██████████░░░░░░░░░░] 50%
  Example Coverage         [████████████████████] 100%
  Error Clarity            [████████████████░░░░] 80%
  Dependency Clarity       [██████████████████░░] 90%
  Identifier Clarity       [████████████████████] 100%
  Polymorphism Clarity     [████████████████████] 100%
  Discoverability          [████████████████████] 100%

  Top 3 Hotspot Operations

  POST /orders (createOrder)
    Agent Readiness: 38.7
    - High parameter count (12)
    - Deep schema nesting (depth 6)
    - Missing request and response examples

  PUT /orders/{id} (updateOrder)
    Agent Readiness: 44.0
    - Polymorphism (anyOf) without discriminator (3 anyOf)
    - No structured error responses (4xx/5xx)

JSON output

Use --format=json for machine-readable output:

redocly score openapi.yaml --format=json

The JSON output includes the full data: top-level scores, subscores, per-operation raw metrics, per-operation scores, dependency depths, and hotspot details with reasoning.

The JSON format is suitable for CI pipelines, quality gates, or feeding results into dashboards.

score