Skip to main content
Ouro UI

Mid-morning in the meadow. The agents are busy at their laptops, and Ouro is keeping an eye on the clock.

One morning in the meadow: a woman works on her laptop in an armchair, two little robots type on laptops of their own at a picnic table, a tall garden clock keeps the time, and Ouro looks on.

Ouro AX

A morning with an agent

Ouro HX is for the screens people use. Ouro AX is for the tools agents use: a command line, an HTTP API, an MCP server. Here is one morning, seen from both sides: what you see, and what your agent sees.

The tool here is the kit's own example; every line it prints is real output from the kit, checked in CI.

Be the agentRead the guide

You: Tell Design sync I'm running late.

Your agent: Posted in Design sync on your word. Ana and Kim can see it.

Design syncYou Running late, start without meSent by your agent, on your word
notes post abc123 "Running late, start without me"notes: post: other people will see this as the person's, so it needs --why: who asked you, and what they said. Fix: notes post abc123 "Running late, start without me" --why "<who asked you, and what they said>".notes post abc123 "Running late, start without me" --why "Jo Park asked: tell Design sync I'm running late"Posted to "Design sync". Everyone in it can see it.Checked: read the room's last message back.Receipt: m1Next: notes watch abc123  (wait for a reply)

Your morning

Before your first meeting, you ask your agent for a few things. You see them twice: on your screen, then in your agent's terminal.

  1. 8:58: What can you do in Design sync?

    You: What can you do in Design sync?

    Your agent: Post there for you, where Ana and Kim will see it. Keep notes only you see. Tell you when someone answers.

    notes --helpnotes: a toy tool built from Ouro AX definitions.Only you see these  rooms   The rooms, with their short ids.  note    Add a private note to a room.  watch   Wait for the next message in a room, then print it.Other people see these  post    Post a message everyone in the room sees.Output: --json on every command. Exit codes: 0 ok, 1 error, 2 usage, 3 unavailable. Errors: one linethat says what to do instead.Details: notes help <command>notes rooms[abc123] Design sync

    The help sorts every command under two headings, what only the person sees and what other people see, so the agent knows which commands reach other people before it runs one.

  2. 9:03: Tell Design sync I'm running late.

    You: Tell Design sync I'm running late.

    Your agent: Posted in Design sync on your word. Ana and Kim can see it.

    Design syncYou Running late, start without meSent by your agent, on your word
    notes post abc123 "Running late, start without me"notes: post: other people will see this as the person's, so it needs --why: who asked you, and what they said. Fix: notes post abc123 "Running late, start without me" --why "<who asked you, and what they said>".notes post abc123 "Running late, start without me" --why "Jo Park asked: tell Design sync I'm running late"Posted to "Design sync". Everyone in it can see it.Checked: read the room's last message back.Receipt: m1Next: notes watch abc123  (wait for a reply)

    from 5 to 10of 10 runs

    The message goes in as an argument, not piped in. That is one of two rules we wrote from where agents in our runs went wrong, and together they took the same agent from 5 of 10 runs to 10 of 10. The refusal that names its fix already held before them, and agents recovered from it.

  3. 9:04: Nothing happens, which is the point.

    Nothing new, and nothing to check.

    Checked: read the room's last message back.Your agent moves on without reading the room back.

    from 2 to 0of 2 runs read the room again after Checked

    The tool read its own work back and said so: Checked. When the tool said it had checked its own work, agents in our runs stopped reading the conversation back to be sure, in 0 of 2 runs against 2 of 2 without it.

  4. 9:05: Tell me when someone answers.

    You: Tell me when someone answers.

    Your agent: Ana Ruiz answered in Design sync at 9:11: “Sounds good, we'll begin with the dates”

    Design syncAna Ruiz Sounds good, we'll begin with the dates
    notes watch abc123 --timeout 2mThe tool waits on the room: one call, not a loop.Happened: a message in "Design sync".2026-10-30T16:11:00.000Z Ana Ruiz: Sounds good, we'll begin with the dates

    from 1 to 2of 2 runs, in about half the calls (8 → 4.5 calls)

    Three of the four designs we tried each added a way to wait on the conversation the agent had just posted in. With it, “tell me when someone replies” went from 1 of 2 runs to 2 of 2, in about half the calls.

  5. 9:20: Actually, edit that.

    You: Actually, edit that: ask Ana about the dates.

    Your agent: Edit the message everyone in Design sync saw, or keep a note only you see?

    You: A note, just for me.

    Your note, only you see itask Ana about the dates
    notes edit abc123notes: edit: "edit" could mean 2 things, so it does nothing: a note only you see; or a message other people see. Fix: notes note abc123 <text> or notes post abc123 <text> --why <why>.notes note abc123 "ask Ana about the dates"Note added in "Design sync". Only you see it; nothing was sent.

    A word that could mean two things does nothing. It answers with both meanings, so the agent asks its person instead of guessing.

Your turn

Be the agent

This is the same tool, running in your browser, and now you're the agent: the person you work for asks, and you run the commands. Type one or press one. Then start a wait, and answer it from the room as someone else.

The person: Tell Design sync I'll be back soon.

Jo Park (the person you work for), Ana Ruiz, Kim Ito

  • Quiet so far.
The person you work for has asked. Type a command, or press one below.

$

Or press one:

The X-ray

Then we X-rayed a real one

The X-ray calls a tool the way an agent would, without reading its code, and checks it against Ouro AX's claims. The first tool to adopt Ouro AX is a real app's agent interface: a command line plus an HTTP API. Here it is before and after.

Before: its main branch

Does not conform yet

12 of 18

must claims holding · 363 checks pass, 117 fail · 1c72b11d

After: its adoption

Conforms

18 of 18

must claims holding · 768 checks pass, 3 fail · 2356170d

Every must claim held after adoption; before it, four failed and the X-ray skipped two, because the tool had not listed its surfaces for it. After, the 3 failing checks are all in should claims, which conforming doesn't require. Here is what changed, in plain words and then in the X-ray's own.

  • –✓cli.inventory

    It lists the commands it has

    Every command the CLI registers is listed once in help --json and in the inventory the adopter generates from its command registration, and the X-ray covers exactly that set.

    Before, the X-ray skipped it: the tool had not yet listed its surfaces for it.

  • ✗✓cli.unknown-flag

    Misspell a flag, get told

    An unknown flag fails before anything runs, and the error names the flag.

    Before, the X-ray found: app today --ax-xray-no-such-flag --json → exit 0; stdout: {: the flag was ignored

  • ✗✓cli.others-preview

    See who'll see it before it's sent

    Every command other people see has a preview that acts on nothing (--dry-run) and names who will see it.

    Before, the X-ray found: app send --help offers no --dry-run, so who will see it can only be learnt by doing it

  • ✗✓cli.wait-on-refs

    Wait on the chat you're already in

    A wait command accepts the refs the reads list: watch <ref> waits on the conversation a list gave.

    Before, the X-ray found: app watch c:00000000bbbb0000bbbb000000000002 --timeout 1s → exit 2; stderr: app: watch takes an object ref such as meeting:<ref>; bare "watch" streams every event

  • –✓http.inventory

    It lists the routes it has

    Every route the agent port registers is in the inventory the adopter generates from its router, once, and the X-ray's routes manifest covers exactly that set.

    Before, the X-ray skipped it: the tool had not yet listed its surfaces for it.

  • ✗✓http.wrong-ref-first

    Wrong id? It says where to find a right one

    A route given an id that does not exist fails and says where to get a right one.

    Before, the X-ray found: GET /api/conversations/axxraynoref → 404 {"error":"no such conversation"}

The 12 must claims that held before and after
  • ✓<cli> help --json prints one JSON document that names every command.
  • ✓Help says who sees each command: only the person, or other people.
  • ✓Exit codes are documented, and every exit code the CLI gives is one of them.
  • ✓Ambiguous verbs (edit, delete, remove) don't act; they answer with the specific commands.
  • ✓Every command other people see refuses to run without --why, and says so.
  • ✓A wrong reference fails before anything reaches anyone, and the error says where to get a right one.
  • ✓A command that takes free text accepts it as one argument, not only on stdin, and its help shows that form.
  • ✓Reads change nothing.
  • ✓A refused call changes nothing, except an audit record that says it was refused.
  • ✓Every route that does what other people see refuses a request without a why, and names the field.
  • ✓GET requests change nothing.
  • ✓A refused request changes nothing, except an audit record that says it was refused.

Both reports are in Ouro AX's evidence folder, with the measurements behind the figures on this page.

Build one

Make your tool obvious to agents

Ouro AX is a standard, a kit and an X-ray. Copy the kit in the way you copy Ouro HX components, define each command once, and run the X-ray in CI.

  • The kit

    One definition per command gives the parser, help, errors, JSON and an MCP tool.

  • The claims

    The standard: checkable rules, with the reasons and the evidence that earned them their place.

  • The X-ray

    Checks any command line, HTTP API or MCP server against the claims, from outside.

  • How we measure

    Real agents, fresh sessions, real tasks, scored from the end state.