Vol. IX · The Agent-Computer Interface · IX.3
Designing the Agent-Computer Interface
The ACI is names, schemas, errors, pagination, and idempotency. A sloppy tool surface makes a smart model look drunk. A tight one makes a small model look hired.
8 min read
humanlayer/12-factor-agentsAider-AI/aiderhuggingface/smolagents567-labs/instructormodelcontextprotocol/python-sdkvercel/ai
Doctrine
- One job per tool. A god-tool with a JSON blob argument is an untyped shell.
- Names are verbs the model will say out loud: read_file, apply_patch, ask_human — not handle_misc.
- Errors are the smallest string that enables the next correct action. Include what to try, not a stack trace.
- Cap result size. Return paths and hashes, not 200k tokens of HTML. Offer pagination or a file write.
ACI is the prompt you cannot see
Horthy: tools are structured outputs. Aider proved that the edit format is a product. Instructor and Pydantic AI make the contract typed. MCP standardizes discovery. Vercel AI SDK makes the TS side of the same idea. None of that helps if your search tool returns a novel.
Design the observation the way you design a CLI: short success, actionable failure, no surprise side effects. Prefer apply_patch over write_file for code. Prefer grep over read-whole-repo. Prefer code-act in a sandbox when the model must compose.
Anti-patterns
- One mega-tool whose argument is 'action plus payload'.
- Silent truncation of tool results.
- Non-idempotent tools with no journal, so a retry doubles a charge.