When an AI assistant uses an API, it does not read the documentation the way a person does. It picks from a list of named tools. How those tools are named, described and labelled decides whether it picks the right one. So I looked at how ready public APIs are for that.
What I did
I took 150 OpenAPI files from a public, open dataset and ran an open-source linter on each, entirely offline. I did not call any live API and I did not test any AI agent. I am not naming companies, because a gap in a specification is not a verdict on a company or its product.
What I found
- 42 of the 150 files (28%) had operation IDs missing on at least half of their operations. An operation ID is the short name a tool is usually built from.
- The median lint score under the linter’s default rules was 19 out of 100. I do not treat that as a quality measure: the default rules are mostly about style, so a low score says little about whether an API works.
Why operation names matter to an agent
If a specification has no operation IDs, a generator has to invent tool names from the URL path. Invented names tend to be long, similar to each other and hard to tell apart. An agent choosing between two near-identical names is more likely to pick the wrong one.
What I would do about it
- Give every operation a clear, unique ID and a one-sentence description of when to use it.
- Expose a curated set of tools instead of every endpoint.
- Label which tools only read, which write, and which delete or cost money, including any GET request that does more than read.
Limits of this study
The dataset copies may be older than the live specifications. The linter checks the file, not the running API. I did not measure any agent, so I make no claim about how much better tuned specs perform. Treat these figures as a snapshot of the files, not as a ranking of the companies behind them.
If you would like a short snapshot of your own specification, you can ask for a free spec check on the Contact page.
