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

Annotations already mark this as non-readOnly, non-idempotent, and non-destructive; the description adds rich context beyond them: what the preview returns (blast radius contents), that nothing changes without confirm, refusal conditions, and that a duplicate address:port yields action "noop".

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-loads the core action in the first sentence, then the safety/gating rules. Slightly dense but nearly every clause carries actionable information about preview behavior or refusal conditions; 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 6-parameter mutation tool with no output schema, the description covers the mutation semantics, preview/apply gating, failure modes, and the side-effect rescan. Coverage is strong, though the returned dict's shape is only named (blast_radius, action) rather than detailed.

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 parameters are already documented, but the description adds meaningful semantics for the gating flag (confirm=True applies, otherwise preview) and reinforces the deprecated dry_run alias relationship and the enable_iscsi dependency. This exceeds the baseline 3 without fully restating every field.

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?

Opens with a specific verb and resource: adding an iSCSI send (dynamic discovery) target to an ESXi host's software iSCSI adapter, plus the automatic HBA/VMFS rescan. It is clearly distinguishable from siblings like remove_iscsi_target, enable_iscsi, and rescan_storage.

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 states the confirm=False preview default and instructs the agent to show the blast radius and not set confirm=True on its own; it also says no separate rescan_storage call is needed and directs to enable_iscsi when software iSCSI is disabled. When-to-use and prerequisites are fully spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavioral context beyond them: the search is recursive by default, the response is a list envelope with items/returned/total/truncated, and truncation never occurs because all matches are returned.

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 the '[READ]' marker and the core action, then the routing guidance, then the setup hint, then the return contract. Four short sentences, no filler, nothing repeated from the schema.

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?

There is no output schema, so the description carries the burden of explaining return values — and it does, describing the list envelope fields and the truncation invariant. With 4 params at full schema coverage and declared annotations, nothing an agent needs to call this correctly 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 path/pattern/target semantics are already documented in the schema and the baseline is 3. The description adds provenance meaning beyond the schema by stating datastore_name comes from list_all_datastores, and reinforces the recursive-glob behavior that ties pattern usage together.

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+resource+scope: '[READ] Search a datastore folder and all its subfolders for files.' It explicitly distinguishes itself from the sibling scan_datastore_images by naming it, so an agent can route without opening a second 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?

It states when to use this tool ('arbitrary files or a glob') and names the preferred alternative for the other case ('prefer scan_datastore_images for deployable images'). It also tells the agent where the required datastore_name value comes from (list_all_datastores), closing the setup loop.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description adds far more: preview-vs-apply semantics, the exact contents of the blast_radius preview, noop behavior for an already-enabled adapter, non-disruptive guarantee (no reboot, no datastore impact), and the refusal condition when the storage view is unreadable. No contradiction with the non-destructive annotation, since enabling an adapter does not destroy anything.

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 the action, then prerequisites, then the confirm contract and side-effect profile. Sentences are short, imperative and non-redundant; nothing could be deleted without losing operational information.

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?

No output schema exists, and the description compensates by describing the return shape ('returns a dict', action 'noop' with HBA device and IQN) plus the preview payload. For a 4-parameter, open-world write tool this covers everything an agent needs to call it safely.

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 baseline is 3, but the description adds workflow meaning the schema lacks: it explains what confirm=False actually returns (blast_radius with host, current adapters, whether the software adapter exists) and how to interpret confirm=True, and it ties host_name to get_iscsi_status for verification. This is real semantic value beyond the mechanical 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?

Opens with a specific verb and resource: 'Enable the software iSCSI adapter (vmhba) on an ESXi host.' It also names related siblings (add_iscsi_target, get_iscsi_status), so an agent can place it precisely in the storage workflow without reading any other tool.

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?

Explicit ordering ('Required prerequisite before add_iscsi_target'), an explicit alternative for state checking ('check state first with get_iscsi_status'), and an explicit prohibition ('Do not set confirm=True on your own because the user asked earlier — they have not seen the preview yet'). This is the rare case of when/when-not/alternatives all stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the required privilege, what is returned (target, account, privilege states per tool or grouped by verdict), and three concrete gotchas about root-folder checking, not_granted_at_root, and undetermined.

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 the purpose, then usage, then return shape, then a labeled 'Gotchas' block. Despite its length, every sentence carries distinct information an agent needs (privilege requirement, verdict semantics, undetermined handling) 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?

There is no output schema, so the description carries the return-value burden and does so thoroughly, describing both output modes and the meaning of each verdict. An agent has everything needed to call it and interpret the result.

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 baseline is 3, but the description adds meaning the schema does not: passing tool yields that tool's requires/verdict/meaning, while omitting it returns every tool grouped by verdict. This clarifies the behavioral difference between the two modes rather than just restating parameter names.

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 opening line states a specific verb and resource: it reports which account the server uses and whether that account holds each tool's vSphere privileges. This is clearly distinct from every sibling (storage/datastore tools), so an agent can route to it 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 triggering conditions: 'when a tool fails with NoPermission, or before a write.' It even notes the low privilege requirement (System.View), removing any doubt about whether it is safe or possible to call in a failing state.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds meaningful behavior beyond them: the exact return shape and the disabled-adapter edge case (enabled=false with null device/IQN and empty target list). This is real disclosure the 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?

Three tight sentences, front-loaded with the action, then the return contract, then the routing guidance. No filler; every sentence earns its place.

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?

With no output schema, the description compensates by specifying the return structure and the disabled-state behavior, and it points to the sibling tools for the follow-up actions. Nothing an agent needs to call this correctly 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 description coverage is 100%, so both parameters (target, host_name) are already documented, including the pointer to list_esxi_hosts for valid names. The description adds no parameter-level detail, so baseline 3 applies.

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?

Specific verb+resource: 'Get the software iSCSI adapter state and configured send targets for an ESXi host.' It clearly distinguishes itself from adjacent siblings such as list_fc_adapters (different adapter type) and the mutating enable_iscsi/add_iscsi_target tools.

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 states when to use: before enable_iscsi / add_iscsi_target / remove_iscsi_target to check prerequisites, and afterwards to verify the change. Names the specific alternatives and the conditions that select them.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial beyond-annotation behavior: null vs 0 for inaccessible datastores with the explicit rationale that vCenter returns 0 and '0 GB used reads as a healthy empty datastore', accessible=null meaning the summary was silent, and vsan_enabled=false rather than an error. This is exactly the kind of guidance an agent cannot infer from structured fields.

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 the read tag and purpose, then the return shape, then the non-obvious failure semantics, then sibling routing. Every sentence carries information; the only near-redundancy is the trailing 'No side effects.'

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?

There is no output schema, so the description carries the return contract itself by enumerating the fields and the three accessible states. Combined with the stated error condition and sibling alternatives, nothing an agent needs to call this correctly 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 description coverage is 100% and both parameters are documented in the schema, including the 'errors if the cluster is not found' note that the description repeats. The description adds no new parameter-level syntax or format detail, so the baseline 3 applies.

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 and resource ('Get space usage of a cluster's vSAN datastore for capacity planning') with the exact scope named. It clearly separates itself from get_vsan_health and list_all_datastores by naming both and their domains.

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?

Explicit routing: 'Use get_vsan_health for disk-group layout and host details; use list_all_datastores for non-vSAN (VMFS/NFS) datastore usage.' It also states the one error condition (cluster name not found), so an agent knows the boundary of valid use.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond: it discloses the SDK path used, the null-with-message semantics when space efficiency is off (avoiding a fabricated false), the exact error trigger, and the two capabilities deliberately NOT exposed. This is precisely the behavioral 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 the READ marker, purpose, and return shape, then constraints and limits in a trailing note. Dense and well-organized, though the final note is slightly long for two capabilities that are simply unavailable.

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?

With no output schema, the description supplies the return fields, the null-vs-false edge case, the error condition, the SDK provenance, and cross-references to related tools. Nothing an agent needs to call this correctly 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% and the schema already documents both target and cluster_name (including the case-sensitivity and error-on-not-found note). The description adds little parameter-specific meaning beyond restating the error condition, so the baseline of 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?

States a specific verb and resource ('Get vSAN data-efficiency (deduplication + compression) status for a cluster') and immediately distinguishes itself from siblings get_vsan_capacity and get_vsan_health. An agent can tell exactly what this returns without opening the 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 routes the agent: use get_vsan_capacity for space usage and get_vsan_health for disk-group layout, and use the vCenter/vSAN UI for Global Dedup and v2v replication. It also states the sole error condition (cluster name not found), so when-to-use and when-not-to-use are both covered.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds substantial context: it reads the cache rather than running a full health check, explains that a null overall_health means 'not measured' and never a measurement, warns that disk_groups is incomplete when hosts are unread, and notes vSAN-disabled returns a message rather than an error.

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-loads purpose, then the return shape, then the important caveats (null semantics, disk_groups_complete, vsan-disabled path). It is dense and each sentence earns its place, though the return-shape enumeration is lengthy.

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?

With no output schema, the description fully carries the burden: it enumerates the return shape and explains the semantics of the ambiguous fields (overall_health nulls, health_checked_at, disk_groups_complete). Nothing an agent needs to interpret the result 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 description coverage is 100% (both target and cluster_name are documented, including the 'errors if not found' behavior), so the schema carries the parameter burden. The description adds no parameter-specific detail beyond what the schema states, making the baseline 3 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?

States a specific verb (Get) plus resource (vSAN health) and scope: overall health, per-check-group health, and per-host disk-group layout for a cluster. It explicitly distinguishes itself from the sibling get_vsan_capacity, so an agent can route between them without opening a 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?

Names an alternative explicitly ('Use get_vsan_capacity for space usage instead') and clarifies that it reads vCenter's cached summary rather than triggering a full health run, which tells the agent when this is the cheap option. It lacks broader when-not guidance, but the routing context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: enumeration happens before limit is applied, so 'total' is the real count and 'truncated' is only true when limit cut rows off. That pagination semantics is real value beyond the annotations, though it stops short of explaining default limit or the accessibility field's meaning.

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-loads the [READ] marker and the core action, then the workflow routing, then return-shape semantics. Three tight sentences with no filler; every clause carries information the agent uses.

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?

There is no output schema, and the description compensates by documenting the list envelope (items, returned, total, truncated). Combined with the routing guidance and the 100%-covered input schema, an agent has everything needed to call this correctly and interpret the result.

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% (both params documented), so the baseline would be 3, but the description goes further by explaining the interaction between 'limit' and the returned total/truncated values. It clarifies that total reflects the full enumeration rather than the truncated list, which meaningfully disambiguates the limit parameter. It adds nothing about 'target', hence not a 5.

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 (List) and resource (datastores), and names the exact fields returned (capacity, usage percentage, accessibility). It also distinguishes itself from siblings by naming browse_datastore and scan_datastore_images as downstream consumers, so an agent can place it in the workflow without opening any 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 says 'Use this first for the datastore_name that browse_datastore and scan_datastore_images require', which names both the alternative tools and the condition that selects this one. The sequencing guidance (call this before the others) is exactly the when-to-use signal an agent needs.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description nonetheless adds real behavior: it reads ~/.vmware-storage/image_registry.json, may be stale, is empty until a scan runs, and is filtered entirely in memory so 'truncated' is always false. This is substantially more than the annotations convey.

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 '[READ]' tag and one-line purpose, followed by the data-source caveat and the return-envelope semantics. Every sentence carries distinct information; nothing is redundant with the name or schema.

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?

No output schema exists, but the description supplies the return contract (items holding {target, datastore, name, ds_path, size_mb, type, modified}, plus returned/total/truncated). Combined with full param coverage and annotations, an agent has everything needed to call and interpret it.

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%, so the schema already documents target/datastore/image_type in depth. The description adds only an indirect note that the whole registry is filtered in memory, which does not add per-parameter meaning beyond the schema. Baseline 3 applies.

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 (List) plus resource (deployable images OVA/OVF/ISO/VMDK) and scope (from the local cache registry). It explicitly distinguishes itself from the sibling scan_datastore_images, so an agent can route correctly without opening 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?

Names the alternative (scan_datastore_images) and the condition that selects it ('For a live listing use scan_datastore_images instead'). It also states the cache is populated by a prior scan and may be stale/empty until one has run, giving clear when-and-when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: the hosts_not_read contract ('never report it as having no FC adapters'), the speed_reported caveat that vSphere reports Gbit/s despite documented bits-per-second, and that it reads host config only with no rescans. These are exactly the behavioral traps an agent needs to avoid misreporting.

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 purpose and usage in the first two sentences, then the return-shape and caveat details. Dense and mostly waste-free, though the block is long enough that the hosts_not_read and speed_reported caveats could be tightened slightly.

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?

With no output schema, the description carries the return burden and does so: it documents the list envelope (items, returned, total, truncated, next_offset) plus the two non-obvious extra fields (hosts_without_fc, hosts_not_read with reason). Nothing an agent needs to call and interpret this tool correctly 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 documented parameters already stand on their own (limit, offset, next_offset paging, exact-match naming). The description still adds value by clarifying the precedence between cluster, host, and target ('with neither, every host on the target is read') and by noting the operation stays cheap at that scope.

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+resource ('List Fibre Channel HBAs (FC and FCoE) per ESXi host') and enumerates the returned fields (vmhba, model, driver, status, port type, WWPN/WWNN, link speed). It explicitly distinguishes itself from the sibling list_storage_device_paths, so an agent can route correctly without reading 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?

It gives concrete use cases in the user's own words ('which FC adapters does each host have', 'to find a host's WWPNs') and names the alternative (list_storage_device_paths) with the condition that selects it (devices and paths behind the adapters). Scope semantics (cluster OR host; neither = all hosts on target) are also spelled out.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds substantial behavior: hosts_not_read semantics ('refused, not connected... vCenter's copy may be stale'), how to interpret 'complete: false', that 'standby' can be normal on active/passive arrays, that a path count does not prove independent fabrics, and 'No rescans.' This is exactly the value-add the description should provide.

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?

Content is organized under clear signposts ('Use for:', 'Per device:', 'Gotchas:') and front-loads purpose before detail. It is dense, and the long per-device field enumeration is heavier than strictly necessary, but for a 9-parameter tool most sentences carry real information rather than padding.

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?

With no output schema, the description accepts the full burden of describing returns — it lists per-device fields, per-path detail conditions, and the 'summary counts the whole result, not just this page' pagination note — plus caveats about NFS/vSAN/vVol and NVMe-oF. Nothing an agent needs to invoke or interpret the result correctly 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 baseline is 3, but the description adds meaning beyond the schema: it enforces the 'exactly one of cluster/host/datastore' mutual-exclusion rule, clarifies that adapter matches by vmhba name which 'can be a different card on each host', and explains only_differences scoping. These semantics are not present in the schema fields.

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 opening sentence gives a specific verb ([READ]), resource (SCSI multipath state per device/NAA), and scope (across hosts of one scope), then enumerates what it reports (path counts/states, adapters, target WWPN, PSP/SATP, VMFS datastores). This lets an agent distinguish it from siblings like list_fc_adapters or list_all_datastores without opening any 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?

Four concrete 'Use for:' scenarios map directly to parameter combinations (datastore=X; cluster+device; cluster+only_differences=true; host+adapter). The constraint 'Exactly one of cluster, host or datastore is required — this tool will not read every host at once' is an explicit when-not rule, leaving nothing to inference.

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

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.

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

Annotations only give the coarse safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true); the description adds substantially more: a preview/confirm gate, the exact blast_radius payload, an anti-pattern warning against auto-confirming, I/O visibility and duration on busy hosts, and a refusal condition. This is well beyond what structured fields convey.

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 the operation class and action, then ordered by importance: purpose, usage, when-not, preview semantics, safety warning, cost/refusal, return shape. No sentence is filler despite the multi-sentence length.

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?

With no output schema, the description compensates by stating the return shape (a dict) and the blast_radius contents, plus refusal conditions and timing expectations. An agent has everything needed to call and gate 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 coverage is 100%, but the description still adds meaning the schema lacks: it explains what the confirm preview actually returns (blast_radius listing host, adapters, mounted VMFS volumes) and why the agent must not set confirm=True without user review. The only untouched param is the deprecated dry_run alias.

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 (rescan) plus the resources touched (all HBAs and VMFS volumes on an ESXi host) and the goal (discover newly presented LUNs and datastores). The [WRITE] prefix signals the mutation class, and it explicitly differentiates itself from add_iscsi_target/remove_iscsi_target.

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?

Gives explicit when-to-use ('when a storage array presents new LUNs, or after out-of-band SAN changes') and explicit when-not ('Not needed after add_iscsi_target / remove_iscsi_target — those rescan automatically'). It also prescribes workflow gating around confirm=True, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds live-vs-cached semantics and describes the return envelope ('items', 'returned'/'total'/'truncated') that no output schema provides. It also discloses that 'all patterns are browsed, so truncated is always false', a behavioral guarantee not derivable from annotations. It does not mention that the scan repopulates cached entries (that detail lives only in the schema).

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?

Three short blocks: purpose, routing guidance, return contract. Front-loaded with the verb and resource, no filler, and every sentence carries information an agent needs.

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?

With no output schema, the description fills the gap by explaining the list envelope and truncation semantics, and it covers the live-vs-cached decision plus parameter provenance. For a 3-parameter read tool this is complete.

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%, so the baseline is 3; the description nudges above it by explaining that datastore_name is sourced from list_all_datastores, tying the parameter to a concrete workflow step. It does not elaborate on 'path' or 'target', which the schema already documents.

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 (scan) and resource (datastore images) and enumerates the artifact types it finds (OVA, ISO, OVF, VMDK). The '[READ]' prefix plus the explicit contrast with list_cached_images makes it immediately distinguishable from its closest sibling.

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 scopes usage: 'live scan of one datastore; prefer list_cached_images for a cached answer' names the alternative and the condition that selects it. It also tells the agent where the required datastore_name value comes from (list_all_datastores).

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