Write descriptions agents can use

Agents do not read your docs site. They read help, man and the tool list, and all three are generated from your command definitions. So the description, the schemas and the examples are the documentation that matters most.

Names #

• Start with the provider, then a verb: cart add, nav go, form set.
• Use the same verbs everywhere: status, list, find, get, set, add, remove, save, discard.
• Lowercase words, single spaces. Hyphens are fine inside a word.

The description #

One line, what the command does, from the caller's side:

Say what happens that the caller cannot see: that nothing is saved yet, that the page reloads, that new fields can appear.

Input properties #

• Give every property a type.
• Add a description when the name does not say enough: where the value comes from ("Product code, from shop list"), what format it takes, what a yes/no field accepts.
• Prefer enum for a closed list. It checks input, completes with Tab, and tells agents the choices.
• Set default when there is a sensible one, and minimum/maximum when there are limits.
• For dynamic choices, add suggest.

Output #

Add an output schema. Agents see "Returns { count, total }" in the tool description and know what to read. Give properties a title when the column heading should differ from the key.

Examples #

Add examples for any command with more than one argument, or with a value that needs quoting. Write them as command lines: man shows them, and agents copy their shape.

examples: ["cart add V60-02", "cart add GUJI-250 2", "cart add SCALE --qty=1"],

Annotations #

They are part of the description too. A missing readOnly: true makes a harmless command look risky; a missing consequential: true lets an agent place an order without asking. Decide each one on purpose.

Check your work #

› help <provider>
› man <command>

Then read Sutram.tools() as if you had never seen the app. If you would not know what to call, neither will an agent.

This page as MarkdownEdit on GitHub