Designing APIs for Agents

TL;DR Highlight

Dropping defaults, using specific field names, and writing precise errors help agents misuse your API less.

Who Should Read

A backend developer designing SDKs or internal APIs that agents will call and unsure how many human-friendly conveniences to keep.

Core Mechanics

Agent API design is the opposite of human design
- Human-first APIs work in fifty lines and reveal other fields through autocomplete.
- Agents read your whole docs in the first prompt and write thousands of lines in seconds.
- So clarity, where reading the code tells you what it does, comes first.
Defaults are bad, so fill everything in
- Agents can read the docs and fill in sensible starting values for every field.
- The cost of filling many fields has vanished, while the cost of understanding code has gone way up.
- Separate less important fields with comments.
Errors are good if they are precise
- Coalescing like uppercase-to-lowercase or accepting true, yes, on, 1 hurts agent codebases.
- It makes functions use different values for the same thing and confuses later reviewers.
- In the author's data, 27% of the friction agents hit comes from errors.
- Telling agents to read the docs in the error message helps.

Community Reactions

A feedback tool for agents
- One commenter heard of an MCP with a feedback tool whose description tells coding agents to call it whenever they struggle with the rest of the MCP.
- They called it cheap to implement and expected actionable signal.
Removing defaults hurts human debugging
- One commenter said it makes quick debugging with curl hard.
- They compared it to HTTP/1, where a couple of headers are enough to type a request by hand.
- Another used CreateFile in Win32 to show that filling every parameter makes code harder to read.
Six tips from someone who built for agents
- A commenter shared text-first output, grep-friendly lines, and short prefixed IDs like cus_abc123.
- They also suggested context-rich list responses, bulk operations, and errors with doc links and hints.
- They applied these in an open-source CRM called crmkit.
Materializing defaults as a compromise
- One commenter writes extension defaults into the settings file at startup.

How to Apply

Find and rename vague API fields
- Grep your API schema today for generic fields like name, id, type, and value.
- List replacement candidates such as displayName, slug, and externalId.
- Write allowed characters and ranges for each field in doc comments.
Put cause and doc links in error responses
- In 4xx errors, say which value is wrong and what is allowed.
- Include the relevant doc URL and a correct example in the body.
- Turn silent corrections like case folding or multiple spellings into errors.
Add a feedback tool to your agent-facing API
- Add one feedback tool to your MCP or internal tools.
- In its description, tell agents to call it when they can't figure out usage.
- Review the logs to find where agents get stuck and fix the docs.
Replace a thin wrapper SDK with a guide
- Pick an SDK utility that agents use that a single exec or HTTP call could replace.

Try It

copy & run

// Paste into Claude or ChatGPT (simplified version of the article's principles: agent-facing API audit)

Below is our API schema (OpenAPI or SDK type definitions).
{{API schema}}

Assume a coding agent will use this API, and audit it by these criteria.
1. Find fields like name, id, and type that can be read several ways, and suggest specific replacement names for each.
2. Find fields that rely on defaults and list the values that should be filled in explicitly.
3. Find places that silently coerce bad input (case folding, multiple accepted spellings) and write the error message that should replace each.
4. Write 5 example error messages that include the cause, allowed values, and a doc link.

Present the result as a table.

Next step: give the revised schema to an agent, run the same task 10 times, and compare whether it uses the fields consistently.

Terminology

HarnessThe scaffolding around an LLM that runs tool calls and the execution loop. Think of it as the chassis that lets the engine drive.

CoalescingSilently merging variants like different cases or spellings into one value. It helps humans but hides inconsistency in agent-written code.

MCPA protocol that lets agents connect to external tools and data. Think of it as a USB port for AI.

OpenAPI specA machine-readable description of a REST API's endpoints and fields. It works as the API manual that agents read.

Doc commentA documentation comment placed in code. It tells agents what a field means.