July 15, 2026 · The MCPCloud team
Why agents can’t use your OpenAPI spec
Spec summaries are written for humans with the docs open. Agents pick tools from descriptions alone — here is what goes wrong, with real before/after rewrites.
Your OpenAPI spec is probably fine. It is accurate, it is complete, and it was written for a reader who does not exist in an agent loop: a human developer with the full reference docs open in the next tab. An agent choosing a tool mid-conversation has none of that. It sees exactly what tools/list gives it — a name, a description, a schema — and it decides from the description alone.
Two very different readers
A human who reads “Delete a customer” in a spec index clicks through to the reference page, sees the warning about irreversibility, checks what happens to the customer’s subscriptions, and then decides. The one-liner was never meant to carry the decision — it was an index entry pointing at the real documentation.
The agent gets the index entry and nothing else. When the description says “Merge.” — and we have seen exactly that string come out of a spec — the model fills the gap with its own assumptions about what merging means here, which strategy applies, and what comes back. Sometimes it guesses right. The failures are the point: an agent that guesses is an agent you cannot put in front of a write endpoint.
What goes wrong in practice
Two failure modes dominate. The first is wrong-tool calls. Our Stripe showcase server exposes a curated 34-tool surface, and it includes both POST /v1/subscriptions/{id} (update) and DELETE /v1/subscriptions/{id} (cancel). With framework-generated one-liners, those two descriptions differ by roughly one verb. A model choosing between them mid-conversation, with a user who said “stop billing this customer,” is doing coin-flip disambiguation on a destructive action.
The second is unsafe invocation of the right tool. Nothing in “Delete a customer” says the deletion is permanent, or that the correct move for “this customer churned” is usually cancelling the subscription, not erasing the customer record. A human learns that from the docs. The agent can only learn it from the description — so the description has to say it.
Before and after, verbatim
These are real pairs from our showcase servers — the terse summary the spec produced, and the description the enrichment pass shipped. First, the bluntest one we have, from the Forge code-review showcase:
Merge.
Merge a pull request into its base branch. This mutation combines the changes from a pull request's head branch into its base branch using the specified merge strategy (merge commit, squash, or rebase). Returns the updated pull request state including merge status, commit SHA, and full repository context.
The rewrite states the behavior, the options that change it, and the return shape. Next, a payments tool from the Tally showcase — note the last sentence, which is the part a spec summary never carries:
Confirm Payment Intent
Confirm a payment intent to process the associated payment. This operation finalizes a payment intent that was previously created, optionally binding it to a specific payment method. Once confirmed, the payment will be charged against the customer’s account. This is a critical operation in the payment workflow and should only be called when you are ready to commit the transaction.
And the same idea running in the safe direction, from the Slate database showcase — telling the model a tool is harmless is as useful as warning it a tool is not:
Query Database
Query a database by ID to retrieve records matching optional filter and sort criteria. This is a read-only operation that returns an array of matching database records. Use this to search, filter, and sort database contents without modifying data.
What a good agent-facing description contains
- Behavior and return shape — what actually happens, and what comes back, stated as facts rather than a noun phrase.
- Irreversibility and side effects — “once confirmed, the payment will be charged” is the sentence that prevents the incident.
- When to use it — and when to reach for a sibling tool instead, so near-duplicate operations stop being a coin flip.
- Pagination and filter hints — how to narrow a list call, so the model does not pull an entire collection to answer one question.
- Argument semantics — which parameter is an ID, which is a search term, what a sensible default looks like.
The takeaway
Write for the reader with no docs open. For an agent, the description is not a pointer to the manual — it is the entire manual.
How MCPCloud does this at ingestion
When you paste a spec into MCPCloud, every tool description is rewritten as part of the import. The enrichment pass produces more than prose: a rewritten description and input schema, related-tool links (prerequisite, follow-up, alternative, companion), workflow hints, per-parameter semantics, usage examples, recovery guidance for common failures, and a risk classification — read, write, delete, or external effect, plus whether the call is idempotent.
None of it is locked in. Suggestions land as a review step you apply explicitly, and any description stays editable in the tool editor afterward. Curation is the other half of the same job: our Stripe showcase ingests a spec of roughly 470 operations and ships 34 tools; the GitHub showcase takes roughly 700 down to 28. A precise description of a tool that should not exist is still the wrong tool.
Every showcase server publishes its live before/after diff — the terse spec summary next to the deployed description — for every tool. Browse them at mcpcloud.sh/showcase and judge the rewrites yourself. And the rewritten server does not leave home afterward: it deploys onto the same platform, behind managed auth, rate limits, and runtime-injected secrets, with every tool call showing up in its dashboard.