esxi_storage_manage

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

Annotations already flag destructiveHint=true and non-idempotent. The description adds non-obvious behavior: a preview-first workflow, the need for expected_host, a write switch, dependency confirmation, and request_id for idempotency. It does not explain what each of the 16 actions actually does, which matters given a destructive tool.

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?

It is compact but the opening is a 16-item action dump that crowds out the workflow guidance in the second sentence. Content is front-loaded enough to be usable yet the run-on enumeration hurts readability.

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?

An output schema exists, so return values need not be explained, but for a destructive 9-parameter tool with 16 sub-actions the description should convey per-action impact and which parameters gate destructive operations. It covers the safety workflow but leaves the action-to-argument mapping and the impact flags under-specified.

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 0% across 9 parameters, and the description leaves the action string with no enumeration of valid values even though the tool supports 16 named actions. It mentions expected_host, request_id, and the preview flag but does not explain dry_run semantics, allow_disruption, acknowledged_vm_ids, or the free-form arguments object, so the description fails to compensate for the coverage gap.

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 clearly states this is dedicated storage management and enumerates the 16 supported actions (rescan, vmfs_format, lun_attach, iscsi_* etc.), which precisely identifies the verb family and resource. It does not explicitly contrast with the many siblings, but the enumerated action list separates it from esxi_datastore_manage and esxi_esxcli.

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 advises running resource_schema/get and the default preview first, and requires expected_host, write switch, and dependency confirmation before execution. That gives real when-to-use context but never names when a sibling (e.g. esxi_datastore_manage) should be chosen instead.

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