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?

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?

The description provides rich behavioral context such as [WRITE], automatic rescanning, audit logging, and return behavior. However, it explicitly claims 'Idempotent' while the annotations set idempotentHint to false, which is a direct contradiction and forces a low score.

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: core action first, then prerequisite, idempotency, rescan implication, audit trail, and return type. Every sentence earns its place and there is no filler.

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

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

For a write operation with five parameters and a complete schema, the description covers prerequisites, side effects, idempotency, audit logging, and return behavior, so an agent can call it correctly. The contradictory idempotency metadata introduces avoidable uncertainty and prevents a perfect completeness score.

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 each parameter already has a meaningful schema description including defaults and validation intent. The description adds the address:port duplicate semantics but does not substantially increase parameter-level understanding beyond the schema, 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 uses a specific verb ('Add') and names the exact resource: an iSCSI send (dynamic discovery) target on an ESXi host's software iSCSI adapter. It also clearly distinguishes itself from sibling tools like storage_iscsi_enable, storage_iscsi_remove_target, 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 prerequisite storage_iscsi_enable is explicitly named, including the failure behavior if it is not met. It also tells the agent that no separate storage_rescan is needed, giving clear routing guidance relative to siblings.

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 declare idempotentHint=false, but the description claims 'Idempotent: if the adapter is already enabled... without making changes.' This directly contradicts the annotations, which is a serious inconsistency. Per the rubric, a description contradicting annotations must receive a score of 1.

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 [WRITE] and the action verb, and nearly every sentence carries useful operational information: prerequisites, state-checking, effects, audit logging, and error behavior. It is reasonably sized, though the misleading idempotency assertion slightly undermines the trustworthiness of an otherwise tight definition.

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?

Covers prerequisites, side effects, non-disruptiveness, audit trail, the recommended status check, and return/error behavior; an output schema exists, so exact return details are not required. However, the contradictory idempotency statement means the behavioral contract is not fully reliable, so it is not a perfect score.

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?

Input schema description coverage is 100%, so the schema already documents host_name, target, and dry_run. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline score of 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 ('Enable'), a specific resource ('software iSCSI adapter (vmhba)'), and a clear host context ('on an ESXi host'). The [WRITE] prefix also immediately classifies the operation and distinguishes it from sibling inspect/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?

Explicitly says this is a 'Required prerequisite before storage_iscsi_add_target' and tells the agent to 'Check current state first with storage_iscsi_status.' This gives clear sequencing and names the relevant sibling tools, so an agent knows when to use this tool versus alternatives.

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 annotations, the description discloses significant behavioral details: the operation triggers an HBA/VMFS rescan, LUNs served only by this target become inaccessible, errors occur for unconfigured pairs or disabled iSCSI, the operation is reversible only by re-adding, and it is audit-logged. This far exceeds what destructiveHint/readOnlyHint already 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?

The description is dense but well-organized: action first, then consequences, verification steps, error conditions, reversibility, audit trail, and return type. Every sentence adds useful information, and no fluff is present.

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 mutation tool, the description covers side effects, preconditions, failure modes, recovery, logging, and return behavior. Combined with the schema and annotations, an agent has everything needed to decide whether and how to invoke 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 baseline is 3. The description does not substantially add parameter-level meaning beyond what the schema already provides, though it does hint that address and port together form the identity of the target.

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: remove an iSCSI send target from an ESXi host's software iSCSI adapter. It also distinguishes itself from the sibling storage_iscsi_add_target by framing the action as removal and explicitly naming re-adding via that 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?

The description gives explicit preconditions: verify the target exists with storage_iscsi_status and check datastore dependencies with list_all_datastores. It also states error conditions and the recovery path via storage_iscsi_add_target, giving clear guidance on when and how to use the tool safely.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, and the description adds meaningful context beyond those flags: it is non-destructive yet I/O-visible, may take minutes with many paths, is audit-logged, returns a confirmation string, and errors include remediation hints. This fully discloses expected side effects and operational impact.

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: the purpose, use case, exclusions, side effects, timing, logging, and return behavior are packed into a compact paragraph. It is front-loaded with the action and keeps all guidance relevant without filler.

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

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

For a complex, I/O-visible operation, the description fully covers invocation context, exclusions, side effects, timing, logging, return value, and error behavior. The presence of an output schema further reduces the need to explain return structure, and nothing important 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 all parameters (host_name, target, dry_run) already carry clear descriptions. The tool description adds no additional parameter-level semantics beyond what the schema provides, so the baseline 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 uses a specific, action-oriented statement: 'Rescan all HBAs and VMFS volumes on an ESXi host to discover newly presented LUNs and datastores.' This clearly identifies the resource and scope, and the [WRITE] prefix plus the use-case context distinguish it from sibling storage tools like storage_iscsi_add_target and list_all_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?

It explicitly states when to use the tool ('when a storage array presents new LUNs, or after out-of-band SAN changes') and when not to use it, naming the alternatives storage_iscsi_add_target / storage_iscsi_remove_target and explaining they rescan automatically. This gives an agent clear routing 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 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.