API discoverability for AI agents: why your docs aren't the interface anymore

Agents don't read your docs. They read your surface — and if your surface doesn't describe itself, the agent picks wrong, calls the wrong endpoint, or gives up. API discoverability for AI agents is a runtime property now, not a documentation exercise, and most SaaS platforms are still solving it with a portal refresh.

That's the wrong layer. Discoverability used to mean "can a developer find the right endpoint in under five minutes." For agents, it means "can a model, mid-reasoning-loop, resolve which of your 400 endpoints to call, with what arguments, under this user's permissions." Those are different problems. Confusing them is why agent projects on public APIs stall even when the docs look great.

Discoverability is now a runtime property, not a docs property

A human developer discovers your API asynchronously. They read, prototype, come back the next day. Latency doesn't matter — they'll figure it out. An agent discovers your API inside a single request. It has a user's task, a token budget, and no memory of yesterday's session. The "index" it consults is whatever tool descriptions you handed it at runtime.

So the real question isn't whether your API is documented. It's whether the machine-readable description of each capability — name, purpose, arguments, error contract, permission scope — is available at the moment the agent needs to choose. If that description lives in a Notion page, a PDF, or prose paragraphs on a developer portal, it's invisible. See our take on why public API documentation practices have to change for the agent era — the short version is that docs are now a compilation target, not a destination.

The three things agents actually need to discover

We keep seeing the same gap on discovery audits. Teams have great reference docs and no discoverability. Agents need three things, in this order:

1. What capabilities exist. Not endpoints — capabilities. create_invoice is a capability. POST /v2/billing/invoices is an endpoint. Agents reason about the first and call the second.
2. When to use each one. A one-line purpose statement that disambiguates from adjacent capabilities. "Creates a draft invoice for a customer" vs "finalises and sends an existing draft invoice." That's the sentence the model reads at selection time.
3. What arguments are required, and what they mean. Field names and types aren't enough. customer_id is not self-describing. customer_id (the Stripe customer ID from your accounts system, format cus_xxx) is.

That's it. Most OpenAPI specs cover #1 by accident, #2 poorly, and #3 not at all. See OpenAPI specification best practices for agents and SDK generators for what a spec that carries this weight actually looks like.

Why "just publish an OpenAPI spec" isn't the answer

We hear this one a lot: "we have a spec, we're covered." A spec is necessary. It's not sufficient. An OpenAPI document tells an agent that an endpoint exists and what shape its request body takes. It rarely tells the agent whether this is the endpoint it should call for the task at hand.

Two problems in practice. First, most public specs describe roughly the 2% of platform capability that got API'd — the endpoints your APIs actually expose, not what your product can do. That's the structural gap we've written about elsewhere. No amount of metadata polish fixes it. Second, specs describe endpoints in the language of the API team. Agents pick tools in the language of the user's task. The translation between the two — semantic descriptions, disambiguating summaries, worked examples — is what actual agent-friendly API design produces, and it almost never lives in the spec.

MCP moved some of this into a protocol. The Model Context Protocol (MCP) formalises tool descriptions as runtime metadata the model reads at selection time. That's progress. But MCP inherits whatever your source surface exposes — if the underlying API only covers 2%, the MCP server covers 2% too. Protocol doesn't manufacture surface.

What actually moves the needle

Three shifts, in order of impact:

Treat tool descriptions as production code. Version them, test them, review them. The one-line purpose statement on each tool is a product decision, not a doc string. When two capabilities have overlapping descriptions, agents oscillate between them non-deterministically. That's a bug — file it like one.

Add semantic metadata, not just structural metadata. Structural metadata (types, formats, required fields) tells the agent how to construct a call. Semantic metadata (when to use this, when not to, what typically comes before or after, what user permission is required) tells the agent whether to call it at all. The second category is where agent-friendly API design earns its keep.

Close the loop with runtime observability. You'll never know if your discoverability is working until you can watch agents choose. Which tools get selected. Which get selected and then abandoned mid-argument-filling. Which never get selected despite matching the task. That signal is where the next round of description improvements comes from — and it's the same principle as agent evals grading tool calls, not just outputs.

How Pontil fits

Discoverability at scale is where the argument in this piece meets the argument for Tools-as-a-Service. If your platform has 400 endpoints and you're writing tool descriptions by hand, you'll ship the first 40 well and the rest will drift. That's not a discipline problem — it's a compounding-work problem.

Pontil generates tools from your existing codebase and keeps their descriptions, argument schemas, and permission scopes aligned with the product as it changes. The agent surface stays current because it's derived from the source, not maintained alongside it. Runtime execution happens as the authenticated user, so the discoverability layer and the permission layer stay in sync — an agent can't discover a capability it isn't allowed to invoke. That combination is what makes discoverability a solved property of the platform rather than a per-endpoint chore.

If you want to see what that looks like against a real codebase, book a walkthrough.

What this means for your roadmap

Stop treating discoverability as a docs milestone. It's a runtime interface, and it deserves the same review discipline as your public API contract. Audit your tool descriptions the way you audit endpoint responses. Instrument tool selection the way you instrument request latency. Ship semantic metadata alongside structural metadata, and treat gaps between the two as bugs.

The teams pulling ahead on agent projects aren't the ones with the best-looking developer portals. They're the ones whose agents pick the right tool on the first try — because someone made discoverability a property of the surface, not a property of the documentation site sitting next to it.