Node Power Control

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

Annotations already declare destructiveHint=true, which covers the mutating nature of shutdown/reboot. The description adds the important detail that all actions require elevated privileges ('all elevated'), which is not in the annotations. However, it does not disclose other behavioral aspects like whether wakeonlan requires the node to be off, whether actions are synchronous, or if there are side effects on running guests. Since annotations cover the destructive nature, the added elevation note is useful but minimal.

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 description is very short and front-loaded with the core purpose. It uses minimal punctuation and packs the action list and elevation note into a terse phrase. It contains no fluff or filler. While not perfectly structured (it's a fragment, not a full sentence), it is efficient and easy to parse.

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?

Given the tool has no output schema, the description should hint at what the operation returns (e.g., task ID, success status) but does not. It also fails to clarify that this is for physical nodes (not VMs) compared to many guest power siblings, and it doesn't explain prerequisites like wakeonlan requiring the node to be powered off or network configuration. For a tool with a large sibling set and no output schema, the description is incomplete and could mislead an agent on usage.

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 50%: the 'node' parameter is described as 'Node name', but 'action' has only an enum without a description. The tool description repeats the action enum values in parentheses ('shutdown|reboot|wakeonlan'), which does not add semantic meaning beyond the enum itself. It does not compensate for the missing action description or clarify any nuances (e.g., whether wakeonlan only applies to bare-metal nodes). Thus it adds little beyond 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 description states a clear verb ('control') and resource ('node power'), and enumerates the specific actions (shutdown, reboot, wakeonlan). It is distinct from guest-level power tools by the explicit 'node' qualifier, though it doesn't explicitly contrast with proxmox_guest_reboot etc. This makes the purpose clear enough for an agent to differentiate from the majority of siblings.

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 implicitly indicates this tool is for physical node power operations, but it provides no explicit guidance on when to use it versus the many guest power tools (proxmox_guest_reboot, proxmox_guest_shutdown) or other node tools. It doesn't mention alternatives or exclusions, leaving the agent to infer based on the name. The context is clear enough that an agent could guess, but it lacks direct routing.

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