esxi_expand_disk

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=false. The description usefully adds that expansion is growth-only and requires no existing snapshots, which the annotations do not convey. It omits other meaningful behavior, notably that dry_run defaults to true and what a rejected call returns.

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?

A single terse clause-pair with no filler, and the constraints are front-loaded. It is efficient, though the extreme brevity borders on under-specification rather than tight concision.

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 no explanation, but for a 5-parameter destructive mutation with 0% schema coverage the description is far too thin: no dry_run semantics, no explanation of expected_name or vm_id, and no failure/permission context.

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 coverage is 0%, so the description must carry parameter meaning, but it only touches device_key (precision targeting) and implicitly new_size_gb (growth only). Key parameters vm_id, expected_name and especially dry_run (default true) are left completely unexplained, leaving most of the 5-param surface undocumented.

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 is entirely constraint-based ("growth only", "rejected with snapshots") and never states the core action of expanding a virtual disk; the agent must infer the verb+resource from the tool name alone. It distinguishes the constraint from siblings like esxi_vm_hardware, but the purpose itself is only implied.

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?

"有快照时拒绝" conveys a when-not-to-use condition (no snapshots present), which is genuine guidance. However, it names no alternative (e.g., delete snapshot first) and gives no positive context for when to choose this over esxi_vm_hardware or esxi_configure_vm.

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