Technical perspective
AI extraction vs OpenAPI specs
OpenAPI specs are a great starting point. But human-written docs almost always contain richer context — and that context is what makes a CLI actually useful for AI agents.
We support both. Here's why we don't stop at OpenAPI.
If your API has an OpenAPI spec, InstantCLI can use it. Specs give you structured endpoint definitions, parameter types, and response schemas — all machine-readable and reliable.
But in practice, most OpenAPI specs are auto-generated from framework code. They capture the shape of an API without the intent. The descriptions are minimal, the field-level documentation is often empty, and the context that helps a developer (or an AI agent) understand what an endpoint actually does is missing.
That context lives in the human-written docs. So we scrape those too.
OpenAPI specs are sometimes great. Sometimes not.
Some teams maintain excellent OpenAPI specs with rich descriptions, thorough examples, and complete field documentation. For those APIs, the spec is a fantastic resource and we use it.
But in our experience, most specs fall into one of these categories:
- Auto-generated and minimal — framework scaffolding with empty or one-line descriptions
- Out of sync — the spec was written once and hasn't kept up with the actual API or its docs
- Non-existent — many APIs only have human-written docs
By scraping the human-written docs with AI, we capture the full picture regardless of what the spec provides.
A real comparison: PokeAPI
PokeAPI is one of the most well-known public APIs. It has both comprehensive human-written docs and an OpenAPI spec. We ran both through our pipeline and compared the results.
Endpoint descriptions
The OpenAPI spec has descriptions, but they're typically one-liners. Our AI extraction from the docs produces significantly richer context:
| Endpoint | OpenAPI spec | AI extraction |
|---|---|---|
| Berry Firmness | Berries can be soft or hard. | Berries can be soft or hard, and firmness determines how they perform in Pokéblocks or Poffins. Retrieve by ID or name. |
| Nature | Natures influence how a Pokémon's stats grow. | Natures influence how a Pokémon's stats grow, affecting one stat positively and one negatively by 10%. Returns stat changes, flavor preferences, and battle style preferences. |
| Encounters | Handles Pokemon Encounters as a sub-resource. | Retrieve location areas where a Pokémon can be encountered, including game versions, encounter methods, level ranges, and rates. |
| Pokemon Shape | Shapes used for sorting Pokémon in a Pokédex. | Categorize Pokémon by body shape (ball, squiggle, fish, etc.). Returns shape name, 'scientific' names, and all species with that shape. |
| Move Learn Method | Methods by which Pokémon can learn moves. | The different ways Pokémon can learn moves, such as 'level-up', 'machine', or 'breeding'. |
The extracted descriptions explain what the resource is, why it matters, and what to expect back. These become the --help text in the generated CLI — the first thing an AI agent reads when deciding which command to run.
Schema descriptions: the bigger gap
Endpoint descriptions are one thing. But the real gap is at the field level. PokeAPI's OpenAPI spec defines detailed response schemas — but none of the fields have descriptions:
| Schema | Fields | With descriptions |
|---|---|---|
| BerryDetail | 12 | 0 |
| PokemonDetail | 20 | 0 |
| MoveDetail | 24 | 0 |
| AbilityDetail | 9 | 0 |
| NatureDetail | 10 | 0 |
Our extraction captures response examples with realistic data for every endpoint — actual field names, values, and nested structures. An AI agent reading these examples immediately understands what growth_time, fling_power, or damage_relations contain, without needing field-level docs.
Even PokeAPI — a well-maintained, popular, open-source project — has typos in its spec summaries (List charecterictics, Get pokemom habita). The human-written docs don't have these issues.
Why this matters for AI agents
When an AI agent runs pokemon-cli pokemon get --help, the help text it sees determines whether it uses the command correctly. Richer descriptions mean:
- The agent picks the right command on the first try, not after trial and error
- It understands parameter formats (ID vs name, required vs optional)
- It knows what to expect in the response without making a speculative call first
This is the difference between a CLI that technically works and one that an agent can operate fluently.
InstantCLI reads your human-written docs the same way a developer would — understanding context, extracting examples, and capturing the explanations that make an API make sense. If you have an OpenAPI spec, we use that too. The combination of both produces CLIs with the most complete, most helpful documentation — which is exactly what AI agents need to operate effectively.
InstantCLI generates agent-ready CLIs from any REST API docs — with rich help text, JSON output, and lazy discovery built in.
Get started