Agent-First Data v0.7: Help Output Should Be Complete

Agents read --help differently from humans.

A human can run a command, notice a subcommand, run tool sub --help, notice another subcommand, and keep exploring. An agent can do that too, but it turns a basic interface lookup into a crawl. It burns tool calls and still risks missing a branch.

Agent-First Data v0.7 made the recommendation explicit: help output should be complete enough for an agent to understand the CLI in one read.

The problem: nested help makes agents discover by trial and error

Many CLIs only show top-level commands:

Commands:
  users
  projects
  jobs

The flags that matter may live under jobs run, jobs cancel, or jobs logs. An agent now has to recursively ask every subcommand for help before it knows how to call the tool.

That is not just inefficient. It creates bad behavior: the agent guesses flags, gets an error, reads another help page, and tries again.

The rule: one help call should reveal the command tree

AFDATA’s CLI guidance became:

• tool --help should include all subcommands and their flags.
• tool sub --help should include that subcommand and descendants.
• tool --help-markdown should generate documentation from the same command definition.

This keeps the interface discoverable without requiring the agent to crawl.

The Rust helper: render clap as agent-readable help

The v0.7 work added optional Rust helpers for clap-based tools:

let help = agent_first_data::cli_render_help(&cmd, &subcommand_path);
let md = agent_first_data::cli_render_help_markdown(&cmd, &subcommand_path);

cli_render_help walks the command tree and produces recursive plain-text help. cli_render_help_markdown uses the same command definition to generate docs.

The important property is single source of truth. The flags the binary accepts and the flags the documentation shows come from the same CLI definition.

The agent benefit: fewer guesses before execution

Complete help is a safety feature. Before an agent runs a command with side effects, it should know:

• which subcommands exist
• which flags are required
• which values are enumerations
• which fields are secrets by name
• which timeout, size, or currency units the CLI expects

AFDATA naming helps with the last two. Complete help helps with the first three. Together, they reduce guessing.

Where this fits: generated docs and local skills

The markdown helper also made docs generation less hand-written. A project can render CLI docs from the binary and put those docs into a site, README, or local agent skill.

For agent-first tools, --help is not an afterthought. It is part of the API.