# How to Choose Which APIs to Make Agent-Ready

A practical way to decide which of your APIs need agent-ready work first, based on evidence instead of guesswork. Ends with a free 12+2 point checklist.

## The question every platform team eventually asks

Once agents show up, enterprise platform teams start asking the same question: which APIs should we make agent-ready first? And what's in scope? Do we need MCP servers everywhere, or is a better API enough? Many teams don't have a systematic answer. They guess, or they wait.

## Don't do everything. Start with what customers need most

You don't need to make every API agent-ready. Start with the work your customers need most often. Talk to them. Ask which agents, models, harnesses and clients they use or plan to use. Above all, ask which tasks they want their agents to handle. Those use cases tell you which APIs matter. Make those agent-ready first, and leave the rest for later.

## Expect to redesign, not just document

Map each use case to the calls it takes today. You'll probably find that a task an agent wants to do in one step takes several calls. Agents do better with fewer, bigger steps, so aggregate those discrete calls into flows that match the use case. Cut the fields and endpoints your use cases don't need. Design for the use cases you want to encourage, not every possible one.

## Simplify. Be boring

Keep it simple. Stick to established standards. Don't surprise the agent. Name it well. Describe it well. Agents run on pattern matching, so the most predictable API wins.

## The myth: agents read your docs and your spec

They don't, not the way you'd hope. Agents skip specs for well-known APIs: they use training data, so your docs and specs only matter for APIs they haven't seen before. And agents won't look for docs they think they don't need. They default to confidence over curiosity. They'll try, fail, and retry before reading additional documentation. What they do read is the description in front of them, and descriptions can override schema. Design so the first guess is the right one.

## Good errors make retries cheap

Agents will retry, so make every one count. Good errors enable one-try recovery. Don't just return "400 Bad Request". Use Problem Details ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) and tell the agent which field failed and why. Here's the RFC's own example, shortened. A request sends `"age": 42.3`, and the API answers:

```http
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://example.net/validation-error",
  "title": "Your request is not valid.",
  "errors": [
    {
      "detail": "must be a positive integer",
      "pointer": "#/age"
    }
  ]
}
```

The agent knows exactly which field to fix and how, so one retry does it.

## Run evals with golden prompts

Test with the agents your customers actually use, on the tasks they care about. Turn their use cases into a set of golden prompts: direct prompts that name your product, indirect prompts that only describe the job, and negative prompts where the agent should not call you at all. Run the set, watch where an agent guesses, retries, follows a description over a schema, or gives up and hallucinates an endpoint, and measure how often it succeeds. That gives you a baseline before you change anything and proves each change helped. Run it again whenever the models change.

You can see this kind of testing done in public. Lightsage's [Devtool Arena](https://devtoolarena.com) gives coding agents a real developer task for each tool and scores what happens: success, errors, cost and time. The same tools rank differently depending on the agent. On its CLI boards for November 2, 2026, LiveKit ranked second on Codex but fifth on Claude Code. That's why you test with the agents your customers use.

## Score readiness, but don't trust the score blindly

Automated readiness scoring tools are worth running as a first pass. But most scanners only see the spec ([OpenAPI](https://www.openapis.org) for example). They can't see how agents actually call your API or what your users need from it, and they can flag a choice that's right for your context as a gap. Treat automated scores as a starting point, not a final verdict. Check findings against the spec and real agent behavior before you prioritize based on a number.

## Sequence the stack correctly

Agent readiness isn't only about deciding "API vs. MCP". The API is the foundation: MCP and CLI can wrap your API, and skills should enhance it. Get the API wrong and nothing built on top of it works reliably. An MCP server bolted onto a bad API just wraps the same problems in a new interface. Fix API-level issues (naming, errors, list endpoints, idempotency) before deciding whether a given API also needs an MCP server.

## Start free: the 12+2 point checklist

You don't need a formal engagement to start this work. Run the free [AI-Ready API Checklist](/resources/ai-ready-api-checklist) (12 insights plus 2 pitfalls to avoid) against your top few candidate APIs. It covers the concrete, testable items that show how much work an API needs: descriptive naming, list endpoints, idempotency, structured errors, deprecation signaling and response verbosity.

Want an outside assessment of your APIs, docs and MCP server, run as a developer and as an AI agent, with the fixes to make first? See the [Agent Readiness Assessment](/services/dx).

### FAQ

**Should we make all our APIs agent-ready at once?** No. Start with what your customers need most. Ask them which agents, models, harnesses and clients they use, and which tasks they want their agents to handle. Make the APIs behind those tasks agent-ready first.

**How do we know an API is actually agent-ready, not just well-documented?** Run evals: give the agents your customers use the tasks they care about, and measure how often they succeed. Automated scoring tools are a useful first pass, but they only see the spec. Check any score against actual agent behavior before you trust it.

**What's a low-cost way to start scoping this?** Run the free 12+2 point checklist against your top 3-5 candidate APIs before you build anything. It surfaces the concrete gaps that set both effort and priority: missing list endpoints, weak error responses, vague field names.

Source: Level 250 — https://www.level250.com/guides/how-to-determine-which-apis-to-make-agent-ready