Mira wants the book
It is Monday morning of story week 3. The GET /v1/books endpoint Devon shipped on Tuesday has been live almost a week. I am at the branch for my usual Monday morning with Devon; I have claimed a small corner table near the front window.
Mira walks up to the front desk. “The system says you have The Quiet Library. Your chatbot said it’s at 813.5. There is no 813.5.” The librarian walks her to fiction. Mira leaves with the book.
I pull up the doc page on my phone. The example response shows call_number: "813.5". There is no description on the field. There is no sentence on the page about what a call number is.
Last week I asked you which reader the doc page is for: the developer or the chatbot. Today I learned there are three. Her name is Mira.
Today you will leave with
- The three readers of every API doc page.
- A three edit pattern (schema description, realistic example, one prose sentence) for any ambiguous field.
- A Gemini prompt that reads your page the way an agent will.
The three readers
I walk back to Devon’s desk. By 9:30 Priya pings me in Slack: “user agent breakdown for /v1/books, you should see this.” The breakdown is a short list of strings. Near the top: Marginalia Atlas/0.4.
Marginalia is a small Goodreads competitor. Atlas is their reading assistant. Borrowers ask Atlas what to read next, and Atlas calls our API to check availability. Atlas read our doc page, hit the endpoint, read call_number: "813.5", and told Mira “It’s at 813.5.”
Then the lesson. The doc page has at least three readers, and they are not the same kind of reader.
The dev is the engineer at Marginalia integrating Greenfield’s API into Atlas. They read the page to copy a snippet, ship code, and move on.
The agent is Atlas itself, the agent reading the page literally and quoting fields back at runtime.
The human is Mira, who never reads the page at all. She hears what Atlas said.
An audience is a class of reader , not a single person. Each of those three is an audience of your doc page. The same field can matter to one audience and not to another.
The user agent string is what told Priya which audience was hitting the endpoint. A user agent is the string a caller sends to identify itself. Browsers send strings like Mozilla/5.0. Atlas sends Marginalia Atlas/0.4.
Atlas reads what your schema makes available, what your example response shows, and sometimes your prose. Different agents read different surfaces. The doc page has to do its work in each.
Three is the count I keep coming back to. Slice it differently if your stack demands. The number matters less than knowing which one you wrote for and which one showed up.
On Tuesday I wrote for the dev. By Monday two other readers had shown up.
sequenceDiagram participant Mira participant Atlas participant Doc as Doc Page participant API Mira->>Atlas: where is Quiet Library Atlas->>Doc: read schema Doc-->>Atlas: field meanings Atlas->>API: GET /v1/books?q=quiet API-->>Atlas: 200 with results Atlas->>Mira: it is at 813.5
Look at the diagram. Find the doc page. It is the one I get paid to write. Now look at where Mira is. The page reaches her only through what Atlas said.
How we fix the page
Writing for three readers does not mean writing three pages. It means adding three small things to one page. I write the description text and the prose paragraph. Devon adds them to the schema and pushes.
The schema description. The call_number field in our schema
has no description
on it. A description is the sentence on a OpenAPI
field that explains what the field is. In 2026 it is also the sentence agents read at runtime. I write one. Devon adds it to openapi.yaml:
call_number:
type: string
description: |
Dewey decimal subject classification for the title.
Not a shelf location. Branches shelve fiction alphabetically by author.
example: "813.5"
The field now carries a sentence the agent can quote. “Not a shelf location” is the clause that does the work. An agent reading the schema sees the disambiguation. An agent that does not read the schema sees nothing different yet. That is what the next two edits are for.
The realistic example. The legacy doc page shows the response keys with no values. I add an example response with real Greenfield data. A book that exists. A branch that exists. A call number that resolves cleanly:
{
"results": [
{
"id": "bk_184932",
"title": "The Quiet Library",
"available_branches": ["branch_north"],
"call_number": "813.5"
}
],
"total": 1
}
A dev who copies this snippet sees the shape AND the kind of value call_number carries. “813.5” reads as a Dewey number to anyone who has been near a library. The example does what no field description can. It shows the value as a number, in context.
The prose disambiguation. Below the example response, one paragraph on the doc page itself:
The
call_numberfield returns the Dewey decimal subject classification for the title. It is useful for filtering or grouping titles by subject. It is not a shelf location. Branches shelve fiction alphabetically by author. If you are writing an interface that tells a borrower where to find a book, do not read this field back to them as a location.
The last sentence is the agent aware sentence. It is written for the dev shipping a chatbot AND for the chatbot reading the prose at runtime. Two readers, one paragraph.
Three edits. One page. The next Mira gets an answer that means what it says.
The toggle below shows the two reading acts on the same response. Mira does not read the page; she appears in Atlas’s pane as what Atlas told her.
Try it on Greenfield
The trap
Words you can drop in standups now
-
- audience
- Use this when you mean a class of reader, not a single person. “The doc page has three audiences” settles a debate that “we should think about who reads this” does not.
-
- description
- Use this when you mean the sentence on an OpenAPI schema field that explains it. “Add a description to that field” is what you say when an agent quoted a value back wrong.
-
- example response
- Use this when you mean a realistic JSON sample on the doc page, not a placeholder. “The example response is stale” is different from “the field changed.”
-
- user agent
- Use this when you mean the string a caller sends to identify itself. “Check the user agents on the access log” is how you find out whether your readers are humans or software.
Today’s prompt for your AI assistant
Gemini, this time.
The situation. You have your doc page open and you want to know what an agent will do with it before a borrower does. Gemini’s long context handles a doc page plus a sample response in one pass.
The prompt, exactly as written:
You are going to read this API doc page three times.
Doc page: [paste the page, including the response example]
First read: as a developer integrating this API. List the three things
you need from the page to write working code.
Second read: as a chatbot that has called the endpoint and received the
response. For each field in the response, write the exact sentence you
would say back to a user when reporting that field's value. Quote the
field value verbatim. Do not interpret.
Third read: as a human user receiving the chatbot's answer from the
second read. For each sentence, would you understand it? What would
confuse you?
What to expect back. An answer in three sections. The middle section is the one that catches problems. If the chatbot’s literal sentence reads as weird, your page has a description to write.
What to watch for. Gemini will sometimes flatten the three reads into one summary. Press it on the literal pass with “do not interpret; just quote.” The summarized version is not useful. The literal one is.
Before you go
Pick one field in your own doc page. Read its value the way Atlas would: just the field name and the value. Did you just say a sentence Mira would understand?
Next week at Greenfield
Next week Devon shows me why it is GET /books and not POST /search. The answer involves letters from 1969.
Maya.