remove_iscsi_target

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

Annotations already flag destructiveHint=true, but the description adds far more: exactly what is destroyed (LUNs served only through this target become inaccessible after rescan), the preview/confirm gate semantics, refusal conditions, and that it is reversible only by re-adding. This is precisely the context annotations cannot carry.

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?

Front-loaded with a [WRITE] tag followed immediately by verb+resource+side effect, then the destructive warning and gating rules. Each sentence carries distinct, necessary information with no filler.

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 destructive six-parameter tool with no output schema, the description covers the mutation's blast radius, the confirm gating, refusal cases, reversibility, and even describes the returned blast_radius dict. Nothing an agent needs to invoke it safely is missing.

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 100%, so the schema already documents all six parameters (including confirm/dry_run), giving a baseline of 3. The description nonetheless adds behavioral meaning to confirm (preview vs apply, the 'do not set on your own' constraint) and implies the exact-match requirement on address, going beyond the schema text.

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?

States a specific verb (Remove) and resource (iSCSI send target) plus the affected scope (ESXi host's software iSCSI adapter, then rescan HBAs and VMFS volumes). This clearly distinguishes it from siblings like add_iscsi_target and rescan_storage without needing either schema.

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?

Explicitly defines the preview-vs-apply workflow (without confirm=True it previews), the human-in-the-loop requirement (show blast_radius and get explicit decision; do not set confirm on your own), and the refusal conditions (datastore losing every path, unconfigured address, disabled iSCSI, unattributable paths). It also names the reversal path via add_iscsi_target.

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