vsphere_create_snapshot

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

The annotations only indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description goes far beyond this by warning that snapshots are not backups, that they grow and degrade performance, and by explaining the effects of include_memory and quiesce. It also provides permission requirements and task-related behavior via the 'wait' parameter. This adds substantial behavioral context not available in the annotations.

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 structured effectively: a one-sentence purpose, a crucial caveat, a permission note, and a clear list of parameters. Every sentence delivers valuable information without redundancy. The length is justified given the seven parameters and the need to explain caveats.

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?

Given the complexity of seven parameters, no enums, and an existing output schema, the description covers all necessary aspects for an agent to correctly select and invoke the tool. It includes lifecycle warnings, permission requirements, and parameter semantics. The output schema handles return values, so the description need not repeat that information.

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?

The input schema has 0% description coverage, leaving all meaning to be supplied by the description. The Args section does this thoroughly: it explains the accepted formats for 'vm', the purpose of 'name', the optionality of 'description', the implications of 'include_memory' and 'quiesce', and the behavior of 'wait' and 'timeout_seconds'. This fully compensates for the lack of schema descriptions.

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 begins with a clear, specific statement: 'Take a snapshot of a virtual machine.' This uses a specific action verb and resource, and it is clearly distinguishable from sibling tools such as vsphere_list_snapshots, vsphere_revert_to_snapshot, and vsphere_delete_snapshot, which handle different operations on snapshots.

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 provides important usage context: snapshots are not backups, they grow with writes, degrade performance if left in place, and should be deleted after use. It also states the required permission level ('write or higher'). However, it does not explicitly mention alternative tools or when-not-to-use cases, so it stops short of a 5.

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