API stands for Application Programming Interface.

I think that is about to change.

Not the acronym.

The A.

The next consumer of your API is not an application someone programmed against your docs.

It is an agent.

And agents read.

We always wrote APIs for humans

We have invented many ways for systems to talk to each other.

SOAP.

REST.

Protocol Buffers.

GraphQL.

But in all of them, the meaning lived outside the wire.

The endpoint returned data. The understanding of that data lived in documentation, written for the human who would program the client.

REST actually promised more. The original idea included hypermedia: responses that tell the client what it can do next, links that let a client discover the API by walking it.

It was a beautiful idea.

Almost nobody implemented it.

And I think I know why: for twenty years, there was no client that could use it. Clients were code. Code written by a human who had already read the docs. The response did not need to explain itself, because the programmer had done the understanding up front, once, at design time.

Then agents arrived.

An agent is the first API consumer that can read prose, follow a hint, and change its plan mid-call.

The discoverability we never built finally has a reader.

What I saw building CompanyOS

I am building CompanyOS, a tool that shares a company’s knowledge, procedures, and templates across a workspace through MCP.

One of the integrations is Recruit CRM. Their API is fine, but the MCP story around it was not good enough, so I implemented the interface inside CompanyOS myself.

That is where this idea stopped being theory.

Take a simple case: the agent asks for a client that does not exist.

The lazy answer is a 404.

Status code, empty body, done.

But to an agent, a bare 404 is a dead end. It does not say why the client was not found or what to do about it.

So we kept the 404 and changed the body:

Client not found. You can search clients by name using the search tool. If you are not sure of the exact name, search with a partial one.

Plain text. No new protocol. No new standard.

And then I watched it work.

The agent hit the not-found, read the guidance, called the search tool, found the right record, and finished the task.

No human in the loop.

The same request against a bare 404 would have ended with the agent stuck, or worse, guessing.

Responses as signposts

The error case was just the beginning.

The same pattern shows up everywhere once you look for it.

In CompanyOS, listing candidates or job descriptions could return huge payloads. CVs are long. Job descriptions are long. So the list returns only the main information.

But then the agent needs a way to go deeper.

So when you fetch a candidate, the response includes one more thing: a line of guidance.

If you need the full CV or the full job description, use this tool to fetch it.

The full data is behind a second call, and the response tells the agent so, in plain text, at the exact moment it matters.

Every response became a signpost.

Here is what you got. Here is what you can do from here.

Why not just put it all in the docs?

A fair question. We already have OpenAPI specs. MCP tools already have descriptions. Why put guidance inside the response?

Because of context.

An agent cannot hold your full spec in its head. Context is scarce, and attention degrades as it fills up.

Up-front documentation is just-in-case information. Most of it goes unread on any given task.

A signpost in the response is just-in-time. It arrives exactly when it is relevant, and it costs tokens only when it is needed.

That is also why the lists are lean. You pay for context at the moment of use, not before.

Just-in-time beats just-in-case.

A new layer, not a new protocol

To be clear, I am not saying REST is dead or that we need to rewrite our APIs.

Programs will keep calling APIs billions of times a day, and a deterministic client will simply ignore the extra guidance.

This is a layer on top of what we already have.

Same endpoints.

Same status codes.

Same JSON.

Plus one new thing: responses and metadata that describe, in plain language, what the consumer can do next.

Four rules I now design by

From the CompanyOS work, this is what I apply to every API and MCP server I build:

  1. Errors must teach. Every failure says what went wrong and what to try next. A 404 with guidance is worth more than a 200 with silence.
  2. Lists are menus, not meals. Return lean summaries with a clear path to depth. Do not flood the context.
  3. Every response is a signpost. Say in plain text what the consumer can do from here. The agent will read it.
  4. Write for the reader who cannot see your docs. The agent in the middle of a task has your response in front of it, not your documentation.

None of this requires a new standard.

It requires remembering that, for the first time, something on the other side of the wire can actually read.

The A in API is changing.

Design like it already has.