AI agent discoverability: reduce trial-and-error for CLI syntax

Problem

AI agents (e.g. Claude Code) repeatedly fail to remember swamp CLI syntax across sessions and waste time stepping through --help output for every command. Common mistakes include:

• --arg instead of --input for model method run
• model run <name> <method> instead of model method run <name> <method>
• Guessing subcommand structure (extension describe instead of extension pull/extension search)

Each session, the agent has to re-discover the correct syntax through trial-and-error, which adds latency and noise to every interaction.

Possible Solutions

1. swamp help --agent or swamp schema — Emit a structured JSON summary of all commands, subcommands, and their arguments in a single call. Agents could fetch this once per session and cache it in context, eliminating repeated --help calls.

2. MCP tool server — Expose swamp operations as MCP tools (e.g. swamp mcp serve). This would let agents discover available operations through the standard MCP tool listing protocol, with typed argument schemas, instead of parsing CLI help text.

3. Command suggestion in error output — The CLI already does "Did you mean ...?" for unknown subcommands. Extending this to flag-level suggestions (e.g. Unknown option "--arg". Did you mean "--input"?) would help agents self-correct faster. (Note: flag-level suggestions may already be partially implemented.)

Alternatives Considered

• Saving CLI syntax in agent memory files: Works but is fragile — memory drifts as the CLI evolves, and every user's agent has to independently learn the same syntax.
• Wrapper scripts: Adds maintenance burden and doesn't scale across the full CLI surface.

Additional Context

This was observed during a session where the agent tried --arg, then model run, then --help on three different subcommands before arriving at the correct swamp model method run <name> <method> --input key=value invocation. The full discovery took 4 tool calls that could have been 1.