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

Beyond the annotations, the description discloses the two-phase preview/apply behavior, the contents of blast_radius, the refusal conditions, duplicate handling, and the automatic HBA/VMFS rescan. It makes the tool's side effects and safety workflow clear even without relying solely on the annotations.

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?

The description is front-loaded with the write operation and its main side effect, then proceeds to preview/confirm guidance and failure cases. Despite its length, every sentence carries relevant 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?

It covers the critical context for a complex write tool: prerequisites, preview behavior, confirmation caution, automatic rescan, duplicate noop, and refusal conditions. It is slightly incomplete on the full shape of the returned dict, but the preview return contents are described.

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 all five parameters are already documented. The description adds operational meaning for confirm and address:port duplicate handling, though it does not add much beyond the schema for host_name, target, or port.

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 states a specific verb and resource: add an iSCSI send/dynamic discovery target to an ESXi host's software iSCSI adapter. It also names the automatic rescan side effect, so an agent can distinguish this from sibling tools like rescan_storage or enable_iscsi.

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 usage conditions: call enable_iscsi first if software iSCSI is disabled, use confirm=True only after showing the preview, and do not make a separate rescan_storage call afterward. It also states that duplicate address:port calls return noop, which clarifies an important edge case.

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 already declare write and non-destructive traits, but the description adds substantial operational detail: preview-only default, blast_radius return, noop when already enabled, non-disruptive behavior, and refusal when the storage view is unreadable. None of this is present in 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?

The description is front-loaded with the core action and prerequisite, and every sentence carries useful safety or behavioral information. It repeats the confirm preview guidance slightly, preventing a full 5, but contains no fluff.

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?

Despite having no output schema, the description explains the return shape (blast_radius, noop, dict) and tells the agent to check state first via get_iscsi_status. It covers the prerequisite, safety gate, and operational caveats needed to call the 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?

With schema description coverage at 100%, the schema already documents host_name, target, and confirm. The description reinforces confirm's preview semantics but does not add much parameter-specific syntax or edge cases beyond what the schema provides, 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?

The description opens with a specific verb and resource: 'Enable the software iSCSI adapter (vmhba) on an ESXi host.' It distinguishes the tool from siblings by naming add_iscsi_target as the dependent operation and get_iscsi_status as the pre-check.

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 explicitly states when to use this tool (required before add_iscsi_target, after checking get_iscsi_status) and gives a strong when-not rule: do not set confirm=True on your own before showing the preview. The workflow routing is unambiguous.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context: it reads vCenter's storage.perDatastoreUsage, reports on-disk space rather than provisioned size, and explains unattributed_gb and unmeasured_vms. This is exactly the kind of semantic detail an agent needs to interpret results correctly.

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?

The description is front-loaded with the core question and then structured into usage, data-source distinction, return shape, and caveats. Despite its length, every section adds operational value for a tool with a rich return payload and no output 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, but the description fully documents the return object, item fields, truncation behavior, and the meaning of unattributed_gb and unmeasured_vms. Combined with annotations covering safety, an agent has everything needed to call and interpret this tool.

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 three parameters. The description adds useful provenance for datastore_name by pointing to list_all_datastores, and its 'largest first' wording reinforces top_n behavior, though it does not add much beyond the schema for target or top_n.

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 states a specific query: which VMs consume space on one datastore, ordered largest first. It explicitly distinguishes this from browse_datastore by noting that it reads vCenter per-VM accounting rather than provisioned VMDK sizes, so an agent can select it confidently.

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 a clear use case ('is this datastore filling up, and who is using it?') and names the alternative browse_datastore for provisioned VMDK sizes. It also tells the agent where datastore_name comes from (list_all_datastores), removing ambiguity about the required parameter.

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 destructive/openWorld/non-idempotent, but the description adds substantial context: what becomes inaccessible after the rescan, the exact refusal conditions (all-paths-loss datastore, unconfigured address, disabled iSCSI, unattributable paths), reversibility limits, and return type.

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 the destructive warning and confirm protocol. Dense but nearly every sentence carries decision-relevant information; minor verbosity in the blast_radius enumeration.

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, yet the description fills that gap by describing the returned dict's blast_radius contents (targets, paths, devices, datastores losing paths). Complete for an agent to call and interpret this destructive tool 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 description coverage is 100%, so all five parameters are already documented in the schema. The description reinforces the confirm semantics but adds no new per-parameter meaning beyond what the schema provides; 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 (Remove) and resource (iSCSI send target from an ESXi software iSCSI adapter) and includes the immediate side effect (rescan HBAs/VMFS). This clearly separates it from add_iscsi_target and rescan_storage among the siblings.

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 describes the preview-then-confirm workflow, warns against setting confirm=True on the user's prior request, and tells the agent to surface blast_radius for an explicit decision. It also names the alternative recovery path (re-add 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?

Beyond annotations, it discloses the two-step preview/apply behavior, the exact blast-radius contents, the I/O visibility and possible duration, the fact that nothing is deleted, and the refusal condition. The guardrail against setting confirm=True without showing the preview is especially valuable for a write operation.

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?

The description is front-loaded with a [WRITE] tag and the core action, then proceeds through usage, preview behavior, safety warnings, and failure conditions. Despite its length, every section earns its place for a risky storage operation.

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 no output schema, the description explains the preview return as a blast_radius containing host, adapters, and mounted VMFS volumes, but the confirmed/apply return is only summarized as a dict. The optional target parameter is also left to the schema, but overall the definition is complete enough to call 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%, so host_name and confirm are already documented. The description adds useful meaning around confirm by explaining the preview return contents and the interaction policy of showing the blast radius to the user before applying, though it does not discuss the optional target parameter.

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 states a specific verb and resource: rescan HBAs and VMFS volumes on an ESXi host to discover new LUNs and datastores. It also distinguishes itself from sibling operations by noting that add_iscsi_target/remove_iscsi_target rescan automatically.

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 when-to-use guidance: after a storage array presents new LUNs or after out-of-band SAN changes. It also states when the tool is not needed and explains the confirm-preview workflow that must be shown to the user before applying.

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.