Agent-Computer Interface (ACI)

The tools an agent uses are its interface to the world, and their definitions deserve as much prompt-engineering attention as the main prompt. The framing: invest in the agent-computer interface (ACI) the way software teams invest in human-computer interfaces (HCI). Since an agent is just an LLM using tools in a loop (Workflows vs Agents), tool quality directly gates agent reliability — for the SWE-bench agent, more time went into optimizing tools than the overall prompt.

Two levers: tool format and tool documentation. Format matters because cosmetically equivalent representations differ wildly in how hard they are for a model to produce — writing a diff means counting changed lines in the header before writing the code; writing code inside JSON adds escaping overhead. Documentation matters because a tool the model has to puzzle over is one it will misuse.

Format heuristics:

Give the model enough tokens to "think" before it writes itself into a corner.
Keep formats close to what the model has seen naturally on the internet.
Remove formatting overhead (line counts, string-escaping).

Documentation & robustness heuristics:

Put yourself in the model's shoes — if the tool isn't obviously usable from its description and params, it won't be for the model either. Include example usage, edge cases, input-format requirements, and clear boundaries from other tools.
Write the description like a great docstring for a junior developer — especially with many similar tools.
Test how the model uses the tool on many example inputs and iterate.
Poka-yoke the tool: change arguments so mistakes are hard to make (e.g. require absolute filepaths so the model can't break after changing directory).

Claims

Give tool definitions as much prompt-engineering attention as the overall prompt. principle — durable: the tools are the agent's interface to reality, so their clarity bounds what the agent can reliably do.
Invest in the agent-computer interface (ACI) as much as teams invest in HCI. principle — durable: the model is a user of your tools, and interface quality determines its success the same way it does for humans.
Choose tool formats that are cheap for the model to produce — natural, low-overhead, no bookkeeping like line counts or heavy escaping. best practice — context: designing a tool's I/O format; cosmetically equal formats differ in model difficulty, so "best" depends on what the model finds easy to write, which is model-dependent.
Give the model room to "think" before committing to output. best practice — context: tool/format design for tasks where the model can write itself into a corner.
Write tool docs like a docstring for a junior dev: examples, edge cases, input formats, boundaries. best practice — context: any nontrivial toolset, especially many similar tools where disambiguation matters most.
Poka-yoke tools — design arguments so mistakes are hard to make. best practice — context: recurring tool-misuse failure modes (the absolute-filepath fix eliminated a whole error class); the mitigation is discovered by watching real misuse.
Test how the model actually uses tools and iterate on the definitions. principle — durable: tool quality, like eval quality, is found empirically by looking at real usage, not designed correct up front.

Workflows vs Agents — an agent is an LLM looping on tools; ACI quality sets the ceiling on agent reliability.
The Augmented LLM — "well-documented interface for the LLM" is the ACI discipline at the level of a single call.
Error Analysis — "test how the model uses your tools and iterate" is error analysis aimed at the tool layer: watch real misuse, fix the interface.
Agent Supervision — the mirror image: ACI is the agent→tools interface (agent→world); supervision is the human→agents interface (HCI for agents).
CLI Tools over MCP Servers — ACI applied to the choice of surface: a CLI wrapped in your own skill is a hand-tuned ACI that beats an off-the-shelf MCP server on token cost and extensibility.
Distillate: Building Effective Agents.
Distillate: Nimbalyst — Visual Workbench for Supervising Coding Agents.
Distillate: My 4-Layer Claude Code + Playwright CLI Skill (Agentic Browser Automation & UI Testing) — "use CLIs, not MCP servers" as a concrete surface-choice instance of the ACI discipline.

Agent-Computer Interface (ACI)

Claims

Related

Linked from