esxi_esxcli

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and not idempotent. The description adds valuable context: SSH is disabled by default, execution requires administrator privileges, independent host-key verification, and full impact confirmation. This goes beyond the annotations and clarifies the operational and safety constraints.

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 a single dense sentence that front-loads the core purpose and then lists key operational constraints. It is appropriately concise for the amount of context provided, with no wasted words.

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 tool's high risk (destructive, open-ended argv) and 8 parameters with zero schema coverage, the description rightly emphasizes safety prerequisites. However, it omits any explanation of parameter effects (e.g., what dry_run or allow_disruption do) and does not guide the agent on selecting this tool over the numerous specialized siblings, leaving significant gaps 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?

Schema description coverage is 0% for all 8 parameters, yet the description provides no information about what any parameter means, including the required arguments array, dry_run, timeout, expected_host, allow_disruption, max_output_bytes, acknowledged_vm_ids, or allow_protected_impact. The description fails to compensate for the complete lack of schema documentation.

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 identifies this as a complete argv entry point for ESXCLI on the host, covering configuration/patch/driver/storage operations outside the SDK. It is a clear purpose but does not explicitly distinguish it from the many sibling management tools or the esxi_esxcli_query tool, leaving ambiguity about when to use this versus those.

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 implies usage for host operations beyond the SDK, and notes SSH is disabled and admin access is required, which hints at prerequisites. However, it does not state when to use this generic entry point versus the many specific sibling tools like esxi_patch_manage or esxi_storage_manage, nor does it mention alternatives.

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