v0.2 · draft

Machine
Mode.

The standard for agent‑operable tools.

Today’s models can think, write, plan, and converse. They cannot yet operate. Every real action — every file written, ticket created, deployment shipped, sensor read, transaction approved — happens in the world outside the model. To cross that boundary, an agent has to use a tool.

Today’s tools were built for humans: prose, tables, color, prompts, progress bars, ambiguous errors. They are unreadable and unsafe for autonomous systems.

Machine Mode is the interface across that boundary. A standard for how a tool behaves when a non‑human invokes it — typed, discoverable, bounded, safe, auditable. A second interface, for agents.

MCP makes a tool reachable. Machine Mode makes it operable.

Read the specification Jump to the ten factors

§ 01

Two interfaces, two readers.

for people

Human Mode

Optimized for reading. The default for every tool since the 1970s. Works for a person at a terminal. Falls apart the moment something tries to read the output back.

prose, tables, color
progress bars, prompts
ambiguous errors
exit-code-only completion
no schema, no discovery
every tool different

for agents

Machine Mode

Optimized for operating. A typed interface a non‑human can rely on: discoverable, bounded, safe, auditable. The second interface every serious tool should ship.

typed event streams
capability discovery
standard event envelope
defined completion semantics
structured error taxonomy
explicit, reversible writes

§ 02

Sense, act, verify.

Fig. 1 · Machine Mode is the interface across the model boundary

§ 03

Ten factors of agent-operable tools.

I
Typed
general
Every emission declares its shape. Consumers know the contract before they consume it. No string‑sniffing, no regex‑on‑output, no guessing what a column means.
For the agent · Dispatch on event.type, never on regex against prose. Hallucination‑resistant.
II
Discoverable
sense
Schema and capability surface on demand. A consumer can learn what a tool exposes without invoking it, without credentials, without network access — before any real work happens.
For the agent · Plan over the surface instead of guessing at it. No flag‑hallucination.
III
Streamable
sense
Results arrive incrementally as they are produced. Long operations remain observable while in flight. The consumer is never blocked waiting for the whole answer to materialize.
For the agent · Start reasoning over the first result while the rest are still being computed. Lower time‑to‑first‑useful‑token.
IV
Bounded
sense
Every read has a limit. Every collection has a continuation. Nothing is unbounded by accident. A request specifies its appetite; the response honors it and signals more when more exists.
For the agent · Context budget is preserved. A wrong --limit can't dump 100k rows into the window.
V
Safe
act
Reads do not write. Writes require explicit intent. Bulk destruction requires a confirmed count. Default behavior is the behavior that cannot regret itself.
For the agent · The agent operating under uncertainty defaults to non‑destructive. Bad guesses produce refusals, not disasters.
VI
Idempotent
act
Writes accept retry keys; replays are not duplicates. A mutation can be attempted, interrupted, and re‑attempted without doubling its effect. Retry is a first‑class operation, not a foot‑gun.
For the agent · Safe retry of writes. No "did the previous call actually go through?" anxiety.
VII
Auditable
act
Every side effect produces a structured record: what was created, updated, deleted, sent, moved. The audit is part of the interface, not an afterthought a log scraper has to reconstruct.
For the agent · Confirm an action took effect; hand stable IDs to memory or a downstream auditor; never assume.
VIII
Verifiable
verify
Success, partial success, truncation, cancellation, and crash are distinguishable. A consumer can tell — without inference — what actually happened. The interface refuses to be ambiguous about its own outcome.
For the agent · summary.ok=true is the only honest success signal. Retry logic stops guessing.
IX
Composable
general
One tool’s output is another tool’s input. The interface holds across the chain. Pipelines are not happy‑path scripts; they are typed compositions with predictable failure semantics.
For the agent · Chain tools without writing regex bridges. The plan executes; pipefail makes failure observable.
X
Versioned
general
Schemas evolve without breaking consumers. Change is explicit and announced. A tool can ship a new version of its interface without silently betraying every agent that already trusted the old one.
For the agent · When a tool updates, the agent knows whether its parser still applies — explicitly, not by debugging silent breakage.

§ 04

On the wire.

01$ outline search "agent operable" --output jsonl --limit 2
02{"type":"aoi:meta","tool":"outline","tool_version":"1.8.2","aoi_version":"0.2","schema_name":"com.example.outline.events","schema_version":"1.0.0","command":"search"}
03{"type":"hit","rank":1,"id":"doc_123","title":"Agent-Operable Tools","snippet":"A conforming tool exposes a stable interface…"}
04{"type":"aoi:summary","ok":true,"count":1,"warning_count":0,"error_count":0,"truncated":false}

A small example — Machine Mode at the wire

§ 05

MCP and Machine Mode.

MCP makes a tool reachable. Machine Mode makes it operable.

MCP is how an agent finds and calls a tool. It is the discovery and invocation layer for the agentic era — necessary, and increasingly settled.

Machine Mode is what the tool does: the interface it presents when something calls it. Reachability is not operability. A tool can be perfectly callable and still emit unsafe, unparseable, unbounded, unauditable output. Reachability without operability is where today’s agent failure modes live.

The two compose. MCP gives agents access; Machine Mode gives tools a contract. The Machine Mode interface a tool exposes is the same interface whether the caller is MCP, a shell pipeline, a queue worker, or another agent.

§ 06

AOI and what comes next.

Machine Mode is the public concept. AOI — the Agent-Operable Interface — is its formal technical specification. AOI‑CLI, its first formal profile, applies the ten factors to command‑line tools: the most common, worst‑instrumented surface in software.

The concrete thing this site is about is AOI‑CLI v0.2 — a CLI with a particular argument structure, schema‑conformant JSONL output, and explicit completion semantics. Where the work is headed beyond that — session mode, alternative wire formats, profiles for other surfaces — is tracked separately so it doesn't crowd the concrete spec.

Read the AOI‑CLI specification Where it's going next