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

readOnlyHint=true already establishes this as a safe read, and the '[READ]' prefix merely restates that. The description does add value by naming the fields exposed per cluster, but it says nothing about pagination, ordering, or what an empty result means.

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 content is front-loaded into one sentence followed by a tight Args block with no filler. Structure is appropriate for a two-parameter list tool, though the leading purpose clause reads slightly telegraphically.

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 partially compensates by naming the key per-cluster fields returned, and it covers both parameters fully. Missing only secondary details such as result ordering or pagination behavior for a simple read-only list.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: it documents the limit range (1-1000) and default (100) plus the meaning and default fallback of target, details absent from the schema. It could still clarify units or ordering semantics for limit.

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

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

The description states the resource (clusters) and the salient fields returned (compatibility version, CPU type, memory over-commit policy), which is more specific than a tautology. It does not distinguish itself from siblings like host_list or datacenter_list beyond the resource name, so it stops short of a 5.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative. The only conditional behavior stated is for the `target` argument (omit to use the default), which is argument behavior rather than tool-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 only declare readOnlyHint, so the description carries the rest and does so well: it enumerates possible status values, mentions the compat version field, documents the limit range (1-1000) and default (100), and explains that `truncated` signals more rows exist. Only the pagination mechanics (how to fetch the next page) remain unstated.

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

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

Front-loaded with the read tag and resource, then a compact args block. Slight redundancy in restating `limit`'s default of 100, which the schema already carries, but overall the text is tight with no filler.

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

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

With no output schema, the description is responsible for conveying the return shape, and it does so by naming status and compat version plus the truncation flag. For a simple two-parameter read-only lister, nothing critical is missing beyond explicit next-page retrieval instructions.

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

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

Schema description coverage is 0%, so the description must compensate and it largely does: `limit` gets a range and default plus the `truncated` interaction, and `target` is explained as an engine target name from config with an omit-for-default rule. Both parameters gain meaning beyond their bare type declarations.

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

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

The description names the resource (data centers) and the specific attributes returned (status values like up/uninitialized/maintenance and compat version), so the agent knows exactly what it gets. It does not differentiate itself from siblings such as cluster_list or host_list, which sit in the same listing family.

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 [READ] prefix and the note that omitting `target` falls back to the configured default give implicit usage context, but there is no explicit when-to-use/when-not statement and no alternative tool is named. The agent must infer that this is the enumeration entry point for data centers.

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 only supply readOnlyHint=true; the description carries the real behavioral load. It enumerates what is read (health check, version, clock drift vs. this machine, summary counts), defines the event-inclusion rule (warning-or-worse events naming no host, VM or storage domain), and pre-empts two classification edge cases (10803, 2024) plus the severity semantics and rank ordering.

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 placement is correct — purpose and trigger first, args last — and most sentences do work. The two multi-line digressions on events 10803 and 2024 are precise but heavy for a tool description; they are defensible edge-case guidance rather than padding, yet they stretch the entry considerably.

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

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

There is no output schema, and the description compensates by telling the agent what a finding is, that results are ranked worst-first, and that each signal should be quoted. It stops short of describing the return envelope or how the 'summary counts' are structured, which is the only remaining gap.

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 0%, so the description must compensate and does: events_limit is bounded 1-1000 (default 200), events_window_hours bounded 1-720 (default 24), and target is explained as 'Engine target name from config; omit to use the default', resolving the anyOf string/null ambiguity.

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

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

The opening line names a specific verb+scope: '[READ] Problems with the engine itself, ranked worst first, in one call.' The resource (engine, not host/VM/storage) and the ordering guarantee are stated, which separates it from host_health_rca, vm_health_rca and storage_capacity_rca without opening a schema.

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

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

It gives an explicit trigger — 'call this first for "is anything wrong"' — and an explicit scope limit: these alerts 'appear in no other diagnosis,' so they cannot be recovered from the sibling RCA tools. That is routing guidance an agent can act on, even though the sibling tools are not named individually.

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 only supply readOnlyHint=true; the description goes well beyond it by disclosing default sort order (newest first), the order inversion when after_index is used, the truncated/scanTruncated signalling semantics, and that SSO session ids in login events are redacted. These are non-obvious behaviors an agent must know to poll safely.

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

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

Front-loaded with the one-line purpose, then behavior, then parameters; every sentence carries information. The Args block restates parameter names, but at 0% schema coverage that repetition is load-bearing rather than filler.

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

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

With no output schema, the description still names the return signals an agent needs (index, order, truncated, scanTruncated) and gives the correct polling algorithm. Nothing required to call 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 0%, so the description carries the full burden and does so: limit range 1-1000 with default 100, the four legal min_severity values, since_minutes bounds 1-129600, target's meaning and default, and the interaction constraint on page.

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

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

The opening line states a specific verb (list), resource (engine events), and scope (at or above a severity, newest first). No sibling tool covers events, so there is no ambiguity to resolve against the other 16 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?

It explains exactly when to use each mode: after_index for following new events (with the repeat-while-truncated loop), since_minutes for a rolling window, and page for older history. It also states a hard exclusion — page is not combinable with since_minutes or after_index — and that omitting target uses the default.

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 '[READ]' tag and the annotation readOnlyHint=true agree, so the safety profile is clear. Beyond that the description adds only the target-default behavior ('omit to use the default'); it says nothing about error behavior when an id is unknown, pagination, or output shape.

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

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

Two short, front-loaded lines: the read scope comes first, then a compact Args block. Nothing is padded, though the host_id line adds little.

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 two-parameter read tool with no output schema and no nested objects, the description covers the resource, the id requirement, and the target default. An agent has enough 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 0%, so the description must carry parameter meaning, and it does: target is explained as an engine target name from config with an omit-to-use-default rule, which is not derivable from the schema. host_id is documented only as 'Host id', which is essentially a restatement.

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 (retrieve one KVM host) and scopes it by id, so the agent knows exactly what it returns. The parenthetical '(see host_list)' cross-references the sibling, though it does not explicitly contrast the two (single host vs. listing).

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

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

'(see host_list)' implies the agent should use host_list to discover ids before calling this tool, which is useful implicit routing. There is no explicit when-to-use/when-not guidance or statement of prerequisites beyond that pointer.

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

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

With only readOnlyHint=true in annotations, the description adds substantial behavioral context: in-progress installs/reboots are reported as in-progress not failed, alert 9000 is informational on hosts without fencing, event 10802 is scoped to the guest not the host, relatedVmEvents are paired on time alone, and an empty list means none was logged. This is exactly the kind of semantics annotations cannot convey.

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

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

It is front-loaded with the purpose and every sentence carries interpretation content, but the middle is a dense wall of edge-case prose that could be broken into clearer structure. Length is largely justified by the absence of an output schema, though it borders on over-specified.

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

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

There is no output schema, yet the description explains the returned finding fields (signal, cause, action, rank), the auxiliary fields (vmCandidates, relatedVmEvents, eventsOutsideWindow, scanTruncated), and how to interpret each. Nothing an agent needs to invoke or read results is missing.

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

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

Schema description coverage is 0%, so the description must carry the burden and does: it documents events_limit (range 1-1000, default 200), events_window_hours (range 1-720, default 24, older events counted in eventsOutsideWindow), and target (engine target name, omit for default). Ranges and the out-of-window side effect are meaningfully beyond the bare 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 first line states a specific resource and scope: 'What needs attention on KVM hosts, ranked worst first, in one call.' It also distinguishes itself from the sibling vm_health_rca, which is named as reporting the VM half. An agent can tell what this tool is and is not without opening the schema.

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

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

The description gives clear context for when the tool applies (host-level health triage) and routes the VM half of an operation to vm_health_rca by name. However, it never explicitly states when to prefer this over siblings like host_get or engine_health_rca, so the selection guidance is contextual rather than an explicit when/when-not rule.

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 only declare readOnlyHint=true, and the description adds real behavioral context beyond that: unreported fields are null rather than 0, and the 'truncated' flag signals when more rows exist. It does not cover auth/target-resolution behavior in depth, but the null-semantics disclosure is genuinely non-obvious and useful.

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

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

Front-loads what the tool is and its field set, then a caveat, then a compact Args block. Every sentence adds information and the args are terse but complete.

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 supplies the key return behaviors (field list, null semantics, truncation signal) and the pagination contract. What's missing is only the response envelope shape, a minor gap for a list tool whose annotations already confirm it is a safe read.

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

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

Schema description coverage is 0%, so the description must carry all three parameters, and it does: limit with its 1-1000 range and default 100, search with the query language and literal examples ("status=up", "status!=up"), and target with its config-name meaning and default fallback. This fully compensates for the empty schema.

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

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

States a specific verb and resource ('[READ] KVM hosts') and enumerates the returned fields (status, SPM role, memory, VM counts), which cleanly separates it from host_get (single host) and host_health_rca (diagnosis). An agent can distinguish it from siblings without opening a schema.

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

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

Gives an explicit routing rule: for "what is wrong with my hosts" use host_health_rca instead of reading this list yourself. That is a concrete when-not-use plus a named alternative, exactly the condition an agent needs to pick between the two tools.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the [READ] marker (redundant with the annotation) and enumerates the status values, but says nothing about result ordering, pagination, or what 'duration' measures for in-flight jobs.

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 one-line summary is front-loaded and the Args block is tight, with no filler. Formatting is functional though the block-style parameter list is slightly less scannable than inline prose.

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 3-parameter read tool with no output schema and only a readOnlyHint, the description covers parameters well but omits return-shape context (e.g., what fields a job row carries, ordering, or truncation behavior at the 1000 limit). Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must carry the burden — and it largely does: it documents limit's range (1-1000) and default (100), the exact status enum values that the schema lacks, and target's default behavior. It stops short of explaining whether status is exact-match only across multiple values or any format nuances.

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 resource (engine jobs / long-running operations) and what the listing conveys (status and duration). It's clear what the tool does, though it doesn't explicitly contrast itself with any sibling (none of the siblings are job-related, so this is minor).

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 target parameter note ('omit to use the default') gives a small amount of invocation guidance, but there is no statement of when to use this tool versus alternatives or any prerequisites/exclusions. Usage is implied rather than spelled out.

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

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

With only readOnlyHint declared in annotations, the description carries the behavioral load well: it discloses severity rules, that warning-or-worse events naming a domain get attached, that unattached domains are skipped, and the edge case where unset thresholds (engine reports 0) are reported low. These are substantive traits beyond the 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 core purpose is front-loaded, which is good, but the severity discussion is dense and some sentences (e.g., the 'nothing — not the engine, not this tool — will warn' clause) are convoluted and could be tightened. Roughly adequate but with clear verbosity.

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

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

There is no output schema, so the description must explain what findings look like — and it does, covering rank ordering, quoting signals, severity semantics, skipped domains, and the unset-threshold edge case. For a complex RCA tool this is complete enough to invoke and interpret correctly.

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

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

Schema description coverage is 0%, but the Args block fully compensates: events_limit 1-1000 (default 200), events_window_hours 1-720 (default 24), and target (engine target name from config, omit for default). All three parameters get meaning, bounds, and defaults that the bare schema lacks.

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: storage-domain problems ranked worst-first in a single call, explicitly tagged [READ]. This is clearly distinguishable from storage_domain_list/get (raw listing) and engine_health_rca (different domain), so an agent can select it without opening the schema.

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

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

It gives rich interpretive guidance — severity mapping (critical below free-space blocker, medium below low-space warning, high for inactive/unknown/mixed domains) and exclusions (unattached domains are skipped; over-commit alone is not a space shortage). It lacks any explicit routing to a sibling alternative, keeping it short of a 5.

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 readOnlyHint annotation already establishes this is a safe read, and the '[READ]' tag merely restates it. The description does add genuine context by noting the returned status is data-center-scoped and that target selection defaults from config, but it says nothing about failure behavior for a missing id or about target mismatch across data centers.

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?

One front-loaded sentence carrying the scope, followed by a tight two-item Args block. No filler, and the parameter notes each add information rather than restating 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?

With no output schema, the description partially compensates by naming the payload ('one storage domain ... with its data-center-scoped status'), which tells the agent roughly what comes back. For a simple two-parameter read tool this is close to sufficient, with only error/empty-result behavior 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 0%, so the description must carry both parameters, and it largely does: domain_id is explained as a storage domain id sourced from storage_domain_list, and target is explained as an engine target name from config that defaults when omitted. Only the string format of domain_id (e.g., name vs. UUID) is left unspecified.

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 with an explicit scope qualifier: fetch exactly one storage domain by id, returning its data-center-scoped status. This distinguishes it cleanly from the sibling storage_domain_list, which the description also cross-references.

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 is implied rather than stated: 'One storage domain by id (see storage_domain_list)' tells the agent to use the list tool to obtain ids, which is a soft routing hint. There is no explicit when-to-use/when-not statement, no mention of what happens for an unknown id, and no contrast with other read tools beyond the list 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds genuinely useful behavior beyond that — status provenance via statusSource, deliberate nulls rather than guesses when statusErrors occur, and a truncated flag indicating more rows exist. No auth or rate-limit details, but the provenance semantics are a real value-add.

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

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

Front-loaded with the read tag and purpose, then the status-provenance caveat, then a compact Args block. Every sentence carries information — no filler, no 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 read-only list tool with no output schema, the description covers what is returned, the null-status edge case, and pagination via truncated. It could note how this differs from storage_domain_get, but nothing essential for correct 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 coverage is 0%, so the description carries the full parameter burden, and it does: limit is documented with range 1-1000, default 100, and the truncated signal; target is explained as an engine target name from config with a default when omitted. Both parameters gain meaning not present in the bare schema.

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

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

States a specific verb and resource — listing storage domains — and enumerates the returned attributes (status, free/used/committed bytes and %). It implicitly contrasts with the sibling storage_domain_get by being a listing operation, but never names that sibling, so it falls short of explicit differentiation.

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 '[READ]' tag and the listing framing imply usage, and the target arg hints at multi-engine contexts, but there is no explicit when-to-use guidance or routing to alternatives such as storage_domain_get or storage_capacity_rca.

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 destructive=true, idempotent=false, readOnly=false; the description adds that the inverse executes through its own governed tool and risk tier (audit behavior) and that tokens are single-use. Useful beyond the annotations, though it doesn't say what the inverse might mutate.

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 [WRITE][risk=medium] tag front-loads the mode and risk, and the body is tight. The Args block partially restates the schema titles, but each line adds semantics, so little is wasted.

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

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

No output schema, but the description explains the dispatch model, the dry-run preview path, and the one-time token constraint, which covers the essentials for a mutation tool. It could clarify failure behavior (e.g., applying an already-used token) to be fully 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 0%, so the description must carry the load, and it documents all three params: undo_id's source, dry_run's preview semantics, and target's pass-through role. The 'target' explanation ('when it accepts a target') is a bit thin but directionally complete.

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

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

States a specific verb ('apply') and resource ('a recorded undo') plus the mechanism (dispatching its inverse tool). This clearly distinguishes it from the sibling undo_list, which only enumerates tokens.

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 concrete guidance: undo_id comes from undo_list or an _undo_id in a write result, use dry_run=True to preview, and a token can only be applied once. It stops short of saying when not to use it or when preview is mandatory, but the context is clear.

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

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

Annotations only declare readOnlyHint, yet the description discloses substantial behavior: an extra row is read so 'truncated' is measured rather than inferred, effectVerified=false means the reversed change is probable not confirmed, and it warns against reporting an unverified restore. This is well beyond what the annotation covers.

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

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

Front-loaded with purpose, then usage, then a non-obvious implementation note, then args. The paragraph on effectVerified is long but every clause carries decision-relevant information; nothing is filler.

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

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

No output schema exists, so the description supplies the return shape itself (original tool, inverse tool, human note, truncated, effectVerified) plus the truncation semantics. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema description coverage is 0%, so the description must carry the burden — and it does: limit is documented with default 50 and a cap of 500 (the cap is absent from the schema), and target is explicitly marked unused and explained as CLI uniformity.

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

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

States a specific verb and resource ('List recorded, not-yet-applied undo tokens') with ordering scope ('most recent first') and the [READ] marker. It is immediately distinguishable from its sibling undo_apply, which it names.

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

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

Explicitly routes the agent onward ('Use the undoId with undo_apply') and gives a conditional check before applying when effectVerified is false. It doesn't state an explicit when-not-to-use case for undo_list itself, but the workflow context is clear.

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

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

The '[READ]' tag merely restates the existing readOnlyHint=true annotation, so it adds no behavioral value. No information is given about error behavior, missing-VM handling, or what fields are returned.

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?

Brief and front-loaded with the operation, followed by a clean Args block. No filler sentences, though the parameter lines are terse to the point of being thin.

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 single-resource read with readOnlyHint annotations and no output schema, the description is largely sufficient to invoke correctly; only the return shape and id format remain unstated.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It usefully documents that 'target' is an engine target name that defaults when omitted, but 'vm_id: VM id' is circular and adds nothing about format or source.

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: retrieves one VM by id, and the parenthetical '(see vm_list)' signals the sibling that handles the collection case. It is distinguishable from vm_list, though it gives no cue about vm_stats or vm_health_rca.

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 '(see vm_list)' pointer implies the list-vs-single distinction, but there is no explicit when-to-use guidance and no mention of the related read tools (vm_stats, vm_health_rca) that could serve similar lookups.

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 only declare readOnlyHint=true, so the description carries the behavioral burden and does so well: it discloses the ranking logic, that events are correlated one-finding-per-VM-and-code, and the superseding rule (VM started after the event, or engine reported back up and it is up now). It also notes eventsOutsideWindow behavior.

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

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

Front-loads the key claim ('VM problems ranked worst first, in one call') and every subsequent sentence carries information. It is dense and long, but the length is justified by the correlation rules; a small trim of the severity rubric would not hurt.

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

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

No output schema exists and this is a complex diagnostic tool, yet the description explains the finding model, ranking, event correlation, and every argument. An agent has enough to invoke it and interpret results without opening anything else.

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 0%, so the description must compensate, and it does: events_limit (1-1000, default 200), events_window_hours (1-720, default 24, and how out-of-window events are surfaced), and target (engine target name from config, omittable for default). All three parameters are fully documented.

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 — VM problems ranked worst first, in one call — with an explicit read-only marker. It implicitly distinguishes itself from the sibling *rca tools (host_health_rca, engine_health_rca, storage_capacity_rca) by scoping to VMs.

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

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

Gives a concrete severity rubric (high/medium/info/low) tied to VM states, and explicitly routes to an alternative: 'check storage_capacity_rca' for storage I/O errors. It also flags a false-positive case — 'Down VMs without HA are normal' — which is genuine when-not-to-alarm guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine behavioral context beyond that: the '[READ]' marker reinforces the non-mutating nature, and the note that 'truncated' says when more rows exist discloses pagination behavior an agent needs to detect incomplete 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?

Front-loaded with the read marker and returned fields, then a compact Args block where every line adds distinct information. No filler or restatement of the tool name.

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

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

With no output schema, the description usefully enumerates returned fields and the truncation flag, and fully specifies inputs. The remaining gap is routing: it never mentions the sibling tools (vm_get, vm_stats) that an agent might otherwise confuse it with.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so well: it documents the limit range (1-1000) and default (100), the 'truncated' signal, the search query language with two concrete examples, and the meaning of target plus the omit-to-use-default behavior. All three parameters gain semantics not present in the schema.

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

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

The description states a specific verb+resource ('[READ] VMs') and enumerates the fields returned (status, host, vCPUs, memory, HA flag), so an agent immediately knows this is a bulk inventory read. It doesn't explicitly distinguish itself from sibling vm_get, but the list/get naming convention makes the split reasonably clear.

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 is implied rather than stated: 'target: omit to use the default' gives a real conditional, and the search examples show how to filter. However, there is no explicit guidance on when to pick vm_list over vm_get, vm_stats, or vm_health_rca, which is the primary selection risk among these siblings.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the '[READ]' prefix is partly redundant. The description adds that stats are 'current' (i.e. live, not historical), which is mild behavioral context, but says nothing about freshness, rate limits, permissions, or failure modes.

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

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

Front-loaded with the outcome, then a compact Args block; every sentence carries information and there is no filler. Slightly terse on vm_id but appropriately sized for a two-parameter read tool.

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

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

With no output schema, the description correctly carries the return-value burden by naming the metrics and noting 'with units'. What remains missing is the concrete response shape/format and any indication of whether values are instantaneous or averaged.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain target meaningfully ('Engine target name from config; omit to use the default'), which goes beyond the bare schema title 'Target'. But vm_id is only restated as 'VM id' with no format or source guidance, leaving one of two params essentially undocumented.

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

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

States a specific verb+resource (read a VM's current statistics) and enumerates the returned metrics (memory, CPU %, network, disk), so the agent knows exactly what it gets. It does not differentiate itself from the nearby vm_get or vm_health_rca siblings, so it falls short of a 5.

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 '[READ]' tag and 'current statistics' framing imply a monitoring/observation use case, and the target arg note ('omit to use the default') gives some operational guidance. However, there is no explicit when-to-use versus vm_get or vm_health_rca, and no stated prerequisites.

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