Let Your Agent Improve Your APIs for AI-Readiness

Assessing APIs for AI-readiness is clearly an important step for thousands of companies worldwide undergoing AI transformation. The reason is simple: APIs are critical to enabling AI agents connect to enterprise landscapes. Getting a clear baseline on your API landscape's ability to be discovered and safely used by AI consumers is enlightening.

Then comes the harder question: what do you actually change, in what order, and how do you know the result is better without breaking anything?

That is the gap our new jentic-api-improve agent skill closes.

In a previous post, we showed how the Jentic API Scorecard skill lets your agent measure AI-readiness across six dimensions of our AI-readiness framework and surface exactly which signals are dragging the score down. The next step was always obvious: once you know where your API falls short, your agent should be able to do something about it.

The Jentic api-improve skill

jentic-api-improve is a native agent skill that takes an OpenAPI document and drives a structured improvement loop. It scores, plans, generates a standards-compliant OpenAPI Overlay, applies it, validates the result against a three-way diff, and rescores. The agent reasons over what actually needs to change and why, constrained to non-breaking improvements throughout.

It works natively with Claude Code and the Vercel Skills CLI.

See it in action

The walkthrough above shows the full cycle: baseline score, improvement loop, revised OpenAPI, Overlay file, and changelog — from a single agent instruction.

Getting up and running in under two minutes

Everything you need is in the jentic/jentic-api-scorecard repository. The short version:

1. Install the skill

Claude Code:

/plugin install api-improve@jentic-api-improve

Vercel Skills CLI:

npx skills add jentic/jentic-api-improve

2. Get a free API key

Head to app.jentic.com/scorecard, create a key, and export it in your terminal:

export JENTIC_API_KEY=***

3. Ask your agent to improve an API

That is it. No CLI flags to memorise. No options to configure. Just ask:

Improve ./openapi.yaml for AI-readiness
Generate an improved version of https://petstore3.swagger.io/api/v3/openapi.json

How the improvement loop works

This is not a one-shot patch. jentic-api-improve runs a structured, validated loop with explicit checkpoints at every stage.

Score: establish a baseline

The agent scores the input OpenAPI document using the Jentic API Scorecard and records the starting grade and per-dimension breakdown. This is the benchmark everything is measured against.

Improvement iterations

Each iteration follows the same fixed sequence:

1. Plan: the agent analyses the scoring signals and identifies the highest-impact improvements that can be made without introducing breaking changes. It reasons over trade-offs: what will move the score, what is safe, and what should be deferred.

2. Generate an Overlay: rather than modifying the source OpenAPI directly, the agent produces an OpenAPI Overlay file. An Overlay is an OAI standard: a structured, machine-readable diff that describes exactly what changes and why. The improvement record is portable, reviewable, and reapplicable independently of the skill.

3. Apply the Overlay: the Overlay is applied to the original document to produce an improved OpenAPI file.

4. Validate: the skill runs a three-way diff: original vs improved vs Overlay. It verifies that the applied changes match the Overlay exactly, no more and no less. If the diff does not align, the iteration fails and the agent does not proceed. This is the quality gate most tools skip entirely.

5. Rescore: the improved document is scored against the same JAIRF dimensions. The delta tells the agent whether the changes had the intended effect and whether further improvements are viable.

The loop runs for up to two iterations by default. After each pass, the agent determines whether further non-breaking improvements remain. If the score has plateaued, or only breaking changes would move it further, the loop ends.

After the iterations, you review the outputs and decide whether additional passes are warranted. That decision stays with you, not the agent.

What you get at the end

Each run produces three artifacts:

• Revised OpenAPI: the improved document, ready to use or review
• Overlay document: the machine-readable record of every change made, in OpenAPI's Overlay format
• Human-readable changelog: a plain-language markdown summary of what changed, what score improvement was achieved, and what was intentionally left out of scope

The Overlay is not a by-product, it is a first-class output. You can inspect it, version it, apply it selectively, or use it as a specification for follow-up work. That matters practically: if your organisation has a review and approval process before API changes land in production, the Overlay is the artifact that drives that pipeline. It tells reviewers exactly what changed and why, in a machine-readable format they can diff, audit, or reject. That is what separates jentic-api-improve from a script that rewrites your OpenAPI and hopes for the best.

Why non-breaking changes only

Improving AI-readiness does not require touching your API contract. The gap between a valid OpenAPI document and one an agent can actually use is almost entirely in the metadata layer: descriptions, summaries, examples, error response detail, parameter semantics, and discoverability signals.

Fixing those things does not change a single endpoint. It does not break existing clients. It does not require a version bump. And it can move a score from the 30s into the 60s or 70s.

Breaking changes are engineering decisions. They involve trade-offs that require human judgment, and in its initial version jentic-api-improve deliberately stays out of that territory.

Why this matters

From our analysis of over 6,000 APIs, one thing is clear: most were built with a human developer in mind, and many did not adequately address even basic developer experience. There has long been a gap between what API producers deliver and what consumers actually need. That gap compounds significantly when the consumer is an agent. Agents do not ask colleagues for clarification or make informed guesses when something is ambiguous. When an API is incomplete, inconsistent, or poorly described, the results range from silent failures and unhelpful retries to agents that confidently do the wrong thing.

The API AI-Readiness Framework makes that gap measurable. The OpenAPI Overlay specification makes the fix machine-readable, auditable, and safe to apply without breaking existing consumers. Together, they are what makes it possible to harness both insights, turning a measurable shortfall into a non-breaking, validated improvement loop your agent can run, and your team can review and trust.

Score it, automatically improve it, and ship APIs your agents can actually use.

Skill: github.com/jentic/jentic-api-scorecard

Scoring baseline: jentic.com/scorecard