sutram Discovery: help, man, status
An agent that cannot find out what a page offers falls back to screenshots and guessing. In Sutram, discovery is part of the contract, and all of it is generated from your command definitions, so it always matches the page.
| Question | Ask | Answer |
|---|---|---|
| What can I do here? | help, help <provider> | One line per command: usage, description, annotation |
| How does this one work? | man <command>, <command> -h | Arguments, output, annotations, examples, related commands |
| What state is the page in? | status | Every provider's <provider> status, at once; status form page for only some |
| What values fit here? | Tab, a command's suggest | Completions for names, options and values |
› help cart
cart add <sku> [qty] Add a product to the cart
cart status Show what is in the cart [read-only]Cheap first, details on demand
help costs one line per command. man is read only for the command the agent is about to use. --json=a,b returns only the fields asked for. This is why discovering a page through help costs about a third of the full tool list on the Drupal demo (see Measurements).
Agents without the console
- Through WebMCP or
Sutram.tools(), an agent gets every command as a tool with its schema, plussutram_status. Start withsutram_status. agentPrompt()sends an agent to the console and tells it to start withhelpandstatus.
Look again when things change
Commands come and go with the page's state. A command that runs and changes what is possible should say so in its result ("The form now also asks for: invoice, amount"). Agents are told to look again when they expect something new. The help output, the tool list and completion follow the registry without any work from you.
The integration ladder
How well a part of the page works with agents depends on how far up this ladder it goes. Each step is useful on its own.
| Level | The provider… | People and agents get |
|---|---|---|
| 1 · Status | answers <provider> status with its current state | Agents can read the page without screenshots |
| 2 · Writable | gets and sets values through its own logic, so the UI stays in sync | Agents can fill it reliably |
| 3 · Commands | adds its own actions, with annotations | cart add, editor clear |
| 4 · Suggests | offers values for its arguments | Completion for people, real choices for agents |