For a few months now, a GoodBarber app can be operated from whatever AI client you already use — Claude, Cursor, VS Code, Codex, Gemini. An MCP server exposes the platform's operations; the assistant connects, authenticates, and can read a catalog, publish an article, send a notification. Pierre-Laurent wrote up how that server holds together.
Once it exists and works, there's a question a server doesn't answer: where do you start?
An agent facing a hundred tools has the same problem as a user facing a hundred menus. Nothing is missing, and nothing invites you in. Our answer is a public repository of markdown files, one per usage scenario: who my best buyers are, prepare the winback for subscriptions about to expire, publish this article and schedule it for Monday. It will grow over time, as we spot uses that deserve a recipe of their own.
That examples help is not a discovery. What took up our time wasn't writing them — it was what writing them forced us to decide.
A scenario, not an API endpoint
One of those files doesn't describe an operation. It describes an intention, phrased the way people actually phrase it, and the sequence that serves it: what to fetch, in what order, what to cross-check, and the exact shape of the report you want back. Sometimes that's a single call. Sometimes it's six, with aggregation in between.
The skeleton is the same everywhere: the goal, the order of calls, the shape of the result — with a filled-in sample report, right there in the file — the guardrails, and what to do next.
That last line is the one we thought least about and the one that changed usage the most. Every scenario ends by pointing at two or three neighbors, without exception. A customer segmentation ends by offering to build the matching promotion; a weekly digest ends by offering to go look at stock levels. Chaining scenarios together has become fairly common craft among the people who write them; what we hadn't anticipated was the effect on the whole. It stopped being a catalog and became a map.
Writing that isn't documenting an API. It's taking a position on how your own product should be used.
Writing the rule is how you find out you had one
Someone asks their assistant to notify the subscribers. They mean the active ones. Never the expired ones — unless they say so.
Nobody had ever had to write that sentence down. In front of a dropdown you decide in a second, without even noticing you decided: the list is there, the three options are visible, your eye does the choosing. An agent has no dropdown. It has a sentence, and it has to get a decision out of it.
That was the surprise of the exercise, and it came back with every file: writing the rule is how you find out you had one. Written nowhere, held up by habit and by the shape of a screen. An interface doesn't just offer options — it decides, quietly, on everyone's behalf, and nobody ever argued about it because nobody ever had to put it into words. Take the screen away and the decision is still there, with nothing holding it up. You have to write it down. Which means owning it, re-reading it, and being able to change your mind about it.
The second of the same family: never guess an ID. The scenario has to search all three lists a person could be in — prospects, active subscriptions, expired subscriptions — not stop at the first one, and ask the user to pick when several match. The hard part isn't "search". It's "don't conclude too early". And that isn't editorial caution: OpenAI researchers have shown that standard training and evaluation reward guessing over admitting uncertainty — graded on how many answers it gets right, a system is always better off taking a shot. A scenario that doesn't say keep looking inherits that pull. And as with anything that changes something, nothing goes out without an explicit confirmation.
None of these decisions is new. They all existed already, scattered across habits and screen layouts. The scenario makes them explicit — which makes them reviewable, and arguable.
Document the silences too
The call that sends a notification returns an acknowledgement and a processing time. No ID, no recipient count: delivery is asynchronous, to the devices that opted in.
An agent reporting back has a natural pull of its own: fill in the blank. "Notification sent to 3,412 subscribers" is exactly the sentence you expect at the end of a task, and exactly the one nothing in the response entitles it to write. It would have been wrong about half the time, which is worse than always.
So the file states what the API doesn't give you, and the report template carries the note in plain sight. It's a small discipline we never needed while our readers were human: document an interface's silences, not just its answers.
What "half done" means
Publishing an article means creating the article, adding paragraphs one at a time, then ordering them. Several calls, and nothing that binds them into one operation you could cancel in a single move.
The rule we wrote: if a paragraph fails after the article has been created, no automatic rollback. We don't delete what exists — we stop, and we list exactly what's missing so the person can pick up where it broke.
Undoing automatically, across operations that aren't transactional, isn't going back: it's firing a second series of calls that can fail in turn, on real work. A partial state you can name gets fixed in three minutes. A partial state you have to guess at surfaces three weeks later.
Every scenario that builds something in several steps carries that rule: publishing an event, assembling a gallery, launching a product. The ones that only read don't need it.
What we put in the public domain
What makes these files interesting is that they're not quite documentation and not quite code. The same file is read by a human for the idea and executed by an agent for the action: you open it to see what's possible, you let it run to make it happen. Nothing to install, nothing to compile, nothing that rots inside a proprietary format. Text.
Which is what makes sharing them obvious. What we published isn't capability — capability is the server, and it was already there. It's decisions: the order of operations, what needs a confirmation, what a word means when nobody qualifies it, what we refuse to invent. Our playbook, open, in the public domain, no restrictions. Our resellers ship it as-is under their own brand, and anyone can fork it to fit their own app — a way of working only becomes a habit once it's been read, copied and changed.
There's a simpler reason to make it public. Talking to your app instead of learning its screens is worth nothing if nobody knows what to say to it. I wrote at the time that the unit of interface was no longer a pixel to draw but a verb to define. Half that sentence was missing: defining the verb isn't enough. You still have to say when it gets used, in what order, and what never happens without asking first.
The server says what the app can do. The playbook says what we decided it should do.
Top comments (2)
The capability-versus-judgment distinction is useful. One thing I’d make executable is the report’s epistemic contract.
If a tool returns an acknowledgement but no recipient count, don’t leave that only as prose in the scenario. Require each result claim to be marked
observed,inferred, orunavailable, with the supporting tool-call ID. A validator can then reject “sent to 3,412 subscribers” when no call produced that number.The same structure helps with half-finished multi-step work: emit an operation ledger with created object IDs, completed steps, missing steps, and the explicit decision not to auto-rollback. That turns “document the silences” from good guidance into a property you can test across different agents and clients.
That is ideal way , but agents are powered by LLMs which means they are by design probablistic and the more data they accumalate with time, the more they change their behavior which leads to mistakes or sometimes unaccepted behavior, are you using any solution for making agents reliable continously?