Everything I Knew About Developer Experience Is Wrong for Agents

Most of what we know about developer experience we learned from humans. Agents are a different user, and some of our best practices quietly work against them.

Your APIs were written for human developers. Agents use them anyway: they skip the docs, guess from training data, and throw calls at your API until something sticks. Every extra turn multiplies failures and hallucinations, and quietly runs up your token bill.

In this session I'll share a framework for measuring how usable an API really is for agents, built on experiments you can rerun on your own APIs. We'll walk through two or three live, I'll hand you seven more to take home, and we'll draw the general conclusions. Fair warning: they overturn sacred cows I've personally taught and defended for more than fifteen years. Accurate documentation is not the be-all-end-all. A machine-readable spec does not automatically make your API agent-ready. And some standard advice on things like idempotency doesn't work the way you think.

What you'll leave with:

1. Three widely-believed developer experience best practices that fail for agents, and what to do instead.
2. What actually moves agent success rates: 
   1. Naming that leverages everything the model already knows
   2. Errors designed so an agent recovers on the next try 
   3. Accurate descriptions and schemas 
   4. Code samples/SDKs/Skills over prose and tutorials
3. How usability shifts across models and agent types (a coding agent, a chat assistant, and an autonomous agent are three different users), and when to choose APIs, MCP, or CLI, or combine them.
4. How to run these experiments yourself, and why no generic checklist or rating tool, mine included, replaces testing with your own use case, agents, and models.