REST APIs for AI agents: design patterns that actually work

## The mental model When an LLM calls your API it has no documentation, no Postman collection, and no human to ask. It has exactly one thing: the tool description and JSON schema you give it. That means the **shape of your endpoint matters as much as what it does**. ## What works ### 1. One endpoint, one verb Models reliably pick the right tool when each tool does **one thing**. A `create_invoice` tool beats a generic `invoices(action: "create" | "update" | "void")` every time. ### 2. Required inputs only Every optional field is a chance for the model to hallucinate a value. Mark fields required when they truly are required, and provide sensible defaults server-side for everything else. ### 3. Human-readable errors Return `{"error": "Customer email is missing"}`, not `{"code": 422}`. The model reads your error and retries — give it something to work with. ### 4. Stable IDs in responses Return IDs the model can pass to a follow-up tool. A `create_customer` that returns `{ id: "cus_123" }` lets a follow-up `attach_payment_method(customer_id)` chain naturally. ## What breaks - **Deeply nested JSON** — flatten responses where you can - **Free-form date strings** — pick ISO-8601 and stick to it - **Pagination cursors without total counts** — agents loop forever - **204 No Content** — return at least `{ ok: true }`; empty bodies confuse parsers ## How easyMCP helps When you wrap an API with [easyMCP](/), you can override descriptions, rename fields, and rewrite responses without touching the original API. That means you can ship an LLM-friendly surface on top of an existing REST API in minutes — no fork required.