Your API was designed for a developer who reads the docs, tries it, gets confused, and asks a colleague. An agent does none of that. It reads your description once and commits.

That single difference changes what good API design looks like, and most of the fixes are cheap.

Names Are Now Documentation

A developer seeing POST /v2/entities will go and find out what an entity is. An agent will guess, and it will guess confidently.

Name endpoints and parameters for what they do in the language of the domain. create_customer_refund beats post_txn_v2 even if the latter matches your internal vocabulary. Your internal vocabulary is not in the model training data. Plain English is.

Errors Should Tell the Caller What to Do Next

This is the highest-leverage change on the list. A bare 400 tells an agent that something is wrong and nothing about what to try next, so it retries the same call and burns your rate limit.

Return errors that name the fix. Customer not found for that email, use search_customers to get an ID first turns a dead end into a next step. Agents follow instructions well, which means an error message is now a control surface.

Six Changes That Make an API Agent-Friendly

• Return fewer fields by default. Every unnecessary field is context an agent pays for and may misread. Offer expansion rather than dumping everything.
• Make pagination obvious. Explicit cursors and a clear has_more flag. Agents handle offset pagination badly and will loop.
• Give idempotency keys on writes. Agents retry. Assume every write will happen twice and design so that is harmless.
• Provide a search or resolve endpoint. Agents constantly have a name and need an ID. Without a lookup, they invent one.
• Document preconditions in the description. Say when NOT to use an endpoint. That single sentence prevents most wrong tool selection.
• Keep enum values readable. Status values like pending_review beat integer codes an agent has to remember a mapping for.

Then Consider an MCP Server

Once your API is agent-friendly, wrapping it in an MCP server is a small step and it changes distribution. Your API becomes usable from any compliant client without anyone writing an integration.

The current stateless spec makes this cheap to host: no session store, no sticky routing, just an HTTP handler. But resist the temptation to map every endpoint to a tool. A server exposing eight well-chosen tools outperforms one exposing eighty, because tool selection accuracy falls as the menu grows.

The Test to Run Before You Ship

Hand your API description to an agent with no other context and ask it to complete a realistic task. Watch where it hesitates, what it invents, and which endpoint it reaches for wrongly.

Every wrong turn is a documentation bug you can fix in an afternoon. This test takes twenty minutes and finds more usability problems than a quarter of developer surveys.

Conclusion

Rename for clarity, make errors prescriptive, add idempotency keys and a resolve endpoint, and trim your default responses. Then test the whole thing by letting an agent try to use it cold. Agent-ready APIs are simply well-documented APIs with better error messages, which means this work improves the human developer experience at the same time.

Frequently Asked Questions

Do we need a separate API for agents?

Rarely. A thin tool layer over your existing API is usually enough, and a second API doubles your maintenance for little benefit.

How many tools should one MCP server expose?

Start under ten. Group related operations rather than exposing every endpoint. Precision beats coverage when the caller is choosing from a list.

What about rate limiting agents?

Rate limit per identity and expect bursty traffic. The current MCP spec puts method and tool names in HTTP headers, so your gateway can meter specific tools without parsing request bodies.