delete_disk

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly warns 'DESTRUCTIVE' and 'This permanently deletes the disk image,' and explains the preview behavior when confirm is false. This gives the agent critical information about irreversibility and execution requirements.

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 compact and well-structured. It front-loads the destructive nature, follows with the permanent effect and prerequisite, then provides an Args list that maps directly to the schema. Every sentence conveys essential information without fluff.

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 destructive deletion tool, the description covers all critical context: the destructive irreversible action, the requirement that the VM be stopped, and the confirmation mechanism. An output schema exists, so return values need not be described. This is complete for an agent to use the tool safely.

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%, so the description must compensate for the bare schema. It does so by listing all three parameters (vm_id, disk_id, confirm) and adding crucial semantics: confirm must be true to execute and otherwise returns a preview. The parameter names alone are fairly self-explanatory, but the confirm clarification adds real value 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 opens with 'DESTRUCTIVE: Remove and delete a disk from a virtual machine,' which clearly identifies the action taken on a specific resource. This differentiates it from sibling tools like delete_vm or delete_snapshot by naming the disk as the target.

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 states a key prerequisite: 'The VM must be stopped.' It also explains the confirm parameter's role, saying it 'Must be true to execute' and that otherwise it returns a preview. While it doesn't explicitly mention alternatives or when not to use this tool, the context is clear enough for an agent to decide.

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