Everyone is talking about making tools “agent-friendly.” Most of the advice — use flags, do not be interactive, return structured output — is just good CLI design. It applies equally to humans scripting in CI.
After building mtor, a Temporal-based coding task dispatcher that is consumed almost exclusively by AI agents, I found exactly four principles that are genuinely agent-specific. Everything else is table stakes.
The first is a structured output contract. Every response is a JSON envelope with a stable shape: ok, result, error, fix, next_actions, version. Not text, not tables, not pretty-printed summaries. The envelope shape is the API, and it is versioned. The agent parses one schema for every command, not a different text format per subcommand. Human CLIs can get away with tabular output because humans read flexibly. Agents cannot.
The second is next_actions, and it is the one that matters most. Every response includes exact, runnable commands for what the agent should do next. The agent never constructs commands from memory. It follows suggestions. This eliminates the entire class of “agent does not know the right flags” failures. The CLI is the expert on its own interface — let it drive. I have not seen a formal standard for this pattern, but Anthropic’s tool design guidance describes exactly this: outputs that steer agents towards more token-efficient tool-use behaviours.
The third is actionable errors. A bad error says “connection refused” with a code. A good error says “cannot connect to Temporal at ganglion:7233 ” and includes a fix field — the exact command to start the worker — plus next_actions pointing to the health check. The agent does not need to understand Temporal infrastructure. It runs the fix command and retries. Anthropic’s guidance is emphatic on this: helpful errors include specific and actionable improvements, rather than opaque error codes.
The fourth is self-description in one call. Bare invocation returns the command tree as JSON. The agent discovers all capabilities without reading docs, READMEs, or man pages. For deeper discovery, a schema command emits full JSON schema of every command’s parameters. The agent goes from zero knowledge to correct invocation in two calls.
Everything else is just good CLI practice. Flags for optional modifiers, positional arguments for the primary input — clig.dev has been saying this for years. Non-interactive execution, progress to stderr, semantic exit codes, token-efficient responses. These help agents, but they help bash scripts and CI pipelines equally. They are not the differentiator.
The real test: if you took away all documentation, could an agent use your CLI effectively by just calling it and reading its responses? If yes, it is agent-facing. If no, it is a human CLI with JSON output bolted on. The next_actions pattern is what makes the difference. Everything else follows from it.