Why API Docs Are Broken for AI Agents

LAP Team
apiagentsproblem

Every major API publishes an OpenAPI spec. It’s the universal contract — endpoints, parameters, auth, examples, all in one file. Human developers skim it in a browser. AI agents have to swallow it whole.

That’s the problem.

The Token Tax

The average OpenAPI spec is 87,000 tokens. Stripe’s is 1.2M. Salesforce clears 200K. An agent that needs to call an API must first understand the spec — and understanding means reading the entire thing into its context window.

For a single API call, an agent might burn 100K tokens just to learn how to make the request. The actual work — figuring out which endpoint to call and what parameters to pass — takes a fraction of that. The rest is noise: verbose descriptions written for humans, redundant schema definitions, deprecated endpoints nobody uses, example values that don’t help a machine.

This is the token tax. Every agent-to-API interaction pays it.

Why Specs Are So Bloated

OpenAPI wasn’t designed for agents. It was designed for documentation generators, SDK builders, and API gateways. These tools want verbosity:

  • Human-readable descriptions with markdown formatting, usage notes, and caveats
  • Exhaustive examples showing every possible request/response shape
  • Deprecated endpoints kept for backward compatibility
  • Deeply nested schemas with $ref chains five levels deep
  • Redundant definitions — the same error object defined in every response

A documentation tool renders all of this beautifully. An AI agent chokes on it.

The Cost Multiplier

Token bloat isn’t just a performance issue - it’s a cost issue. With Claude Sonnet at ~$3 per million input tokens, loading Stripe’s 1.2M token spec into context costs $3.60 before the agent even starts reasoning. Now multiply that across the 5-10 APIs a real agent needs in a single session.

Our benchmarks across 50 APIs and 500 agent runs show the real impact:

  • Agents using full specs: $0.37 per run average
  • Agents using compressed specs: $0.24 per run
  • That’s a 35% cost reduction — without losing any capability

In fact, agents performed slightly better with compressed specs (0.851 vs 0.824 success rate). Less noise means clearer signal. Full benchmark report.

The Context Window Problem

Even with models supporting 100K+ token windows, context is a shared resource. An agent that burns 1.2M tokens on a single API spec has that much less room for:

  • The user’s actual request and conversation history
  • Results from previous API calls
  • Other tools and APIs in the agent’s toolkit
  • Chain-of-thought reasoning

When agents orchestrate multiple APIs — say, reading from Salesforce, writing to HubSpot, and sending a Slack notification — the combined spec size can exceed the entire context window. Something has to give, and usually it’s the agent’s ability to reason effectively.

What “Agent-Ready” Actually Means

An agent-ready API spec is one that gives the agent exactly what it needs to make correct API calls — and nothing else:

  • Endpoint signatures with parameter names, types, and constraints
  • Auth requirements — what credentials are needed and where they go
  • Essential descriptions — one line per endpoint, not a paragraph
  • Schema structure — without redundant nesting or unused definitions

Everything else is documentation, not instruction. The distinction matters.

This Is a Format Problem

The solution isn’t better prompting or smarter agents. It’s a better format. API specs need a representation optimized for machine consumption — one that preserves the information agents need while stripping the 90% they don’t.

That’s what we built LAP for. A compiler that takes any API spec — OpenAPI, GraphQL, AsyncAPI, Protobuf, Postman — and produces a lean, agent-ready version. Across our registry of 1,500+ APIs, the average compression is 10×.

The details of how it works are a story for tomorrow. Today, the point is simpler: the specs we’re feeding our agents were never designed for them, and it’s costing us — in tokens, in money, and in capability.

Try it yourself:

Install a pre-built API skill in one command:

npx @lap-platform/lapsh skill-install stripe

Your agent now has Stripe access at 10× fewer tokens. Browse 1,500+ APIs at registry.lap.sh.

Building your own? Compress any spec:

pip install lapsh
lapsh compile your-api-spec.yaml