list_vm_snapshots

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

Annotations already mark readOnly/idempotent/non-destructive, and the description adds meaningful behavioral detail: the served CRD version is discovered at runtime, the return envelope includes specific fields, truncated is always false because it walks to completion, and old Supervisors produce errors naming the required version. This goes well beyond the annotations and conditions the agent to expect a specific response shape.

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 front-loaded with the core purpose, then efficiently packs only relevant operational details: CRD discovery, return envelope fields, completion behavior, error semantics, and prerequisites. No filler or redundant restatement of the schema is present. Every clause contributes to safe invocation.

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 there is no output schema, the description's explanation of the returned envelope (items fields, returned/total/truncated, served_version) is essential and fully supplied. It also covers error behavior, prerequisite calls, and the alternative for NICs, making it complete for an agent to use this tool correctly.

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% (target and namespace both have explanatory descriptions), so the schema already communicates parameter meaning. The description adds minor value by noting the namespace comes from list_namespaces and target defaults via config.yaml, but it does not substantially extend the schema definitions. Baseline 3 is appropriate.

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 a specific verb and resource: 'List VirtualMachineSnapshot objects in a vSphere Namespace.' It clearly differentiates this from siblings by explicitly naming list_vm_network_interfaces for NICs and referencing the vSphere Namespace scope. The 'READ' tag reinforces the intent without ambiguity.

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 gives explicit when-to-use guidance: run list_namespaces first for the namespace, and use list_vm_network_interfaces for a VM's NICs instead. It also explains the behavior when the Supervisor predates v1alpha5, which tells an agent what to expect and how to respond. This is strong routing guidance relative to alternative tools.

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