list_templates

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description carries the full burden. It discloses that the tool requires a Proof account and returns templates organized by channel and message type, but it does not state whether this operation has side effects, pagination limits, or any other behavioral details beyond the listing itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: the main action and output shape come first, followed by a clearly labeled access note. Every sentence adds useful information and there is no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema listing tool, the description covers the essential context: what is listed, the account scope, how results are organized, and the required setup to authenticate. The tool is simple enough that no additional information is necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema coverage is 100%, so there is nothing meaningful to add about parameters. The description's mention of result organization provides context, but parameter semantics are inherently fully covered by the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all custom message templates for the authenticated account, and specifies the result organization by channel and message type. This distinguishes it from related tools like get_default_templates, get_template, and list_profile_templates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides concrete access prerequisites: a Proof account, setting PROOF_API_KEY, restarting the server, and calling again. It also explicitly notes that start_login does not open this tool, preventing a common misuse. It does not explicitly compare to alternative template listing tools, but the 'custom' vs 'default' distinction is implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.