server_power

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

With no annotations, the description carries the full burden and does add real value: it warns that a preview is always shown first and that the SSH link will drop during execution, which prevents an agent from misreading a disconnection as failure. It does not state that the operation is destructive/irreversible, what permissions are required, or how the preview relates to the confirm flag.

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?

Three short, front-loaded sentences with no filler; the action semantics and the connection-drop warning both land early. The 'Always shows a preview first' sentence is terse to the point of ambiguity about whether a follow-up call is needed.

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 no explanation, and the description covers the key hazard (SSH drop) and the preview behavior. Still, for a destructive host-level mutation with zero annotations and zero schema coverage, it should clarify the preview/confirm workflow and the meaning of 'host'.

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 0%, so the description must compensate; it does clarify the required 'action' parameter by enumerating 'reboot or poweroff'. However, 'host' (empty default, presumably local) and 'confirm' are never explained, and the preview sentence does not explicitly tie to confirm, leaving two of three parameters 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 ('Reboot or power off the host') plus the allowed action values, which pins down exactly what the tool does at the host level. It does not explicitly name why it differs from siblings like docker_container_action or server_service, but 'host' scoping makes the distinction inferable.

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 tool's trigger conditions are only implied: use it when you need a host reboot or poweroff, with the action values enumerated. There is no guidance on when not to use it, whether a container/service restart would be a safer alternative, or prerequisites such as confirm.

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