pikvm_power

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

No annotations exist, so the description carries the full burden, and it does disclose the destructive semantics of each action (soft short press vs. hard power cut vs. reset) and the safety gate required before executing them. It omits operational details such as permission requirements, what happens if confirmation is wrong or stale, and whether any action is idempotent.

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 with the core purpose, then a compact action list and the confirmation rule. The action enumeration is long but each item carries distinct semantic information, and no sentence is filler.

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-value explanation is unnecessary, but the definition still leaves gaps for a tool with four undocumented parameters and no annotations: the 'server' parameter, the default action of 'status', and the mechanics of obtaining a valid confirm_phrase are all unstated.

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 all four parameters are undocumented in the schema, yet the description only covers 'action' (enumerating values and defaults implicitly) and the confirm/confirm_phrase pairing. The 'server' parameter is never mentioned at all, so a meaningful portion of the surface remains undocumented.

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: power control of the target machine via ATX, with an enumerated action list that makes the operation concrete. It is clearly a power-management tool rather than an info/status tool, though the overlap between 'action: status' and the sibling pikvm_status is never addressed.

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 warns that every action except status and on can shut down or restart the machine, and states that those need confirm=true plus a confirm_phrase taken from the reply – effectively describing a two-step confirmation protocol. It does not say when to prefer this over pikvm_status for plain status reads, and the source of the confirm_phrase ('the path shown in the reply') is only implied.

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