Backup audit

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

Annotations already establish readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description goes beyond them by explaining data provenance (queries every backup storage including Proxmox Backup Server directly, so results reflect actual volumes rather than scheduled intent) and by disclosing a real coverage limitation in the task-derived failures. It does not mention cost/latency of scanning all storages, which is the one behavioral trait an agent might still want.

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?

Front-loaded: the first sentence states exactly what is found, before any caveats. The remaining sentences each contribute a distinct fact (data provenance, parameter tuning rule, task-history limitation) with no restatement of the title or name.

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?

With an output schema present, return-shape details are correctly omitted, and the description covers provenance, the key limitation, and parameter intent. The only gap for a cluster-wide audit tool is any hint about scale/latency when many nodes and storages are scanned.

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 coverage is 100%, so baseline is a 3. The description adds genuine meaning beyond the schema's terse 'Backups older than this are stale' by telling the agent how to derive a value from its own backup schedule. The `node` parameter is left entirely to the schema, keeping it at 4 rather than 5.

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 first sentence names the specific verb+resource (audit of backups) and enumerates the three distinct findings it reports: missing/stale backups, unscheduled guests, and failed jobs. The second sentence adds a differentiating scope claim ('reads backup volumes directly from every backup storage ... not what the schedule promises') that separates it from schedule-based or task-list-based siblings like recent_task_failures.

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 gives concrete usage guidance for tuning max_age_hours ('~170 for weekly backups') and discloses a boundary condition: failed tasks come from the recent task list, so only recent history is covered. What's missing is explicit routing to alternatives (e.g. when to prefer recent_task_failures or storage_health), but the context for when this tool is the right call is clear.

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