What It Means to Make a Product Agent-Readable

For decades "machine-readable" meant parseable by code: JSON over HTTP, a stable schema, a documented endpoint. That bar covered one consumer. Software now has a second one. Coding agents, background workers, and chat-style operators drive the same products a person drives, and they have different costs, different failure modes, and a different sense of what a doc is for. The property that lets those consumers operate a system safely is starting to need its own name. "Agent-readable" is a good candidate.

The shortest definition: an agent can read the product, predict what a command will do, verify that the command did it, and recover when it didn't, without a human hand-holding it through the gap. The longer definition has parts, and the parts are the work.

Machines parse. Agents operate.

A REST API with a JSON schema is machine-readable in the original sense. An LLM can paste a curl command into a context window and the schema parser will not flinch. Neither fact tells you whether an agent should drive that endpoint. Parsing is syntax. Operating is judgment under cost, and judgment needs more than a schema.

Three differences separate the two.

Output shape. A human reads a progress bar and infers "this is working". An agent needs the same command to print structured output it can parse: a known shape for results and a known shape for errors. CLIs that grew up human-only are accumulating a --json flag for exactly this reason, the way database engines grew an EXPLAIN and infrastructure tools grew a plan phase.

Error contract. A human sees "permission denied" and tries something else. An agent needs the failure to carry enough structure to decide between retrying, escalating, and abandoning. Exit codes are the floor. Named failure classes are better: not_logged_in, project_not_selected, and quota_exceeded branch cleanly, while "something went wrong" branches nowhere.

Cost. A human skims past a long doc. An agent pays tokens for every paragraph it reads, and a context window is a budget. Some teams now state a doc's price in its first lines, the way one CLI's routing guide opens by estimating its own token cost and telling the agent when to skip it. A doc that doesn't say when to skip it is billing the agent for content it doesn't need.

API-first gets close and stops short. API-first is about design order: build the API, then build the UI on top. Agent-readable is about whether an agent can finish a real task on that API without breaking things.

Readability covers the whole interaction

Vendors put "AI-ready" on a data product to mean the schema is clean. That is one slice. The agent's experience has four moments: what it sees before the call, what it sees during, what it sees after, and what it can use to recover. Five surfaces decide how those moments go, each with a concrete test.

Discovery. Can the agent find what to call without reading source? Help built to be parsed, a machine-readable command catalog, a routing guide whose first decision maps a situation to the right action. The right help costs less than the wrong help.

Confirmation. Can the agent see the mutation before it happens? A dry-run mode that prints the exact request, and a separate, explicit go signal that fires only after a human approves. Plan and apply is the pattern; the preview is the verifiable half of the write.

Discipline. Can the agent trust that an unknown flag gets rejected instead of warned and ignored? Warn-and-ignore belongs to humans at a terminal, where eyes catch the warning. In scripted mode a typo should fail loudly, because a silently ignored flag turns one intended command into a different real one.

Re-verification. Can the agent tell the mutation landed? Re-reading state after every write, as a rule rather than a habit. And when a write is staged until a second command completes it, the docs must say so plainly, or the agent will report a change as live while the system still serves the old state.

Write semantics. Can the agent predict whether a write patches or replaces? A partial record pushed over a whole-record replacement zeroes every field left out. A product aimed at agents either merges writes itself or documents the replacement behavior where the agent will read it, field-name mismatches included.

Pass all five and the product is close to agent-readable. Pass one or two and you have what the market calls "AI-ready".

Verification is a surface you ship

The part of a product agents consume most heavily is the verification surface: the commands and methods that read state, dry-run a change, or diff before and after. Ship a feature with no way to verify it shipped and the agent is guessing with your name on the action.

Mature codebases already treat verification as a feature. Contract tests that check every CLI route against the service that implements it. Documentation mirrors regenerated by the build, with a test that fails when the mirrors drift from the source. Provenance stamped on vendored dependencies so a reinstall cannot quietly change behavior. Each one converts a class of drift from "found during an incident" to "caught by a test".

Verification designed in looks different from verification bolted on. One Blocks CLI, for instance, keeps a verify:endpoints script that checks every CLI route and verb against the checked-out service controllers; it exists because a stale API base and a wrong HTTP verb once shipped that way, and the script is why neither could recur silently.

Documentation is part of the contract

A README is for evaluation: what is this, should I depend on it, how do I install it. An agent needs operational content instead: which commands verify a change, which paths are forbidden, which mistakes were already made once. The convention that has emerged splits the two audiences into separate files. Thousands of repositories now carry an AGENTS.md alongside the README, and the pattern is spreading because it works.

The format forces the second kind of doc to behave like code. A rule reads as a post-mortem with its fix attached: run this script after touching that surface, and the same sentence says why, because the last team that skipped it shipped a stale endpoint. A rule with no reason attached reads as a suggestion, and agents treat suggestions as optional.

The other half is publishing. Byte-exact text mirrors of guides, and an llms.txt index pointing at them, let a developer paste a whole document into a context window without a renderer mangling it. Build the mirrors as artifacts and test them, and a docs change that skipped the build never reaches the site.

The detail that closes the loop is routing. When two capabilities sit close together, say editing your own profile versus editing another user's roles, an agent will confuse them. A description that names the neighbor it borders catches the misroute at lookup time instead of at damage time.

Identity is where the cost hides

Most readability work shows up in the developer experience. The expensive part is the auth model.

A long-lived API key taped to a config file works for a service. Hand the same key to an agent and it inherits every permission the key carries: no way to scope it to one task, no way to expire it for one task, no audit trail that says which agent used which permission at which moment.

The pattern that fits machine-driven work is delegation. The agent redeems a short-lived grant for a short-lived token through the identity provider's token endpoint, as a standard token exchange (RFC 8693 describes the flow). Renewal means redeeming the grant again. Permissions are resolved at mint time, so anything revoked after the grant was written never reaches the token. Validation runs in a fixed order and stops early, so a malformed request costs a signature check, not a database read.

That is the shape agent identity needs: short-lived, revocable, cheap to audit. Teams that issue static service tokens to make agents happy will pay for it at the first audit. Teams that scope agent identity through the same auth surface as user identity get the audit trail for free.

What skipping it costs

Every undocumented knob is a place an agent will guess. A guessed flag on a warned-and-ignored parser becomes a silently different command. A hand-rolled request around the supported API becomes state drift, and unwinding drift costs an afternoon that a rejected flag would have cost a second.

The remedy is rarely more documentation. The fix is usually a smaller surface (delete the knobs nobody needs), a stricter one (reject what you don't understand), or a verifiable one (ship the check that catches what the agent is about to break). Teams that went through this cycle have landed on the same conclusion from both directions: document the surfaces you keep, and keep only the surfaces you can document.

One product built this way

Blocks, SELISE's platform, is a working example of most of the above, which is why its CLI reads the way it does. Every command carries a JSON output mode, and a machine-readable command catalog lists each command's arguments, scope, and whether it mutates. Failures carry names such as not_logged_in and project_not_selected. Every mutating command runs as a dry-run first and fires only after an explicit go signal, and a standing rule requires reads to confirm writes after the fact. Save and update commands merge changes over the current record, because the platform's own endpoints replace whole records and a missing flag should not zero a field. Its identity service handles machine access through the delegated, short-lived token pattern described above, through the same token endpoint users already use.

The point of the example is the shape, not the brand. Any product can adopt the same surfaces: structured output, named failures, a verifiable preview, a read-back rule, and delegated identity.

The test

A product is agent-readable if a coding agent can do five things on it without help.

1. Discover the right command or method without reading source.

2. Predict the mutation before it happens and verify it after.

3. Fail loudly when a flag, path, or input is wrong, with a structured error that says which.

4. Re-read state to confirm the change, or learn from a system test that the change did not land.

5. Recover by reaching a verifiable surface, not by retrying the same guess.

Fail any of those and the fix is rarely more docs. The fix is a smaller surface, a stricter one, or a verifiable one.

The cost of agent-readability is paid up front: smaller surface, stricter contracts, byte-exact mirrors, a dry-run on every mutator. The benefit compounds with every agent that runs the workflow after the first one. The two are not symmetric, and that asymmetry is the case for doing it now.

Blocks CLI passes that test today: its discoverable catalog, plan-then-apply flow, named failure classes, read-back rule, and delegated token exchange cover all five checks against the live services. You can run the test yourself on any machine with Node.js 20 or newer:

npm install -g @seliseblocks/cli-os@latest
blocks --help              # discovery: the full command catalog, no source reading
blocks login               # delegated identity through the IdP token exchange
blocks auth status --json  # structured state an agent can parse
blocks doctor --json       # one named call that diagnoses the whole       environment

Then pick any mutating command and pass --dry-run first. The CLI prints the exact request it would send, fires nothing until you pass --yes, and the docs' standing rule is to re-read state afterwards to confirm the write landed.