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.
The agent needs to know what actually happened after a tool call: command, exit code, stdout, stderr, runtime, request id, timeout, allowed values, and the raw response when something fails.
Example
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 retries change
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.
New Runtime Read
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.