ergonomics
Ergonomics
Judge a tool surface from the position of its most literal consumer, an AI agent: a CLI, HTTP API, MCP or agent tool, SDK or library, or a proposed design for one. A human developer is the second consumer and is usually served by the same fixes. Neighbours: threats are Security; help text and READMEs are Doc; lasting proof is Test; applying fixes is Implement; acceptance is Validate.
The literal reader
An agent sees only text, exit codes and structured output. It has no screen, no colour cue and often no terminal or open stdin. It copies the printed next step and runs it as written. It cannot ask what a message meant. When something fails it retries, and a retry after a mutation that may already have happened is where a vague error costs the most. Read every help page, output and error as that reader would, and ask what it does next.