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

Goes well beyond the annotations: it discloses the response envelope with a real total, enumerates row fields, mentions the current-session flag, and describes privilege-dependent behavior (single explanatory row instead of a traceback). The read-only nature is consistently reinforced. No contradiction with readOnlyHint/idempotentHint/destructiveHint.

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

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

Three dense, purposeful sentences with no filler. The core purpose is front-loaded, followed by return shape, privilege caveat, use case, and limitation. Every sentence earns its place.

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

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

Despite lacking an output schema, the description covers the return format, key fields, privilege requirements, failure/fallback behavior, and a practical pairing with active_tasks. The low parameter count and full schema coverage mean nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, with both limit and target already well described in the schema. The description does not add extra parameter-level detail, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Returns') and resource ('currently authenticated vCenter/ESXi sessions'), and clarifies 'who is logged in'. The scope is unmistakable and distinct from sibling list tools, with the [READ] marker reinforcing intent.

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 to use it 'to attribute a change to a person' and recommends pairing with active_tasks. It also notes that session termination is not supported, which is a clear exclusion. It could more explicitly contrast against read-only siblings, but the context is strong.

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

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

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

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

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

The description is moderately long but every sentence earns its place: purpose, output shape, caveat, usage guidance, and cancellation boundary. It is front-loaded with the core purpose and then adds operational context without repetition or filler.

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

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

With no output schema, the description compensates by detailing the return envelope and row contents. It covers the tool's safety profile, its relationship to sibling tools, and the important vCenter retention caveat, making the tool fully actionable for an agent.

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

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

Schema description coverage is 100%, so the schema already fully documents limit, target, and include_recent. The description adds contextual meaning around the returned envelope and the 'optionally just-completed' behavior, but it does not need to add parameter-level details; the baseline of 3 is appropriate.

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

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

The description states a specific verb ('[READ] In-flight... vCenter tasks') and a precise resource, and immediately frames the tool's purpose with 'Answers "why is the cluster busy?"'. It differentiates from siblings by explicitly comparing to host_performance and active_sessions, so an agent can select it without opening other schemas.

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

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

It gives explicit when-to-use guidance: 'Use this before blaming load' and explains that an in-flight migration/clone explains pressure shown by host_performance. It also provides an exclusion by noting that cancelling a task belongs to vmware-aiops, and recommends pairing with active_sessions to see who started the task.

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

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

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

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

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

The description is longer than strictly necessary (the outage-motivation sentence is not required for invocation), but it is front-loaded with the essential read/resource and every other sentence carries either return-format or routing information. Slight trimming would make it a 5.

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

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

With no output schema, the description compensates by listing the returned row fields, sort order, scope limitation, and read-only boundary. Together with the fully documented schema, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so all three parameters (limit, target, warn_days) are already documented in the schema. The description adds no new parameter-level detail beyond mentioning the expiring flag, so the baseline of 3 is appropriate.

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

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

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

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

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

Positions the tool as part of a platform-hygiene sweep alongside license_status and ntp_status, and explicitly states what it cannot do (renew certificates) with a pointer to vmware-aiops or vCenter. This gives an agent clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description reinforces this with '[READ]'. It adds valuable behavior beyond annotations: the return envelope shape, the 'not the list envelope' caveat, the point-in-time/no-trending limitation, and the instruction to echo customization_hint last.

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

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

The description is dense but every sentence carries distinct value: purpose, use case, alternative, return behavior, point-in-time semantics, and drill-down routing. It is front-loaded with the core purpose and remains highly scannable.

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 aggregation tool with no output schema, the description supplies the necessary return keys, the ranking behavior, the absence of trending, and the recommended next steps. All parameters are already fully described in the schema, so nothing needed to invoke the tool 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 schema fully documents all four parameters. The description does not add parameter-specific detail beyond what the schema already provides, which makes the baseline 3 appropriate.

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

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

The description clearly identifies the tool as a one-glance health rollup for clusters, with a specific verb ('rollup', 'scores', 'ranks') and resource ('every cluster'). It distinguishes itself from sibling tools by explicitly saying to use it instead of stitching list_all_clusters + list_esxi_hosts + get_alarms.

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

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

It explicitly says 'Start here for single-vCenter triage' and names the exact alternative tools for drill-down (vm_investigation_bundle, host_investigation_bundle, datastore_investigation_bundle) and broader coverage (cross_vcenter_attention). It even tells the agent that acting on a finding belongs to vmware-aiops, which is strong routing guidance.

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

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

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

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

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

The description is well structured under clear headings, is front-loaded with the core read intent, and every sentence earns its place. It packs usage timing, return shape, error behavior, and a cross-tool pointer without unnecessary padding.

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

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

With no output schema, the description fully compensates by enumerating the return fields and expected error cases. It also covers when to retry, how to interpret the MoID, and the read-only nature, making it complete for an agent to call the tool effectively.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds extra meaning by explaining that 'cluster' is the cluster MoID and pointing to list_all_clusters for discovery, which goes beyond the schema's 'Cluster MoID' text.

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

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

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

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

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

Explicit guidance is provided: use after a patch/remediation to confirm the last apply succeeded and when it finished. It names the alternative cluster_patch_compliance and tells the agent exactly when to use that instead, so the agent can select correctly.

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

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

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

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

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

The description is well-structured with labeled sections: purpose, when to use, return behavior, and gotchas. It is front-loaded with the core purpose and maintains focus without redundant filler. Each section adds operational value, and the length is appropriate given the absence of an output schema.

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

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

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

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful value by specifying that 'cluster' must be a cluster MoID such as domain-c123, not a display name, and directs the agent to list_all_clusters for the correct value. It also explains the requirement originates from the REST API, which clarifies parameter semantics beyond the schema.

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

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

The description opens with a clear verb and resource: '[READ] vLCM software (patch) compliance for one cluster.' It goes further than a generic statement by explaining what compliance means: checking whether hosts match their assigned image/baseline. It also distinguishes itself from sibling host_memory_tiering by noting per-cluster lifecycle state instead of per-host hardware.

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

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

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

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

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

Beyond the readOnly/idempotent annotations, the description discloses graceful degradation for unreachable targets, states that results are point-in-time with no trending, and explains that the return value is a rollup rather than the list envelope. This gives the agent useful behavioral expectations not captured in annotations.

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

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

The description is front-loaded with the core purpose and each sentence adds distinct value: scope, aggregation model, alternative, return shape, failure handling, point-in-time semantics, and next-step guidance. There is no filler or repetition.

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

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

Despite lacking an output schema, the description explains the key return concepts: globally ranked top_issues, per-target rollup, unreachable section with reasons, and vcenter tagging. Combined with the parameter schema and annotations, the agent has enough context to invoke the tool correctly and 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?

The input schema already provides full descriptions for both top_n and cluster_filter, including defaults and behavior. The tool description does not add much specific parameter-level detail, but that is acceptable because schema coverage is 100%, so the baseline of 3 applies.

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

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

The description uses a clear interrogative framing ('What needs attention now?') tied to a specific resource ('every configured vCenter') and delivers one aggregated, globally ranked list. It explicitly contrasts itself with cluster_health_summary and the investigation bundles, making the tool unmistakable.

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

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

It explicitly says to 'Start here when the estate has more than one vCenter' and tells the agent to use this 'instead of calling cluster_health_summary once per target and merging yourself.' It also names the drill-in successors for follow-up, leaving no ambiguity about when and with what to use this tool.

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

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

Annotations already convey readOnly and idempotent behavior. The description adds behavioral context beyond that: the list is ordered 'riskiest first', it is 'point-in-time', and it explains the overcommit semantics (over 100% means more promised than physically exists, thin datastore can fill while showing free). This goes beyond the annotation baseline, enriching agent understanding.

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

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

Every sentence earns its place: first sentence states the core purpose and return fields, second explains the unique risk signal, third provides usage and drilldown guidance. There is no filler, and the core information is front-loaded. The structure is tight and efficient.

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-based list tool with no output schema, the description fully specifies the return fields, ordering, point-in-time nature, and the key risk concept. It also covers the follow-up actions and ownership boundaries. An agent has everything needed to decide when and how to invoke it correctly.

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

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

The schema description coverage is 100% (both 'limit' and 'target' are documented in the schema). The description does not add any parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate. No additional value is needed.

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

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

The description opens with '(READ) Per-datastore capacity with thin-provisioning over-commit.' It specifies the resource (datastores) and the unique angle (thin-provisioning over-commit, risk signal) and explicitly contrasts with list_all_datastores, which it says lacks the overcommit signal. This distinguishes it from siblings without ambiguity.

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 when to use it (capacity view) and then routes to datastore_investigation_bundle for drilling into hosts/VMs/alarms, and to vmware-aiops for reclaiming actions. This provides explicit context and alternatives, fulfilling the usage guidance requirement fully.

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

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

Annotations already mark it read-only, but the description adds substantial behavioral detail: batched reads, correlated bundle vs list envelope, point-in-time snapshot semantics, output presentation guidance, and the caveat that per-datastore latency is omitted. No contradiction with annotations.

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

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

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

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

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

For a complex bundle tool with no output schema, the description fully carries the return semantics, including what is and is not included. It also positions the tool within the workflow relative to cluster_health_summary and remediation tools, so an agent has enough context to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents datastore_name, hours, and target fully. The description reinforces the exact-name requirement and suggests where to source the name, but adds little new parameter-level meaning beyond the schema.

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

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

The description opens with a concrete question and states it is a 'one correlated drill-down' for a datastore, listing exactly what the bundle contains (capacity, free space, hosts, VM rollup, alarms, event timeline). It differentiates itself from the individual list/get tools by explicitly naming the stitching alternative, and from sibling investigation bundles by the resource type.

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

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

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

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond annotations: it returns a list envelope with a real 'total', each alarm carries 'suggested_actions' naming a companion remediation tool, and empty 'items' with 'truncated' False means there are truly no active alarms. This prevents a likely misinterpretation.

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

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

The description is front-loaded with purpose and then compactly covers return semantics, empty-result interpretation, and routing guidance. Every sentence earns its place, and the total length is reasonable for the amount of behavioral and routing information it conveys.

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

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

Given the simple two-parameter schema, rich annotations, and no output schema, the description provides all necessary context: return envelope shape, the meaning of 'total', remediation guidance via suggested_actions, and explicit handling of empty/truncated results. Nothing an agent needs to invoke or interpret this tool 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 parameters (limit and target) already have clear descriptions in the schema. The tool description does not add any parameter-level semantics, so the baseline score of 3 is appropriate.

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

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

The description opens with '[READ] Get active/triggered alarms across the VMware inventory,' naming a specific verb, resource, and scope. It further distinguishes itself from siblings by calling itself the 'raw alarm list' and pointing to alternatives like cluster_health_summary and investigation bundles.

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

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

Usage guidance is explicit: 'Use this for the raw alarm list; prefer cluster_health_summary when you want alarms folded into a whole-cluster verdict. Then drill into the flagged object with vm_investigation_bundle or host_investigation_bundle.' This tells an agent exactly when to select this tool and when to route elsewhere.

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

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

The annotations already mark the tool read-only and idempotent, but the description adds substantial behavioral context beyond them: the envelope behavior, the reason total is null, the 'unknown' severity being returned rather than filtered, the unclassified counter, and the warning that empty items plus non-zero unclassified does not mean a quiet window. This is exactly the kind of nuance an agent needs to interpret results correctly.

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

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

The description is longer than typical, but every sentence carries essential interpretive or routing information. It is front-loaded with the core purpose, then builds through envelope semantics, severity quirks, and finally sibling-tool differentiation. No filler or redundancy is present; the length is justified by the subtle failure modes it prevents.

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

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

For a tool with no output schema, the description thoroughly explains the return envelope, key fields, caveats, and the unclassified/unknown edge cases. It also covers when to use this tool versus correlated bundles and log scanning. Given the tool's complexity, nothing needed for correct invocation or result interpretation is missing.

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

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

The input schema already covers all three parameters with 100% description coverage, so the baseline is 3. The description adds meaningful extra semantics for hours ('widen hours if you need to be sure nothing older is being missed') and severity (ranking behavior and 'unknown' handling), elevating it above baseline. Target is not elaborated, but the schema already describes it sufficiently.

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

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

The description opens with a clear '[READ] Get recent vCenter/ESXi events filtered by severity', identifying the exact verb, resource, and filtering dimension. It further differentiates from siblings by framing this as an 'inventory-wide event sweep' and explicitly contrasting with vm_investigation_bundle / host_investigation_bundle, making selection unambiguous.

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

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

Usage guidance is explicit: 'Use this for an inventory-wide event sweep' states when to call it, and it names the preferred alternatives when the object is already known. It also excludes a common confusion case by stating ESXi syslog lines are not events and routing to host_log_scan. No inference is 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral detail beyond those structured hints: it documents the list envelope's real 'total', the row fields, the green/yellow/red status values, and the critical meaning of empty 'items' as 'no host exposes sensor data' rather than a failed query. This directly prevents a common false-negative 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?

Three short paragraphs each serve a distinct purpose: what it returns, how to interpret empty results, and when to use alternatives. The most important facts are front-loaded, and there is no filler or repetition. Every sentence earns its place.

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

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

For a read-only listing tool with no output schema, this description is complete: it covers purpose, returned fields, status semantics, empty-result interpretation, and routing to related tools. An agent has everything it needs to invoke the tool correctly and interpret the result without further inference.

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

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

Schema description coverage is 100% with both 'limit' and 'target' already documented: 'Max sensor rows to return (None = all)' and 'vCenter/ESXi target from config (default if omitted)'. The description does not add parameter-level syntax or examples, so the baseline 3 is appropriate because the schema carries the parameter meaning.

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 hardware sensor status (temperature, voltage, fan, ...) for all hosts.' It clearly names the resource, scope, and data categories, and distinguishes itself from siblings through the 'physical hardware only' framing. This is far beyond a tautology and gives an agent an immediate mental model of the 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?

Explicitly tells when to use this tool ('physical hardware only'), names the alternative for load data ('host_performance'), and gives a follow-up action for red sensors ('host_investigation_bundle'). It also explains an edge case (nested ESXi) to prevent misinterpretation. This is model guidance for when-to-use vs alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the return envelope structure, row fields, and the guarantee that truncated is always False because all matching hosts are enumerated. It also states the read-only boundary explicitly, adding meaningful behavioral context.

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

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

The description is compact and dense, with the core purpose first, followed by return details, then usage guidance and exclusions. Every sentence earns its place and no information is redundant with the schema or annotations.

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

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

For a tool with two optional parameters, read-only annotations, and no output schema, the description fully covers what the agent needs: the exact fields returned, the truncated behavior, a concrete use case, and a clear alternative for NTP. Nothing essential is missing.

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

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

Schema coverage is 100%, and the parameter descriptions for target and host_name already document their meaning and defaults. The tool description does not add deeper semantics for these parameters, but the schema carries the required burden, so the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource: 'Get host service status (running state and startup policy).' It clearly distinguishes the tool from siblings by stating its scope (services, not sensors or VMs) and by explicitly pointing to ntp_status for NTP-specific checks.

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

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

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

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

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

Annotations already mark the tool read-only/idempotent; the description adds return-shape context ('one correlated bundle, not the list envelope'), batching behavior, point-in-time semantics, and output guidance (operational language, not raw dump). No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then uses short paragraphs for alternatives, return contents, trigger context, and limitations. Every clause adds non-redundant information and nothing reads as filler.

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

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

With no output schema, the description compensates by itemizing the bundle's contents (host state, cluster, VM rollup, datastores, alarms, performance, event timeline) and its operational caveats. Given the tool's read-only nature and well-documented parameters, nothing essential is missing.

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

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

All three parameters are fully documented in the schema with defaults and usage notes (e.g., exact host name, teaching error, hours look-back). The main description does not add parameter meaning, so the high schema coverage baseline of 3 applies.

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

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

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

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

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

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

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, and the description adds valuable behavioral detail: it explains that only matching lines are returned, describes the envelope format, and notably clarifies that 'total is null on purpose' and empty items means no matches. This prevents misinterpretation of scan results.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then covers behavior, return format, the total-null caveat, and usage guidance without repetition or filler.

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

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

The tool has no output schema, but the description fully covers the return envelope and row fields, plus the semantics of total and empty items. Combined with the complete input schema and annotations, nothing essential is missing for correct invocation and interpretation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful parameter context beyond the schema: it explains that 'lines' is per log and that 'host_name' can narrow the scan for performance. It does not add much for 'target', but the schema already adequately documents that parameter.

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

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

The description states a specific action ('Scan recent ESXi host syslog lines for error/warning patterns') against a clear resource. It also differentiates from related tools by noting that vCenter events and ESXi syslog are different sources, which helps an agent select this tool among siblings like get_events and host_investigation_bundle.

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

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

Explicitly says when to use the tool: 'Use this when get_events or host_investigation_bundle show a host in trouble but not why.' It also provides an optimization hint: 'Filter with host_name to keep the scan fast on large clusters.' This goes well beyond a vague context statement.

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

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

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

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

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

The description is dense but well-organized, with front-loaded purpose, a 'When to use' section, return envelope details, and gotchas. The only minor redundancy is restating 'Read-only' at the end after '[READ]' and despite the readOnly annotation, but overall every section earns its place.

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

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

Even though there is no output schema, the description fully explains the return shape, row fields, per-tier breakdown, and the special meaning of 'noTiering'. It also covers version prerequisites and behavior on older hosts, making it complete for an agent to call this tool correctly.

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

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

The input schema already documents all three parameters completely, including defaults and filtering intent, with 100% coverage. The description does not add parameter-level detail, but the schema carries that burden adequately, so the baseline of 3 applies.

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

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

The description states a specific purpose: reporting per-host memory tiering and NVMe uplift ratio. It also differentiates itself by claiming to be 'the only source of measured tier byte sizes,' which helps distinguish it from generic host-list tools.

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

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

The description explicitly begins with 'When to use' and lists concrete scenarios: identifying ESXi hosts backed by NVMe, checking tier sizes, and understanding how much memory rides on NVMe. It does not enumerate alternatives or explicit 'when not to use' conditions, but it provides clear contextual guidance.

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

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

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

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

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

The description is compact and front-loaded with the essential read/live nature, then efficiently packs the most useful operational details without redundancy. Every sentence contributes either scope, differentiation, behavioral edge cases, or an alternative routing suggestion.

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

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

Although there is no output schema, the description compensates by enumerating returned fields, explaining the 'total' envelope semantics, stating which hosts are excluded, and describing ordering. No hidden behaviors or call prerequisites remain unaddressed.

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

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

Schema description coverage is 100%, and each parameter has a clear inline description (limit, target, host_name), so the schema already fully documents parameter semantics. The tool description adds no extra parameter guidance, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the action ('[READ] Real-time CPU/memory/disk/network utilisation per ESXi host') and distinguishes itself from list_esxi_hosts by contrasting live PerfManager data with static config data. It also names specific fields returned, leaving no ambiguity about what the tool produces.

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

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

The description is explicit about when to use this tool: 'Use this to find which host is hot'. It also routes the agent to follow-up tools such as host_investigation_bundle and vm_performance, and contrasts with list_esxi_hosts for static host configuration needs.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond that: it documents the list envelope, per-row fields, the unlimited flag semantics ('row total == 0'), and guarantees 'truncated is always False' because every license is enumerated. It also discloses what is not reported.

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

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

The description is front-loaded with the core purpose and [READ] marker, then returns semantics, usage context, exclusions, and alternatives. Each sentence contributes distinct information with no redundant fluff.

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

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

With no output schema, the description carries the burden of explaining return contents, which it does thoroughly: envelope type, row fields, unlimited flag semantics, and truncation behavior. It also covers scope limitations and related tools, making the tool self-sufficient for correct invocation.

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

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

The sole parameter 'target' has 100% schema description coverage: 'vCenter/ESXi target from config (default if omitted).' The description adds no additional parameter-specific meaning, which is acceptable because the schema already carries the necessary semantics.

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

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

The description names a specific verb and resource: '[READ] vCenter/ESXi license inventory with usage and expiry.' It also distinguishes itself from siblings by explicitly stating that host-level license consumption is not reported and pointing to list_esxi_hosts, and by noting that license assignment belongs to vmware-aiops.

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

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

Usage context is explicit: 'Use this to catch over-allocation or an approaching expiry' and it is framed as part of a platform-hygiene sweep with certificate_status and ntp_status. It also gives clear when-not-to-use guidance: host consumption is handled by list_esxi_hosts and license assignment by 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond those hints: it labels the data as 'Static topology only' and warns about the 'list envelope' with a 'real total.' It also documents the intended workflow. Not as rich as full pagination/performance notes, but it genuinely supplements the annotations.

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

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

The description is three sentences with no fluff. The core purpose is front-loaded, the return envelope note is brief, and the usage guidance is packed into a single efficient sentence. Every sentence earns its place.

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

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

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

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

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

Schema description coverage is 100%, and both limit and target already have clear descriptions in the schema. The tool description adds no parameter-specific information, but because the schema fully documents both parameters, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List clusters with host count, DRS/HA status, and resource totals.' It also clarifies this is a static topology listing, distinguishing it from cluster_health_summary, a very close sibling. An agent knows exactly what data this tool provides and what it does not.

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

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

The description explicitly instructs: 'use this to resolve a cluster name, then cluster_health_summary, which supersedes stitching this with list_esxi_hosts and get_alarms yourself.' This gives clear when-to-use guidance and directs the agent away from an alternative composition. Nothing is left to inference.

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

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

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

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

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

The description is compact yet information-dense, with the core purpose in the first line and follow-up guidance in two short sentences. No filler, and the key exclusions and successor tools are front-loaded.

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

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

Given the simple list operation, the description fully covers what the tool returns (envelope with fields and total), its limitation (raw free/used only), and when to use which alternative. With no output schema, the description adequately explains the return shape and all necessary context for an agent to call it correctly.

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

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

Schema coverage is 100%, with both 'limit' and 'target' fully described by the schema. The description does not add parameter-specific detail, which is acceptable given the baseline, but no extra value is provided beyond the schema.

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

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

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

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

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

Explicitly states when to use this tool: to resolve a datastore name, and then routes to datastore_capacity or datastore_investigation_bundle for deeper analysis. Also notes that only raw free/used data is provided, implying it is not for thin-provisioning risk assessment.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by noting the return is a 'list envelope with a real total' and by explicitly limiting results to name, vm_count, and accessible, which helps set agent expectations beyond the structured metadata.

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

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

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

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

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

For a simple read-only listing tool with no output schema, the description covers the returned fields, the envelope behavior, the limitation of detail level, and the intended follow-up workflow. Combined with rich annotations and full schema coverage, this is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters (limit and target) are already documented in the structured schema. The description does not need to compensate, and it does not meaningfully add parameter-level semantics beyond what the schema provides.

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

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

The description states a specific verb and resource ('List networks') and enumerates the exact fields returned: name, attached VM count, and accessibility. It goes further by explicitly excluding VLAN, uplink, and NSX overlay detail, which cleanly distinguishes it from what an NSX-specific tool would provide.

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

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

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

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: the response is a list envelope, 'total' is the authoritative host count, and the values are static config rather than live load. This goes beyond what the annotations alone provide.

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

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

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

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

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

Given the simple read-only tool with two optional params and full schema coverage, the description is complete. It covers return shape, field content, the static-config caveat, and related tools, with annotations covering safety. Nothing needed for correct selection or invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented clearly. The tool description adds context around static vs. live data and host-name resolution, but it does not add significant parameter-level meaning beyond the schema.

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

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

The description uses a specific verb ('List'), identifies the resource (ESXi hosts), and enumerates the returned fields (CPU cores, memory, version, VM count, uptime). It also separates this tool from related siblings by explicitly mentioning host_performance and host_investigation_bundle for different purposes.

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

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

The description gives explicit usage guidance: use this for static config and resolving a host name, then use host_performance for live load or host_investigation_bundle for deep drill-down. It clearly distinguishes when to use this tool versus the stated alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's job is to add runtime behavior. It does so in detail: the response envelope, the meaning of 'total' vs 'truncated', the 50-VM default-field truncation, and the deprecated 'vms' alias. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, response semantics, truncation caveat, deprecation note, and usage routing. It is front-loaded with the core operation and uses code formatting to isolate field names. No filler or redundancy.

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

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

Given there is no output schema, the description fully carries return-value explanation: envelope fields, truncation semantics, and the deprecated alias. It also contextualizes the operation among siblings. For a read-only list tool with six optional parameters, nothing critical is missing for an agent 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 coverage is 100%, so the baseline is 3. The description adds genuine extra semantics beyond the schema by explaining how 'limit' and 'fields' interact under the 50-VM threshold and introducing the 'mode' field as an indicator of which fields were returned. This goes beyond simply restating parameter names.

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 states an explicit verb and resource: 'List virtual machines, with filtering, sorting, and field selection.' It further distinguishes itself by steering agents to use this for resolving an exact VM name, versus vm_info, vm_investigation_bundle, or cluster_health_summary for other needs.

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 final paragraph gives explicit routing guidance: use this tool to resolve an exact VM name, then delegate to vm_info for detail or vm_investigation_bundle for deeper investigation, and use cluster_health_summary for a fleet-wide view. This clearly tells the agent when this tool is the right choice and when a sibling is preferable.

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

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

Annotations already mark readOnly/idempotent, and the description adds valuable context beyond that: every host is enumerated so truncated is always False, null vs false semantics for unreachable hosts, and the need to check hosts_unreachable/unreachable_note before declaring the estate healthy. No contradiction with annotations.

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

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

The [READ] prefix and first line front-load purpose, then flow into return shape, null semantics, and routing guidance in logical order. Although longer than minimal, every sentence contributes an operational detail the agent needs; nothing feels wasted.

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

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

Even without an output schema, the description fully specifies the return envelope, row fields, the healthy flag logic, null behavior for unreachable hosts, and the unreachable-host caveat. For a two-optional-parameter read tool, this is complete and actionable.

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

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

Input schema coverage is 100%, and both params have descriptions (target from config; host_name filter by exact name). The description does not add parameter-level detail, but the schema already carries the full semantic burden, so 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 and resource: reports per-host NTP configuration health covering servers and ntpd service state. It explicitly distinguishes itself from get_host_services for time problems, so the agent can tell them apart 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 explicit routing guidance: prefer this over get_host_services for time problems because it covers configured servers plus ntpd state, use esxcli for live clock offset, and use vmware-aiops for fixes. This is clear when-to-use and when-not-to-use direction.

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

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

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

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

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

The description is moderately long but every sentence earns its place: it front-loads the read marker and core purpose, details output format, then provides usage context. No redundant sentences, though it could be slightly tightened without losing value.

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

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

With no output schema, the description fully explains return fields, sorting, and special values, plus usage guidance. For a read-only tool with two optional parameters, this is complete; an agent can call it correctly without needing further documentation.

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

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

Schema coverage for both parameters is 100%, so the description adds minimal new meaning. It only indirectly references the limit parameter via the -1 semantics in results, but does not elaborate on the target parameter beyond the schema.

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

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

The description clearly states it returns per-resource-pool CPU/memory reservation, limit, and usage, and enumerates the exact fields in each row. It names specific resources and the read action, distinguishing it from sibling tools that focus on hosts, VMs, clusters, or datastores.

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

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

It explicitly specifies when to use this tool: "when a VM is throttled but its host is not busy." It also gives clear follow-up steps, mentioning vm_performance and cluster_health_summary as alternatives, effectively routing the agent.

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

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

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

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

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

The description is compact, with the primary purpose and use case front-loaded in the first two sentences. Every sentence earns its place: purpose, usage, return structure, field caveats, and read-only note. No fluff.

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

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

Despite having no output schema, the description fully explains the return structure (including fields like total_snapshots, old_snapshots, vms_with_snapshots, threshold_days, snapshots[], hint) and caveats about est_size_mb. It also covers the only behavioral caveat (read-only, no deletion). For a tool with 4 optional parameters and no output schema, this is complete.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description does not add new parameter-level semantics beyond what the schema already provides, hence the baseline of 3 is appropriate.

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

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

The description states a specific verb (sweep) and resource (ALL VMs' snapshots) with a clear purpose (flag old/sprawling ones). It distinguishes itself from the sibling vm_list_snapshots by saying 'prefer vm_list_snapshots when you only care about one VM.' This leaves no ambiguity about what the tool does.

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

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

The description explicitly says 'Use this for fleet-wide snapshot sprawl' and directly names the alternative tool with the condition to switch. This is a textbook example of usage guidance, covering both when and when-not to use this tool.

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

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

The description goes well beyond the readOnly/idempotent annotations, explaining the exact return shape ({available, note, fields}), the meaning of available: False (vCenter 503, nothing crashed), and the 9.1-only endpoint behavior with older vCenters returning 404. This gives the agent essential runtime context and failure semantics.

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

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

The description is compact, well-structured into 'When to use,' 'What it returns,' and 'Gotchas.' Every sentence serves a purpose, and the most important information (what it reads, when to use it) appears first without unnecessary padding.

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

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

For a tool with one optional parameter, no output schema, and rich annotations, the description covers all relevant context: purpose, use case, return format, failure semantics, API version constraints, and verification status. An agent has everything needed to correctly invoke and interpret the result.

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

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

The input schema fully documents the only parameter 'target' with a clear description, so schema coverage is 100%. The tool description adds no parameter-specific details, but none are needed since the schema already covers it; baseline 3 is appropriate.

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

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

The description opens with a clear verb and resource: '[READ] vCenter appliance deployment size,' and further specifies it reads current and target deployment size class. It also distinguishes itself from sibling inventory/perf tools by stating this is capacity-planning context they do not cover.

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 explicitly states the intended use case: reading vCenter deployment size class for capacity planning. It also notes that inventory/perf tools do not cover this context, providing implicit guidance on alternatives, though it does not explicitly name a specific sibling to use 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 mark the tool read-only, idempotent, and non-destructive, so the description adds substantial behavioral context beyond that: it returns a rollup rather than a raw list envelope, history_unavailable and coverage_note can indicate incomplete data, duplicate VM names raise an error, and the result is a lower bound on backup duration.

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

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

The description is longer than average, but every section earns its place: scope, lower-bound semantics, return shape, failure-signal fields, duplicate-name behavior, and pointer to alternatives. It is front-loaded with the core purpose and uses formatting to make caveats scannable.

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 carries the full burden of explaining what is returned: counts, four-hour statistics, latest and longest cycles, unmatched rows, and the two fields that must be checked before reporting all-clear. It also covers the duplicate-name failure mode and directs to sibling tools appropriately.

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

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

The input schema already documents all five parameters with 100% coverage, so the baseline is 3. The description adds meaningful nuance for vm_name by stating that duplicate names are refused rather than guessed, and for days by explaining that coverage_note can mean the returned window is shorter than requested.

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

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

The description opens with a specific, measurable statement: 'How long backups held a snapshot open on one VM, from task history.' It names the exact resource, source of data, and one-VM scope, and it distinguishes this tool from snapshot_aging and vm_list_snapshots by pointing those tools at current snapshots.

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

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

The description explicitly routes users to vm_list_snapshots or snapshot_aging for snapshots that exist right now, while positioning this tool as the historical backup-window view. It also clarifies when the data is meaningful (image-level backup products) and warns not to treat the result as the full backup job duration.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavior beyond those: it returns static configuration only, returns a single dict rather than a list envelope, and warns that an unknown name yields a teaching error instead of a match.

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

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

The description is compact and front-loaded with the core purpose. It covers return format, scope, error behavior, prerequisites, and sibling alternatives in a few sentences, with no filler or repetition of the schema.

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

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

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

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

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

Schema description coverage is 100%, so both parameters (target and vm_name) are already meaningfully documented in the schema. The description reinforces that vm_name must be exact and tells the agent where to get it, but does not add substantially new parameter semantics.

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

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

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

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

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

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

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

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

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

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

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

The description is dense but every sentence earns its place: it states purpose, lists contents, gives usage triggers, sets expectations, and issues a clear output instruction. The most important information is front-loaded, and the length is justified by the tool's composite nature.

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

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

For a composite read-only tool with no output schema, the description is unusually complete: it enumerates the returned components, states ordering, clarifies batch behavior, warns against trending/acting, and even documents error behavior for unknown VM names. An agent has enough context to select and invoke this tool correctly.

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

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

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

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

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

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

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

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

It explicitly tells the agent when to use it ('after cluster_health_summary names a problem VM, or when asked "what's going on with <vm>?"'), when not to use it ('Point-in-time snapshot — no trending'; 'Acting on what you find ... belongs to vmware-aiops'), and what to use instead of stitching lower-level tools together. This is strong alternative-selection guidance.

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

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

Annotations already include readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful behavioral context on top: distinguishing a genuinely empty snapshot list via 'empty items with truncated False,' explaining the level hierarchy, and clarifying that mutating snapshot operations live in vmware-aiops. No contradiction with annotations.

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

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

The description is efficiently organized into three short paragraphs, each earning its place: what/returns, alternatives and preconditions, and error behavior. Key scope and read-only details are front-loaded, and no sentence is filler.

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

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

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

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

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

Schema coverage is 100% and both parameters are already described in the schema. The description adds extra practical meaning by requiring an 'exact name,' telling the agent to obtain it from list_virtual_machines, and reinforcing that the target defaults from config. This goes beyond the baseline schema-only explanation.

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

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

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

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

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

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

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

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

Beyond the readOnly/idempotent annotations, the description discloses important runtime behavior: only powered-on VMs have a real-time provider and are included, powered-off VMs are skipped, data is point-in-time only, the returned total reflects VMs that reported metrics, and truncated indicates pagination. This meaningfully enriches what annotations alone convey.

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

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

The description is well-structured and front-loaded: purpose first, then response semantics, then usage guidance. Every sentence contributes information, with no filler or repeated schema content.

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

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

Given there is no output schema, the description does a strong job of explaining the response envelope, exposed metric fields, ordering, filtering behavior, and alternatives. An agent can correctly select and invoke this tool without needing additional details.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful context about limit behavior and result ordering, but it does not materially explain individual parameters beyond what the schema already states.

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

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

The description opens with a clear statement of what the tool does: returns real-time CPU/memory/disk/network utilization per VM, prefixed with [READ]. It further differentiates itself from siblings by explicitly naming vm_info and vm_investigation_bundle as alternatives for different needs.

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 when to use this tool ('rank load across VMs') and explicitly points to alternatives for other scenarios: vm_info for a single VM's configuration and vm_investigation_bundle for host/alarms/events correlation. This gives an agent direct routing guidance.

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