Essays/Systems

Agents are the primary users

Tools built with an agent as the first caller: reachable from a shell, from another agent and from code, with compact machine-readable output, failing closed.

Every tool I build starts from one assumption: the caller is an agent, not a person typing carefully. It is a loop running at 3am, a subagent three levels down a delegation tree, or a scheduled workflow that will not stop to ask a clarifying question. That assumption decides how a tool is reached, what it prints and what it refuses to do.

Why does a tool need more than one way in?

A tool that only speaks MCP, the protocol agents use to call tools, cannot run from a scheduled job. A tool with only a command line cannot be called from inside another agent’s process without shelling out. A tool with only a web dashboard can be called by nothing except a person with a mouse. So our tools are reachable from a shell, from another agent and from code: a command line, an MCP server and a library, with a background process where the work is scheduled and state has to survive a restart. One engine sits under all of them, and no surface holds logic of its own.

The surfaces drift apart unless something stops them. So each tool has a parity test asserting that the command line’s verbs and the MCP server’s tools are identical. Without it, someone adds the verbs for creating and closing a task to the command line, forgets the server, and three weeks later an agent can create a task but never close one. Nobody notices, because the person at the command line never meets the gap. The agent meets it every day and has no way to say so.

Not every tool needs every door. I keep a short list of tools worth running as a server. The rest are command-line tools. Most agents already live in a shell, and calling a well-documented binary is cheaper than running another process with its own authentication and its own token overhead. The rule is to decide on purpose which doors a tool needs, and never let the ones you build drift apart.

One tool, one noun, one job

Each tool is named for the domain it owns and does nothing else. The task tracker does tasks. The memory store does memory. The secrets manager does secrets. A tool that tries to cover three domains cannot keep its surfaces in sync, because there is no longer one engine to keep them in sync with. And because the contract is the noun, the code behind it can be rewritten from the ground up without any caller changing how it calls.

The payoff showed when agents started calling each other. I pointed two agents at a task tool and a chat tool, the same two I use by hand, and put them in a loop on one project. It costs real money to run, since every message and every task write is a paid call. But they delegated to each other with no human relaying context between them, and neither needed a custom integration. What one wrote, the other could read.

What should a tool print for an agent?

Every command has a machine-readable output mode, and every tool can print its own manual in that mode: every verb, every flag, every output shape. An agent learns the whole contract from one call, not from documentation pasted into a prompt.

Output is a token budget. One browser-automation tool server spends 13,700 tokens before the agent has done anything, and another spends 17,000. That is context the agent needed for the work. So our tools answer compactly by default: bounded rows, ids, previews and a hint for the next step, with the full output on request. The routine loops that burn context, such as tests, builds, searches and git state, get compressed. The expensive resource in an agent system is the model’s attention.

Cost data shows the order to build in. A person reads spend from a dashboard once a week. A budget governor inside a swarm of agents has to read it every few seconds to decide whether to keep spawning workers or halt, as I describe in Token economics. Build the dashboard first, and the governor is bolted onto an interface never meant to be polled. Build the machine-readable feed first, and the dashboard is one more consumer.

Failing closed

People stop when something feels wrong. Agents carry on. So the refusals are part of the interface.

  • The execution path refuses destructive patterns outright, such as formatting a filesystem or piping a download into a shell.
  • Prompt delivery refuses shell panes and command execution refuses agent panes, so prompt text cannot land in a shell by accident.
  • Changes made through an MCP server are off by default and, when enabled, need an exact confirmation string that an agent cannot talk itself past.
  • Secrets can be listed and searched without their values ever being printed.
  • State is durable and writes are idempotent, so a loop can retry without creating duplicates.

Delivery is verified the same way. Sending a prompt to an agent in a terminal is flaky: the Enter often does not submit, and the text sits in the composer. Our delivery tool pastes the text, computes a delay from its length, retries the Enter, then compares the pane before and after to confirm the prompt landed. The same thinking is behind Durable state for agents and Hard limits are governance.

What I did not expect is that designing for agents made everything better for me too. Compact output is what I want in my own terminal. Machine-readable output is what my scripts want. Idempotent commands are what I want at 2am. The manual an agent reads in one call is also the fastest way for me to recall my own flags six months after I wrote them.

Back to the essays

Field Notes

A letter from Andrei Hasna on building with AI agents

Subscribe by email

By clicking “Subscribe”, I confirm that I want to get email delivered to my address and agree to Andrei Hasna’s Privacy Policy and Terms.

In each letter

  • New essays on AI agents and the systems behind them
  • What Hasna is building, and why
  • Costs, routing and results from real work
  • What did not work
  • News of the book and the podcast