storage_iscsi_status

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: the exact return shape ({host, enabled, hba_device, iqn, send_targets}), the behavior when the adapter is disabled (enabled=false with null device/IQN and empty target list), and the error condition for host_name ('Errors if not found'). This goes beyond the annotations and gives the agent a clear model of the tool's 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?

The description is dense but not bloated. Every sentence earns its place: a one-line purpose, a terse return-format overview, a usage directive, and clear parameter explanations. The most critical information (purpose and usage context) is front-loaded, and the parameter section is organized for quick scanning.

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 provides the complete return structure inline. It also covers edge cases (disabled adapter), error behavior (host not found), prerequisites (list of hosts from another tool), and post-conditions (verification after mutations). For a read-only status tool with two params, 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 0%, so the description must carry the full burden for parameter meaning. It fully explains host_name: 'ESXi host name exactly as shown in vCenter inventory (FQDN or IP). Errors if not found. No host listing here — get names from vmware-monitor list_esxi_hosts.' And target: 'Optional vCenter/ESXi target name from config.' This adds format, source, error behavior, and optionality, which is far beyond the schema's bare string type.

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 the software iSCSI adapter state and configured send targets for an ESXi host,' which uses a specific verb (Get) and resource (software iSCSI adapter state and send targets) and clearly scopes to an ESXi host. It distinguishes from siblings by explicitly naming related tools (storage_iscsi_enable, storage_iscsi_add_target, storage_iscsi_remove_target) as actions that follow this status 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?

The description provides explicit when-to-use guidance: '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 also names an alternative for host listing ('get names from vmware-monitor list_esxi_hosts') and clarifies that this tool does not list hosts.

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