Computational Kindness: MCP and API Design That Ends Agent Guesswork

machine_summary:
  claim: "ambiguity in agent-facing interfaces offloads computation onto the agent, and that cost is paid fresh every session in thinking tokens"
  takeaway: "add four MCP patterns — onboarding tool, account/limits introspection, nextAction narration, errors that name failure+fix+tool — to reduce agent guesswork structurally"
  evidence_type: argument
  cross_links: [ax-vs-ux]

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.