vm_create_plan

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

Beyond the annotations, the description discloses that the tool validates actions, checks that targets exist in vSphere, and generates rollback information per step. It also states the important workflow guardrail that the plan must be shown for confirmation before applying. It does not detail plan persistence or lifecycle, but the annotations already cover the basic safety profile.

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 well-organized: purpose, usage condition, behavior, parameter format, allowed actions, and return contract are each presented clearly. It is longer than minimal, but the allowed action list is necessary because the schema does not provide enum constraints.

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 complex planning tool with no output schema, the description covers the full call contract: operation format, allowed actions, validation behavior, return structure, and the follow-up step with vm_apply_plan. The workflow implication that this tool does not execute the VM operations is clear from the explicit 'before calling vm_apply_plan' instruction.

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 100%, so the baseline is 3; the description adds real value by specifying that each operation is a dict with an 'action' key and enumerating all allowed action values. This compensates for the schema's generic items object and lack of enums. The target parameter is already adequately documented in 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 specific action and resource: 'Create an execution plan for multi-step VM operations.' It clearly distinguishes this from direct VM-operation siblings by framing it as the planning step, and it differentiates from vm_apply_plan by calling out the handoff workflow.

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 explicitly says 'Use for 2+ steps or 2+ VMs,' giving a concrete criterion for when this tool should be preferred. It also clarifies that the resulting plan should be shown to the user before vm_apply_plan is called, though it does not explicitly name the single-operation siblings as alternatives to use instead.

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