Help text MUST be layered so agents (and humans) can drill from a short summary to concrete usage examples without reading the entire manual. The critical layer is the one that appears after the flags list, because that is where readers look for invocation patterns.
Why Agents Need It
Agents discover how to use a tool by calling --help and scanning the output. They skip past flag definitions (which describe what is possible) and hunt for examples (which describe what to do). A flags list alone is enough rope to produce a failed invocation; examples are what turn discovery into action. Without examples in the help output, an agent trial-and-errors its way into a working call, burning tokens and sometimes landing on a wrong-but-silent success.
Audited live by anc audit <tool> --principle 3: behavioral and source checks.
Requirements
The principle is framework-agnostic. clap's after_help is the worked example below; analogs include cobra's Example (Go), argparse's epilog (Python), docopt's usage block, and the Examples: convention in gh / kubectl.
Evidence
after_help (or after_long_help) attribute on the top-level parser struct.
after_help attribute on every subcommand variant that takes its own arguments or options.
Example invocations in after_help text that include realistic arguments, not placeholder <foo> tokens.
about (short) present on each subcommand, and after_help (examples) on each subcommand that takes its own arguments or options.
The command list's left column holds bare command tokens; the binary name appears in the Usage: line and in examples, not at the head of each command entry.
Anti-Patterns
Relying solely on /// doc comments: those populate about / long_about, not after_help, so no examples render after the flags list.
A single about string serving as both summary and usage documentation.
Examples buried in a README or man page but absent from --help output.
after_help text that describes the flags in prose instead of demonstrating them in code.
A hand-written command list that prefixes every entry with the binary name, so the command token sits second on each line and a scanner has to strip the prefix before it can read the command.
Measured by audit IDs p3-subcommand-examples, p3-help, p3-version, p3-paired-examples, p3-about-long-about, p3-unprefixed-command-list, p3-examples-subcommand. Run anc audit --principle 3 . against the CLI under test to see each.