Quick answer: An AI coding agent is only as good as the context it is given and the verification it is held to. The two failures that dominate real work are under-context (the agent guesses the API and invents fields) and over-trust (it reports "done" after a green local run, without exercising the real flow). The fix is structural: give the agent the contract and tools through an MCP server instead of pasted docs, keep it on the OpenAPI, and define "done" as a runnable command that passes in CI — not a confident summary.

This guide covers how to give agents context, how to design APIs so agents can use them, how to verify their work, and the recurring anti-patterns. Follow the links for the concrete cases.

Give the agent the right context

An agent that does not know the real API will politely invent one. Pasting a curl command or a doc dump is a weak, lossy way to supply context; the better architecture is to connect the agent to the contract through tools. Start with AI coding agents, API context, and MCP, then stop pasting API docs and give the AI an MCP server. When an agent is asked to work from an unknown contract, the honest alternative is in unknown is better than an AI-invented contract.

Design APIs so agents can use them

An API that is easy for a human is not always easy for an agent: agents need discoverable operations, typed errors, and stable identifiers. The design principles are in designing APIs for AI agents. When the agent needs structured data back, enforce the shape with a schema rather than parsing free text; structured outputs, JSON Schema, and tool calling.

Define "done" as a verified command

The word "done" from an agent is a claim, not evidence. The most common failure is a green local run that never exercised the real path. The rule is in the agent said done but didn't verify, and for APIs the bar is a 200 is not done: run the business scenario. A green build after a refactor is also not proof; green CI after an AI refactor means nothing explains what it can still miss.

The recurring agent anti-patterns

Autonomous agents repeat a recognizable set of mistakes. Scan for these in review; each is a real case:

Switching tools without reintroducing the API

Teams move between coding agents and IDEs as the landscape changes. The way to keep your API contract stable across those switches — rather than re-integrating it into each tool — is in switching AI tools without reintroducing your API. The client landscape is compared in MCP clients compared.

Where to go next

The mechanism that makes all of this work is the contract and the tools built from it. Read the MCP server guide to expose the API, and the API testing guide to verify the agent's work. For the underlying contract, return to the OpenAPI guide.

FAQ

How much should I let an AI agent do autonomously? Let it draft, explore, and implement, but keep a human on the decisions that change the contract or touch money and auth. Autonomy should scale with how fast you can verify its output.

Why does the agent keep using fields that don't exist? Because it is working from memory or a doc dump rather than the live schema. Give it the contract through MCP and it will call the documented tools instead of guessing.

What is the minimum verification for an agent change? Run the relevant test suite and the real business flow in CI, and confirm the change fails without the fix. A test that cannot fail, or a run that never touches the changed path, is not verification.