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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, yet the description still adds real behavioral context: the exact rollup return shape ({total_snapshots, old_snapshots, vms_with_snapshots, threshold_days, snapshots[], hint}), the caveat that est_size_mb is only a lower bound because delta-disk growth isn't separable per-snapshot via the API, and an explicit scope boundary that deletion lives in vmware-aiops.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and scope in the first clause, then usage routing, then the return contract, then the caveat. No sentence is filler; the bracketed [READ] tag signals safety up front.

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

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

There is no output schema, so the description carries the return contract itself and does so concretely, including per-row fields and the size-estimate limitation. Combined with rich annotations, an agent has everything needed to call and interpret this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so limit/target/only_old/age_threshold_days are already fully documented. The description references threshold_days in the return shape but adds no parameter syntax, formats, or defaults beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource+scope: 'Sweep ALL VMs for snapshots and flag old / sprawling ones.' It immediately distinguishes itself from the sibling list_vm_snapshots by naming that tool as the single-VM alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing guidance: 'Use this for fleet-wide snapshot sprawl; prefer list_vm_snapshots when you only care about one VM.' The when-to-use and the named alternative are both stated, leaving nothing to inference.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description goes well beyond them with real behavioral caveats: privileges are checked on the vCenter/ESXi root folder only, ``not_granted_at_root`` does not imply no access, ``undetermined`` must never be read as granted, and group-derived permissions count in the verdict but are not listed by name. These are exactly the traps that would otherwise cause misreads.

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 a [READ] tag, then cleanly partitioned into When to use / What it returns / Gotchas. It is dense but every sentence carries information an agent needs, with no filler or restatement of the tool name.

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 takes on the burden of describing the return payload (target, account, checked_on, privileges map, tool block or tools_* lists, direct permissions) and it does so. Combined with the gotchas, an agent has everything needed 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 both parameters, including the 'None = all tools' default. The description adds the behavioral consequence of omitting ``tool`` (grouping into granted / not granted / undetermined) but no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description names the specific resource — the configured account on a target and its privilege verdict for a given tool — which no sibling tool covers (all siblings are inventory/health/investigation tools). The opening sentence is a noun phrase rather than an explicit verb+resource, but the scope is unambiguous once read with the 'What it returns' line.

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 concrete triggering conditions: a tool failed with NoPermission, returned fewer objects than expected, or you want to pre-check what the account may read. It also explains the two invocation modes (ask about one ``tool``, or omit it to classify every tool), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/destructive=false, yet the description goes far beyond them: it discloses the response envelope (real ``total``, ``stale_alarms`` count), the three ``condition_now`` states and their meanings, that expired-license alarms are re-checked against real license assignment, and the object_label vs entity_name distinction. It also guards against misreporting (cleared as live, unknown as resolved).

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 front-loads purpose and routing before the interpretive detail, and given there is no output schema the return-value semantics earn their space. The '[READ]' tag and some parenthetical asides are slightly noisy, but there is little waste.

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 and only two optional params, the description carries the full burden, and it does so: it documents the envelope, the meaning of each alarm field and condition state, and edge cases like empty items with truncated=False. An agent has everything needed to call and interpret 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% for the two parameters (limit, target), so the schema already carries the semantics. The description says nothing further about limit or target behavior, so it neither adds nor subtracts; baseline 3 applies.

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

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

The opening sentence names a specific verb and resource with scope ("Get active/triggered alarms across the VMware inventory"), leaving no ambiguity about what is returned. It explicitly distinguishes itself from the sibling get_cluster_health_summary, so an agent can route correctly without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States when to use this tool ("Use this for the raw alarm list"), names the preferred alternative for a different intent (get_cluster_health_summary), and prescribes the follow-up drill-down path via investigate_vm/investigate_host. This is explicit when/when-not/alternatives 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 read-only/idempotent/non-destructive, so the description correctly spends its words elsewhere: it explains the operational consequence of the data ('An expired ESXi cert drops host management'), the return shape (list envelope with a real total, rows containing host/not_after/days_until_expiry/expiring, soonest first), and an explicit coverage limitation. That is 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?

Front-loaded with the [READ] tag and the resource, then rationale, return shape, and routing guidance in tight order. Slightly dense with the mid-paragraph field enumeration, but 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?

No output schema exists, so the description carries the return-value burden and does so (envelope, fields, ordering), plus scope caveat and alternatives. Nothing an agent needs to call and interpret this tool 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 the schema already documents limit, target, and warn_days fully; baseline 3 applies. The description only indirectly gestures at warn_days via the 'expiring' flag and does not add format or default-syntax detail 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 a specific verb+resource ('Per-host ESXi management certificate expiry') and immediately scopes it against the obvious confusion: 'Host certificates only — the vCenter appliance's own certificate is not covered.' An agent can distinguish this from sibling status tools like get_license_status without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes usage: 'Use this alongside get_license_status and get_ntp_status for a platform-hygiene sweep,' and states the boundary condition for acting — 'Renewing a certificate is a write this skill cannot do; use vmware-aiops or vCenter directly.' Both when-to-use and when-not are covered.

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

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

Annotations already declare read-only/idempotent, but the description adds substantial behavior beyond them: it is point-in-time with no trending, top_issues is ranked worst-first, cleared vs unknown alarm handling differs, and thin-provisioned datastores past 100% are folded in. These are exactly the nuances an agent needs and none are derivable from 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?

Front-loads the core purpose and is organized into scannable blocks (purpose, return shape, alarm nuance, drill-down). It is on the long side and the alarm-paragraph is dense, but nearly every sentence carries actionable meaning, so waste is limited.

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 enumerating the return keys ({totals, top_issues, issues_total, clusters, snapshot, customization_hint}), explaining what each leads with, and clarifying that it is not the list envelope. Nothing needed to call and interpret it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter is well documented there, so the baseline is 3. The description reinforces a couple of semantics (top_issues capping, cluster_filter behavior) but adds little beyond what the schema descriptions already state.

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+resource ('health rollup for every cluster') and immediately frames the intent with a memorable question ('is anything on fire?'). It explicitly distinguishes itself from siblings by naming list_all_clusters + list_esxi_hosts + get_alarms as the thing it replaces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('Start here for single-vCenter triage'), when not to stitch the primitives yourself, and routes follow-up work to investigate_vm/investigate_host/investigate_datastore and get_cross_vcenter_attention. It even delegates remediation ('Acting on a finding 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real context beyond them: a 'not found' teaching error for a never-remediated cluster and a 503 that yields available: False mid-patch with a retry instruction. This error/retry behavior is not derivable from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Structured into when-to-use, what-it-returns, and gotchas sections with the operation and scope front-loaded. Every sentence carries distinct information; none 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?

With no output schema, the description takes on the burden of describing the return shape ({available, cluster, status, end_time, note, fields}) and the degraded cases. Nothing an agent needs to call and interpret this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds a discovery pointer ('see list_all_clusters') that tells the agent how to obtain the required cluster MoID, plus reiterates the MoID format with a concrete example.

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

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

Specific verb+resource+scope: the last vLCM remediation apply result on a single cluster. It explicitly names the sibling it is not (get_cluster_patch_compliance) so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States when to use ('after a patch/remediation, to confirm the last apply succeeded and when it finished') and gives the explicit alternative plus its selection condition ('use get_cluster_patch_compliance for current drift; use this for the outcome of the most recent apply'). 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 cover read-only/idempotent/non-destructive, and the description adds substantial context beyond them: the 503-mid-patch meaning of available=False with retry guidance, an explicit statement that it never runs remediation, and that the endpoint was verified 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?

Front-loads the one-line purpose then uses clear labelled sections (When to use / What it returns / Gotchas) with no filler sentences. It is longer than typical but each block carries distinct, load-bearing information; minor redundancy in the return-field list keeps it just short of 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 enumerating the return shape (available, cluster, status, hosts_total, non_compliant_hosts, scan_time, note, fields) and by flagging the required-MoID gotcha. An agent has everything needed to call and interpret this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds actionable meaning: cluster must be the MoID (domain-c123), the REST API requires it, and it must come from list_all_clusters rather than the display name. That routing advice goes beyond the schema's terse 'Cluster MoID' note.

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

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

States a specific verb (get), resource (cluster patch/software compliance), and scope (one cluster, vLCM, via vSphere Automation REST). It also explicitly contrasts itself with the sibling get_host_memory_tiering (per-host hardware vs per-cluster lifecycle state), so an agent can place it 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?

The 'When to use' section names the triggering condition (checking host match to assigned image/baseline before or after a patch cycle) and contrasts with a sibling. It does not, however, distinguish itself from the closely related get_cluster_last_apply_result, which an agent might reasonably confuse with compliance.

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 safe read/idempotent/open-world behavior, so the bar is lower, yet the description adds substantial context beyond them: graceful degradation with the unreachable list, guarantee that unreachable targets never count as healthy (totals.worst_status floor), identity-based dedup rules, point-in-time (no trending), and the fact it returns a rollup rather than the list envelope.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core question and the 'start here' decision, then layers degradation, dedup, and drill-in guidance in a logical order. It is dense but every block carries information; minor verbosity from the backtick field references 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 return-shape responsibility and does so — explaining top_issues, the per-target rollup, unreachable, also_seen_via, and the totals breakdown. For a multi-target aggregation tool this is complete enough to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (top_n, cluster_filter) are fully documented in the schema. The description explains the top_issues return field that top_n caps but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — rolls every configured target's cluster-health summary into one globally ranked top_issues list — and explicitly contrasts itself with the sibling get_cluster_health_summary. An agent can distinguish it without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear 'start here when the estate has more than one vCenter', names the alternative it replaces ('use this instead of calling get_cluster_health_summary once per target'), and routes follow-up work to investigate_vm/host/datastore. When-to-use, alternative, and drill-in path are all explicit.

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), yet the description adds substantial non-obvious behavior: point-in-time semantics, that provisioned_gb is aggregated by the endpoint over registered VMs so vCenter and direct ESXi diverge, that vm_count delimits the figure's coverage, and that vms_not_connected uses None as 'could not be read'. This is exactly the extra context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the tag, one-line summary, then the returned envelope and the risk rationale; the 'whose figure' paragraph is dense but every clause resolves a real ambiguity about divergent per-endpoint numbers. Slightly long and could be tightened, but nothing 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?

For a read-only list tool with no output schema, the description supplies the return fields, the risk interpretation, the point-in-time caveat and the multi-endpoint aggregation caveat — everything an agent needs to call it and correctly interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the two parameters (limit, target) are already documented in the schema. The description adds no argument syntax or format detail beyond the schema, so the baseline 3 for full-coverage schemas applies.

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

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

States a specific verb and resource ('per-datastore capacity') plus the distinctive capability (thin-provisioning over-commit) and explicitly contrasts itself with list_all_datastores, which it says 'lacks' the risk signal list. An agent can distinguish it from the 30+ siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: 'Use this for the capacity view, then investigate_datastore to drill into a specific datastore's hosts, VMs and alarms.' It also draws an out-of-scope boundary by handing remediation ('delete snapshots, storage vMotion') to another agent (vmware-aiops), which tells the agent when not to act here.

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, yet the description discloses behavior they cannot: a 5000-event read cap with read_truncated/read_note, severity 'unknown' events returned rather than filtered and counted in 'unclassified', and the trap that empty items with non-zero unclassified is not an all-clear. This is exactly the extra context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and the truncation caveat before the routing advice. It is long, but nearly every sentence encodes a distinct failure mode (truncation, unclassified, routine folding) rather than padding, so length is justified rather than wasteful.

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, and the description compensates by naming the return envelope fields (read_truncated, read_note, unclassified, classification_note, routine_folded) and their semantics. For a complex, open-world read tool this is complete enough to call and interpret correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic guidance beyond the schema: it explains why to narrow 'hours' (truncation means the oldest events were never examined) and how severity ranking works (skill ranking, else vCenter catalogue, else 'unknown' still returned). It does not restate the start/end interaction the schema already covers.

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: '[READ] Get recent vCenter/ESXi events filtered by severity.' It also names the siblings it is not (investigate_vm/investigate_host) and the adjacent log tool (scan_host_logs), so an agent can distinguish it 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?

Explicit routing: use for an inventory-wide event sweep; when the object is known, prefer investigate_vm/investigate_host; ESXi syslog lines are not events, use scan_host_logs. All three conditions (when, when-not, alternative) are stated.

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' safety profile, the description discloses important behavioral traits: ESXi 8.0U3+/9.x requirements, the pyVmomi field read, older hosts reporting 'unknown', and the meaning of 'noTiering' as a real checked result rather than missing data. This is rich context that materially affects interpretation.

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-structured with a [READ] tag, 'When to use', 'Returns', and 'Gotchas' sections. Every sentence adds useful information, and key constraints 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?

Even without an output schema, the description fully explains the return envelope and row fields, including edge-case values like uplift_ratio None and tiering_type 'noTiering'. It covers version prerequisites and invariant semantics, so an agent has everything needed to invoke and interpret 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?

Schema description coverage is 100%, so the schema already documents limit, target, and host_name. The description adds no parameter-specific syntax, defaults, or edge cases beyond what the schema provides, making the baseline score 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: per-host memory tiering and NVMe uplift ratio. It also states the unique value ('only source of measured tier byte sizes'), distinguishing it from sibling host tools like get_host_performance or list_esxi_hosts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear 'When to use' scenario and notes it is the only source of measured tier byte sizes, which effectively rules out alternatives. However, it does not explicitly state when-not-to-use or name any alternative tool for similar host-level information.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavioral context beyond them: 20-second sampling cadence, point-in-time only with no historical trend, disconnected or provider-less hosts being skipped rather than reported as zero, and busiest-first ordering. The 'skipped, not zero' detail is exactly the kind of edge case that prevents misreading a result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short paragraphs, front-loaded with the read-only marker and the resource, then the differentiating metrics, then the routing advice. No sentence is filler and each carries distinct 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?

There is no output schema, so the description carries the return-value burden and does it: the list envelope with a real total, the precise metric field names, and the sort order. Combined with the safety annotations and full schema coverage, an agent has everything needed to call and interpret this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so limit, target, and host_name are already documented in the schema, and the description adds little about them directly. It does imply ordering ('busiest first') which interacts with how limit truncates results, but that is marginal. Baseline 3 applies when the schema does the heavy lifting.

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 ('real-time CPU/memory/disk/network utilisation per ESXi host') and enumerates the exact metrics returned. It explicitly distinguishes itself from the sibling list_esxi_hosts by labelling that tool as static config versus this one as LIVE PerfManager data, so an agent can choose without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: 'Use this to find which host is hot, then investigate_host to drill into it, or get_vm_performance to see which VMs on it are driving the load.' It also names the condition that rules it out in favor of list_esxi_hosts (static config vs live metrics).

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: the list envelope shape, the per-row fields, and crucially the warning that missing rows do NOT mean healthy hardware, plus the hosts_without_sensors / cim_server_running explanation and the instruction to quote sensors_note. This is exactly the kind of misinterpretation guard the annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the [READ] marker and the core action, then layers return shape, the negative-result caveat, and routing guidance in short, dense sentences. No filler; every sentence carries operational 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 carries the return-value burden and does so fully: envelope with total, per-row fields, and the hosts_without_sensors structure. Combined with the safety annotations and 100% param coverage, an agent has everything needed to call and interpret this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (limit, target) are already documented in the schema. The description adds no syntax, defaulting, or filtering detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ([READ] Get hardware sensor status) with the exact data domain (temperature, voltage, fan) and scope (all hosts). It explicitly distinguishes itself from the closest sibling, get_host_performance, which handles CPU/memory load rather than physical hardware sensors.

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 when-to-use ('physical hardware only'), names the alternative for the adjacent use case (get_host_performance for CPU/memory load), and prescribes a concrete follow-up workflow (investigate_host after a red sensor). Both routing decisions an agent faces are covered.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered structurally. The description adds genuinely useful behavior: it returns a list envelope, guarantees 'truncated' is always False because every matching host is enumerated, and clarifies that all mutating service operations are out of scope. It stops short of documenting error/auth behavior, so not a full 5.

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 a [READ] marker and the core verb-resource pair, then return shape, then routing guidance in three tight sentences. No sentence is redundant; each adds a distinct fact (what, what it returns, when to use something else).

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

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

There is no output schema, but the description compensates by naming the envelope and every row field plus the truncated flag guarantee. Combined with the sibling routing and write-exclusion notes, an agent has everything needed to call and interpret this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: both 'target' (vCenter/ESXi target, default if omitted) and 'host_name' (exact-name filter, None = all hosts) are already documented in the schema. The description's 'Every matching host is enumerated' only loosely reinforces the host_name semantics without adding format or syntax detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get host service status') and immediately enumerates the returned fields (host, service key, label, running, policy). It also names the sibling it should not be confused with (get_ntp_status) and the write-capable alternative (vmware-aiops), so an agent can distinguish it 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?

Explicit when-to-use ('check whether SSH, NTP or the firewall service is in the expected state'), an explicit alternative with its selection condition ('For NTP specifically prefer get_ntp_status, which also reports the configured servers'), and an explicit exclusion ('Starting or stopping a service is a write — this skill cannot do it').

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, and the description adds genuinely new behavioral context: 'truncated' is always False (complete inventory), license keys are never returned, and 'assignments' is null with a note when the account lacks read permission. It also flags that assigning a license is a write, which the read-only annotations would not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the one-line purpose, then return shape, then usage. Information-dense and mostly waste-free, though it runs long across several sentences and the assignments/expiry explanation could be tightened.

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

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

With no output schema, the description carries the full burden of describing returns and does so thoroughly (row fields, envelope, unlimited flag semantics, assignments behavior). An agent has everything needed to 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?

Single optional 'target' parameter with 100% schema description coverage, so the schema already documents it. The description never mentions 'target' or its default-to-config behavior, adding no meaning beyond the schema — baseline 3 applies.

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

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

Opens with a specific verb+resource+scope: '[READ] vCenter/ESXi license inventory with usage and expiry.' An agent can distinguish this from sibling read tools immediately, and the field list (edition_key, total/used units, expiration) further nails down the resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the use case ('catch over-allocation or an approaching expiry') and positions itself in a platform-hygiene sweep alongside get_certificate_status and get_ntp_status. No when-not-to-use or exclusion guidance, which is the only gap.

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), yet the description adds substantial non-obvious context: truncated is always False, null-vs-false semantics for unreadable hosts, hosts_unreachable/hosts_unreadable envelope counts, and ntp_sources_consistent cross-host comparison. This is exactly the behavioral detail annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose and the return envelope, then handles edge cases in dense but relevant prose. It is long, but nearly every sentence addresses a real semantic trap (null vs false, unreachable vs unreadable); minor tightening is possible but little is 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?

No output schema exists, so the description must carry the return contract — and it does, enumerating each row field, the healthy flag logic, and the envelope-level counts/notes. Nothing an agent needs to call and interpret this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both params (target, host_name) are already documented in the schema, so baseline 3 applies. The description adds no syntax or format detail beyond what the schema states for these two filters.

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 ("Per-host NTP configuration health (servers + ntpd service state)") and immediately distinguishes itself from the closest sibling by noting the SOAP API does not expose clock offset. An agent can tell exactly what this returns versus get_host_services without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: "Prefer this over get_host_services for time problems," plus the exclusion (not for live offset — use esxcli) and the write boundary ("Fixing NTP is a write; use vmware-aiops"). This covers when-to-use, when-not, and alternatives all in one place.

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 establish read-only/idempotent/non-destructive, and the description adds substantial context on top: the list envelope with a real total, the exact field set, descending-memory ordering, the -1 sentinel meaning 'unlimited', and the caveat that pool names are not cluster-qualified. That last point is a non-obvious data trap an agent needs.

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 [READ] tag and usage trigger are front-loaded and the prose is largely waste-free, though the mid-paragraph enumeration of every returned column is somewhat heavy. With no output schema that detail arguably earns its place, but it reads more densely than necessary.

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

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

With no output schema, the description fully carries the return-value burden — envelope shape, columns, ordering, sentinel semantics — plus the known ambiguity caveat and usage routing. Nothing needed to call and interpret it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both 'limit' and 'target' are documented in the schema. The description adds nothing specific beyond this — the 'limit of -1' line refers to a returned field, not the limit parameter — so the baseline 3 applies while the schema does the work.

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

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

The opening verb+resource is exact: per-resource-pool CPU/memory reservation, limit, and current usage. It names the concrete row fields and the sort order, so an agent immediately knows what this returns and how it differs from cluster- or VM-level 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?

It gives an explicit trigger ('a VM is throttled but its host is not busy — the cap is usually the pool') and routes to named alternatives (get_vm_performance for which VMs, get_cluster_health_summary for the cluster picture). This is genuine when-to-use plus 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 declare readOnlyHint/idempotentHint, and the description goes well beyond them: it explains the response envelope {available, note, fields}, that available:False signals a 503 or pre-9.1 vCenter with reason distinguishing them, and that this is not a failure condition. This is exactly the failure-mode disclosure an agent needs and cannot get from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the [READ] marker and purpose, then uses short labeled blocks (When to use, What it returns, Gotchas) so an agent can scan the relevant part. Slightly redundant between the "What it returns" and "Gotchas" mentions of the 9.1/available:False behavior, keeping it short of 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 present, the description fully covers the return envelope and its non-obvious sentinel value, plus the version prerequisite that gates the endpoint. Nothing an agent needs to interpret a result or diagnose an empty response 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?

Only one optional parameter (target) with 100% schema description coverage, so the schema already carries its meaning. The description adds no syntax, defaulting, or target-selection detail beyond the schema, which is the expected baseline when the schema is complete.

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?

Names a specific verb and resource (read vCenter appliance deployment size) and immediately scopes it against the rest of the toolset by noting it covers capacity-planning context that inventory/perf tools do not. An agent can tell it apart from list_all_* and get_*_performance siblings without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Includes an explicit "When to use" block and states what this tool covers that inventory/perf tools do not, giving both the selecting condition and the boundary against adjacent categories. No ambiguity about when to reach for it.

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

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

Annotations cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds far more: it is a lower bound, not a duration; duplicate VM names raise rather than resolve; the in-flight creation task is invisible; and it flags history_unavailable / coverage_note / window_fully_covered as fields an agent must read before reporting an all-clear. This is unusually rich disclosure beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the one-line purpose before any caveats, and virtually every sentence carries a real misinterpretation hazard (unmatched rows, open cycles, duplicate names). It is still very long and dense for a single read tool, and a few clauses could be trimmed without losing guidance.

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 describing the return shape — and it does: rollup vs list envelope, the four hour statistics, latest/longest cycle, unmatched rows, and the three sentinel fields. Nothing an agent needs to interpret the result correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it explains that the returned counts can describe a shorter period than the 'days' argument asked for due to task.maxAge retention, tying the days parameter to an expiry semantic. It also ties limit to include_cycles, though that is largely already in 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 opening line states a specific verb, resource and unit ('how long backups held a snapshot open on one VM, from task history'), and the description later names the sibling tools it is not (list_vm_snapshots, find_aging_snapshots). An agent can distinguish it from every other VM/snapshot tool without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing: 'For snapshots that exist right now use list_vm_snapshots or find_aging_snapshots,' and frames the tool's niche (recovering the backup window from vCenter task history without backup-server credentials). When-to-use is stated positively and negatively.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavior beyond them: the return is a single detail dict rather than a list envelope, coverage is static configuration only, and an unknown name yields a teaching error instead of an empty match. That error semantics disclosure is exactly the kind of thing annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb+resource, then routing, then the input constraint; every sentence carries routing or error information. The '[READ]' prefix is mildly redundant with readOnlyHint=true, keeping it just short of 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 explicitly describes the return shape (single detail dict, not a list envelope) and what it does and does not cover (static config vs. live performance). Everything an agent needs to call this correctly is present.

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 goes further by stressing that vm_name must be the exact name and by describing the failure mode for a wrong name, which materially shapes how the agent supplies the argument. It says nothing extra about target, but that parameter is already documented as an optional config default.

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

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

States a specific verb (Get) and resource (one VM) and enumerates the returned fields (CPU, memory, disks, NICs, snapshots). It explicitly distinguishes itself from get_vm_performance, investigate_vm, and list_virtual_machines, so an agent can route correctly 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 when-to-use ('when you already know the exact name'), a prerequisite workflow ('get it from list_virtual_machines first'), named alternatives for other needs, and a when-not clause ('Reconfiguring the VM belongs to vmware-aiops'). 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 readOnly/idempotent/non-destructive, but the description adds substantial behavior beyond them: only powered-on VMs (no real-time provider) are returned, results are point-in-time, ordering is busiest-first, the list envelope carries total/truncated, and it discloses a metric pitfall (mem_usage_pct can read low under pressure; balloon/swapped are the real pressure signals) plus a counters field mapping.

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 '[READ]' tag front-loads the operation type and the rest is dense with no filler, though the mem_usage_pct/counters passage is long enough to slightly dilute the core routing message. Every sentence carries actionable information, so nothing is truly 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?

No output schema exists, yet the description fully explains the return shape (list envelope with real total and truncated, named live fields, counters mapping) and the powered-off exclusion. An agent has everything needed to call and interpret it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; however the description adds meaning beyond the schema by tying the default limit of 25 to the 'truncated' flag semantics and clarifying that an omitted vm_name covers all powered-on VMs, which the schema does not state.

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+resource ('Real-time CPU/memory/disk/network utilisation per virtual machine') and explicitly distinguishes itself from siblings by naming get_vm_info and investigate_vm with their respective scopes. An agent can select it correctly 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: 'Use this to rank load across VMs; for one VM's configuration use get_vm_info, and to see the same VM correlated with its host, alarms and events use investigate_vm.' Names the alternatives and the condition selecting each.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: reads are batched, returns a correlated bundle rather than the list envelope, excludes per-datastore latency, is a point-in-time snapshot with no trending, and unknown names yield a teaching error.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded scope statement, then alternative-routing, then bundle contents, then boundaries — every sentence earns its place and there is no filler. Length is justified by the composite return.

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 enumerates the returned bundle (capacity/free space/accessibility, mounting hosts, VM rollup, alarms, merged event timeline) and states what is excluded, so an agent knows exactly what it gets back.

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 hours, target, and datastore_name are already documented structurally; the description adds only the provenance hint for datastore_name (from list_all_datastores or get_datastore_capacity). Baseline 3 is appropriate where the schema carries the parameter burden.

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

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

Specific verb (investigate) plus resource (datastore), and it explicitly frames the tool as a correlated drill-down that replaces stitching four named sibling tools together. An agent can distinguish this from list_all_datastores, get_datastore_capacity, get_alarms, and get_events 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?

Explicit when-to-use ('Reach for it after get_cluster_health_summary flags storage pressure'), explicit alternative-avoidance ('instead of stitching ... yourself'), and explicit when-not / hand-off ('Freeing space ... belongs to vmware-aiops'). 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 cover read-only, idempotent, non-destructive safety. The description adds real beyond-annotation context: point-in-time snapshot with no trending, batched reads, and a note that unknown host names produce a teaching error. It does not, however, describe pagination or size/rate characteristics of the merged timeline.

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 core question, followed by the replacement statement, the return shape, the trigger condition, and routing to alternatives. Every sentence earns its place with no 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?

For a read-only aggregator with no output schema, the description covers what comes back, how to interpret it ('operational language; do not dump it raw'), when to invoke it, and where to go for log-level detail or corrective action. An agent has everything needed to call and use 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 host_name, hours, and target are all documented in-schema (including the default 24h look-back and the teaching-error behavior). The description itself adds little parameter-level detail beyond naming the bundle contents, so the schema 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 a specific question and verb ('one correlated drill-down'), then enumerates exactly what the bundle contains (host state, cluster, VM rollup, datastores, alarms, performance, merged timeline). This clearly distinguishes it from siblings like get_host_performance or get_events, which it explicitly says it replaces.

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 when-to-use ('after get_cluster_health_summary flags a host'), when-not-to-use ('for syslog lines use scan_host_logs'), and routes action-taking elsewhere ('maintenance mode, evacuate belongs to vmware-aiops'). It also names the four tools it stitches together. 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description focuses on behaviors they can't express: it returns one correlated bundle rather than the list envelope, all reads are batched, it is a point-in-time snapshot with no trending, and unknown VM names return a teaching error. Only gap is that it doesn't hint at cost/latency or size of the merged timeline.

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 question it answers and the replacement claim, then return shape, then invocation triggers, then boundary. Every sentence carries distinct information, though the list of covered data sources is dense and could be trimmed.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: VM state, host, cluster, datastores, snapshots, alarms, live performance, and a newest-first merged event timeline. It also instructs how to present the result ('explain it in operational language; do not dump it raw'), which is unusual and useful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every parameter is already documented there, including the default 24-hour window and the source for vm_name. The description adds only marginal param context ('merged event timeline' implying the hours window drives it), so the baseline 3 is appropriate.

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

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

States a specific verb (investigate/drill-down) and resource (this VM) with explicit scope: 'one correlated drill-down'. It directly distinguishes itself from the composite siblings it replaces (get_vm_info, list_vm_snapshots, get_alarms, get_vm_performance, get_events) and from investigate_host/investigate_datastore by naming the VM as the object.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: use it instead of stitching five specific sibling calls, reach for it after get_cluster_health_summary flags a problem VM, or on a 'what's going on with <vm>?' question. It also draws a clear boundary for when-not: acting on findings (power, migrate, delete snapshot) 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 cover read-only/idempotent/non-destructive, and the description goes well beyond them: it discloses the required Sessions privilege, the graceful-degradation behavior for low-privilege accounts (single explanatory row instead of a traceback), and the default folding of vCenter solution users into service_sessions. That is exactly the privileged-operations context an agent needs.

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 core purpose, then return fields, then usage guidance. The row-field enumeration (user_name, full_name, login_time, ...) is dense but earns its place given there is no output schema. Slightly long, but no filler sentences.

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 enumerating the row fields and the envelope's total, plus the current flag and service-session folding. Permissions, targeting and the read-only boundary are all covered, so nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, but the description adds real semantic value for include_service by explaining that solution users are folded by default and surfaced in the service_sessions count. It does not add anything for limit or target, but the default-behavior clarification lifts it above 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?

Opens with a specific verb and resource: 'Currently authenticated vCenter/ESXi sessions (who is logged in).' The scope is unambiguous and it is clearly distinguishable from sibling monitoring tools like list_all_clusters, and it explicitly names list_active_tasks as a related-but-different tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit purpose statement ('Use this to attribute a change to a person'), names the complementary sibling (list_active_tasks, which names the user who started each task), and states a boundary ('terminating a session is not supported here'). When-to-use and when-not-to-use are both covered.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds non-obvious behavior: the short vCenter recent-task retention window, ordering (running/queued first, then newest), and the consequence that limit silently drops the oldest rows. It also describes the return envelope and the truncated flag, none of which the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the [READ] tag and the core question, then layers in ordering, envelope, and retention details efficiently. Slightly redundant in restating read-only ('[READ]' plus 'Read-only') already covered by annotations, but no sentence is wasted overall.

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 describing the return envelope and per-row fields, plus truncation and retention caveats. Nothing an agent needs to call or interpret this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description still adds meaning by explaining that ordering makes limit drop the oldest records and that include_recent pulls in just-completed/failed tasks, which the terse schema labels do not convey.

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 in-flight vCenter tasks) and frames the question it answers ('why is the cluster busy?'). It explicitly distinguishes itself from siblings get_host_performance and list_active_sessions, so an agent can select it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('Use this before blaming load'), the alternative it complements (get_host_performance) and the pairing tool (list_active_sessions) to attribute the task to a user. It also routes the out-of-scope action (cancelling a task) 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine context beyond that: it returns a list envelope with a real total, rows carry a moid (e.g. domain-c123) that is the cluster id consumed by vLCM patch tools, and the data is static topology only. Pagination behavior with the limit parameter is left implicit, which keeps it from a 5.

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 [READ] tag and the purpose sentence are front-loaded and the second paragraph is dense but each clause earns its place (return shape, id semantics, alternative routing). Slightly heavy phrasing ('supersedes stitching this with...') keeps it short of 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 carries the burden of describing returns and does so: list envelope with total, row fields, and the moid identifier. Combined with the routing guidance to get_cluster_health_summary, an agent has everything needed to call and interpret this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both limit and target are already documented in the schema; the description adds no syntax or format guidance for them. The moid explanation is about return values, not parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ('List clusters') plus the exact row contents (host count, DRS/HA status, resource totals), and explicitly contrasts itself with get_cluster_health_summary and the manual stitching of list_esxi_hosts/get_alarms. An agent can distinguish it from every sibling without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use ('use this to resolve a cluster name'), a when-not ('static topology only'), and names the superseding alternative (get_cluster_health_summary) along with the anti-pattern it replaces. 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds meaningful behavior beyond that — it returns raw free/used values only (no derived over-commit analysis) and the list envelope reports a real total rather than a truncated count. It does not mention auth/permission requirements or rate limits, so it stops short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the [READ] marker and the core purpose, then a second sentence devoted entirely to routing. Two sentences, no filler; the minor [READ] redundancy against readOnlyHint costs nothing.

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

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

With no output schema, the description carries return-shape responsibility and does so: it enumerates the fields returned and notes the envelope's total semantics. For a simple two-parameter list call with full annotation coverage, nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% — limit (None = all) and target are already documented in the schema. The description adds no syntax, default, or format detail beyond that, so the baseline 3 applies.

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

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

Specific verb+resource ("List datastores") plus the exact fields returned (capacity, free space, type, VM count). It explicitly names the two sibling tools it is not (get_datastore_capacity, investigate_datastore), so an agent can distinguish it 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?

Gives an explicit routing rule: use this first to resolve a datastore name, then get_datastore_capacity for thin-provisioning over-commit risk, or investigate_datastore to drill into one datastore. Both the when-to-use and the when-to-use-something-else conditions are stated.

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, so the safety profile is covered. The description adds genuine behavioral context beyond that: the envelope carries a real 'total', and the response deliberately omits VLAN, uplink, and NSX overlay detail, which preempts wrong assumptions about richness. It doesn't address pagination behavior, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, zero filler, with the read-only marker and resource leading. The scope limitation and the routing to siblings each earn their place.

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

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

With no output schema, the description carries the return-value burden and does so by naming the returned fields and the real total. It stops short of explaining ordering or pagination semantics tied to 'limit', which is the only remaining ambiguity for a two-optional-param list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and both parameters (limit, target) are already fully documented in the schema. The description adds no parameter-level syntax or defaulting nuance, so the baseline 3 applies.

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

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

States a specific verb and resource ('List networks') and enumerates the returned fields (name, vm_count, accessibility), plus explicitly scopes out VLAN/uplink/NSX overlay detail. An agent can distinguish this from list_all_clusters, list_all_datastores, and NSX tooling 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 an explicit use case and workflow: resolve a port-group name here, then call get_vm_info for the NICs of one VM. It also names an exclusion ('NSX segments live in vmware-nsx'), so the agent knows when not to use it and where to go instead.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real value beyond them: the '[READ]' marker, the warning that returned values are static config only (cores, total GB) not live load, and the note that 'total' in the envelope is the real host count even when 'limit' truncates the list. It stops short of describing other envelope fields or auth/target-resolution behavior, so it is strong but not complete.

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?

Two short sentences plus a parenthetical; the scope and return contents are front-loaded and the sibling routing comes last. 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?

With no output schema, the description carries the burden of explaining returns and does so reasonably: it enumerates the core host fields and clarifies the envelope's 'total' semantics. It could say more about the remaining envelope structure or how targets resolve, but an agent has enough 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% and both parameters ('limit', 'target') are already documented with defaults, so the description need not re-explain them. It adds only an indirect hint about truncation via the 'total' remark, which is baseline-level value here.

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 ESXi hosts') plus the exact fields returned (CPU cores, memory, version, VM count, uptime). It also distinguishes itself from nearby inventory siblings by scoping to hosts and their static config. An agent can identify this as the host-inventory tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the two conditions and alternatives: use this to resolve a host name, then get_host_performance for live load, or investigate_host to drill into a single host. This routes the agent between three related tools with no inference required.

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?

With annotations already declaring readOnly/idempotent/non-destructive, the description goes well beyond: it discloses the truncated result envelope, that `total` is post-filter, that >50 VMs with no limit/fields returns only the first five fields (mode says which), and that `vms` is a deprecated pre-1.8.0 alias removed in 2.0. These are real behavioral constraints an agent would otherwise miss.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and routing, and every sentence carries behavioral weight. The envelope-key enumeration is slightly dense and could be trimmed, but it substitutes for a missing output schema, so it 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?

This is a 7-param, no-output-schema listing tool, so the description must carry the return-shape burden — and it does, naming the envelope keys, the truncated flag, the mode field, and the deprecated alias. Nothing an agent needs to call and interpret it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains the limit/fields interaction that triggers truncation and singles out name_filter as the tool's intended mechanism for locating a VM by name. That is value beyond the per-parameter 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?

Opens with a specific verb+resource and scope ("List virtual machines, with filtering, sorting, and field selection") and immediately distinguishes itself from siblings by naming get_vm_info, investigate_vm, and get_cluster_health_summary as the routes for other needs. An agent can tell exactly what this tool is for without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States a concrete use case ("resolve an exact VM name") and explicit routing: get_vm_info for detail, investigate_vm to drill in, get_cluster_health_summary for a fleet-wide view. Alternatives are named with the conditions that select them, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine beyond-annotation context: the return envelope shape, level semantics, empty-items meaning, and the teaching-error behavior on unknown 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] marker and purpose, then return semantics, then routing guidance. A couple of phrases (the truncated-False explanation) are slightly verbose but each sentence carries useful 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?

For a read-only list tool with no output schema, the description supplies return structure, level semantics, empty-result meaning, error behavior, and alternative-tool routing. Only minor gaps remain, such as pagination/truncation mechanics beyond the empty-items note.

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 both parameters (target, vm_name) are already documented in the schema. The description notes vm_name must come from list_virtual_machines and that an unknown name yields a teaching error, which is mild added meaning over the schema 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?

Specific verb+resource ('List all snapshots of one VM') with explicit scope ('including the nesting hierarchy'). It distinguishes itself from siblings by naming find_aging_snapshots as the sweep alternative and confining itself to one known VM.

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?

Clearly states when to use this (one known VM) versus find_aging_snapshots (whole-inventory sweep), and routes the agent to list_virtual_machines for the name. Lacks explicit when-not conditions beyond the sibling contrast, 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 cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial context beyond them: grouping behavior and what each mode returns, that total is null by design, that logs_unavailable enumerates unreadable hosts (with the Global.Diagnostics permission example), that empty items is only meaningful when logs_unavailable is empty, and that every call re-reads the last lines afresh. Missing only explicit rate-limit or cost expectations for large lines values.

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?

Effectively front-loaded, with the purpose in sentence one and usage guidance placed after the return-shape detail. It is on the long side with several dense parentheticals (severity tokens, envelope fields), but with no output schema almost all of that text is load-bearing rather than 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?

Absent an output schema, the description fully specifies the return envelope ({items, returned, limit, total, truncated, hint}), the per-mode item shapes, the null-total caveat, and the logs_unavailable contract. Four optional parameters plus a mutation-free read operation are covered adequately; nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning on top: it explains the differing row shapes produced by group=true vs group=false, the default grouping rationale, and the exact-match failure semantics of host_name. It is more than a restatement of the schema descriptions.

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 ('[READ] Scan recent ESXi host syslog lines for error/warning patterns') and immediately distinguishes itself from siblings by naming get_events and investigate_host as a different data source ('vCenter events and ESXi syslog are different sources'). An agent can route between this and the event tools 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?

States the trigger condition explicitly ('Use this when get_events or investigate_host show a host in trouble but not why') and names the alternatives. It also gives operational guidance — filter with host_name for speed on large clusters, get exact names from list_esxi_hosts, and warns that a non-matching name errors rather than returning empty.

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