list_backups

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

With no annotations, the description carries the full burden and adds useful behavior: it reads the same /file menu that create_backup's duplicate-name check uses, returns empty list rather than an error when no backups exist, and returns name, size, and creation-time. It still does not describe permission or authentication requirements.

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 compact paragraphs, front-loaded with the tool's purpose and return shape, followed by the usage context and edge-case behavior. Every sentence contributes specific information.

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 simple list tool with an output schema and no annotations, the description covers purpose, usage context, return behavior, and the empty-list edge case. The remaining gap is the undocumented device_name parameter, but the tool is otherwise sufficiently described.

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% and the single required parameter is device_name, but the description never mentions the parameter, its expected format, or how it maps to 'the device'. Because coverage is low, the description must compensate and it does not.

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?

States a specific verb and resource ('List backup files stored on the device'), specifies the hidden path filter ('/file', names ending in '.backup'), and names the returned fields. The mention of create_backup is contextual, not tautological.

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?

Explicitly says to call it after create_backup to confirm a new backup landed and see its real size, giving a clear usage context. However, it does not name alternatives or state when not to use this tool, so it falls short of the top-level when/when-not/alternatives standard.

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