install_os_on_volume

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

Beyond the destructiveHint annotation, the description discloses irreversibility ('overwriting whatever's on it entirely. Irreversible — requires confirm=true'), the asynchronous nature ('Asynchronous — poll get_volume_task_status'), and the prerequisite of detaching the volume. These are not conveyed by annotations alone and provide crucial safety information.

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 a compact set of five sentences, each adding distinct value: purpose, destructiveness, prerequisite, credential conditions, and async behavior. It is front-loaded with the core function and no 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?

For a tool with 5 parameters, no output schema, and no enums, the description covers the essential aspects: what it does, side effects, required preconditions, parameter conditions, and follow-up polling. An agent has enough information to call it safely and correctly.

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 compensates by explaining the conditional semantics of root_password and ssh_public_key (Windows vs. non-Windows), and confirm's role in the irreversible action. It does not explain the operating_system parameter, but that's covered by sibling tools like list_available_os_for_volume. Overall, it adds meaningful value beyond the bare names.

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 the specific verb and resource: 'Install a fresh OS onto this standalone volume,' and clarifies the overwriting behavior. It differentiates from sibling tools like reinstall_vps (for VPS) and list_available_os_for_volume (listing) by explicitly targeting standalone volumes.

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?

It provides clear prerequisites: the volume must be detached (detach_volume), and OS-specific credential requirements. It does not explicitly name alternative tools or say 'use this instead of X', but the context makes the intended use clear. Minor gap: no explicit when-not-to-use guidance, but overall it gives solid direction.

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