pve_lifecycle

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

No annotations are provided, so the description carries the full behavioral burden, and it falls short: it does not say that 'stop' and 'reset' are forceful operations with data-loss risk, that 'shutdown' is graceful, what happens if the target is already in the requested state, or what permissions are required. Only the node auto-discovery behavior is 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?

Short, front-loaded, and well-structured as a docstring: the summary sentence comes first, then a compact parameter list. Every line carries information; the only waste is the 'Args:' boilerplate style, which is harmless.

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?

Output schema exists so return values need no explanation, and parameters are covered. But this is an unannotated mutation tool that can force-stop or reset guests, and the description says nothing about preconditions, destructive consequences, or error conditions — the elements an agent most needs before invoking it.

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?

With 0% schema description coverage, the description must compensate, and it largely does: it defines each parameter's meaning, enumerates the seven valid action strings (which the schema lists with no enum constraint), and explains that 'node' is optional with automatic discovery. It stops short of giving format hints for node names or noting whether vmid must exist.

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?

"Perform a lifecycle state transition on a VM or container" names a specific verb and resource, and the enumerated actions make the scope concrete. It is clearly distinct from siblings like pve_edit_system (configuration) or pve_destroy_system (deletion), though it never states that distinction explicitly.

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 action list implies the tool's use — power/state management — but there is no guidance on when to choose this over siblings, and no side-by-side discrimination between overlapping actions such as 'stop' vs 'shutdown' vs 'reset', which matters a great deal for an agent. Usage is inferable but not stated.

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