convert_vm_to_template

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

Beyond the annotations, the description discloses important behavioral effects: the VM becomes a template, cannot be powered on, and serves only as a clone source. It also states the return value is a status string. Since the annotations only indicate readOnly=false and destructive=false, the description adds meaningful state-change context without contradicting them.

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 three short sentences with no filler. It front-loads the operation verb and resource, then adds the most important consequence and downstream usage. Every sentence earns its place.

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 state-changing tool with two parameters and an output schema, the description covers the prerequisite, the effect, and the follow-up tool. It does not mention failure modes or whether the conversion is reversible, but these are secondary given the schema and output schema already provide structural coverage.

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 100%, so the input schema already documents vm_name and target fully. The description reinforces that the VM must be powered off but adds no new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the load.

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 uses a specific verb and resource: "Convert a powered-off VM to a vSphere template." It clearly differentiates from siblings by explaining the resulting role as a clone source for deploy_vm_from_template, leaving no ambiguity about what this tool accomplishes.

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 gives a clear use case: "freeze a golden image" and explains the consequence that the VM cannot be powered on afterward. It does not explicitly name alternatives or when-not-to-use conditions, but the downstream workflow with deploy_vm_from_template provides enough context for an agent to select it appropriately.

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