machinemode.io

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 characteristics

§ 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 characteristics 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.

§ 04

On the wire.

01$ outline search "agent operable" --output jsonl --limit 2
02{"type":"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":"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 characteristics to command‑line tools: the most common, worst‑instrumented surface in software.

Different surfaces get different profiles. For HTTP services, OpenAPI already does almost everything a Machine Mode profile would require — the AOI HTTP supplement, when authored, will reference it as the wire format and add the missing characteristics as an extension. Future profiles will cover message queues, embedded devices, and physical actuators. The characteristics generalize; the wire format does not have to.

Read the AOI‑CLI specification