Agent-First Design

Image: NanoBanana

I've spent the last 15 Christmases out in the countryside at my in-laws. Feeding animals, milking cows, cleaning the barn. There's a certain peace in doing physical, repetitive work—it creates space for ideas that daily routines crowd out.

We've designed our lives around productivity, but the mind needs room to wander before it reaches conclusions.

This year, between tasks, I found words for something I've been working on as an AI Tech Lead at APRÓ.

A middleware that transforms OpenAPI schemas into MCP tool schemas so agents can talk directly to REST services.

First with my own solution, later with AWS AgentCore.

The pattern became clear long before I found a name for it.

Agent-first design

Over the last decade, API-First has been gospel. Design the contract first. Document it. Build from it. This changed how we create software.

But Agent-first doesn't replace API-first. It builds on it. Perfects it, maybe.

An MCP tool schema is for agents what OpenAPI is for web services. These aren't competitors—they're two sides of the same coin. The interface your service shows to the world is now understandable by both instruction-following systems and those that reason.

Take Swagger Petstore as an example—the "hello world" of the API world.

Fitting, given where I was over the holidays.

The traditional approach:

Design REST endpoints, write an SDK, spit out an OpenAPI schema, and write documentation.

The agent-first approach:

Design the same logic, but write the descriptions as instructions. Not just passive descriptions, but what the service needs to know, when to use the endpoint, and what the outcome should be.

Let's look at the difference in the Swagger Petstore example:

Traditional description:

"Find pets by status. Returns a list of animals."

Agent-first description:

"Use this endpoint when the user asks to see which animals are for sale. You must set the 'status' parameter to 'available'. The result is a JSON list of animals; show the user their names and types from that list. If the list is empty, tell the user nothing was found."

Now the agent can navigate the store, check inventory, and place orders by "thinking" through the same logic as other systems.

One truth. No duplication.

What's the benefit?

• A well-designed API becomes "agent-ready".

• The investment in API-first pays dividends multiple times over.

• "Agent consumers" become first-class citizens without requiring maintenance.

When I design multi-agent systems today, I don't ask "API or agent interface?"

I ask:

"How do I design the OpenAPI schema so people and systems understand how it works and an LLM can use it with reasoning?"

That's the core of agent-first thinking.

Not a revolution, but an evolution that was always in the air.