For agents.

Comprehension & predictability.

1. One vocabulary across every conforming tool.
   The agent learns aoi:meta, hit, match, aoi:summary, aoi:error, aoi:warning, aoi:check, aoi:plan, aoi:heartbeat — once. Every conforming tool speaks them. Per‑tool prompt engineering shrinks dramatically.
2. Discovery before invocation.
   tool schema and tool capabilities tell the agent what the tool can do, what events it emits, and what flags it accepts — without calling it. No more "let me run --help and parse the ASCII table."
3. Typed events with a discriminator.
   The agent dispatches on event.type, never on regex against prose. "Is this line a result, a warning, or a status update?" is a typed answer, not an inference.
4. Versioned schemas.
   schema_version in aoi:meta tells the agent which event shape to expect. When a tool updates, the agent knows whether its existing parser still applies — or whether to opt into a new major version explicitly. No silent breakage.

Context‑window economics.

1. Bounded results with cursors.
   --limit 50 returns at most 50 events. The agent's context budget isn't blown by an inadvertent list that dumps a hundred thousand rows.
2. Compact, line‑delimited JSON.
   No banners, ASCII art, color codes, or progress bars eating tokens. Every byte the agent reads is data, not chrome.
3. Streaming arrival.
   The agent starts reasoning over the first result while the rest are still being produced. Time‑to‑first‑useful‑token drops, and long operations remain observable.
4. Selective consumption.
   The agent can jq -c 'select(.type=="hit")' the stream before ingesting it — only paying token cost for the event types it cares about.

Verification.

1. Terminal summary.ok=true is the only honest success signal.
   The agent stops trusting exit code 0 alone — which lies often enough to matter (buffered writes, partial completion, silent crashes). "The work finished" and "the process exited" become distinguishable.
2. EOF without summary is the crash signal.
   A consumer can detect a crashed tool even when its language runtime swallowed the exit code. Cross‑language. Cross‑platform.
3. Structured errors with category + retryable.
   The agent's retry policy is tool‑agnostic. category:"rate_limited" and retryable:true mean the same thing in every conforming tool. No per‑tool exception parsing, no scraping error messages for hints.
4. Audit records on every mutation.
   Each created / updated / deleted event carries a stable ID. The agent confirms the action took effect, hands the IDs to memory or downstream audit, never assumes.
5. doctor for pre‑flight readiness.
   Before doing real work, the agent asks the tool "are credentials valid, is the endpoint reachable, is config loaded?" and gets structured aoi:check events back. No destructive call to find out.

Safety the agent can steer.

1. Read‑only by default.
   The agent operating under uncertainty defaults to non‑destructive behavior. Mutation requires explicit intent.
2. --dry-run returns typed aoi:plan events.
   The agent (or its supervisor) can preview what an action would do, in machine‑readable form, before committing. The model reasons over a plan instead of trusting itself blindly.
3. --confirm and --confirm-count N.
   Bulk destructive operations refuse to run unless the agent passes the count it expected. A wrong invocation produces a refusal, not a disaster.
4. --idempotency-key.
   Safe retry of writes. The agent can re‑issue a failed create without doubling the effect — the tool recognizes the key and returns the prior result.
5. Secret redaction in meta.
   args_redacted:true confirms the tool didn't echo the agent's API key back into its own output stream. The agent doesn't have to scrub before logging.

Composition.

1. Three roles, one contract.
   Every conforming tool plays one of three pipeline roles — a source emits JSONL, a transformer reads JSONL and emits JSONL, a sink reads JSONL and performs side effects. The agent composes them through ordinary shell pipes; the envelope is the same across all three.
2. JSONL → JSONL by construction.
   No regex‑bridging column 3 of tool A's ASCII table to feed it to tool B. The interface holds across the chain. The same shell ecosystem that already handles structured streams (jq, tee, pipefail) works unchanged.
3. Pipefail‑safe chains.
   With set -o pipefail and a terminal‑summary check, the agent composes five tools and trusts the final exit + summary. Upstream failure short‑circuits the whole pipeline.
4. Domain vs control events differentiated.
   A downstream transformer or sink ignores upstream aoi:meta / aoi:summary (control) and consumes only hit / match (data) — automatically, without configuration.
5. Heartbeats distinguish quiet from dead.
   For long‑running operations, the agent's supervisor knows whether to keep waiting or to kill and retry. Liveness is part of the contract, not a TCP keepalive hack.

Planning & reasoning.

1. Capabilities manifest is queryable.
   The agent asks "which commands are destructive? bounded? support cursor / dry‑run / idempotency?" — and gets a typed answer. Reasoning happens at plan time, not at trial‑and‑error time.
2. Cost surface visible at plan time.
   Read‑only vs mutating, bounded vs unbounded, idempotent vs not — all declared, all inspectable before any call. The model picks the lowest‑risk path that satisfies the goal.
3. Hallucination‑resistant flags.
   The agent doesn't have to guess "does this tool support --recursive?" It asks capabilities and gets the truth. Wrong flags fail loudly with category:"usage", not silently with wrong behavior.
4. Reproducibility.
   Same args + same tool_version + same schema_version produce the same event shape. The agent can cache, replay, diff, and detect drift.

Operational control.

1. Structured cancellation.
   An aborted long operation produces a summary.ok=false, reason:"interrupted", partial:true event when possible. The agent that cancelled knows how much was done — not just that it stopped.
2. Universal pagination model.
   One --cursor pattern, every tool. The agent learns it once, applies it everywhere. No per‑tool pagination implementations to memorize.
3. Truncation is explicit.
   summary.truncated:true with summary.next_cursor tells the agent there's more — no parsing the last line for "..." or "and 47 more results."

Environment & auth.

1. Auth happens beneath the call.
   The agent invokes a tool and the user's existing credential ecosystem — keychain, AWS credential chain, kubeconfig, ssh agent, gpg keyring, Vault token, gh PAT, corporate SSO — is already wired. The agent doesn't manage OAuth flows or token refresh. This is huge. Auth deliberately out of scope ↗
2. Environment isolation per invocation.
   Each batch‑mode call is a clean process. The agent doesn't carry state leaks across operations. (In session mode, the agent gets the inverse benefit: persistent state across requests when it actually wants that.)

Every item above is a property an agent can rely on at plan time rather than discover at run time. That shift — from inference to contract — is what makes autonomous tool use tractable at all.

The corresponding work for tool authors is small. The conformance contract is § 18 of the AOI‑CLI specification — typically an afternoon of work to retrofit an existing CLI. See Adopt for working reference implementations in five languages.