list_base_vm_snapshots

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

No annotations are provided, so the description carries the behavioral burden. It does clarify that the returned snapshots are those usable as an image for instant clones, and 'List' implies a read-only operation. However, it does not disclose whether snapshots are filtered, ordered, paginated, or whether any prerequisites beyond vcenter_id and base_vm_id apply.

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?

Two sentences, zero filler. The first sentence defines the tool, the second states the downstream value. The most important scoping information ('instant clone pool or farm') is front-loaded.

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 simple two-parameter list call with an output schema, the description is nearly complete: it provides identity, purpose, and downstream consumers. The only minor gap is an explicit statement about what the snapshots do or do not include, but the existing sentences plus schema are sufficient for correct invocation.

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 100% description coverage — both base_vm_id and vcenter_id have clear provenance descriptions ('obtain from list_base_vms' / 'obtain from list_virtual_centers'). The tool description adds no parameter-level meaning beyond the schema, so it hits the baseline exactly.

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 exact action and resource: 'List snapshots of a base VM' — not base VMs, not templates, but snapshots. It also explains the downstream purpose ('can be used as the image for an instant clone pool or farm'), which clearly distinguishes this from sibling tools like list_base_vms.

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 second sentence is explicit usage guidance: the snapshot_id returned is required by create_desktop_pool and create_rdsh_farm provisioning_settings when source is INSTANT_CLONE. This tells an agent exactly when this tool is needed, tying it to a concrete downstream workflow.

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