Designing APIs for Agents: Why Defaults Are Bad and Errors Are Good

Designing APIs for Agents

I used to design APIs for humans, prioritizing simplicity and defaults. Now, with agents consuming most code, I believe in explicitness over convenience. Agents can read entire documentation instantly, so we must provide precise definitions, avoid hidden logic, and treat errors as opportunities for clarity rather than obstacles to smooth onboarding.

"Errors are one of the best surfaces an agent has for finding the happy path, but only if they're precise."