Agent-Ready APIs: 8 Things That Break AI Agents

Your API works. Developers use it every day. So it should work for AI agents too, right?

Not quite. A developer reads your docs, tries a few calls and learns as they go. An agent reads each action once, fills in the inputs and acts on whatever comes back. It can’t ask a colleague. It can’t open your docs site. Every small gap a developer quietly works around becomes a dead end.

We wanted to see those gaps for ourselves. So we took three public APIs, a weather forecast service, a directory of public APIs and the Swagger Petstore demo shop, turned each into an MCP connector with Gephyr, and used them from real AI apps (Grok and Cursor). Then we asked the questions any user would.

Here’s what broke, how to fix it, and what an agent-ready API looks like.

1. Inputs agents have to guess

What happened. The directory API takes a provider. It means a domain, like googleapis.com, but nothing says so. An agent that sends “Google” gets a 404 and no idea why.

The fix.

• Give every parameter a one-line description and an example.
• List allowed values as an enum, and give numbers a minimum and maximum. Bad values are then caught before the call is ever made.
• If you generate an MCP server from your OpenAPI file, check that your examples survive. Many converters drop them.

With Gephyr: your docs’ examples and rules stay on every input, and Gephyr AI rewrites any input description that’s missing, unclear or written for developers into a short, plain line, using only what your docs show.

2. Rules buried in the docs

What happened. The weather API only returns a forecast if you ask for at least one of current, hourly or daily. Leave them out and you get the location and nothing else. The agent didn’t know the rule, so “what’s the weather this weekend?” came back empty.

The fix.

• Write each rule as one plain sentence in the endpoint’s description: “Ask for at least one of current, hourly or daily.”
• Set a sensible default where you can, so leaving an input out still gives a useful answer.
• If AI rewrites your descriptions, check the rules survive. A friendlier description that drops “at least one of” is worse, not better.

With Gephyr: Gephyr AI keeps rules like these in each action’s description. If it ever leaves one out, Gephyr adds the sentence back from your docs.

3. Docs that disagree with the API

What happened. The pet shop’s docs say a pet’s name is optional when you change its status. The API refuses without one: “No Name provided. Try again?” Its docs also say you can filter by several statuses at once, while its own schema allows only one.

The fix.

• Test your OpenAPI file against your real API, not just your code against your tests. Agents believe the spec.
• Mark what’s really required as required.
• When the two disagree, a clear error message (next section) is what lets an agent recover.

4. Errors that don’t say what to fix

What happened. An unknown field came back as “400 Bad Request”. An unknown provider came back as “404”. The weather API had actually explained the problem (“Invalid timezone”), but that reason never reached the agent. It had nothing to correct.

The fix.

• Return 4xx errors as JSON with a message a person could act on: “Invalid timezone”, “latitude must be between -90 and 90”.
• Pass that reason on to the agent. Never pass on a server error’s stack trace, or anything that echoes a credential.
• For a 404, say what wasn’t found, or point to the list of valid values.

With Gephyr: agents get your API’s own reason when it refuses a call, cleaned and kept short. Sign-in failures, server errors and HTML error pages never reach them. A bare 404 tells the agent to check its names against an action that lists them.

5. Answers that are far too big

What happened. The directory’s “list every API” endpoint returns several megabytes. No agent can use that, and many MCP servers pass it straight into the conversation anyway.

The fix.

• Page every list, and give agents the same limit and cursor inputs everywhere.
• Cut long answers to fit, and tell the agent how much it saw and how to get the rest.
• Switch off endpoints that only return everything at once.

With Gephyr: lists are cut to fit, and the agent is told how much it saw and how to see more. Paging gives every list the same limit and cursor inputs, and import sets it up where your docs show how a list pages. Nothing over 1 MB is ever passed on, and the agent is told how to ask for less instead.

6. Changes that look like they failed, or happen twice

What happened. The pet shop deleted a pet and answered 200 Pet deleted, in plain text rather than JSON. A strict connector reads “not JSON” as “something went wrong” and tells the agent the delete may not have happened. It had.

The opposite mistake is worse. A change times out, the agent tries again, and the class is booked twice.

The fix.

• Answer changes with JSON, or an empty 204. A 2xx with JSON, plain text or no body means done. A 2xx that’s an HTML page (a proxy or sign-in page can answer 200) proves nothing: treat it as unknown and check before trying again.
• Make risky changes wait for the user’s approval, and make each approval work only once.
• When you really can’t tell whether a change happened (a timeout, a 500), say so, and never repeat it automatically.

With Gephyr: payments, cancellations and deletions start on Ask first. The user approves exactly what will happen, the approval works once, and a retry gets the first result back instead of running again. A plain-text “done” from your API counts as done, an HTML page never does, and anything Gephyr can’t be sure of is listed on your dashboard for you to check.

7. Actions an agent can never complete

What happened. The pet shop offers “upload a photo”. An agent in a chat has no file to send, so every call fails with “No file uploaded”.

The fix. Don’t offer agents what they can’t finish: file uploads, binary downloads, admin and webhook endpoints. A short list of actions that work beats a long list that doesn’t.

With Gephyr: import picks the actions a typical user would want (up to 20), leaves out admin, internal and deprecated endpoints, and tells you what it left out and why.

8. Public data behind a sign-in

What happened. The weather API needs no account. But unless the spec marks it public, a connector assumes users must sign in first, and asks them for nothing.

The fix. Mark public operations with security: [] in your OpenAPI file.

With Gephyr: endpoints marked security: [] need no sign-in, and you can switch any action to public data in one click.

The agent-ready API checklist

Frequently asked questions

Is a good REST API automatically a good API for AI agents? It’s a strong start. But agents depend on things developers quietly work around: descriptions, examples, plain rules and readable errors.

Do I need to change my API? Mostly not. Most fixes live in your OpenAPI file: descriptions, examples, enums, defaults, required and security: []. Readable 4xx messages are the main code change.

Does auto-converting OpenAPI to MCP handle this? Rarely. Converters copy what’s in the spec, gaps included, which is why an OpenAPI file on its own isn’t an agent-ready MCP connector. For the bigger picture, see MCP vs embedded AI.

How do I test it? Connect your connector to the AI apps your users have and ask what they’d ask. Watch which inputs agents fill in wrongly and which calls fail. On paid plans, Gephyr’s Test with AI does a first pass before you publish, on real AI models.

Built for this

Every gap above is something we found by testing, and fixed once in Gephyr so every app on it gets the fix.

Gephyr turns your OpenAPI file into a hosted MCP connector that works in ChatGPT, Claude, Grok, Cursor and other AI apps that support MCP. It keeps your docs’ examples and rules, describes what your docs leave out, passes on your API’s reasons without leaking anything it shouldn’t, keeps answers to a size agents can use, and makes risky changes wait for the user. You review everything before it goes live, and you write no code.

Our agent-ready guide has the full list and a checklist. Building and testing are free: start free.