Write Your APIs Like You Write a Movie
The Sequel Nobody Asked For (But AI Agents Demanded)
Six years ago, I wrote a piece that the best APIs tell stories. That great API design starts not with code or contracts, but with a developer guide. A narrative with a plot, characters, dialogue, and a beginning, middle, and end. No AI was involved in writing, and I will try that today with this sequel!
Now, the audience have changed.
In 2020, the audience for your API story was a human developer. Someone who could read between the lines, forgive inconsistencies, check with support when your docs were vague, and figure out what you meant even when what you wrote was wrong.
That audience was very, very forgiving.
Your new audience is an AI agent. And AI agents are the most literal-minded audience you will ever have. They don’t infer intent. They don’t check Stack Overflow. They don’t “figure it out.” They read your API schema like a first-year film student reads a screenplay. If you don’t set the scene exactly right, they will misinterpret everything.
The Original Framework, Revisited
In the original piece, I laid out the elements of a good API story: plot, characters, viewpoint, dialogue, style, and a beginning, middle, and end. Every one of these elements breaks when the consumer is an AI agent.
Plot: From Screenplay to Logline
The plot is still your user story. What does the API help someone achieve? That hasn’t changed.
What changed is the container. In 2020, you had the space of a developer guide to tell your story. Pages of context, examples, narrative flow. Your plot could breathe.
An AI agent gets a tool schema. A name, a description, a list of parameters. That’s not a screenplay. That’s a logline. And if the logline doesn’t convey the plot, the agent won’t go looking for the director’s commentary.
Block learned this the hard way. Their first Google Calendar MCP server was a thin wrapper around the API. It exposed raw endpoints. Agents couldn’t figure out the workflow. They didn’t know that to schedule a meeting, you needed to check availability first, then create an event, then send invitations. The “plot” was scattered across a dozen endpoints with no narrative thread.
Their v2 redesigned around workflows. Agent goals, not developer primitives. “Schedule a meeting” became a single tool, not a chain of five API calls the agent had to figure out on its own.
Tool names, descriptions, and parameters are treated as prompts for the LLM. Every piece of your API schema is a line of dialogue in your logline. Get a word wrong and the LLM misinterprets the entire scene.
Enter the Actor
In the original piece, I said: “Think of the customer, not the developer that will consume the API. The developer is the critic, not a character in your story.”
That still holds. But there’s a new role in the production that didn’t exist in 2020. The AI agent isn’t a character in your API story, and it isn’t a critic. It’s the actor. The one who has to read your screenplay and perform it in real time, on behalf of the customer, with no rehearsal.
And this actor doesn’t improvise well. It doesn’t bring creative interpretation. It doesn’t fill in what you forgot to write with raw talent and instinct. It performs exactly what’s on the page. Give it a great script and you get a great performance. Give it a vague script and it delivers the lines wrong without knowing it.
Your developer guide was written for critics. People who evaluate your API, form opinions, and decide whether to use it. Your tool schema is written for actors. Something that will take your words and perform them, literally, every single time. That’s a fundamentally different kind of writing.
Viewpoint: The Lens Cracked
The viewpoint was how you told your story. The customer’s perspective traveling through the API. With agents, that viewpoint fractures.
The customer talks to the agent in natural language. The agent translates that into API calls. The API responds in structured data. The agent translates that back to natural language for the customer. Every translation is a potential failure point.
The API economy is no longer about who has the best developer relations. It’s about who made themselves most machine legible. Your viewpoint needs to work for two audiences simultaneously: the customer who wants outcomes and speaks in ambiguity, and the agent who needs precise instructions.
This is where most “AI-ready” API strategies fall apart. They optimize for the agent with better schemas and richer descriptions, but forget that the agent is serving a human. “Book me something nice for dinner” needs to become a series of precise API calls, and your API’s viewpoint needs to support that translation without losing the customer’s intent along the way.
Dialogue: The Conversation Went Off-Script
In the original piece, the dialogue was a designed journey. A mapped sequence of transitions between API operations. You controlled the narrative.
With AI agents, the dialogue became improv. The agent decides the sequence at runtime based on its interpretation of the user’s prompt and your schema descriptions. You’re no longer writing a screenplay with fixed scenes. You’re writing a Choose Your Own Adventure where the reader has no common sense.
This is where tool hallucinations enter the story. Researchers have formally categorized these into two types: tool selection hallucination (the agent picks the wrong endpoint entirely) and tool usage hallucination (it picks the right endpoint but fills in wrong parameters). Both are failures of dialogue. The conversation between the agent and your API broke down because the script wasn’t clear enough.
And here’s the part nobody talks about: error responses are the most important dialogue you never designed. When a human developer gets a 400 Bad Request, they go read the docs. When an agent gets a 400 Bad Request, it either retries blindly, hallucinates a fix, or gives up entirely.
Your error response IS the documentation now. Every error message needs to include what happened, why it happened, and what the agent should do next. That’s not error handling. That’s screenwriting. Your error responses are plot twists, and they need to resolve cleanly or the whole story falls apart.
Sherlock Domains discovered this when they tested their SDK with Claude and then with Llama 3 running locally. Same API, same errors. Claude figured it out. Llama couldn’t. The error messages weren’t self-explanatory enough for a less capable model to self-correct. The story stopped making sense for a different audience.
Style: Consistency Became Non-Negotiable
Your API style (how you name resources, structure parameters, define conventions) was always important. With human developers, inconsistency was annoying but survivable. With agents, it’s fatal.
LLMs are pattern-followers. All the usual best practices (RESTful guidelines, consistent naming, clear hierarchies) matter more when the consumer can’t adapt to your quirks.
One specific failure mode: inconsistent handling of optional fields. Sometimes an agent includes them, sometimes it doesn’t. The API responds differently each time. This is like changing the rules of your movie’s universe between scenes. Human audiences might not notice. AI agents will break.
Here’s a stat that should keep you up at night: 75% of production APIs have endpoints that don’t match their specs. When humans consumed your API, they worked around these inconsistencies. They read docs, tried things, and adapted. When an agent consumes your API, it trusts the spec literally. Your spec says one thing, your API does another, and the agent is left trying to perform a scene that doesn’t exist.
Beginning, Middle, and End: Now With Alternate Endings
In the original piece, I said to start with a trailer (what the journey is), tell the narrative in the middle (the transitions between APIs), and conclude with a happy customer completing a journey.
With agents, every journey has alternate endings. And you need to design for all of them.
The agent might call your endpoints in the “wrong” order. It might skip steps. It might retry failed calls. It might chain your API with three other APIs you’ve never heard of. The happy path is just one possible storyline in a movie where the lead actor improvises every take.
This is where the Arazzo specification comes in, a standard for documenting chained API workflows. It’s essentially a screenplay format for multi-API narratives. And it’s where HATEOAS (hypermedia as the engine of application state), the most underused principle in REST, suddenly becomes relevant. Including links to valid next actions in every response gives agents a clear awareness of what’s possible next. It’s not just good REST. It’s good storytelling.
From DX to AgentX
Here’s the idea: prompt an AI agent to build an application using your APIs. Don’t give it anything beyond what a real agent consumer would have. Your tool schemas, your descriptions, your error responses. Then watch what happens.
Did it figure out the workflow? Did it call the right endpoints in the right order? Did it hallucinate parameters that don’t exist? When it hit an error, did it recover or spiral? Did it use three API calls where one “chunky” tool would have sufficed?
Every failure is a DX signal. Every hallucinated parameter is a naming problem. Every wrong-order call sequence is a missing workflow narrative. Every retry loop is an error response that didn’t tell the agent what to do next.
This is what consumer-driven tests were always trying to be. The consumer just got instrumented.
And it scales. You can run this against every schema change, every new endpoint, every updated description. You can test with different models (Claude, GPT, Llama) to see if your API story is clear enough for the slowest reader in the audience, not just the smartest. You can test at the speed of CI/CD, not the speed of developer usability studies.
I think this is how Developer Experience becomes Agent Experience. DX was always about “can a human figure this out?” AgentX is “can a machine figure this out?” And the beautiful part is that AgentX is measurable in ways DX never was. You don’t need surveys. You don’t need support tickets. You have logs. You have token counts. You have hallucination rates. You have success and failure on actual workflows. If your API can’t pass that test, it was never as well-designed as you thought. The humans were just too polite to tell you.
The Script Format Changed
In 2020, the OpenAPI Specification was the script. The contract that helps you select the actors and location for your movie. It’s still important. But it’s no longer the only format.
MCP introduced a new screenplay format: tools, resources, and prompts. Function calling schemas introduced another. These aren’t just different ways to describe the same API. They’re different storytelling formats with different constraints and different audiences.
An OpenAPI spec describes what your API can do. An MCP tool description tells an agent when to use your API, why it should use it, and what to expect. That’s a fundamentally different document. One is a technical reference. The other is a narrative.
Writing both from the same underlying API is the new craft. And just like adapting a novel into a screenplay, it’s not a mechanical translation. It requires rethinking what matters, what to cut, and what to combine for the new format.
So What Do You Actually Do?
If you’re building API-based products today, here’s my updated approach:
1. Write the Agent Story First. Not a developer guide. An agent story. What goal is the agent trying to achieve on behalf of a customer? What information does it need at each step? What happens when things go wrong? Write this as a workflow, not as a list of endpoints.
2. Design Tools, Not Just Endpoints. Block’s lesson: expose “chunky” tools that combine multiple endpoints to achieve a specific business outcome. “Schedule a meeting” is a tool. “GET /calendar/availability” is an implementation detail the agent shouldn’t have to orchestrate.
3. Make Error Responses Self-Contained. Every error response should answer three questions: What happened? Why? What should the agent do next? If your error responses require the consumer to go read external documentation, they’re broken for this audience.
4. Embed the Story in the Schema. Tool names, parameter descriptions, and response descriptions are your screenplay. Write them like dialogue, not like database column names. The agent has nothing else to work with.
5. Test with Agents, Not Just for Them. Prompt an AI agent to build something with your API. Run it with multiple models. Measure hallucination rates, wrong-order calls, and error recovery. This is your new consumer-driven test, and it’s more honest than any developer survey you’ve ever run.
6. Don’t Just Wrap. Redesign. If your first instinct is to put an MCP wrapper on your existing API, resist it. Ask whether your existing endpoints actually map to agent workflows. They usually don’t. A good REST API is not a good MCP server, and pretending otherwise is the most expensive shortcut you’ll take this year.
Build a Godfather Trilogy, Not a Scream Series (Revisited)
In the original piece, I ended with: “Like a good movie, there will probably be a sequel, or a remake. Just please, build a Godfather trilogy, not a Scream series.”
Well, here’s the sequel. And the landscape has changed more than I expected.
Most “AI-ready” APIs today are the same bad movie with an AI narrator slapped on top. Better descriptions on the same broken endpoints. MCP wrappers on APIs that were never designed to be consumed autonomously. It’s lipstick on a pig, and the pig is about to go on stage in front of the most literal audience in history.
The companies that get this right won’t be the ones with the most endpoints or the coolest tech stack. They’ll be the ones that understood, the way they understood with human developers, that how well the story is told is what makes or breaks an API product.
The story principles haven’t changed. But the audience is less forgiving, the stakes are higher, and the screenplay format is new. Your API still needs a plot, characters, dialogue, style, and a beginning, middle, and end. It just needs all of those things to work for a consumer that takes everything literally, has no context beyond what you provide, and will improvise the rest.
Write for that audience, and you’ll build something that works for everyone. Humans and agents alike.
Ignore it, and your API will be the movie that everyone walks out of, except the agents who stay to the end and completely miss the point.
Anyway, turns out writing about API design as storytelling in 2020 wasn’t just a metaphor. It was a spoiler for 2026. You’re welcome.
If you want help rewriting your API’s screenplay for this new audience, grab 30 minutes with me.