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

Annotations already cover read-only, idempotent, non-destructive safety, so the description adds value by explaining the return envelope and stating that all matches are returned so truncated is always false. It does not contradict any annotation, and adds meaningful behavioral context beyond structured metadata.

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?

Four short, purposeful sentences with no wasted words. The READ tag and primary use are front-loaded, followed by routing guidance, parameter sourcing, and return semantics. 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?

For a straightforward read-only listing tool, the description covers purpose, when to use it, where required parameters come from, and the return envelope. Even without an output schema, it gives the agent enough information to invoke the tool and interpret the response 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?

The input schema already provides 100% parameter descriptions, so the baseline is 3. The description adds value by linking 'glob' to the pattern parameter and sourcing ds_name from list_all_datastores, which helps an agent understand relationships between parameters and sibling tools.

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 clear verb and resource: 'Browse files in a datastore directory.' It also distinguishes itself from scan_datastore_images by explicitly routing deployable images to that sibling. An agent can tell exactly what this tool is for and what it is not for.

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 when to use this tool ('arbitrary files or a glob') and names the preferred alternative for deployable images. It also tells the agent where ds_name comes from ('list_all_datastores'), removing ambiguity about a 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?

Despite readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already covering safety, the description adds critical behavioral context: hosts_not_read means the host was NOT read and must not be reported as having no FC adapters; speed_reported is raw and not converted; reads host config only; no rescans; and only the adapter list is fetched so it stays cheap.

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 compact and well-structured: a clear one-line purpose, a usage sentence, scoping guidance, and a return-value caveat paragraph. Every sentence carries operational value, and the most important purpose and usage guidance are front-loaded.

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 present, the description compensates fully by explaining the list envelope, hosts_without_fc, hosts_not_read, and the raw speed_reported value. It also covers the returned adapter fields and the read-only, non-rescan behavior, making the tool safe and self-contained for an agent to call.

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 value beyond the schema by explaining the relationship between cluster and host scoping, the all-hosts behavior when neither is provided, and the pagination convention of passing the previous page's next_offset to offset.

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: 'List Fibre Channel HBAs (FC and FCoE) per ESXi host' and enumerates the exact fields returned (vmhba, model, driver, status, port type, WWPN/WWNN, link speed). It clearly differentiates itself from the sibling storage_device_paths by stating that devices and paths behind adapters belong to that 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?

The description explicitly states when to use this tool: for 'which FC adapters does each host have' or to find a host's WWPNs. It names the alternative tool for a different need and gives scoping rules for cluster, host, or neither, including the resulting behavior when no scope is provided.

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, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context by explaining the list envelope and guaranteeing that truncated is always false because enumeration happens in one pass. No contradiction with 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 short and front-loaded with the purposeful [READ] tag and the core listing statement. Four sentences cover purpose, usage, response envelope, and completeness behavior; slightly more verbose than strictly needed but 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?

For a simple listing tool with one optional parameter and no output schema, the description covers purpose, usage dependency, return shape, and listing completeness. Minor missing detail includes capacity/usage field units, but annotations and schema handle the rest.

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?

There is only one optional parameter, target, and the input schema already describes it as an optional vCenter/ESXi target from config. With 100% schema coverage, the description does not need to add parameter 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?

The description states a specific verb and resource: 'List all datastores with capacity, usage percentage, and accessibility.' It also names the dependent siblings, clarifying the tool's role as the entry point for datastore listing.

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 says to use this tool first to obtain the ds_name required by browse_datastore and scan_datastore_images, which is clear usage context. It does not discuss when not to use it or compare with all sibling alternatives, but the dependency is concrete.

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?

Discloses that the tool reads ~/.vmware-storage/image_registry.json, performs no vCenter/datastore I/O, filters in memory, and always reports truncated as false. These details go well beyond the annotations, which already mark the operation as read-only, idempotent, and non-destructive.

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 compact and well-organized: purpose, source/staleness, live alternative, and return envelope. Every sentence carries non-redundant information needed for correct tool selection and invocation, with key facts front-loaded.

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 read-only, zero-required-param tool with no output schema, the description fully explains the data source, staleness behavior, filter semantics, and exact return envelope fields. An agent can accurately predict output for omitted filters and handle empty or incomplete results.

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 because both parameters already have descriptions. The tool description adds that the entire registry is filtered in memory and that truncation is impossible, which clarifies how the optional filters affect results.

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 (deployable images) and scopes it to the local cache registry, clearly distinguishing it from live datastore operations. The [READ] prefix and explicit image types make the tool's purpose unmistakable.

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 names scan_datastore_images as the alternative when a live listing is needed, and warns that cached results may be stale or empty if no prior scan has run. This gives an agent concrete selection criteria beyond the tool name.

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?

The description adds return-structure detail beyond annotations: 'items' holds one row per image and 'returned'/'total'/'truncated' state completeness. It also discloses a non-obvious behavior: 'All patterns are browsed, so truncated is always false.' This complements readOnlyHint/openWorldHint/idempotentHint without contradicting them.

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?

Four compact sentences front-load the action, then give usage routing, parameter provenance, and response shape. No filler or repetition of schema/annotations.

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 read-only scan tool with no output schema, the description covers what an agent needs: purpose, when to choose it vs list_cached_images, where to get ds_name, and what the response envelope looks like. The schema covers parameter details, and annotations cover safety semantics.

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?

The input schema already covers all three parameters at 100% (path, target, ds_name). The description adds one meaningful relationship—'ds_name comes from list_all_datastores'—which helps the agent populate the required parameter correctly.

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 action ('Scan a datastore for deployable images') with concrete artifact types (OVA, ISO, OVF, VMDK). The '[READ]' prefix and 'live scan of one datastore' frame exactly what it does, and the explicit contrast with list_cached_images distinguishes it from a 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?

Directly instructs when to use: 'Use this for a live scan of one datastore; prefer list_cached_images for a cached answer.' It also chains the required parameter to another tool ('ds_name comes from list_all_datastores'), giving the agent a clear call path.

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, idempotentHint, and destructiveHint=false, and the description does not contradict them. It adds substantial operational behavior beyond annotations: hosts_not_read are never in not_seen_on, 'standby' can be normal for active/passive arrays, NFS/vSAN/vVol datastores have no SCSI paths, NVMe-oF namespaces may not appear, and no rescans are performed.

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 long but tightly organized into 'Use for', 'Per device', and 'Gotchas' sections, with the core scoping rule stated early. Every section earns its place by addressing a distinct aspect an agent needs: purpose, query patterns, output shape, pagination, and edge cases.

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?

Although there is no output schema, the description fully enumerates the per-device and per-host result fields, pagination mechanics, failure semantics via hosts_not_read, and known exclusions such as NFS/vSAN/vVol and NVMe-oF. An agent has enough context to invoke the tool correctly and interpret results confidently.

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 each parameter. The description still adds valuable cross-parameter semantics: exactly one scope is required, adapter matching by vmhba name may refer to different cards per host, datastore scopes to mounting hosts and VMFS extents, and pagination uses next_offset while 'summary' covers the whole result. This goes well beyond the schema.

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: '[READ] SCSI multipath state per device (NAA) across the hosts of one scope' and enumerates concrete outputs such as path counts, adapters, target WWPN, and PSP/SATP policy. It clearly distinguishes this tool from storage-related siblings like storage_iscsi_status or vsan_health by focusing on multipath state and path visibility.

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?

The 'Use for' section gives explicit example queries mapped to parameter combinations, and the description states the key selection rule: 'Exactly one of cluster, host or datastore is required.' It also provides when-not-to-use guidance, e.g., warning that hosts in hosts_not_read must not be used to conclude a device is missing.

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?

The description fully discloses the preview behavior with blast_radius, the rescan of HBA/VMFS, and the noop for duplicates. It also explains refusal conditions (software iSCSI not enabled, storage view unreadable). Annotations are minimal, so the description carries the burden and does so well.

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 rich but each sentence serves a purpose. Key items (write action, impact) are front-loaded. It avoids verbosity, though it is a bit long; every sentence is procedural and critical for correct invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (6 params, dual-mode), the description is complete. It covers the required confirmation flow, failure conditions, side effects, and return type. No output schema exists, but the description states it returns a dict, which is enough for an agent to proceed.

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?

The schema has 100% coverage, so all parameters are documented. The description adds clarity on the confirm/dry_run relationship and the address restriction to IP literals. It doesn't need to repeat parameters but could have noted the default port behavior; still, the schema covers it.

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 clearly states that the tool adds an iSCSI send target, then rescans. It also specifies the resource (software iSCSI adapter). The [WRITE] prefix and explicit mention of the confirm workflow distinguishes it from siblings like storage_iscsi_status and storage_rescan.

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?

The description explicitly instructs when to use confirm=False first, warns not to set confirm=True autonomously, names storage_iscsi_enable as a prerequisite, and states that no separate storage_rescan is needed. It also smallnotes the duplicate address:port behavior, which prevents redundant tries.

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, the description reveals the preview/apply split controlled by confirm, the noop behavior when already enabled, non-disruptiveness, refusal when storage view cannot be read, and that it returns a dict. These are meaningful behavioral details not encoded in the annotations. No contradiction with readOnlyHint=false or destructiveHint=false.

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?

Every sentence earns its place: purpose, prerequisite, preview semantics, noop case, safety guidance, disruption profile, failure mode, and return type. The most critical safety instruction is front-loaded and clearly stated.

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 type, the blast_radius content, the noop action with HBA device and IQN, and pointing to storage_iscsi_status for state verification. It covers prerequisites, failure conditions, and operational impact, so an agent has what it needs to call and interpret the 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% and each parameter already has a description. The tool description adds extra operational meaning around confirm: without confirm=True it only previews, and the agent must not set confirm=True autonomously before the user sees the blast radius. This goes beyond the schema's basic 'True applies it' explanation.

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 differentiates from siblings by declaring itself 'Required prerequisite before storage_iscsi_add_target' and describing the already-enabled 'noop' case, so an agent can distinguish it from add/remove/status 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?

The description explicitly says when to use it relative to storage_iscsi_add_target, instructs the agent to 'check state first with storage_iscsi_status', and gives clear guidance not to set confirm=True without showing the preview. This is direct, actionable when-to-use and when-not-to-act 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 signal write/destructive behavior, but the description adds concrete behavioral detail: preview mode semantics, LUN inaccessibility after rescan, side-effect rescanning, refusal guardrails, and reversibility. This goes well beyond destructiveHint.

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 long but every sentence is high-signal for a destructive mutation tool: operation, preview mode, consent rule, refusal conditions, reversal, and return type. It is front-loaded with the action and the [WRITE] marker.

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 6-parameter tool with no output schema, it is complete enough: it describes the blast_radius return contents, refusal conditions, required user confirmation, and reversal path. The schema carries the remaining parameter details.

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 reinforces confirm's preview/apply behavior and the address:port prerequisite, but most parameter meaning is already provided by the schema.

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 names the exact operation: removing an iSCSI send target from an ESXi software iSCSI adapter and rescanning HBAs/VMFS. It also distinguishes itself from adjacent siblings by naming storage_iscsi_add_target as the reversal path.

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 invocation policy: without confirm=True this only previews, the result must be shown to the user, and the agent must not set confirm=True on its own. It also lists refusal conditions and the only reversal path, so an agent knows when not to proceed.

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?

The description discloses the exact return shape and the important edge case for a disabled adapter: 'enabled=false with null device/IQN and an empty target list.' This adds behavioral context beyond the readOnlyHint/idempotentHint annotations, which already establish this as a safe, read-only operation. It does not mention potential errors or auth requirements, but the schema covers host lookup failure.

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 compact and front-loaded: the '[READ]' marker, resource, and return shape appear first, followed only by the disabled-adapter edge case and concrete usage guidance. Every sentence adds functional value with no redundant 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?

With no output schema present, the description compensates by documenting the return tuple and the disabled-adapter behavior. It also explains the tool's role in the broader workflow with sibling tools, and the schema covers the required parameter semantics. The definition is complete for an agent to select and call 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 description coverage is 100%, so the schema already documents both parameters thoroughly, including the required host_name format and optional target behavior. The tool description itself does not add parameter-level detail, which is acceptable given the schema richness; this lands at the baseline 3.

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 starts with the explicit verb 'Get' and names the exact resource: 'software iSCSI adapter state and configured send targets for an ESXi host.' This clearly distinguishes the tool from its sibling mutation tools like storage_iscsi_enable and storage_iscsi_add_target, as well as unrelated datastore/vSAN 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?

The description explicitly states when to use this tool: 'Use this before storage_iscsi_enable / storage_iscsi_add_target / storage_iscsi_remove_target to check prerequisites, and afterwards to verify the change took effect.' It names the relevant alternatives and gives concrete usage timing, leaving no ambiguity about when this status check is appropriate.

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 indicate a non-read, non-idempotent, non-destructive operation, and the description adds important context beyond that: confirm=False previews and returns blast_radius, confirm=True applies changes, the operation is I/O-visible, may take minutes, deletes nothing, and can be refused when the storage view cannot be read. This gives an agent a strong behavioral model.

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 purpose and every subsequent sentence earns its place by covering usage timing, preview behavior, safety constraints, side effects, failure conditions, and return type. It is detailed but not bloated.

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 mutating storage operation with no output schema, the description provides the key missing context: the blast_radius result shape, confirmation gating, runtime cost, I/O visibility, and a refusal condition. An agent has enough to invoke it safely 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 description coverage is 100% and every parameter is already documented, including the dry_run deprecation and confirm default behavior. The tool-level description reinforces confirm's gating behavior but does not need to compensate for schema gaps, 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?

The description opens with a specific verb and resource: 'Rescan all HBAs and VMFS volumes on an ESXi host to discover newly presented LUNs and datastores.' It clearly defines scope and explicitly distinguishes when related sibling tools are not needed, so an agent can tell it apart from storage_iscsi_add_target and storage_iscsi_remove_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?

The description states exactly when to use it ('when a storage array presents new LUNs, or after out-of-band SAN changes') and when not to ('Not needed after storage_iscsi_add_target / storage_iscsi_remove_target — those rescan automatically'). It also gives safety-critical guidance about not setting confirm=True before showing the preview.

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, idempotentHint, and destructiveHint=false, but the description adds rich behavioral nuance: inaccessible datastores return null figures instead of 0, accessible=null means the summary was silent, and vSAN-disabled clusters produce an explanatory message. It also explicitly states 'No side effects'.

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 dense but every sentence earns its place: purpose, return shape, edge-case semantics, error behavior, sibling routing, and side-effect confirmation. It is front-loaded with the core purpose and keeps related details grouped logically.

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 correctly takes on the burden of documenting return fields and edge cases. It covers the expected behavior, error conditions, null semantics, and alternative tools, making it complete for an agent to invoke 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?

The input schema already documents both parameters, including the exact-match requirement for cluster_name. The description adds valuable behavioral context: it clarifies that cluster_name errors only if not found, while vSAN-disabled clusters return a message instead, and it reinforces the meaning of edge-case return values.

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 begins with a clear verb and resource: 'Get space usage of a cluster's vSAN datastore for capacity planning.' It names the specific output fields and explicitly distinguishes itself from siblings by recommending vsan_health for disk-group details and list_all_datastores for non-vSAN datastores.

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?

The description explicitly states when to use this tool and when to use alternatives: 'Use vsan_health for disk-group layout and host details; use list_all_datastores for non-vSAN (VMFS/NFS) datastore usage.' It also clarifies the error boundary (cluster name not found) and that vSAN-disabled clusters return a message rather than an error.

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 the readOnlyHint/idempotentHint annotations, the description discloses that it calls the vSAN Management SDK rather than base pyVmomi, that missing config returns null with a message rather than a fabricated false, and that errors only occur for an unknown cluster name. It also clearly notes the tool's limitations regarding global dedup and v2v replication, which the annotations do not cover.

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 longer than average but well-structured, with the core purpose and return values front-loaded before implementation details and exclusions. A small amount of redundancy exists, such as echoing 'no side effects' despite annotations already declaring readOnlyHint and destructiveHint=false.

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 read-only status tool with no output schema, the description fully covers return fields, error behavior, SDK dependency, a common null-result case, and exclusions. An agent has enough context to invoke it correctly and avoid misusing it for capacity or health queries.

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 both parameters already have meaningful descriptions, including case-sensitivity and config-target semantics. The tool description adds behavioral context like error conditions and return fields, but does not materially add parameter-level meaning beyond the schema.

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 '[READ] Get vSAN data-efficiency (deduplication + compression) status for a cluster,' which names a specific verb, resource, and scope. It also distinguishes itself from vsan_capacity and vsan_health by naming those siblings for other purposes.

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?

The description explicitly says 'Use vsan_capacity for space usage and vsan_health for disk-group layout,' giving clear routing to alternatives. It also states when not to use it: global dedup and v2v replication are not exposed here and require the vCenter/vSAN UI.

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 the readOnlyHint/idempotentHint annotations, the description explains that this reads vCenter's cached summary rather than triggering a full health run, and that null overall_health means 'not measured' rather than a measurement. It also discloses the incomplete disk_groups risk with disconnected hosts, which is important non-obvious behavior.

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?

Although the description is long, it is dense and structured: purpose first, then return shape, then edge-case semantics, then alternative tool routing. Every sentence contributes necessary context, especially given there is 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?

The description covers return fields, null semantics, cache behavior, partial data due to unreadable hosts, and the non-error path when vSAN is disabled. For a health-inspection tool with no output schema, this is fully sufficient for an agent to invoke and interpret results 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 the input schema already documents cluster_name and target well. The description does not add much parameter-level detail, but the baseline of 3 is appropriate since the schema carries the parameter semantics fully.

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 clear '[READ]' marker and names the specific resource: vSAN health per check-group and per-host disk-group layout for a cluster. It distinguishes itself from siblings by explicitly steering space-usage queries to vsan_capacity.

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 says to use vsan_capacity for space usage instead, which gives the agent a clear routing rule. It also clarifies how the tool behaves when vSAN is not enabled, so the agent knows it won't get an error in that case.

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