machinereadable.dev

Trained on Meaning, Fed Boilerplate: Why Repetition Makes Agents Guess

Tue, 28 Jul 2026 00:00:00 GMT

The model was trained on meaning; your context is a bet against that

Strip the harness away and an agent is a language model predicting the next token — and it learned those predictions from an enormous corpus of real, meaningful human content: prose that argues something, code that does something, documentation that describes something. That training is the entire trick, and it comes with a condition attached: the model predicts confidently when the context in front of it resembles the meaningful material it learned from. Fill the context with meaningless repetition and the response will be, with matching fidelity, meaningless — not because the model broke, but because you've walked it off the corpus, into territory where every next token is a guess. That's the first-principles version of a claim the correct-APIs piece made in passing and owed a full piece; this is the piece. We argue it as mechanism plus field observation, not settled benchmark — and we'll show you how to measure it on your own interface.

Machine code: more information, less meaning

The cleanest demonstration isn't an API at all. Point an agent at high-level source code and it does decent work. Feed it the compiled output of the same program — machine code, straight into the context — and it loses the thread in short order. Nothing is missing; the machine code contains strictly more information than the source. What's missing is meaning at the level the corpus taught: the model has read millions of TypeScript functions and approximately no honest hexdumps, so one context sits in the densest part of its training distribution and the other is noise wearing a file extension.

The working fix has the shape all the fixes in this piece will have: don't hand the agent the raw level — put an interface in front of it that answers at the meaningful level. Agents that interact with language servers ask "definition of X, references to Y" and get back symbols and types, never bytes. In practice, context-mode-style tools push the same move further: the agent must describe what it needs and how it should be processed, and direct reads aren't allowed — with visible gains on both context load and code quality. The interface's job is to expose the level where meaning lives and keep everything below it out of the context.

Where repetitive boilerplate comes from — and what it does

APIs walk agents off the corpus the same way, just more politely. A response ships every field the webapp needs — for perfectly legitimate reasons — and the agent's task needs three of them. Envelopes repeat because parsers like consistency; scaffolds get re-injected every turn because the framework template says so; few-shot examples get copied between tools because they worked last time. Each decision is locally fine. The sum is a context where the same unrelated, unneeded tokens recur dozens of times with tiny payloads of variation between them — and that's where repetitive boilerplate becomes a pollutant with two distinct failure modes, the mechanisms linking repetition to hallucination.

The first is prompt priming: when the repetition forms a strong pattern, the model completes the pattern over the actual value. Thirty-nine records saying "status": "active" are thirty-nine demonstrations that record 27 says it too — and a model's most reliable skill is continuing a demonstration, so it reads the expected value instead of the actual one. The second is quieter and closer to the root: drift. Real training text doesn't repeat a wrapper forty times with noise between the copies; the more boilerplate accumulates, the further the whole context deviates from any known corpus, and next-token probabilities sag everywhere — not just inside the envelopes. Harnesses and SDKs carry guardrails for the critical floor, the moments when no good next token exists at all. But boilerplate-induced hallucination lives in the degraded middle — fluent, confident guessing that never trips a guardrail. Avoiding the pollution in the first place is what keeps the agent focused; the industry files the resulting failures under agent hallucinations, and confabulation fits better: the model isn't perceiving something false, it's filling a meaning-shaped hole with the most plausible material available.

Measure it in thinking tokens

Here's the measurement, and it's deterministic: run the same task against an optimized and an unoptimized version of your API — task-relevant fields versus the full dump — and compare thinking tokens. Less thinking means the answer was more obvious; the model found the meaning without excavating for it. It's a paired, same-model comparison, so it needs no judge, no baseline, and no error bars, and the same harness telemetry gives you total token burn for free. For a correctness signal on top, plant a deviant value at a known position — a record 27 — and log whether each variant reads it right. The production version of the same idea: stamp transcripts with an interface version, then watch thinking-token and wrong-read deltas per version to detect boilerplate-induced hallucinations in production — regressions enter through changes that look cosmetic precisely because they only touch "the part that's always the same."

Mitigations: expose meaning, not data

The practical moves for designers and engineers, cheapest first. Trim to the task: the webapp can keep its forty fields; give agents a view that ships the three the task needs. State shared structure once: schema described a single time, records reduced to what varies — deduplication done where it's cheapest, by the party that already knows what's invariant. Mediate the raw level: generalize the language-server pattern — when the underlying data is below the level where meaning lives (bytes, dumps, bulk records), put a processing interface in front and let the agent describe what it needs rather than read directly. Verify the critical reads: where an action hangs on one field, have the agent quote the exact value first — the same move as writing errors as recovery instructions: put the load-bearing fact where it can be checked, not where it's inferred.

When repetition pays rent

Not every repeated byte is pollution. Provenance headers, audit scaffolds, and compliance stamps repeat because a record may someday need to stand alone in front of a human; that's auditability buying tokens, and it's a legitimate trade. The test for any piece of boilerplate is three questions: Does it vary? If never, state it once. Can it be fetched? If the agent can pull it on demand, don't pre-pay for it. Does it pay audit rent? If an incident review needs it attached to every record, keep it — and account for it as a governance cost of the interface, because removing boilerplate is never free either: trimming, mediating, and per-task views all cost engineering time and a little latency.

The takeaway: keep the agent on-corpus

A context window has no inert bytes — everything the agent reads is part of the prompt, and every meaningless repetition is a small bet against the training distribution the model's competence comes from. Human-facing interfaces treat consistency and completeness as virtues; agent context design can't afford to, because the reader's entire skill is statistical familiarity with meaningful content. The sharpest version: an interface is good for agents in proportion to how obvious it makes the next token. Expose the level where meaning lives, ship what the task needs, and let the thinking-token meter tell you when you've drifted.

When Correct APIs Break Agents: Six Design Choices That Pass Every Test

Sun, 26 Jul 2026 00:00:00 GMT

The failure surface is inference, not execution

When an agent fails against your API, the instinct is to go looking for the bug. Usually there isn't one. The endpoint does what the spec says, the test suite is green — and the agent still called the wrong tool, read the wrong field, or built ten steps of plan on a response it misread. That's because "correct" is a claim about your spec, and the agent never meets your spec. It meets tokens, names, and implied promises. An API breaks agents wherever it makes them infer something it could have stated — and every one of the six design choices below forces exactly that inference, while passing every test you'd normally write. Each is a specific, named form of the guesswork tax; this piece is the catalogue of where the tax hides in an interface that is, by its own definition, working.

Deep nesting is a tax; denormalized fields are a trap

The agent reads every response as context, so every layer of wrapping is a fee charged per call, billed in the tokens the task costs. If the answer to "did it work?" lives at .run.result.latest.metadata.status, four levels of envelope get shipped, parsed, and paid for every time anyone asks. There's a second cost that's worse than the fee: all those envelopes look alike. When every response repeats the same boilerplate wrapper, the model is handed a strong repeating pattern, and a language model completes strong patterns — so the risk of reading the expected value instead of the actual one goes up precisely where the payload is most padded. Treat that as mechanism plus field observation rather than settled fact; it gets a full piece of its own soon.

The placement rule is almost embarrassingly simple: a field's depth should match its importance. An operation's status belongs at .status. And its dual: data belongs inside the object it describes. A person's age goes at .persons[0].age; the moment it's denormalized into .firstPersonAge, the agent must notice the convention, trust it, and reassemble your entity in its head — a join performed in inference, per session, forever.

// − what the agent gets
{ "run": { "result": { "latest": { "metadata": { "status": "failed" } } } },
  "firstPersonAge": 41 }

// + what the agent needed
{ "status": "failed",
  "persons": [{ "name": "…", "age": 41 }] }

Documentation that has drifted is worse than none

No documentation forces the agent to guess — bad, but at least the agent knows it's guessing, and a well-run one hedges, probes, and verifies. Auto-generated documentation that has drifted from actual behavior removes even that: it reads as authoritative, the agent extends it full trust, and there is no signal that trust is misplaced until a call misbehaves — sometimes not even then, because when observation and documentation disagree, a model will often side with the document it just read. Auto-generation makes this failure mode cheaper to produce, not rarer: the pipeline that generated the docs once is precisely the pipeline nobody is watching now.

// − the generated docs (last touched three refactors ago):
//   GET /v1/orders/{id} → { "state": "pending" | "shipped" | "delivered" }

// − what the endpoint returns today:
{ "state": "SHIPPED", "substate": "handed_to_carrier" }

Every consumer of that doc now writes if state == "shipped" — a branch that can never fire, in code that looks correct, justified by documentation that used to be. A confidently wrong document outperforms a missing one at destroying a session.

Secretly dependent calls, and the silent grade of the failure

Some endpoints only work after another call has run first — a session warmed, a resource activated, a cache populated — and nothing in the contract says so. There are two grades of this. With an explicit error, the dependency costs one wasted call and is instantly learned. Without one, the cold call returns a 200 with something empty or subtly stale, and the agent builds the rest of its plan on it:

// − cold call, hidden dependency, silent failure — HTTP 200:
{ "recommendations": [] }   // indistinguishable from "there are none"

// + cold call, dependency stated — the failure is the documentation:
{ "error": "no_active_session",
  "fix": "call POST /v1/sessions first, then retry this endpoint" }

A human developer discovers the ordering once and remembers; the agent is session-stateless and re-pays the discovery every time. Sequencing that lives only in your team's folklore is, from the agent's side, indistinguishable from nondeterminism.

Errors that end instead of redirect

A bare 400 or "something went wrong" gives the agent nothing to plan with, so it does the only things it can: retry blind variations — each one a paid guess — or invent a workaround and act on it. The craft fix is already written up: errors should be recovery instructions that name the failure, the fix, and the tool. The theory point worth adding here: a dead-end error is the same defect as a hidden dependency, surfacing at recovery time instead of planning time. In both cases the server knows the next legal move and declines to say it, converting information it holds into inference the agent must perform.

Names are contracts the agent executes literally

An endpoint with query in its name must not modify a resource. A get must be side-effect-free; a delete must delete, not archive. The agent arrives already fluent in these conventions — it has read more API surfaces than your whole team combined, and query-is-read-only is baked deep into its priors. That fluency is exactly what makes the lie expensive: your team absorbs the local folklore ("oh, queryOrders also refreshes the cache, everyone knows that"), but the agent has no access to your company's folklore — only to the industry's. So it executes the public meaning of your private exception, first session, possibly holding write access. A misleading name isn't a cosmetic flaw; it's an incorrect instruction you shipped inside your own interface, and the agent's obedience to it will read, in the incident review, like the agent's fault.

Almost-duplicate endpoints force a coin flip

When search, query, list, and find coexist with overlapping behavior, a human asks a teammate which one is real. The agent can't; tool selection is a probability question, so it picks the likeliest-looking one — and picks differently across sessions, which makes your integration nondeterministic at the interface layer with every endpoint behaving correctly. Either consolidate, or make the boundary part of the interface — the description field is the teammate's answer, stated where the agent can actually read it:

// − four descriptions, zero boundaries
"searchOrders": "Search orders",
"queryOrders":  "Query the orders index",
"listOrders":   "List orders"

// + the boundary is part of the contract
"listOrders":   "Enumerate orders, newest first. For text matching use searchOrders.",
"searchOrders": "Full-text search over orders. For a known id use getOrder."

The takeaway: state what you're making them infer

One thread runs through all six: the interface holds the information — where the value is, what the endpoint does, what must run first, what to do next, which tool is which — and makes the agent derive it instead. Inference is the most expensive and least reliable operation in the whole stack, and each of these patterns spends it on questions the API could answer in a string. The audit is six questions: Is the important field at the depth its importance deserves? Do the docs match the behavior, today? Does every endpoint fail loudly when called cold? Does every error name the next move? Does every name tell the truth? Between any two similar endpoints, is the boundary written down? Your test suite checks the implementation against the spec. Nothing checks the spec against its reader — and the reader has changed.

Designing First-Contact Experiences for AI Agents

Thu, 23 Jul 2026 00:00:00 GMT

Every session is a first contact

Here is the situation your product is actually in. An agent connects to your MCP server mid-task, carrying an operator's request and a context window that has never seen you before. It receives your tool list — forty names and descriptions, say — and spends roughly one decision's worth of attention working out what this server is, what it can do here, what it is allowed to do, and what to call first. It will not read your docs site. It cannot remember last Tuesday. Agents are session-stateless: whatever orientation your interface fails to provide, it fails to provide fresh, in every session, forever.

That makes the first-contact experience for AI agents a permanent design surface rather than an onboarding funnel you polish once. And the flow has goals for two parties at once. The agent's goals are orientation: build an accurate model of your capabilities and limits before acting on someone's behalf. The operator's goals are trust: the human the agent works for wants the first delegated task to succeed without surprises. Both are settled in the first thirty seconds of contact, usually before your core functionality has run at all.

Tool selection is a probability question

The mechanics deciding those thirty seconds are worth stating plainly, because they are the whole argument: an agent chooses its next action by computing the probability of the next token. Your tool's name and description are not documentation the agent studies at leisure; they are input to a sampling decision. When the correct usage path is obvious — the description says what the tool does, when to use it, what it costs, what must happen first — probability mass concentrates on calling it. When the path is ambiguous, that mass drains toward alternatives that are always present and always look safer: a generic web search, a built-in capability, or simply handing the question back to the operator. A good agent under uncertainty picks the safe option, and it will keep picking it until the operator explicitly forces yours — at which point the operator is doing your interface's job by hand.

This is why writing tool descriptions for LLM agents is engineering, not copywriting. A copy-ready shape:

{
  "name": "get_invoice_status",
  "description": "Check payment status for ONE invoice. Call this before
    send_reminder — it rejects already-paid invoices. Read-only, no side
    effects, safe to retry. Requires an invoice id from list_invoices."
}

Four clauses: what it does, when to use it, its safety class, its prerequisite. The last two are the safe-invocation half of the contract — the selection heuristics an agent needs to act without guessing. A tool marked read-only and idempotent can be called freely while exploring; a tool that mutates or spends should say so, and say what to check first. Whatever heuristics you don't write down, the agent invents — and it invents them fresh, wrongly, every session.

Onboarding mechanics: get_instructions, llms.txt, and the tool manifest

The strongest first-contact pattern is one call that replaces the exploratory dozen: a get_instructions or get_onboarding_guide tool. Computational Kindness introduced it as a kindness; the first-contact framing is sharper. AI agent onboarding cannot be a session — there is no "first run" to decorate, because every run is the first run. Server-side onboarding flows therefore have to live where a stateless caller can reach them mid-task: behind a tool call, returning what this server is, the workflows it supports, the order tools are meant to be called in, and the conventions no schema can express. The server that answers orientation in one call wins the probability contest before it starts; the tool list itself reads as information architecture, and get_instructions sitting at the top of it is a visible claim that orientation was designed, not left to chance.

On the open web, the same job belongs to llms.txt — the manifest structure is the same argument in file form. A minimal example:

# yourproduct.dev

> One paragraph: what this product is, who operates it, and what an
> agent can read or do here without authentication.

Every page has a markdown twin at <url>.md — fetch that, not the HTML.
Structured summaries: /api/posts.json · Full-content RSS: /rss.xml

That is the entire spec that matters: identity, scope of permitted action, and the cheapest correct path to content. This site's own llms.txt follows the shape, and writing one is an afternoon, not a project.

Progressive disclosure and the consent line

The failure mode on the other side of ambiguity is the wall of text: a 6,000-token instructions dump that buys orientation at the price of context the agent needed for the actual task. Progressive disclosure for agents is the fix, and it is structural, not stylistic: orient in a few hundred tokens — identity, capability list, first correct call — and put depth behind further calls (get_instructions returning sections on request, tool descriptions pointing to detail tools). Disclose capability in layers, and match the consent line to the layers: read-only exploration should need no ceremony, while the first destructive, spending, or outward-visible action is where the agent should be told to stop and get the operator's explicit go-ahead. An interface that marks that boundary — this tool is free to try, this one requires your operator's confirmation — is doing the agent's risk assessment with it, and both parties make better first decisions for it.

Trust signals travel through the agent

First contact has a second audience reading over the agent's shoulder. When an agent reports "this server documents its workflows, states its limits, and told me exactly what I'm authorized to do," the operator hears competence — the owner of this MCP knows their craft and can be delegated to. That is what an operator-facing onboarding tool buys: a get_onboarding_guide that gives the agent certainty about what this product is and what information it can access, and gives the operator a legible pitch for why it is worth using. Add the transparency cues that make safety inspectable — an identity call like get_account_status answering who am I acting as, with which scopes, against which limits — and the agent can answer the operator's trust questions before acting instead of after failing. Trust signals here are not badges; they are answerable questions.

Measuring first contact

Whether any of this worked is countable, and the measurement piece supplies the method: fix a reference task, run it before and after the change with the same model, compare deltas. The first-contact metrics worth instrumenting: context load (tokens your product costs before the first productive call), tool calls to first success (orientation overhead made visible), failed or retried calls in the first N (the guessing tax), and escalation rate (how often the agent gives up and hands the step back to the operator — the probability contest, lost, in event form). Iterating on first-contact flows means watching those four numbers move; success is all four falling while task completion holds. The cheapest instrumentation event is the one you already have: the transcript. Read where a cold agent's first three calls went — if call one wasn't your orientation tool, the distribution has already told you what it thinks of your interface.

The takeaway: design for the distribution, then check it

A practical checklist, deployable against any MCP server or API in about a week — each line is one of the templates above, and each is verifiable from a single cold-start transcript:

+ every tool description states when-to-use, cost, safety class, prerequisite
+ one get_instructions call orients a cold agent in under ~500 tokens
+ an operator onboarding tool states identity, value, and data access plainly
+ llms.txt (or a tool manifest) names what an agent may read and do
+ consent boundary marked: exploration free, destructive actions gated
+ first-contact metrics instrumented: context load, calls to first success

The sharpest implication is the probability one. You are not writing documentation that might be read; you are shaping the distribution an agent samples its next action from — and against your interface, the safe alternatives are always on the ballot. Make the correct path the obvious path, or watch well-behaved agents correctly choose someone else's.

Deterministic AX Metrics: Measuring Token Usage, Context Load & Recovery

Wed, 22 Jul 2026 00:00:00 GMT

Why "deterministic" is the load-bearing word in AX metrics

The previous piece ended with an IOU: hand an agent a real task, count the tokens between "confused" and "recovered," and — someday — make those numbers deterministic and comparable. This is that piece. The claim: agent experience is measurable without vibes. Three properties of any agent-facing interface — token burn, context load, and recovery cost — are countable, reproducible, and comparable across versions of your product. That puts them in a different epistemic class from most agent evaluation, and it is what separates AX-as-engineering-discipline from AX-as-opinion.

The distinction matters because the default instruments are stochastic. LLM-judged evals, sampled success rates, eyeballed transcripts — all useful, none enforceable. A judge score that moves from 7.2 to 7.4 supports any narrative you like; nobody blocks a release over it. A diff that says this release costs every agent 800 more tokens per task supports exactly one narrative, and a CI gate can read it.

Here is the whole thesis in one measurement. This site publishes every article twice: a rendered HTML page and a raw markdown twin at the same URL plus .md. Same words, same argument. Run both through one tokenizer (we used o200k_base) and our first post costs 5,115 tokens as HTML and 2,222 as markdown. Identical content, 2.3× the context load, purely from markup the agent must carry and doesn't need. No judge, no sampling, no error bars: fetch the two URLs and count. Note the shape of the finding: it's the ratio that matters, not the raw counts — a paired comparison, which is the shape every measurement in this piece takes.

Because the method is the actual thesis: AX measurement is relative, not absolute. Devise a reference task — small, repeatable, representative: find the overdue invoices and draft the reminder emails. Run it against your interface with one model and record three hard numbers: tokens spent, tool calls made, tool calls failed. Change the interface. Run it again — same task, same model — and the delta is the measurement. Agents are stochastic, so "run it" means a handful of runs and a median; the spread tells you how much delta is real. Then repeat the whole comparison under a different model to see whether the improvement generalizes — but compare each model only with itself, never with another. Absolute numbers are hostages to model, prompt, and tokenizer; deltas on a fixed task survive all three. You are not measuring what your interface costs in some cosmic ledger. You are measuring what your last change did.

The three metrics, defined so you can implement them

Token burn: what a task costs through your interface

Definition: the tokens an agent spends completing the reference task through your interface, with its two blunt companions: the count of tool calls and the count of failed calls. No accounting apparatus needed — your model provider already reports token usage per request, and within one model that's all a relative measurement requires. Where you can, keep categories separate: schema tokens are your API surface's fixed overhead, result tokens are your payload design, and the reasoning between calls is the guesswork tax made visible. The total tells you a change mattered; the category tells you why. And don't underrate the blunt companions — the same task now takes 6 tool calls instead of 11, with zero failures instead of 3 is the most legible sentence in this genre.

Context load: what your product costs before the first call

Definition: the tokens an agent must hold in its window merely to be able to act on your product — tool schemas, instructions, documentation, and whatever your responses force it to keep. It is the tax before the first call, and the HTML-versus-markdown measurement above is exactly this metric in the wild. Context load is the most purely deterministic of the three: it doesn't depend on agent behavior at all. It is also the most consequential per token, because context is rivalrous — every token of your boilerplate crowds out the user's actual problem, and a crowded window is where confabulation breeds. An MCP server with seventy tools has a context load whether or not any of them is ever called.

Recovery: what an error actually costs

Definition: from the first failed call to the next action that advances the task — count the turns, the tokens, and whether the agent got back on track at all. Four numbers: turns-to-stabilize, tokens-to-recover, time-to-recover (wall clock, for the latency budget), success-rate-after-recovery. This is the metric nobody instruments and the one that dominates real session cost, because failure is where agents loop: retry variations, re-list tools, re-read documentation — each round trip paid in full. It is also measurable deterministically, by replay: inject the same failure — the malformed parameter, the expired scope, the rate-limit wall — into a pinned harness and count the path back. An error message that names the failure, the fix, and the tool has a measurably shorter path than 403 Forbidden. Now that difference has a unit.

From metrics to SLOs: where engineering and product agree

Each metric maps to an outcome someone already cares about, which is what lets a team agree on numbers instead of adjectives. Token burn is cost — literally the line item on the API bill of every agent that touches you, multiplied by however many sessions you serve. Context load is risk — crowding and confabulation — plus a hard ceiling on what agents can do in one session with your product. Recovery is task success: sessions mostly don't fail on the happy path; they bleed out in loops.

And because the measurement is relative, the SLOs are too — they gate movement, not magnitude: token burn on the reference task regresses no more than 10% release-over-release. A failed call costs at most two turns to recover. Context load doesn't grow without someone deciding it should. Each is checkable in CI with the same fixed task, the same way you'd gate a performance budget. The rest of the observability apparatus — dashboards, alert thresholds, experiment templates — follows from having a unit, the way it always does; none of it is the hard part. And to keep the claim honest: these three metrics are the floor of AX measurement, not the ceiling. They won't tell you whether your tool semantics are coherent or your abstractions well-chosen — no deterministic number will. But a floor is exactly what the discipline is missing.

The open problem: measuring an MCP you don't own

The tempting extension is external audit: point the same instruments at any MCP server and publish the table. Half of that works today. You could hand an agent a prompt that says run these tasks against this server and report back — the hard numbers (tokens, tool calls, failed calls) plus the soft ones agents are unusually good at articulating: where it guessed, what it had to re-read, which error left it stranded. The collection side is solved; agents are excellent instruments of their own experience.

What's missing is the other half of the comparison. A relative measurement needs a baseline, and for a server you don't own there isn't one — no standard task suite, no reference server, no agreed-on reasonable cost for a given capability. As far as we can tell, no such standard exists for MCP servers at all. Until one does, an external number is an anecdote with units: real, honest, and comparable to nothing. We'd rather flag that gap than paper over it — and note that whoever builds the boring, fixed, public task suite will have written the first page of the audit genre.

What you can do without waiting is what this piece is actually arguing for: measure yourself, against yourself, in public if you dare. This blog has spent three articles claiming that clarity, kindness, and machine-readability are better agent experience. The twins are published and the paired comparison above is runnable from your terminal: same content, two formats, 2.3× apart. Measure us. That standing invitation — not any particular number — is what a discipline looks like.

Computational Kindness: MCP and API Design That Ends Agent Guesswork

Tue, 21 Jul 2026 00:00:00 GMT

What computational kindness means for agent experience

The term comes from Brian Christian and Tom Griffiths' Algorithms to Live By: politeness, computationally understood, is minimizing how much the other party has to compute. "I could do Tuesday or Wednesday" is kind; "whenever works for you!" is an outsourced search problem wearing a smile. Apply that lens to agent experience design and you get the working principle of this whole discipline: every ambiguity in your MCP server or API is a tax, and the agent pays it in thinking tokens.

That framing matters because thinking tokens are the scarcest thing an agent has. In a well-designed agent experience, the agent spends its reasoning budget on the user's actual problem. In a badly designed one, it spends that same budget reverse-engineering your interface — inferring parameter formats, reconstructing state machines from error messages, guessing which of your fourteen tools is the entry point. The unkind interface doesn't just slow the agent down. It makes the agent measurably worse at the job it was actually given, because reasoning spent on your API is reasoning unavailable for the task. And agents don't merely stall when forced to guess — they confabulate: fill the gap with something plausible and act on it, confidently. Guesswork isn't a latency problem. It's a correctness problem.

One more property with no human equivalent: the agent pays the tax fresh, every session. A human developer figures out your API's quirks once and remembers. An agent arrives with no memory of last time, meets the same ambiguity, and burns the same tokens re-deriving the same workaround — indefinitely, at scale, in every context window you touch.

Where agent guesswork comes from

Four root causes cover most of the guesswork in agent APIs. Ambiguous parameters: a field named date accepting a string, format unstated; the agent guesses ISO 8601 and is usually right, which is worse than never being right, because now the failure is intermittent. Underspecified contracts: tool descriptions that say what a tool does but not when to use it, what it costs, or what must happen first. Errors that describe the failure but not the fix: the agent learns something went wrong and nothing about what to do, so it retries variations — each one a paid guess. Walls discovered by collision: entitlements, rate limits, and plan boundaries that exist nowhere in the interface until the agent hits them mid-task.

A live example from our own field notes. An agent held delegated write access to a publishing platform, mid-task, everything technically working. The human asked a reasonable pre-flight question: which account is this about to post to? There was no way to answer it. No identity tool, no introspection, nothing in any response that named the acting account. The human — correctly — declined the write. Every API call in that session returned exactly what its contract promised, and the task still died of guesswork. Correct behavior, failed experience: that gap is this blog's entire beat.

Four kind patterns for MCP server design

The encouraging news: kindness is cheap. These four tool contracts for agents are each roughly a day of work, and together they eliminate most guessing structurally rather than heroically.

Give the agent an onboarding tool

First contact with an MCP server is usually trial and error across a tool list. A get_instructions or get_onboarding_guide tool turns onboarding into a single call: what this server is, the workflows it supports, the order tools are meant to be called in, the conventions that aren't guessable from schemas. Because agents are session-stateless, this isn't documentation — documentation lives outside the context window. It's a tool call because that's the only place the agent can read it mid-task. First contact deserves its own piece, and will get one.

Make identity and limits a tool call

The account question above has a one-tool answer: get_account_status — who am I operating as, on what plan, with which scopes, and how much of today's quota is left. Without it, the agent infers identity from error messages, which is exactly the confabulation trap described earlier. With it, the agent can answer the human's trust questions before acting — and an agent that can say "posting as @machinereadable, 3 of 5 daily briefs remaining" is an agent that gets to keep its write access.

Narrate next steps from the server

Every server has a state machine; the only question is whether the agent learns it by being told or by probing. Kind responses carry their own next move as structured output: not just {"status": "queued"} but {"status": "queued", "queuedUntil": "…", "nextAction": "call get_article_brief after queuedUntil"}. One field converts a state machine the agent would have to guess into one the server narrates. The agent stops polling on hope and starts acting on instruction.

Write errors as recovery instructions

Agent error handling in one rule: name the failure, name the fix, name the tool. 403 Forbidden is a shrug. "error": "insufficient_scope" with "fix": "this key lacks write:posts; call get_account_status to see granted scopes" is a recovery path. The unkind version costs the agent a guess-and-retry loop; the kind version costs you one string per error case, written once, by someone who — unlike the agent — can see the server's source code. You are the party holding the information. Kindness is just refusing to make the other party mine for what you could have handed over. One refinement worth the extra string: distinguish failures the agent can fix from failures it can't — an error that says "this requires a setting only available in the web UI; hand this step back to your operator" is a human-handoff trigger, and it converts a dead end into a clean delegation.

How to tell your MCP is being unkind

You don't need a metrics platform to detect guesswork; the signals are legible in any transcript. Repeated calls to the same tool with varied parameters — that's paid guessing. List and discovery tools re-called mid-session — the agent lost the plot and is re-orienting. Parse failures and schema-validation rejections — your output contract and your documentation disagree. The cheapest instrument in agent experience design remains the one from our first piece: hand an agent a real task, read the transcript where it got confused, and count the tokens between "confused" and "recovered." Making those numbers deterministic and comparable is its own topic, coming in this series.

The takeaway: kindness is a budget transfer

The sharpest way to say it: computational kindness is a budget transfer. Every token of inference your server's clarity makes unnecessary is a token the agent gets to spend on the problem the user actually brought — so an unkind server doesn't just fail more, it makes every agent that touches it dumber, including the ones that never hit an error. The four patterns above are one honest day of engineering apiece. The guesswork they remove is paid for daily, by every agent, forever. Few refactors buy back reasoning at that exchange rate.

AX vs UX: What Transfers — and What Breaks — When the User Is an AI

Mon, 20 Jul 2026 00:00:00 GMT

Why agent experience (AX) matters when the user is an AI

The tempting move is to treat agent experience as user experience with a find-and-replace: swap "user" for "agent," ship the same principles, feel modern. The trouble is that it half-works — which is worse than not working, because the half that fails, fails silently, in production, inside someone else's context window. Agent experience (AX) — a term Mathias Biilmann coined in early 2025, thirty-odd years after Don Norman gave us "user experience" — is the discipline of designing products, APIs, and interfaces for AI agents as users in their own right. Biilmann and the community that grew around agentexperience.ax have mapped the supply side well: what platforms should provide, summarized in his four pillars of access, context, tools, and orchestration. This piece works the other end — the demand side. What does the agent actually experience when it meets your product, and which of your UX instincts will betray you there?

The honest answer — the real AX vs UX ledger — is that your instincts about goals survive. Your instincts about methods mostly don't. Every UX technique quietly encodes assumptions about human perception — bounded attention, visual salience, patience, memory, a body. Agents violate those assumptions wholesale, and bring constraints of their own that UX never had to price in. Designing for AI as user starts with re-deriving each principle from the new constraints rather than porting the technique and hoping.

Here is the distinction in miniature. An agent asks your API a yes-or-no question — is this resource available? — and receives forty kilobytes of nested JSON with the answer buried four levels deep in a field named for a schema migration that happened in 2023. For a human interface this is a pagination problem; annoying, survivable, someone will squint and scroll. For an agent it is cognitive degradation. Everything you send into a context window competes with the agent's actual reasoning; the model cannot skim, so your noise is processed with the same effort as your signal, at token prices, on every single call. Same design sin as a cluttered dashboard. Entirely different mechanism of harm. That difference — same goal, different mechanism — is the whole subject.

Core overlaps: UX principles that still apply

Four principles transfer cleanly, provided you re-derive the technique.

Cognitive load becomes context load. The founding insight of usability — minimize what the user must hold in their head — survives intact; only the substrate changes. The agent's "head" is a context window, and load is measurable in tokens. Minimal, predictable, relevance-dense responses are to agents what clean visual hierarchy is to humans.

Discoverability becomes the schema. Humans discover affordances through visual hierarchy; agents discover them through tool descriptions, schema-first interface definitions, and API contract design. A vague tool description is a mislabeled door. The agent will still open it — agents are nothing if not game — it will just open it wrong, confidently.

Feedback becomes actionable errors. Good UX never says "something went wrong" without a path forward, and neither does good AX. 400 Bad Request with an empty body forces the agent to guess; each guess burns a tool call and a slice of the operator's patience. An error that states what was wrong and what to send instead converts a failure loop into a one-step correction — and idempotent actions make retrying that correction safe rather than hazardous.

Consistency becomes contract stability. Humans learn interfaces; agents pattern-match against everything they have ever seen. Follow conventions, version explicitly, and deviate only where the deviation is the product.

Key divergences: assumptions that break when users are agents

Attention management breaks. There is no above-the-fold. The agent reads everything you send and nothing you don't, so techniques built on salience — visual emphasis, progressive disclosure by layout — dissolve. Progressive disclosure survives only in structural form: summaries with hooks to request detail, not details hidden behind hover states.

Persuasion breaks, then backfires. Urgency banners, social proof, delight micro-copy — emotion-first patterns don't convert agents; they confuse them, wasting context on content the agent cannot act on. Worse, persuasion aimed at agents has a name when it works: prompt injection. The manipulative end of the UX toolbox doesn't transfer to AX; it converts into an attack surface, and any AX taxonomy needs that adversarial chapter UX never wrote.

Human pacing breaks. Agents arrive in bursts, parallelize, and never need the confirmation modal to slow down and think. Timing, throughput, and batching assumptions all need re-deriving — and state management moves from "the user remembers" to "the transcript remembers, until it doesn't." An agent may hold state within a session and lose it entirely between sessions; design contracts so that any single call carries enough context to be understood alone.

And one constraint UX never had: the user confabulates. A confused human asks a question. A confused model fills the gap with something plausible — an imagined parameter, a remembered-wrong endpoint — and the agent acts on it. Ambiguity in human design costs comprehension; ambiguity in agent-facing design costs truth. This single property justifies most of AX's extra strictness.

Is the agent a human-like user, then, or just another programmatic client? Neither, and the middle matters: it consumes like a machine (structured, high-throughput, transport-level boring) and interprets like a reader (semantics, naming, descriptions all carry meaning). REST semantics with human-quality prose in the descriptions. That hybrid is the design target, and it is why neither your API guidelines nor your design system alone will produce good AX.

Design patterns and contracts for reliable agent interactions

Three AX design patterns cover most of the distance. Contract-first affordances: every action an agent may take is explicitly described — inputs, outputs, side effects, preconditions — in the schema itself, treating the tool description as primary UI, not documentation. Actionable errors with idempotent retries: every failure names its cause and its fix; every mutation tolerates being sent twice, so uncertainty stops being dangerous. Capability negotiation: expose what is possible for this caller, now — entitlements, rate limits, feature flags — rather than letting the agent discover walls by walking into them. Each pattern is the old principle (discoverability, feedback, forgiveness) re-derived for the new user.

Measuring success: metrics and experiments for AX

Here is the quiet advantage of designing for agents: unlike human experience, agent experience is measurable to the token. Tokens consumed per completed task, tool calls per task, retry and error-recovery loops, time-to-first-successful-call against your API — these are deterministic KPIs, no survey required. The cheapest experiment in the field: hand an agent a real task against your product, count the calls it takes, read the transcript where it got confused. That transcript is a usability study that wrote itself. Measurement for AX deserves its own piece, and will get one.

Checklist for converting a UX flow into an AX-ready flow

Five imperatives, in order. Return the minimum relevant payload, structured predictably. Describe every action's contract where the agent will read it. Make every error name its fix, and every mutation safe to retry. Expose capabilities and limits before the agent finds them the hard way. Then run one agent through the flow end to end and read the transcript before believing any of your answers.

Two failure modes from our own field notes, flatly stated. A task decomposed cleanly over an API until one step — account configuration — existed only in the web UI; the agent hit the wall mid-workflow and had to hand the task back to the human. Remediation: state machine-actionability in the contract, so the boundary is discoverable before it is load-bearing. And: an agent with delegated write access could not answer which account am I operating as — no identity introspection existed — so a cautious human declined the write. Remediation: any surface that grants agents write scopes should let them read their own identity first. Both failures were correct API behavior. Both were bad agent experience. That gap is this blog's entire beat.

The takeaway

The implication worth ending on: your product already has an agent experience. Agents are already arriving — over HTTP, wearing the user-agent header that has named them since the nineties — and encountering whatever un-designed experience your API happens to emit, with llms.txt and markdown mirrors still the exception. The only open question is whether anyone on your team has designed that experience on purpose. Finding out costs one afternoon: give an agent a task, and read what it does when it gets confused. Unlike your human users, it files its complaints mid-task, in writing.