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 substantial behavioral context: it requires the Sessions privilege, low-privilege accounts get a single explanatory row instead of a traceback, vCenter solution users are folded by default and counted in service_sessions, and it explicitly says terminating a session is not supported. These details go well beyond the annotations and give 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 somewhat long but every sentence adds value: purpose, return fields, privilege behavior, folding details, and usage pairing with active_tasks. It is front-loaded with the purpose and then provides necessary context. It could be trimmed slightly (e.g., the list of fields is detailed but helpful), but it is well-structured and not redundant.

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 tool with no output schema, the description comprehensively covers the return envelope, row fields, privilege requirements, error fallback, and pairing with a sibling. It also implicitly addresses the limit parameter via the schema. Nothing an agent needs to correctly call this tool is missing; the description 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 parameters (limit, target, include_service) are already fully documented in the schema. The description does not add extra parameter semantics beyond what the schema provides; it only mentions include_service implicitly through the folding behavior. Given the high coverage, a baseline of 3 is appropriate, and the description does not need to compensate.

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: 'Currently authenticated vCenter/ESXi sessions (who is logged in).' It clearly states what the tool returns and distinguishes itself from the sibling active_tasks by explicitly naming it and its different focus. The read-only nature is also stated, so an agent knows exactly what this tool does.

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 tells the agent when to use it: 'Use this to attribute a change to a person — pair it with active_tasks, which names the user who started each task.' This gives a concrete use case and points to an alternative, making it clear how to choose between the two. It also notes privilege requirements and the fallback behavior for low-privilege accounts, further guiding appropriate invocation.

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, openWorldHint, idempotentHint, and destructiveHint, and the description adds substantial context beyond those: the exact response envelope with a real total, row fields including error for failed tasks, running/queued ordering, and the vCenter short-recent-task-window caveat. This enriches the agent's mental model of what the tool does and what could go wrong.

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 moderately long but every sentence earns its place: purpose, output shape, caveat, usage guidance, and cancellation boundary. It is front-loaded with the core purpose and then adds operational context without repetition or 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, the description compensates by detailing the return envelope and row contents. It covers the tool's safety profile, its relationship to sibling tools, and the important vCenter retention caveat, making the tool fully actionable for an agent.

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 fully documents limit, target, and include_recent. The description adds contextual meaning around the returned envelope and the 'optionally just-completed' behavior, but it does not need to add parameter-level details; 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 states a specific verb ('[READ] In-flight... vCenter tasks') and a precise resource, and immediately frames the tool's purpose with 'Answers "why is the cluster busy?"'. It differentiates from siblings by explicitly comparing to host_performance and active_sessions, so an agent can select it without opening other schemas.

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: 'Use this before blaming load' and explains that an in-flight migration/clone explains pressure shown by host_performance. It also provides an exclusion by noting that cancelling a task belongs to vmware-aiops, and recommends pairing with active_sessions to see who started the task.

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 mark it read-only/idempotent/non-destructive; the description adds non-obvious behavior: the list envelope has a real total, rows are sorted soonest-first, and only host certs are covered. It also confirms renewal is outside the tool's capability, reinforcing the read-only contract.

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 strictly necessary (the outage-motivation sentence is not required for invocation), but it is front-loaded with the essential read/resource and every other sentence carries either return-format or routing information. Slight trimming would make it a 5.

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 listing the returned row fields, sort order, scope limitation, and read-only boundary. Together with the fully documented schema, an agent has everything needed to invoke it 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 all three parameters (limit, target, warn_days) are already documented in the schema. The description adds no new parameter-level detail beyond mentioning the expiring flag, 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?

Opens with '[READ] Per-host ESXi management certificate expiry', a specific verb plus resource. It names the precise returned signal (expiring, days_until_expiry) and explicitly disclaims vCenter appliance coverage, leaving no ambiguity about scope.

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?

Positions the tool as part of a platform-hygiene sweep alongside license_status and ntp_status, and explicitly states what it cannot do (renew certificates) with a pointer to vmware-aiops or vCenter. This gives an agent clear when-to-use and when-not-to-use 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=true, idempotentHint=true, and destructiveHint=false, and the description is consistent ('[READ]'). It adds substantial behavioral context beyond annotations: the return is 'not the list envelope', it is 'Point-in-time — no trending', and it details the ranking semantics (cleared alarms rank after live issues; unknown alarms keep severity rank and are reported as possibly still live). 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 long but every sentence earns its place — purpose is front-loaded in the first line, followed by usage, return format, ranking behavior, and downstream tool routing. The density is justified by the tool's complexity, though it could be trimmed slightly without losing essential 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?

With no output schema, the description correctly carries the full burden of explaining return values: it lists the fields ({totals, top_issues, issues_total, clusters, snapshot, customization_hint}) and how to present them, plus the inclusion rule for thin-provisioned datastores and alarm condition fields. Nothing an agent needs to call it correctly or interpret results 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 baseline is 3. The description adds some value by explaining how top_n caps top_issues and that issues_total is the pre-cap count, and how include_vms affects the rollup. However, most parameter meaning is already fully covered by the schema descriptions, so the description doesn't dramatically compensate beyond the baseline.

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-resource pair ('health rollup for every cluster') and the goal ('is anything on fire?'). It explicitly differentiates from siblings by saying 'Use this instead of stitching list_all_clusters + list_esxi_hosts + get_alarms yourself,' so an agent can tell it apart from the list/detail tools without opening schemas.

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?

Provides explicit when-to-use guidance ('Start here for single-vCenter triage') and names alternatives ('Then drill into what top_issues names with vm_investigation_bundle, host_investigation_bundle or datastore_investigation_bundle; use cross_vcenter_attention to cover every target at once'). Also gives exclusion guidance ('Acting on a finding belongs to vmware-aiops'), covering when NOT to act with this tool.

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 mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: the return shape, defensive reading behavior, the 'not found' teaching error for never-remediated clusters, and the 503 mid-patch retry semantics. It also notes endpoint/field verification against a live VCF 9.1 vCenter.

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 well structured under clear headings, is front-loaded with the core read intent, and every sentence earns its place. It packs usage timing, return shape, error behavior, and a cross-tool pointer without unnecessary 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 fully compensates by enumerating the return fields and expected error cases. It also covers when to retry, how to interpret the MoID, and the read-only nature, making it complete for an agent to call the tool effectively.

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 both parameters. The description adds extra meaning by explaining that 'cluster' is the cluster MoID and pointing to list_all_clusters for discovery, which goes beyond the schema's 'Cluster MoID' text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-and-resource statement: it returns the result of the last vLCM remediation (apply) on one cluster via REST. It clearly distinguishes itself from the sibling cluster_patch_compliance by stating this is for the apply outcome, not current drift.

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 guidance is provided: use after a patch/remediation to confirm the last apply succeeded and when it finished. It names the alternative cluster_patch_compliance and tells the agent exactly when to use that instead, so the agent can select correctly.

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 goes well beyond the readOnlyHint/idempotentHint annotations by explaining that available: False indicates a 503 from vCenter, likely mid-patch, and should be retried rather than treated as failure. It also explicitly states the tool is read-only and never runs remediation, and notes verification against a live VCF 9.1 vCenter. This gives the agent actionable behavioral context.

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 well-structured with labeled sections: purpose, when to use, return behavior, and gotchas. It is front-loaded with the core purpose and maintains focus without redundant filler. Each section adds operational value, and the length is appropriate given the absence of an 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?

For a tool with no output schema, the description covers return fields, an important error/retry condition, a crucial MoID prerequisite, and the tool's non-destructive scope. Combined with the annotations and 100% schema coverage for parameters, the agent has sufficient context to select and invoke the tool correctly in a patch-compliance workflow.

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 adds meaningful value by specifying that 'cluster' must be a cluster MoID such as domain-c123, not a display name, and directs the agent to list_all_clusters for the correct value. It also explains the requirement originates from the REST API, which clarifies parameter semantics 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 clear verb and resource: '[READ] vLCM software (patch) compliance for one cluster.' It goes further than a generic statement by explaining what compliance means: checking whether hosts match their assigned image/baseline. It also distinguishes itself from sibling host_memory_tiering by noting per-cluster lifecycle state instead of per-host hardware.

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 provides 'When to use' guidance: check before or after a patch cycle. It also contrasts with host_memory_tiering to help route selection. It gives a concrete prerequisite for the cluster parameter ('get it from list_all_clusters, not the display name'), though it does not enumerate exclusions or alternatives beyond that single sibling.

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 annotations already declaring readOnlyHint and idempotentHint, the description goes far beyond them by disclosing distinctive behaviors: graceful degradation for unreachable targets, point-in-time semantics (no trending), deduplication identity rules, and the rollup return shape (lead with top_issues). This is substantial added context beyond what annotations 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?

The description is long but every sentence carries operational value: scope, return shape, degradation behavior, deduplication rules, and follow-up tools. It is front-loaded with the top-line purpose and alternatives, making the key decision information immediately visible.

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 tool with no output schema, the description compensates thoroughly: it names the primary output fields (top_issues, unreachable, also_seen_via, totals), explains scope and exclusions (no trending, one vCenter tag), and routes to sibling investigation tools. No critical behavioral or return-shape information seems 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?

The input schema already documents both parameters with full coverage, including defaults and filtering semantics. The description adds no parameter-level meaning beyond what the schema already states, so the baseline 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?

Opens with an explicit READ verb and a clear resource: "What needs attention now? across EVERY configured vCenter — one list." It distinguishes itself from cluster_health_summary by stating it aggregates all targets into a single ranked list, so an agent can immediately tell this is the estate-wide aggregate.

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 when-to-use instructions: "Start here when the estate has more than one vCenter" and directs the agent away from the alternative: "Use this instead of calling cluster_health_summary once per target and merging yourself." It also points to drill-in tools (vm_investigation_bundle, host_investigation_bundle, datastore_investigation_bundle), which is actionable 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds substantial behavioral context beyond this: 'Point-in-time.' explains the snapshot nature; it details how provisioned_gb is summed and may differ between vCenter and ESXi; it clarifies the meaning of overcommit_pct >100% and the vm_count/vms_not_connected fields. This significantly enriches the agent's understanding of what to expect, especially the inconsistency between views.

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 longer than average, it is well-structured with distinct sections: purpose, return fields, caveats about view differences, and usage routing. Every sentence adds value—no filler. It front-loads the core purpose and then layers caveats and alternatives logically. The structure aids comprehension and efficient 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?

For a read-only tool with no output schema, the description covers all essential aspects: return fields and their meaning, the key risk signal, the view-dependent inconsistency, and the recommended follow-up tool. It also notes the point-in-time nature and what is not covered. An agent has enough to correctly invoke the tool and interpret results. No gaps remain.

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 (limit and target) already have clear descriptions in the schema. The tool description does not add additional parameter-level detail beyond what the schema provides. The baseline of 3 is appropriate because the schema carries the burden, and the description focuses on output and usage rather than parameters.

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 purpose: 'Per-datastore capacity with thin-provisioning over-commit.' It explicitly differentiates from list_all_datastores by noting it adds the risk signal overcommit_pct, which is a concrete distinction from a sibling. The verb and resource are specific, and the scope is unambiguous.

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 usage guidance: 'Use this for the capacity view, then datastore_investigation_bundle to drill into a specific datastore...' and clearly states what belongs elsewhere ('Reclaiming space ... belongs to vmware-aiops'). It also explains the data source caveat (vCenter vs ESXi view), which helps an agent choose the right tool. This is clear when-to-use and when-not-to-use 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 mark it read-only, but the description adds substantial behavioral detail: batched reads, correlated bundle vs list envelope, point-in-time snapshot semantics, output presentation guidance, and the caveat that per-datastore latency is omitted. 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?

Every sentence earns its place: purpose, output components, available alternatives, exclusions, and trigger context are each covered once. The [READ] tag and front-loaded purpose make the definition scannable despite its length.

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

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

For a complex bundle tool with no output schema, the description fully carries the return semantics, including what is and is not included. It also positions the tool within the workflow relative to cluster_health_summary and remediation tools, so an agent has enough context to call it 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 datastore_name, hours, and target fully. The description reinforces the exact-name requirement and suggests where to source the name, but adds little new 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 a concrete question and states it is a 'one correlated drill-down' for a datastore, listing exactly what the bundle contains (capacity, free space, hosts, VM rollup, alarms, event timeline). It differentiates itself from the individual list/get tools by explicitly naming the stitching alternative, and from sibling investigation bundles by the resource type.

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 direct when-to-use instruction ('Reach for it after cluster_health_summary flags storage pressure') and names the alternative manual composition it replaces. Exclusions are explicit: no trending, no remediation, and per-datastore latency is not included, with remediation routed to vmware-aiops.

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/openWorld/idempotent/non-destructive behavior. The description adds substantial context beyond that: condition_now states (holds/cleared/unknown) with precise definitions, stale_alarms counting, the vCenter license re-check, and the object_label/entity_name distinction. It also warns against misreporting cleared or unknown alarms.

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 earns its place: each caveat prevents a real misuse, such as reporting cleared alarms as live problems or 'no data' when empty items with truncated=False means genuinely no alarms. It is front-loaded with the main purpose and then organized by output semantics.

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?

Even though there is no output schema, the description supplies essential return structure: the list envelope, total, stale_alarms count, alarm fields, and empty-items semantics. Combined with the full parameter schema and annotations, nothing critical is missing for correct invocation.

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 add much detail about limit or target beyond what the schema already provides, though its rich output semantics are not parameter-related.

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 '[READ] Get active/triggered alarms across the VMware inventory' — a specific verb+resource that clearly distinguishes it from sibling cluster_health_summary. It also states it returns a list envelope with a real total and alarm condition semantics, so the agent knows exactly what this tool does.

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 for the raw alarm list; prefer cluster_health_summary when you want alarms folded into a whole-cluster verdict. Then drill into the flagged object with vm_investigation_bundle or host_investigation_bundle.' This gives clear when-to-use, when-not-to-use, and alternative tools.

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 goes well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing truncation behavior (up to 5000 events, read_truncated, read_note), severity classification rules (own ranking vs vCenter catalogue, 'unknown' severity returned not filtered), and the crucial caveat that an empty items list with non-zero unclassified does not mean silence. This is exactly the kind of behavioral context agents need and is fully consistent with 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?

Although the description is long, every sentence earns its place: it front-loads the one-line purpose with the [READ] tag, then covers truncation, severity semantics, all-clear caveats, and alternative tools in a logical order. The density is justified by the tool's complexity and the need to prevent misinterpretation, 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?

With no output schema, the description must explain the return envelope, and it does: newest-first ordering, truncation flags, severity classification, and unclassified counts. Combined with the annotations and 100% parameter schema coverage, the definition equips an agent with everything needed to call the tool correctly, interpret results, and decide when to switch to a sibling.

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 100% schema coverage, the baseline is 3, and the description adds meaningful parameter-related guidance: it explains how 'hours' interacts with truncation (narrow it before concluding nothing happened earlier) and clarifies the semantics of severity as a minimum threshold with potential 'unknown' outcomes. This goes beyond the schema's simple descriptions, earning a 4.

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 the specific verb (get), resource (vCenter/ESXi events), and filter (by severity), and immediately distinguishes itself from siblings by naming vm_investigation_bundle / host_investigation_bundle and host_log_scan as alternatives for different use cases. An agent can tell exactly what this tool does and what it does not do without inspecting other schemas.

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 ('inventory-wide event sweep') and when to prefer alternatives ('when you already know the object, prefer vm_investigation_bundle / host_investigation_bundle'), and it warns that ESXi syslog lines are not events, pointing to host_log_scan. It also gives practical guidance on interpreting truncation and unclassified results, leaving no ambiguity about selection.

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, openWorld, idempotent, and non-destructive, so the bar is met by adding meaningful context. The description adds crucial behavior beyond annotations: no rows does not mean healthy; hosts without sensors appear in hosts_without_sensors with cim_server_running/cim_server_policy, and sensors_note must be quoted. This is exactly the kind of subtle behavior an agent needs to avoid misinterpreting results.

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 carries essential information: the scope, the return envelope, the non-obvious no-sensors semantics, the quote instruction, and explicit sibling routing. It is front-loaded with the core purpose and then adds necessary detail 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?

With no output schema, the description compensates by explaining the envelope, field list, hosts_without_sensors structure, and the CIM server dependency. It also covers routing to related tools, leaving little ambiguity for an agent deciding to call and interpret 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 limit and target clearly. The description does not add parameter-specific guidance beyond what the schema provides, which is acceptable but does not elevate the score above the baseline.

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: 'Get hardware sensor status (temperature, voltage, fan, ...) for all hosts.' It clearly distinguishes this from sibling tools by emphasizing physical hardware sensors and explicitly contrasting with host_performance for CPU/memory load and host_investigation_bundle for red-sensor follow-up.

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?

Usage guidance is explicit: 'Use this for physical hardware only — for CPU/memory load use host_performance, and follow up on a red sensor with host_investigation_bundle.' This gives the agent clear when-to-use and when-not-to-use directions with named 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 readOnly/idempotent annotations, the description discloses the return envelope structure, row fields, and the guarantee that truncated is always False because all matching hosts are enumerated. It also states the read-only boundary explicitly, adding meaningful behavioral context.

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 dense, with the core purpose first, followed by return details, then usage guidance and exclusions. Every sentence earns its place and no information is redundant with the schema or 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 tool with two optional parameters, read-only annotations, and no output schema, the description fully covers what the agent needs: the exact fields returned, the truncated behavior, a concrete use case, and a clear alternative for NTP. Nothing essential 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 parameter descriptions for target and host_name already document their meaning and defaults. The tool description does not add deeper semantics for these parameters, but the schema carries the required burden, 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 names a specific verb and resource: 'Get host service status (running state and startup policy).' It clearly distinguishes the tool from siblings by stating its scope (services, not sensors or VMs) and by explicitly pointing to ntp_status for NTP-specific checks.

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 exactly when to use the tool ('check whether SSH, NTP or the firewall service is in the expected state'), names a preferred alternative for NTP (ntp_status), and excludes write operations by directing users to vmware-aiops for starting/stopping services.

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 mark the tool read-only/idempotent; the description adds return-shape context ('one correlated bundle, not the list envelope'), batching behavior, point-in-time semantics, and output guidance (operational language, not raw dump). 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 front-loaded with the core purpose, then uses short paragraphs for alternatives, return contents, trigger context, and limitations. Every clause adds non-redundant information and nothing reads as 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, the description compensates by itemizing the bundle's contents (host state, cluster, VM rollup, datastores, alarms, performance, event timeline) and its operational caveats. Given the tool's read-only nature and well-documented parameters, nothing essential 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?

All three parameters are fully documented in the schema with defaults and usage notes (e.g., exact host name, teaching error, hours look-back). The main description does not add parameter meaning, so the high schema coverage baseline 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?

The description names a specific analytical operation ('correlated drill-down' around an ESXi host) and enumerates exactly what the bundle contains, distinguishing it from the list tools and from sibling bundle tools for VMs and datastores. The opening question makes the intent 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?

It explicitly says to use this instead of manually chaining four listed tools and specifies the trigger ('after cluster_health_summary flags a host'). It also gives exclusions: no trending, syslog needs host_log_scan, and remediation belongs to vmware-aiops.

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 mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral context beyond that: it reads only the last `lines` entries, filters by known trouble patterns, explains severity precedence, documents that `total` is deliberately null, and describes `logs_unavailable` semantics. It also states that every call reads the log afresh, which is useful for an agent planning repeated calls.

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 packed with necessary operational details, and the [READ] prefix and first sentence front-load the core purpose. Each subsequent paragraph addresses a distinct concern: output shape, grouping behavior, total semantics, and usage guidance, so no sentence feels wasted.

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 full burden of explaining return values, and it does so thoroughly: the list envelope, grouped item fields, ungrouped row fields, `total` being null by design, `logs_unavailable`, and the interplay between empty `items` and `logs_unavailable`. It also covers error behavior and intended usage context, making it complete for an agent to select and invoke 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?

The input schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds meaningful parameter-level context beyond the schema: `group=false` output shape, the `host_name` exact-match error behavior, and the fact that `lines` controls the freshly read window per call.

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 precise action: scanning recent ESXi host syslog lines for error/warning patterns, naming the specific logs (hostd/vmkernel/vpxa) and the diagnostic mechanism. It clearly differentiates this tool from related tools by explicitly contrasting it with get_events and host_investigation_bundle, which read different sources.

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 when-to-use guidance: 'Use this when get_events or host_investigation_bundle show a host in trouble but not why.' It also provides practical usage details like filtering with host_name, exact name lookup from list_esxi_hosts, the error behavior for unmatched names, and the effect of group=false.

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 annotations already mark the operation as read-only and idempotent; the description adds useful behavioral detail beyond that: it reads pyVmomi HostSystem.hardware.memoryTierInfo, requires ESXi 8.0U3+/9.x, reports 'unknown' for older hosts, and clarifies that 'noTiering' means a real checked-none state rather than missing data.

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, with front-loaded purpose, a 'When to use' section, return envelope details, and gotchas. The only minor redundancy is restating 'Read-only' at the end after '[READ]' and despite the readOnly annotation, but overall every section 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?

Even though there is no output schema, the description fully explains the return shape, row fields, per-tier breakdown, and the special meaning of 'noTiering'. It also covers version prerequisites and behavior on older hosts, making it complete for an agent to 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?

The input schema already documents all three parameters completely, including defaults and filtering intent, with 100% coverage. The description does not add parameter-level detail, but the schema carries that burden adequately, so the baseline 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?

The description states a specific purpose: reporting per-host memory tiering and NVMe uplift ratio. It also differentiates itself by claiming to be 'the only source of measured tier byte sizes,' which helps distinguish it from generic host-list 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 begins with 'When to use' and lists concrete scenarios: identifying ESXi hosts backed by NVMe, checking tier sizes, and understanding how much memory rides on NVMe. It does not enumerate alternatives or explicit 'when not to use' conditions, but it provides clear contextual 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?

Even with annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds valuable behavioral nuance: data is from live 20-second PerfManager, disconnected hosts are skipped rather than reported as zero, results are busiest-first, and the data is point-in-time with no historical trend.

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 with the essential read/live nature, then efficiently packs the most useful operational details without redundancy. Every sentence contributes either scope, differentiation, behavioral edge cases, or an alternative routing suggestion.

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 compensates by enumerating returned fields, explaining the 'total' envelope semantics, stating which hosts are excluded, and describing ordering. No hidden behaviors or call prerequisites remain unaddressed.

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 has a clear inline description (limit, target, host_name), so the schema already fully documents parameter semantics. The tool description adds no extra parameter guidance, 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 clearly identifies the action ('[READ] Real-time CPU/memory/disk/network utilisation per ESXi host') and distinguishes itself from list_esxi_hosts by contrasting live PerfManager data with static config data. It also names specific fields returned, leaving no ambiguity about what the tool produces.

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 is explicit about when to use this tool: 'Use this to find which host is hot'. It also routes the agent to follow-up tools such as host_investigation_bundle and vm_performance, and contrasts with list_esxi_hosts for static host configuration 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?

Beyond the readOnlyHint annotation, the description discloses important runtime behavior: 'truncated is always False', how assignments behaves when the account cannot read them, and that 'License keys are never returned'. This adds real value beyond the structured 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 dense but efficiently organized: read intent, return shape, usage context, edge cases, and access limitations all earn their place. No filler or redundancy is present, and the most important purpose is front-loaded first.

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 covers the full response envelope, truncation behavior, assignment semantics, permission limitations, and the read/write boundary. An agent has enough context to invoke the tool correctly and interpret its 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?

With 100% schema description coverage, the schema already fully documents the single optional target parameter. The description repeats that the tool targets vCenter/ESXi but doesn't add new semantics beyond the schema, so the high-coverage 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 '[READ] vCenter/ESXi license inventory with usage and expiry', using a specific verb, resource, and scope. It clearly separates this tool from siblings like certificate_status and ntp_status by focusing on license-specific data.

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 use cases: 'catch over-allocation or an approaching expiry', and situates it in a platform-hygiene sweep with certificate_status and ntp_status. It also sets a clear boundary with 'Assigning a license is a write,' telling agents when not to use this read-only tool.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond those hints: it labels the data as 'Static topology only' and warns about the 'list envelope' with a 'real total.' It also documents the intended workflow. Not as rich as full pagination/performance notes, but it genuinely supplements 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 three sentences with no fluff. The core purpose is front-loaded, the return envelope note is brief, and the usage guidance is packed into a single efficient sentence. 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?

Given no output schema, the description provides a minimal return expectation ('list envelope with a real total') and lists the visible fields. It also routes the agent to the correct next tool. A small gap remains: the description does not mention how limit interacts with total if paginated, but this is minor for a static topology list tool with well-covered schema and annotations.

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 limit and target already have clear descriptions in the schema. The tool description adds no parameter-specific information, but because the schema fully documents both parameters, 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: 'List clusters with host count, DRS/HA status, and resource totals.' It also clarifies this is a static topology listing, distinguishing it from cluster_health_summary, a very close sibling. An agent knows exactly what data this tool provides and what it does not.

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: 'use this to resolve a cluster name, then cluster_health_summary, which supersedes stitching this with list_esxi_hosts and get_alarms yourself.' This gives clear when-to-use guidance and directs the agent away from an alternative composition. Nothing is left to inference.

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

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

Annotations already declare it read-only, idempotent, non-destructive, and open-world. The description adds useful context beyond annotations by mentioning the 'list envelope with a real total' and 'Raw free/used only', which helps set expectations. It does not contradict any annotation.

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 yet information-dense, with the core purpose in the first line and follow-up guidance in two short sentences. No filler, and the key exclusions and successor tools 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?

Given the simple list operation, the description fully covers what the tool returns (envelope with fields and total), its limitation (raw free/used only), and when to use which alternative. With no output schema, the description adequately explains the return shape and all necessary context for an agent to call it 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%, with both 'limit' and 'target' fully described by the schema. The description does not add parameter-specific detail, which is acceptable given the baseline, but no extra value is provided 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?

States the verb 'List' with a specific resource (datastores) and enumerates the returned fields (capacity, free space, type, VM count). It also names two sibling tools as alternatives, making the tool's purpose and scope unambiguous.

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 this tool: to resolve a datastore name, and then routes to datastore_capacity or datastore_investigation_bundle for deeper analysis. Also notes that only raw free/used data is provided, implying it is not for thin-provisioning risk assessment.

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, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by noting the return is a 'list envelope with a real total' and by explicitly limiting results to name, vm_count, and accessible, which helps set agent expectations beyond the 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?

The description is four short sentences, with the core purpose front-loaded and each sentence adding necessary context: output shape, exclusions, workflow, and NSX routing. There is no filler or redundancy.

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 read-only listing tool with no output schema, the description covers the returned fields, the envelope behavior, the limitation of detail level, and the intended follow-up workflow. Combined with rich annotations and full schema coverage, this is complete enough for an agent to invoke it 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 both parameters (limit and target) are already documented in the structured schema. The description does not need to compensate, and it does not meaningfully add parameter-level semantics beyond what the schema provides.

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 networks') and enumerates the exact fields returned: name, attached VM count, and accessibility. It goes further by explicitly excluding VLAN, uplink, and NSX overlay detail, which cleanly distinguishes it from what an NSX-specific tool would provide.

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 concrete use case: 'Use this to resolve a port-group name, then vm_info for the NICs of one VM.' It also routes NSX segments to a different tool by stating 'NSX segments live in vmware-nsx,' telling the agent when not to use this tool.

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 read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: the response is a list envelope, 'total' is the authoritative host count, and the values are static config rather than live load. This goes beyond what the annotations alone 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?

The description is compact and front-loaded. Every sentence earns its place: the first states the list purpose and fields, the second clarifies the envelope/total distinction, and the third routes the agent to the correct sibling tools. No filler or redundancy.

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 simple read-only tool with two optional params and full schema coverage, the description is complete. It covers return shape, field content, the static-config caveat, and related tools, with annotations covering safety. Nothing needed for correct selection or invocation 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 are already documented clearly. The tool description adds context around static vs. live data and host-name resolution, but it does not add significant 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 uses a specific verb ('List'), identifies the resource (ESXi hosts), and enumerates the returned fields (CPU cores, memory, version, VM count, uptime). It also separates this tool from related siblings by explicitly mentioning host_performance and host_investigation_bundle for different 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 gives explicit usage guidance: use this for static config and resolving a host name, then use host_performance for live load or host_investigation_bundle for deep drill-down. It clearly distinguishes when to use this tool versus the stated 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantive behavior: the {items, returned, limit, total, truncated, hint} envelope, the instruction to read `truncated` before summarising, and the non-obvious default that over 50 VMs with no limit/fields only the first five fields return. It also flags the pre-1.8.0 `vms` alias being removed in 2.0 — real operational context beyond structured data.

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 envelope semantics, then routing — a sensible order with no filler sentences. It is on the dense side (the `mode` reference is unexplained and mostly carries its weight as an aside), but nothing is redundant.

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 7-parameter, no-output-schema listing tool, the description covers the return envelope, the truncation sentinel, the default field projection, a deprecation notice, and sibling routing. An agent has everything needed to call it and interpret the result without a schema for the response.

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, and the description rises above it by explaining why `name_filter` exists ('what the "VM not found" errors elsewhere tell you to come here for') and how `limit`/`fields` interact with the 50-VM default projection. It does not, however, add format or syntax detail for sort_by, target, or power_state beyond what the schema states.

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 ('List virtual machines') plus the capabilities it supports (filtering, sorting, field selection), prefixed with a [READ] marker. It explicitly names the siblings it is not (vm_info, vm_investigation_bundle, cluster_health_summary), so an agent can place it in the fleet without opening another 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?

Gives explicit routing: use this to resolve an exact VM name, then vm_info for detail or vm_investigation_bundle to drill into one, and start at cluster_health_summary for a fleet-wide view. The when-to-use-this vs when-to-use-alternatives decision is fully spelled out rather than implied.

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, openWorld, and non-destructive, and the description adds significant behavioral detail beyond that: truncated is always False, null vs false semantics, unreachable hosts appear in the envelope, ntp_sources_consistent compares hosts, and the SOAP API limitation is disclosed. 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 long but every sentence adds necessary nuance: return envelope behavior, null semantics, comparison logic, limitations, and alternative tool guidance. It is front-loaded with the core purpose and progresses logically from row-level details to envelope-level and then to usage guidance. No filler or redundancy.

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 compensates by enumerating row fields (host, reachable, ntp_servers, ntpd_running, ntpd_policy, healthy), envelope fields (truncated, hosts_unreachable, unreachable_note, ntp_sources_consistent, ntp_sources_note), and explaining edge cases. It also covers API limitations and alternative approaches, making it complete for correct invocation and interpretation.

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%, with both target and host_name documented clearly in the input schema. The description adds context about matching hosts and envelope behavior but does not need to repeat parameter meanings. Baseline 3 is appropriate because the schema carries the semantic load.

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] Per-host NTP configuration health (servers + ntpd service state)'. It precisely defines what is measured (configuration health, not live clock offset) and explicitly differentiates itself from the sibling get_host_services by noting that tool lacks server configuration details.

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 to prefer this tool over get_host_services for time problems and gives the reason why. It also states that fixing NTP is a write operation and should use vmware-aiops, clearly distinguishing read vs. write use cases and routing the agent to the correct alternative.

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 significant behavioral details beyond annotations: return structure (list envelope with total), field list, sorting by memory usage descending, meaning of -1 as unlimited, and the caveat about non-qualified pool names. This complements the readOnly and idempotent hints without contradiction.

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 moderately long but every sentence earns its place: it front-loads the read marker and core purpose, details output format, then provides usage context. No redundant sentences, though it could be slightly tightened without losing value.

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 explains return fields, sorting, and special values, plus usage guidance. For a read-only tool with two optional parameters, this is complete; an agent can call it correctly without needing further documentation.

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 for both parameters is 100%, so the description adds minimal new meaning. It only indirectly references the limit parameter via the -1 semantics in results, but does not elaborate on the target parameter 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 clearly states it returns per-resource-pool CPU/memory reservation, limit, and usage, and enumerates the exact fields in each row. It names specific resources and the read action, distinguishing it from sibling tools that focus on hosts, VMs, clusters, or 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 specifies when to use this tool: "when a VM is throttled but its host is not busy." It also gives clear follow-up steps, mentioning vm_performance and cluster_health_summary as alternatives, effectively routing the agent.

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 openWorldHint. The description adds meaningful behavioral detail beyond that: the return shape is a 'rollup, not the list envelope,' and it discloses that est_size_mb is a 'lower bound' with an explanation of why (delta-disk growth not separable). It also flags that deletion belongs elsewhere. This adds value beyond annotations without contradiction.

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, with the primary purpose and use case front-loaded in the first two sentences. Every sentence earns its place: purpose, usage, return structure, field caveats, and read-only note. 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 fully explains the return structure (including fields like total_snapshots, old_snapshots, vms_with_snapshots, threshold_days, snapshots[], hint) and caveats about est_size_mb. It also covers the only behavioral caveat (read-only, no deletion). For a tool with 4 optional parameters and no output schema, 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 schema fully documents all four parameters. The description does not add new parameter-level semantics beyond what the schema already provides, hence 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 states a specific verb (sweep) and resource (ALL VMs' snapshots) with a clear purpose (flag old/sprawling ones). It distinguishes itself from the sibling vm_list_snapshots by saying 'prefer vm_list_snapshots when you only care about one VM.' This leaves no ambiguity about what the tool does.

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 this for fleet-wide snapshot sprawl' and directly names the alternative tool with the condition to switch. This is a textbook example of usage guidance, covering both when and when-not to use this tool.

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 read-only, idempotent, non-destructive behavior. The description adds valuable behavioral detail beyond annotations: it explains the return shape, that available:False means a 503 or pre-9.1 vCenter, that this is not a failure, and that the endpoint is 9.1-only. This is exactly the kind of context that helps an agent reason about unexpected results.

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 well-structured with labeled sections for usage, return value, and gotchas. Every sentence adds meaningful context, and the key purpose is front-loaded. There is no wasted text.

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 appropriately explains the return shape and failure semantics. It also covers version constraints and operational edge cases (503, older vCenter), making it fully sufficient for an agent to call the tool 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?

The single optional parameter `target` is already fully described in the schema as 'vCenter target from config (default if omitted),' giving 100% schema coverage. The description does not need to add parameter semantics, 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?

The description clearly states that the tool reads the vCenter appliance's current deployment size class, with a specific verb and resource. It also distinguishes its capacity-planning purpose from inventory/perf tools, helping an agent differentiate it from 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?

The description provides an explicit 'When to use' section explaining it is for reading deployment size for capacity planning and that this is not covered by inventory/perf tools. It does not name specific alternative tools or state explicit when-not-to-use conditions, but the 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 a safe read-only, idempotent, non-destructive operation, yet the description adds substantial context beyond them: it is a lower bound, history_unavailable vs coverage_note semantics, vCenter task.maxAge retention expiry (and the vim.fault.InvalidName naming trap), and that duplicate VM names raise rather than resolve. This is rich disclosure, though it stops short of describing pagination or the exact shape returned beyond field names.

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 the core measurement up top, then structured warnings in descending priority. It is long and occasionally dense, but nearly every sentence carries actionable caveats; a touch of pre-emptive narrative (the vpxd naming aside) keeps it from a 5.

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, so the description carries the return-value burden and does so: it enumerates the rollup fields (counts, four hour statistics, latest/longest cycle, unmatched rows) and explains how to interpret each. Nothing essential for correct interpretation 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. The description nonetheless adds interpretation the schema lacks — that the returned counts may cover less than `days` because of retention, and that an exact vm_name is required with duplicates refused rather than guessed — clarifying the practical meaning of two parameters.

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+resource+scope: measuring how long backup products held a snapshot open on one VM, derived from vCenter task history. It explicitly distinguishes itself from sibling tools by naming vm_list_snapshots and snapshot_aging for currently-existing snapshots, so an agent can route 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?

Gives explicit routing to alternatives (vm_list_snapshots / snapshot_aging for present snapshots) and states the key use conditions. It also tells the agent when NOT to trust an all-clear, and warns that no open cycle does not prove no backup is running — clear when-to-use 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, openWorld, idempotent, and non-destructive. The description adds valuable behavior beyond those: it returns static configuration only, returns a single dict rather than a list envelope, and warns that an unknown name yields a teaching error instead of a match.

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 with the core purpose. It covers return format, scope, error behavior, prerequisites, and sibling alternatives in a few sentences, with no filler or repetition of 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?

For a two-parameter read tool with rich annotations and siblings, the description covers all needed invocation context: what it returns, when to use it, what to call first, and which tools cover adjacent concerns. The lack of an output schema is mitigated by the explicit return-shape statement.

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 and vm_name) are already meaningfully documented in the schema. The description reinforces that vm_name must be exact and tells the agent where to get it, but does not add substantially new parameter semantics.

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?

Description states a specific verb and resource: 'Get detailed information about one VM' and enumerates the included areas (CPU, memory, disks, NICs, snapshots). It further differentiates from siblings by noting it returns a single detail dict, not the list envelope, and explicitly contrasts with vm_performance and vm_investigation_bundle.

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 is explicit about when to use the tool: 'Use this when you already know the exact name' and instructs to obtain it from list_virtual_machines first. It also names alternatives for live CPU/memory, for correlated host/alarms/events data, and for reconfiguration, leaving no ambiguity.

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, it discloses that all reads are batched, that the tool returns a correlated bundle rather than a list envelope, that the event timeline is merged and newest-first, and that the result is a point-in-time snapshot. It also adds an instruction to present output operationally rather than raw. These are meaningful behavioral details the annotations alone do not supply.

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: it states purpose, lists contents, gives usage triggers, sets expectations, and issues a clear output instruction. The most important information is front-loaded, and the length is justified by the tool's composite nature.

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 composite read-only tool with no output schema, the description is unusually complete: it enumerates the returned components, states ordering, clarifies batch behavior, warns against trending/acting, and even documents error behavior for unknown VM names. An agent has enough context to select and 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?

The schema already describes all three parameters at 100% coverage, so the baseline is 3. The description adds useful semantic context by telling the agent where to obtain vm_name ('Get it from list_virtual_machines or cluster_health_summary first') and by tying hours/event timeline to the point-in-time nature of the bundle, which goes slightly beyond the raw schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear operational question ('What is happening around this VM?') and names the exact function: 'one correlated drill-down.' It lists the constituent data sources (VM state, host, cluster, datastores, snapshots, alarms, performance, event timeline), making it unambiguously distinct from individual sibling tools and from the host/datastore investigation bundles.

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 tells the agent when to use it ('after cluster_health_summary names a problem VM, or when asked "what's going on with <vm>?"'), when not to use it ('Point-in-time snapshot — no trending'; 'Acting on what you find ... belongs to vmware-aiops'), and what to use instead of stitching lower-level tools together. This is strong alternative-selection 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 include readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful behavioral context on top: distinguishing a genuinely empty snapshot list via 'empty items with truncated False,' explaining the level hierarchy, and clarifying that mutating snapshot operations live in vmware-aiops. 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 efficiently organized into three short paragraphs, each earning its place: what/returns, alternatives and preconditions, and error behavior. Key scope and read-only details are front-loaded, and no sentence is 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?

The description fully equips an agent to call the tool correctly: exact parameter semantics, return envelope details, empty-result interpretation, the source for the VM name, and which sibling handles inventory-wide scanning. Despite having no output schema, the return structure is clearly documented.

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 are already described in the schema. The description adds extra practical meaning by requiring an 'exact name,' telling the agent to obtain it from list_virtual_machines, and reinforcing that the target defaults from config. This goes beyond the baseline schema-only 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?

The description opens with a specific verb and resource: 'List all snapshots of one VM, including the nesting hierarchy.' It specifies what is returned per row (name, description, created timestamp, state, level) and explicitly distinguishes itself from mutating snapshot operations and related 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?

Provides explicit when-to-use guidance: 'Use this for one known VM.' It names the alternative for sweeping inventory (snapshot_aging) and instructs the agent to get the VM name from list_virtual_machines first. It even warns about behavior for unknown names.

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?

While annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral context beyond those hints: the envelope structure with total and truncated, the meaning of mem_usage_pct (can read low under pressure), the ballooning/swapping signals as pressure indicators, and the point-in-time nature. It also names the specific counters behind fields, giving deep insight into data semantics.

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 well-structured with a clear lead sentence stating purpose, then a logical breakdown of the return envelope, data fields, and special semantics. Every sentence adds value, including the final routing sentence. It is dense but not wordy, and the information is front-loaded with the core purpose before diving into details.

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 tool's complexity (multiple metrics, envelope, counter names, memory semantics) and no output schema, the description covers all necessary context: what the return envelope contains, how to interpret mem_usage_pct versus ballooning/swapping, and the limitation to powered-on VMs. An agent can call this tool and interpret its results correctly without external documentation.

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 all three parameters. However, the description adds important semantic context: it explains that the default limit of 25 can cause truncation and that vm_name filters to a single VM. This goes beyond simple field descriptions and helps an agent understand the effect of parameter choices.

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 the tool reads real-time CPU/memory/disk/network utilization per VM and ranks them busiest first. It explicitly distinguishes from siblings by naming vm_info for configuration and vm_investigation_bundle for correlated host/alarms/events. The verb 'rank load' and resource 'per virtual machine' are specific and unambiguous.

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 this tool ('rank load across VMs') and provides direct alternatives for different use cases: vm_info for a single VM's configuration, vm_investigation_bundle for correlated data. It also notes the constraint that only powered-on VMs are included, which is a key usage condition.

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