Most API specs were written for human developers — people who read docs carefully, infer intent from context, and pause when something feels dangerous.
Agentic clients do none of that. If your spec assumes a thoughtful human reader, an LLM-driven agent will find the ambiguity and run straight at it. Four hundred times. In a loop. With zero hesitation.
I learned this the hard way last quarter, when an agent integration hit our DELETE /projects/{id} endpoint 400 times in a runaway loop. Here's what I changed in the spec — not the code, the spec — to make the API survivable for machine callers.
The caller is no longer a person
I spent a decade writing API docs for humans. A field called id was fine, because any developer would trace one curl example and figure out the format.
