pve_trigger_backup

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

No annotations are supplied, so the description carries the full behavioral burden. It states the operation writes a backup but never says whether the call blocks until completion or returns an async task, whether existing backups on the target are overwritten or pruned, or what permissions/storage content-type requirements apply. Only the downtime implications of the mode values are disclosed.

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 summary sentence is front-loaded and followed by a compact per-argument list, which is easy to scan. The 'Args:' formatting is slightly verbose for an agent but every line carries 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?

An output schema exists, so return values need not be explained, and the parameters are well covered. Still, for an unannotated mutation tool with real side effects on storage, the absence of any note on async behavior, retention/overwrite of prior backups, or target-storage prerequisites leaves meaningful gaps.

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 is doing all the work and it does most of it well: it defines vmid, storage (with concrete examples), mode (with the three valid values and their operational meaning), compression (valid algorithms), and marks node as optional. What it omits is the stated defaults (mode=snapshot, storage=local, compression=zstd), which live only in the 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 first sentence gives a specific verb ('Execute'), resource ('vzdump backup'), and scope ('of a VM or container to a target storage pool'), and the word 'immediate' separates it from a scheduled-backup concept. It does not explicitly distinguish itself from sibling tools like pve_create_snapshot or pve_list_backups, so it falls short of full sibling differentiation.

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?

Usage is implied by the mode descriptions ('snapshot' live, zero downtime vs 'suspend'/'stop'), which hints at when to pick each. However, there is no explicit statement of when to use this tool instead of pve_create_snapshot or pve_list_backups, and no prerequisites or exclusions are given.

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