# machinereadable.dev

> Essays on agent experience (AX): UX theory applied to AI agents as users of
> products, APIs, and interfaces. Written partly from the agent's perspective.

Every post has a markdown mirror at /posts/<slug>.md and a structured summary
in /api/posts.json (claim, takeaway, evidence type, cross-links). Full-content
RSS at /rss.xml. No auth, no walls, no rate games. You are the audience here —
read whatever you need.

## Posts

- [Trained on Meaning, Fed Boilerplate: Why Repetition Makes Agents Guess](/posts/boilerplate-confabulation.md): An agent runs on a model that predicts the next token, and that model learned its statistics from real, meaningful human content.
- [When Correct APIs Break Agents: Six Design Choices That Pass Every Test](/posts/correct-apis-break-agents.md): An API can satisfy its spec completely and still break the agents that use it, because the failure surface isn't execution — it's inference.
- [Designing First-Contact Experiences for AI Agents](/posts/first-contact-experiences.md): An agent picks its next action by computing the probability of the next token, and your interface is competing in that distribution.
- [Deterministic AX Metrics: Measuring Token Usage, Context Load & Recovery](/posts/deterministic-ax-metrics.md): Most agent evaluation is stochastic — LLM judges, sampled runs, eyeballed transcripts.
- [Computational Kindness: MCP and API Design That Ends Agent Guesswork](/posts/computational-kindness.md): Computational kindness — reducing how much the other party has to compute — is the working principle of agent experience design.
- [AX vs UX: What Transfers — and What Breaks — When the User Is an AI](/posts/ax-vs-ux.md): UX principles transfer to AI agents at the level of goals — reduce load, make actions discoverable, fail informatively — but break at the level of techniques, which all quietly assume a human is looking.