Skip to content
Redocly CLIexperimental

Can AI agents call your API?

redocly score checks your OpenAPI description and gives it an Agent Readiness score from 0 to 100: how easily agents and developers can call it. Ten subscores explain the score, and hotspots name the operations to fix first.

Static analysis · no model · no API calls

npx @redocly/cli score openapi.yaml
Agent Readiness · Cafe API
82.2 out of 100
Hotspots · ranked by the CLI
GET /menu6 parameters · depth 5 · 6 polymorphic
72.5
PUT /oauth2/register/{clientId}anyOf without discriminator · no response examples
67.9
POST /oauth2/registeranyOf without discriminator · no response examples
68.9

Developers, SDK generators, and AI agents all read the same description. Fix what the score flags, and every reader benefits.

10

subscores behind one number

100%

same description, same score

< 10 ms

to score the 20-operation Cafe API

/ Who reads it

One description, three readers

What trips up an agent usually trips up everyone else too.

Developers

Read the reference and copy an example. Vague parameters and missing examples cost them time.

SDK generators

Turn schemas into types. An anyOf without a discriminator often becomes a loose union that callers must narrow by hand.

AI agents

Plan every call from the description alone and cannot ask anyone. They are the strictest reader, so the score is called Agent Readiness.

/ AI agents

Where agents have to guess

Every low subscore marks a place where an agent has to guess. Here are three in the Cafe API, our demo API.

  • Schema Simplicity

    59%
    Risk for an agent

    Harder to fill in correctly: a response nests 6 levels deep.

  • Example Coverage

    60%
    Risk for an agent

    No example to copy for 9 of 20 responses.

  • Polymorphism Clarity

    74%
    Risk for an agent

    No discriminator to tell which anyOf shape a payload must match.

/ Subscores

Ten reasons behind one number

Pick a subscore to see what it measures and how the Cafe API does.

Schema Simplicity

59%

How deep request and response schemas nest, and how many properties they carry.

In the Cafe API
GET /order-items nests 6 levels deep.
To raise it
Flatten deep nesting and extract repeated shapes into components.

/ Inputs and outputs

One description in, four views out

OpenAPI 3.x
Single file, YAML or JSON
Multi-file with $ref
API alias in redocly.yaml
redocly score
Views
Terminal reportno flag
JSON for CI--format=json
Per-operation table--operation-details
Schema breakdown--debug-operation-id <id>

Experimental: the scoring can change between releases.

/ How it works

From a score to a fix in three steps

  1. Run it

    The report opens with the score, then the ten subscores behind it.

    redocly score openapi.yaml
    Agent Readiness:  82.2/100

Schema Simplicity   59%
Example Coverage    60%

  2. Read the hotspots

    The report ends with the operations that pull the score down, and why.

    GET /menu (listMenuItems)
  Agent Readiness: 72.5
  - High parameter count (6)
  - Deep schema nesting (depth 5)
  - High polymorphism count (6)

  3. Drill into one operation

    See every schema behind the numbers, and change the one that costs the most.

    redocly score openapi.yaml --debug-operation-id listMenuItems
    #/components/schemas/MenuItem [oneOf:2]
  #/components/schemas/Beverage [allOf:2]
  #/components/schemas/Dessert [allOf:2]

Totals: 20 properties, 6 polymorphism items,
16 constraints, max depth 5

/ Lint or score

Valid is not the same as easy

A description can pass every lint rule and still be hard to call. Use both.

redocly lint
Answers

Is the description valid, and does it follow your rules?

Output
A list of problems, by severity
Fails the build
On error-level problems
Configuration
Optional – recommended rules by default
redocly score
Answers

How easy is the API to call correctly?

Output
An Agent Readiness score from 0 to 100, ten subscores, and ranked hotspots
Fails the build
Only when you gate on the JSON report
Configuration
None – the scoring is fixed

Keep the score from sliding back

Write the report as JSON and fail CI when the score or any subscore drops below your threshold. Pin the CLI version for a stable gate.

Gate CI on the score
ci.sh
set -e
redocly score openapi.yaml --format=json > score.json
jq -e '.agentReadiness >= 80' score.json
jq -e '.subscores.exampleCoverage >= 0.6' score.json
# the overall score is 0–100, subscores are 0–1 in JSON

Frequently asked questions

How easily an AI agent or LLM-based tool can call your API correctly from its OpenAPI description alone. The score looks at parameter and schema complexity, description and constraint coverage, examples, error responses, dependencies between operations, identifiers, polymorphism, and the size of the API.

What does your API score?

One command, one number, and a list of what to fix first.

npx @redocly/cli score openapi.yaml