An API that feels convenient to a human is not automatically convenient to an agent. Humans benefit from defaults, short quickstarts, and SDK methods that hide details. Agents benefit from explicit state because the same executor must repair failed calls. It needs command, exit code, stdout, stderr, runtime, request id, timeout, allowed values, and the raw response when something fails.
What does an agent-first API return?
A human-first SDK might expose a pleasant wrapper:
runCode("summary(cars)", { language: "r" })That wrapper is useful until the call fails. An agent-first API should return the runtime, supported languages, exact field path, request metadata, and error category. Then the next attempt is guided by facts instead of by pattern-matching against similar APIs in memory.
Why do precise errors change retries?
When the error says something went wrong, the agent starts guessing.
When the error says:
field sandbox.runtime must be one of node20, python3.12the next call is almost deterministic.
For tool schemas this means fewer magical options bags and more enums, field paths, allowed values, retry hints, and raw response metadata.
What should API teams expose?
An agent often needs one boring internal HTTP client with auth, retries, logging, and raw bodies more than five friendly SDKs with five exception styles.
The point is not that SDKs are bad. The harmful abstraction is the one that hides world state from the same executor that must later repair the failure and leave a trace for a human.