List available undos

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

The annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the description does not need to repeat the safety profile. The description does add the trait that snapshots are 'automatically-captured' and 'recent', which explains the expected contents. It does not disclose whether listing is paginated or whether entries are deduplicated, but for a simple list tool this is an adequate level of addition above the annotations.

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?

Two short sentences: the first plainly states the purpose, the second links to the companion undo tool. There is no filler, and the most important action verb 'List' comes first. Every word contributes to an agent's decision about whether to call this tool.

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?

This is a read-only listing tool with a single parameter and no output schema, so the description does not need to explain return values in detail. It correctly notes the snapshots are the undoable kinds, which is exactly what an agent needs to decide between listing, inspecting, or undoing. It would be slightly stronger if it mentioned that the list may be large or that entries can be inspected individually via nuvio_inspect_snapshot, but the current text is sufficient for routine use.

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?

Schema description coverage is 0%, so the description carries some burden, but there is only one parameter (limit) whose type, default, and min/max are fully declared in the schema. The word 'recent' in the description implies ordering by recency, which meaningfully complements the limit parameter. The description therefore adds enough value beyond schema for the parameter's purpose, though it could have mentioned 'limit' explicitly.

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 starts with a specific verb and resource: 'List recent automatically-captured snapshots.' It immediately distinguishes itself from sibling tools by noting that each snapshot can be reverted with nuvio_undo, separating it from nuvio_inspect_snapshot. This makes the tool's purpose unambiguous.

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?

The description explicitly routes the user to nuvio_undo when they want to revert, which is the key alternative action for the listed snapshots. It does not provide explicit 'when not to use' guidance, but the sibling context (nuvio_inspect_snapshot could inspect a single snapshot) is implied clearly enough given that this tool is the list counterpart.

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