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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds real value beyond the annotation by disclosing how output is organized (grouped by job, classified by category) and that unknown causes come with sample messages for triage, which shapes how the agent interprets 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 [READ][RCA] tags, then one sentence of purpose, then the classification list, then a clean Args block. Every sentence earns its place with no redundancy.

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

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

With no output schema, the description compensates by describing the return structure (per-job groups, cause categories, sample messages). Purpose, parameters, and output shape are all covered for a two-parameter read-only tool.

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

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

Schema coverage is 0% — the schema provides only titles and defaults — so the description must carry the burden, and it does: 'limit' is explained as max recent log entries examined (default 50) and 'target' as a config-derived Xen Orchestra target that defaults when omitted. This adds genuine meaning the schema lacks, though it stops short of format or edge-case detail.

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 (classify) and resource (failed/skipped backup runs), and enumerates the exact output taxonomy (vdi-chain, quiesce, transport, storage-full, unknown). An agent can distinguish this from backup_log_list (raw logs) and backup_job_list (job inventory) 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?

The description makes the use case clear — triaging recent run failures — and the 'sample messages for triage' note implies a diagnostic context. However, it never states when to prefer this over siblings like backup_log_list, nor any prerequisites or exclusions, so usage is inferred rather than prescribed.

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?

readOnlyHint=true already covers the safety profile, so the description earns credit for adding the fields beyond annotations: the return envelope (jobs/returned/limit/truncated) and the meaning of truncation, which is genuine operational context. It stops short of noting anything about ordering, cost, or auth, but it is materially richer than the annotations.

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

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

Front-loaded with the [READ] tag and purpose, followed by return shape then args — a sensible order. The embedded return-shape JSON is justified because no output schema exists; wording 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 supplies the response envelope and truncation semantics, and documents both parameters. The only real gap is the absence of any routing guidance relative to the backup/log siblings, which the structured fields cannot provide.

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 largely does: limit is defined as max jobs with its default, and target is explained as a Xen Orchestra config name with omit-for-default behavior. Both parameters are covered, though no format/validation detail for target is given.

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

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

Specific verb + resource ("List VM backup jobs") plus the identity fields returned (id, name, mode). This is clearly distinguishable from the other backup siblings (backup_log_list, backup_failure_rca) by its resource alone, so an agent can select it 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?

No when-to-use, when-not, or alternative is stated. Nothing tells the agent why it would pick this over backup_log_list or backup_failure_rca, nor what prerequisites (target config) are needed before calling. Usage is only inferable from the tool name.

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

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

Annotations already cover the safety profile with readOnlyHint=true, and the description corroborates it with a [READ] tag. It goes beyond annotations by disclosing the truncation-detection mechanism ('one extra record is requested') and the exact return envelope keys, which is genuinely useful behavioral context. It omits auth/rate-limit context, so not a 5.

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

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

Front-loads purpose, then the return shape, then args — a sensible hierarchy with no filler. The truncation explanation is slightly verbose for what it conveys, but every sentence is functional rather than redundant.

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

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

No output schema exists, and the description compensates by enumerating the return keys (logs, returned, limit, truncated) and their meaning. With annotations covering safety, both parameters documented, and truncation behavior explained, an agent has what it needs; only the structure of individual log entries is left unspecified.

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 load, and it mostly does: 'target' is explained as a Xen Orchestra target name sourced from config with an explicit omit-for-default rule, and 'limit' is described as max recent log entries. The default 50 is repeated from the schema, but the target semantics are real added value.

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] Recent backup run logs: status + failed-task messages.' This is clearly a read-only log retrieval, distinguishable by resource from siblings like backup_job_list (job definitions) and backup_failure_rca (analysis). It does not explicitly name those siblings, so it falls just short of 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?

Usage is implied by the framing (fetch recent logs) and the description gives real operational guidance for re-running with a higher limit when truncated=true. However, it never states when to choose this over backup_job_list or backup_failure_rca, nor any prerequisites, so guidance is only partial.

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?

readOnlyHint=true already covers the safety profile, and the '[READ]' tag is consistent with it. With no output schema, the description adds real behavioral value by naming the fields returned (version, build, memory, VMs) and by disclosing the default-target fallback behavior for the optional parameter.

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 blocks, front-loaded with the read tag and the one-line purpose, followed by only the two argument notes that the schema does not supply. No filler sentences.

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

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

For a two-parameter read tool with no output schema, the description covers purpose, both arguments, and the main returned fields, which is close to sufficient. It stops short of noting error behavior for an unknown uuid or the target-resolution failure mode.

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 largely meets it: host_id is identified as a host uuid with a pointer to host_list, and target is explained as an XO target name from config whose omission selects the default. The target explanation stays vague about which config source and valid values, keeping it below 5.

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 and scope: detail for ONE host identified by uuid, contrasted implicitly with the list-style sibling host_list. The parenthetical enumeration (version, build, memory, VMs) further pins down what kind of detail is returned. Not quite a 5 because the verb is nominalized ('Detail for') rather than an explicit action verb.

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 tells the agent where to obtain the required input ('see host_list') and how to handle the optional target ('omit for the default'), which is useful routing. However, it never states when to reach for host_get versus a sibling such as pool_get or vm_get, or any precondition beyond the uuid lookup.

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 declare readOnlyHint=true, and the '[READ]' tag in the description is consistent with that. The description adds the set of fields returned, which is useful, but says nothing about pagination, result limits, or behavior when the pool filter matches nothing. With annotations covering safety, this is adequate but adds only modest extra 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?

Front-loaded with the read tag and purpose, followed by a short args block. No filler sentences and no repetition, though the field list in the opening line duplicates information the agent could infer from a call result.

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 appropriately enumerates the returned fields, and it documents both parameters. The main remaining gap is lack of guidance on result volume or filtering behavior, but for a simple read-only list tool this is close to 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 coverage is 0%, so the description must carry the burden for both parameters, and it does: 'pool' is identified as an optional pool uuid filter and 'target' as the Xen Orchestra target name from config, with the instruction to omit it for the default. That is meaningfully more than the bare, undescribed schema properties.

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 hosts') and goes further by naming the returned fields (version, state, memory usage, resident VM count). The 'List' framing distinguishes it from the sibling host_get, though it doesn't call that distinction out explicitly.

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 guidance, no exclusions, and no reference to alternatives such as host_get for a single host. The only usage-adjacent text is the 'target' parameter note, which is parameter guidance 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 declare readOnlyHint=true, so safety is covered. The description adds meaningful behavior: it is best-effort, fans out over other read operations, and a failing collection reports an error block rather than blanking the rest. That partial-failure semantics is real behavioral context beyond the annotations, though return format/pagination is not addressed.

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 [READ] tag and a one-line summary, then scoping and failure semantics, then args. Efficient overall, though the bracketed [READ] prefix duplicates the readOnlyHint annotation.

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 single-parameter fan-out read tool with no output schema, the description covers purpose, scope, failure behavior, and the one parameter. The absence of any note on payload structure or size is a minor gap but not blocking.

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% and the schema only gives a title for target with no description. The description compensates by explaining target is a Xen Orchestra target name from config and that omitting it uses the default. Since there is only 1 optional parameter, this is adequate, but no format or valid-value guidance is added.

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: 'One-shot health summary: pools, hosts, VMs, SRs, recent backups.' The resource scope is enumerated precisely, and it is clearly distinguished from siblings like pool_list, host_list, vm_list which each cover one resource.

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

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

'Start any triage here' gives an explicit entry point, and it names the relationship to alternatives by explaining it fans out over the other read ops. An agent knows when to pick this over the individual list tools.

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

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

The '[READ]' tag agrees with readOnlyHint=true, so there is no contradiction, but it adds nothing beyond what the annotation already declares. No auth requirements, rate limits, or return-shape notes are provided; with annotations covering the safety profile, this is minimally viable.

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

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

Front-loads the one-line purpose, then a short Args block with exactly the two parameters. No filler sentences, though the '[READ]' prefix is redundant with the annotation.

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?

A simple read tool with two parameters, both explained, and a cross-reference to pool_list for the required uuid. No output schema exists so return values need not be described, leaving little an agent would still need.

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 burden and does so: pool_id is identified as a pool uuid sourced from pool_list, and target is described as a Xen Orchestra target name from config with the default used when omitted. This meaningfully compensates for the undocumented 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 resource (pool) and scope ('one pool by uuid'), which cleanly separates it from the list-style sibling pool_list, which it also references. 'Detail' is a slightly soft verb but the intent is unambiguous.

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

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

Clearly implies the trigger condition: you need one specific pool and already have its uuid, with 'see pool_list' routing the agent to the tool that supplies that uuid. No explicit when-not or alternative conditions are given, but the context is sufficient.

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?

readOnlyHint=true already declares the safety profile, and the '[READ]' prefix merely restates it. The description does add value by disclosing what each returned record contains (master, HA state, default SR), but says nothing about pagination, filtering, or auth/target resolution behavior beyond the param note.

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?

Short and front-loaded: the capability sentence comes first, followed by a compact Args block for the single parameter. No waste, though the '[READ]' tag duplicates the readOnlyHint annotation rather than earning 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?

There is no output schema, and the description compensates by naming the salient returned fields. For a one-optional-parameter read-only listing tool this is nearly sufficient; the only real gap is the absence of any note on result size/pagination.

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% (only a bare 'Target' title with default null), so the description must carry the param burden and it does: it explains that target is a Xen Orchestra target name from config and that omitting it selects the default. That is real semantic clarification beyond the schema, though it stops short of format examples.

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 XCP-ng pools') and even names the fields returned (master, HA state, default SR), which is more than a tautology. It does not explicitly contrast itself with the sibling 'pool_get', so an agent must infer the list-vs-single distinction, keeping it at a 4 rather than 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?

Usage is implied: a read-only listing tool is obviously for enumeration/discovery, and the target param guidance ('omit for the default') is a useful usage note. However, there is no explicit when-to-use statement, no when-not-to-use, and no pointer to pool_get for fetching a specific pool.

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 goes further by stating findings carry a 'cause + action' per item and enumerating the four condition classes it detects, which tells the agent what kind of result to expect from a tool with no output schema.

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 tag prefix and one-sentence purpose, then an enumeration of findings, then a compact Args block — no filler. The Args section largely restates the schema property names, which is the only minor 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 an analysis tool with no output schema and only a readOnly annotation, the description supplies the missing context: what is analyzed, what is flagged, and that results pair a cause with an action. Adding the default-scope behavior when pool_id is omitted would make it fully self-contained.

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: pool_id is described as an optional pool uuid that narrows analysis to one pool, and target as a Xen Orchestra target name from config that defaults when omitted. That adds real semantics beyond the bare string types, though it omits uuid format details.

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 operation (assess patch & HA posture per pool) and enumerates exactly what it detects: missing patches, pending reboots, version skew, and multi-host pools without HA. This clearly separates it from sibling reads like pool_get or pool_list, which fetch inventory rather than diagnose posture.

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: omit pool_id to scan everything, pass one to narrow scope, and the [RCA] tag signals a diagnostic rather than a mutating call. However, it never states when to prefer this over pool_get or vm_health_rca, nor when-not to use it, so the agent must infer the selection criterion.

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 flag readOnly=false, idempotent=false, destructive=true, but the description goes further by disclosing the undo-recording mechanism (real snapshot id captured from the XO response so snapshot_delete is replayable) and the dry_run no-undo behavior. This is meaningful behavioral detail an agent cannot get from structured fields.

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

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

Front-loaded with the operation class and inverse, then undo semantics, then a tidy Args block. Every line earns its place, though the tag line and inverse line overlap slightly with the write framing.

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 non-idempotent write tool with no output schema, the description supplies operation class, inverse routing, undo mechanics, dry-run behavior, and full parameter meaning. Nothing required to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so for all four params: vm_id (uuid, see vm_list), name (with example format), dry_run (preview without snapshotting, no undo recorded), and target (XO target from config, omit for default). No parameter is left ambiguous.

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 ('Snapshot a VM') and immediately names its inverse (delete THAT snapshot), which cleanly separates it from siblings snapshot_delete, snapshot_revert, and snapshot_list. The [WRITE][risk=medium] tag adds an at-a-glance operation class.

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 clear operational context: the inverse operation is snapshot_delete and the undo is recorded and replayable. It cross-references vm_list for obtaining vm_id. It stops short of stating explicit when-not conditions (e.g. when to prefer snapshot_revert), so it is strong but not fully complete.

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 destructiveHint=true and non-idempotency, but the description adds material context beyond them: irreversibility, that no undo is registered, that prior state (name/time/parent VM) is captured for audit, and that dry_run allows a safe preview. This is unusually rich disclosure for a destructive tool.

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 impact tags and the core action, followed by a tightly structured Args block. The audit-record sentence is slightly wordier than needed but earns its place by disclosing audit behavior.

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 high-risk, non-idempotent write with no output schema, the description covers action, irreversibility, param meaning, and the dry_run escape hatch. It stops short of stating required permissions or the shape of the dry_run/deletion response, which would fully close the loop.

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: snapshot_id is the snapshot uuid (with snapshot_list as source), dry_run is a non-destructive preview, and target is the Xen Orchestra target name from config with an explicit 'omit for default' default behavior.

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

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

Specific verb+resource ('Delete a VM snapshot by uuid') with severity/type tags ([WRITE][risk=high]) and an explicit irreversibility claim. It also points to snapshot_list for obtaining the uuid, distinguishing it from sibling read/restore 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 IRREVERSIBLE warning plus dry_run preview and the 'declares no undo' statement give clear context for when this is appropriate, and snapshot_list is named for id lookup. However, it never explicitly contrasts with snapshot_revert/undo_apply, so the routing is implied rather than stated.

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

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

Annotations only declare readOnlyHint=true; the description goes further by disclosing the return envelope and, importantly, that 'truncated is true' means more snapshots exist than were returned — a non-obvious behavioral trait. It does not cover ordering, rate limits, or permission requirements, so it is strong but not exhaustive.

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 purpose, then the return shape, then a compact Args block — no filler sentences. The return-shape line earns its place because no output schema exists, though it slightly interrupts the purpose-to-parameters flow.

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 exactly what is missing: the response envelope keys and the meaning of the truncated flag, plus documentation for all three otherwise-undocumented parameters. Nothing an agent needs to invoke and interpret this tool correctly is absent.

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 document all three parameters: vm_id as an optional VM uuid filter, limit as a post-filter cap with default 200, and target as a config-derived Xen Orchestra name where omission selects the default. The 'after filtering' qualifier on limit is meaningful semantics the schema does not express.

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 VM snapshots') plus its scope ('optionally filtered to one VM'), which cleanly separates it from the sibling mutation tools snapshot_create, snapshot_delete and snapshot_revert. An agent can identify the read/list tool without opening any schema.

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

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

The '[READ]' prefix and 'optionally filtered to one VM' establish when to reach for this tool, and '(see vm_list)' routes the agent to the sibling needed to obtain a vm_id. There is no explicit statement of when NOT to use it (e.g. versus a single-snapshot fetch), so it falls short of a full 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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the critical operational facts: the operation is IRREVERSIBLE, the VM's current state is replaced, and no undo is declared. This goes well beyond what the annotations convey.

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

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

The risk warning is front-loaded ahead of everything else, which is exactly right for a destructive tool, and the Args block is compact. Minor slack in the audit-record sentence, which is informative but slightly vague about what is being captured.

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 high-risk mutation with no output schema, the description covers safety profile, reversibility, prerequisites, a safe preview path, and every parameter. Nothing an agent needs to avoid a destructive mistake 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 burden — and it does: snapshot_id is a snapshot uuid (source: snapshot_list), dry_run previews without reverting, and target is the Xen Orchestra target name from config with an explicit omit-for-default rule.

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 ('Revert a VM to a snapshot') and immediately scopes it with [WRITE][risk=high]. It is clearly distinguishable from the sibling snapshot_create/snapshot_list/snapshot_delete tools, which it names directly.

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 the agent when NOT to use it carelessly ('take a fresh snapshot first (snapshot_create) if you may need to come back') and offers a safe alternative path via dry_run. Routes the agent to snapshot_list for obtaining the id.

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, and the '[READ]' tag merely restates that. The description adds no behavioral context beyond safety — no error behavior for a bad uuid, no note on what the detail contains, no permission requirements. Little value 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?

Front-loaded with the operation summary, followed by a compact Args block for the two params. No filler sentences, though the '[READ]' prefix is redundant with the annotation.

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 annotations covering safety and no output schema, the description is adequate on parameters. It falls short on what the returned detail contains and failure behavior, which an agent calling with a uuid would benefit from knowing.

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 burden, and it does document both parameters: sr_id as the SR uuid (pointing to sr_list for lookup) and target as the Xen Orchestra target name from config with 'omit for the default'. This meaningfully compensates for the empty schema descriptions.

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

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

States a specific verb and resource ('Detail for one SR by uuid'), and the singular 'one SR' versus the sibling sr_list makes the scope distinction immediately clear. An agent can identify this as the single-resource read 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 parenthetical '(see sr_list)' routes the agent to the sibling for obtaining a uuid, which is useful implied guidance. However, it never states when to use this over other SR-related siblings (sr_usage_rca, sr_rescan) or any preconditions.

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?

readOnlyHint=true already covers the safety profile, and the description adds genuinely new behavioral context: the exact return envelope ({"srs", "returned", "limit", "truncated"}) and the meaning of the truncated flag with its follow-up implication. It does not mention auth requirements or rate limits, so it is not a 5.

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

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

Front-loaded with the [READ] marker and the one-line purpose, followed by return shape, truncation note, and an args block — every line carries information. The pseudo-signature style of the Args section is slightly verbose but not wasteful.

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

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

With no output schema, the description supplies the return envelope and the truncation semantics itself, and documents all three otherwise-undocumented parameters. An agent has everything needed to call this correctly 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?

Schema description coverage is 0%, so the description carries the full burden and does so: pool is documented as an optional pool uuid filter, limit as the maximum returned after filtering with a default of 200, and target as the XO config target name with explicit omit-for-default behavior. Only the uuid format of pool 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?

The description states a specific verb and resource ("List SRs") and even names the payload fields returned (capacity, physical usage, virtual allocation), so an agent knows exactly what it fetches. It does not explicitly contrast with sr_get or sr_usage_rca, which are the closest siblings, so it falls short of 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 the truncation note imply a read/list usage pattern, but no when-to-use conditions or alternatives are stated (e.g., use sr_get for a single SR, sr_usage_rca for capacity analysis). Usage is inferable from the verb but not guided.

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 a non-read-only, non-idempotent write, and the description usefully reconciles this by stating nothing is destroyed ("no data change") and no undo record exists. It adds the dry_run preview mechanism, but it never explains idempotency, expected duration, or failure behavior, leaving some tension with destructiveHint=true unaddressed.

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 risk tag and purpose sentence are front-loaded, followed by a compact rationale and an Args block — a good structure. It is slightly repetitive, restating the "no undo" point twice ("no data change, no undo" and "records no undo (there is no prior state to restore)").

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, 3 parameters, and a mutation annotation set, the description covers the essentials: write class, destructiveness, undo, dry-run, and all parameters. What it omits — return shape, whether the rescan is long-running, and retry/idempotency expectations — is minor for a metadata refresh.

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: sr_id is typed as an SR uuid with a cross-reference to sr_list, dry_run is described as a non-destructive preview, and target is explained as an XO target name sourced from config with an omit-for-default behavior.

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 ("Rescan an SR") and immediately qualifies scope with "metadata refresh — no data change, no undo," plus a [WRITE][risk=medium] tag that separates it from the read-only siblings like sr_list/sr_get. It does not explicitly name a competing sibling to route against (e.g., sr_usage_rca), so it falls just short of the top band.

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 only implied: the tool is framed as the "lowest-impact write" for refreshing metadata, and the dry_run argument hints at a preview-then-commit workflow. There is no explicit "use this when X / use Y instead" and no exclusions relative to sr_list, sr_get, or sr_usage_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 readOnlyHint=true, so the safety profile is covered (the [READ] tag is redundant with it). The description adds useful behavioral detail about what analysis is performed, but says nothing about cost, runtime, or scope limits for large SR sets.

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 purpose followed by three tight clauses describing the analyses, then a compact Args block. The bracketed tags are minor noise but nothing is padded or repeated.

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

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

No output schema exists, yet the description enumerates the key outputs an agent would care about (cause + action per finding, reclaimable bytes). Nothing essential to invoking it correctly is missing for a single-optional-param read tool.

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

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

Schema coverage is 0% and the schema only exposes 'target' as an untyped anyOf with default null, so the description carries the burden — and it does: 'Xen Orchestra target name from config; omit for the default.' It fully explains the one parameter's source and default behavior.

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 ('SR usage root-cause analysis') and enumerates the exact findings it produces: physical fullness ranking, thin-provision overcommit detection, and orphaned VDI totals with reclaimable bytes. This clearly differentiates it from sibling read tools like sr_list, sr_get, and sr_rescan.

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 [RCA] tag and the description of findings imply the diagnostic use case, but the description never says when to pick this over sr_list/sr_get or the sibling *rca tools, nor does it state any exclusion. Usage is inferable but not 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?

Annotations only declare readOnlyHint=true; the description goes well beyond that by spelling out the exact response contract (tasks/returned/limit/truncated) and the meaning of the truncated flag plus the remediation path. This is meaningful behavioral disclosure the annotations cannot provide.

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

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

Front-loaded purpose, then return shape, then an Args block — the ordering is agent-friendly and each sentence carries information. Minor duplication of the 'limit' concept between the return-shape line and the Args block, and the Args-style formatting is slightly verbose for three parameters.

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

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

No output schema exists, and the description supplies the return shape and truncation semantics itself, so an agent has everything needed to call the tool and interpret its result. Filter values, defaults, and target resolution are all covered.

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% and the schema has no enum or descriptions, so the description fully compensates: it defines status's valid values (pending/success/failure), explains that limit is applied after filtering with default 200, and clarifies that target comes from config and may be omitted for the default.

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

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

States a specific verb and resource ('List XO tasks') plus the optional filter dimension ('by status'), and the [READ] tag signals the operation class. No sibling tool (backup_job_list, backup_log_list, snapshot_list, etc.) covers tasks, so the scope is unambiguous.

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

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

Gives concrete follow-up guidance for the truncated case ('re-run with a higher limit or a narrower status filter'), which tells the agent how to act on the result. It does not, however, state when this tool should be preferred over other listing tools or any preconditions, so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructive, non-read-only, and non-idempotent behavior. The description adds that the inverse runs through its own governed tool with separate audit and risk tier, that dry_run previews without executing, and that tokens are single-use. This is meaningful context beyond structured fields.

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

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

Front-loads the write/risk tag, then explains the governed inverse behavior, then lists Args. Every sentence earns its place, though the description is slightly long for three parameters.

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 three-parameter write tool with annotations but no output schema, the description covers invocation, safety context, and parameter meaning. It omits dry_run return format and auth details, but is otherwise complete enough to call 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 0%, but the description documents all three parameters: undo_id source, dry_run preview behavior, and target pass-through when the inverse accepts it. It fully compensates for the missing schema descriptions.

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

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

States a specific verb and resource: applying a recorded undo by dispatching its inverse tool. Distinguishes from undo_list by describing apply versus list. The [WRITE][risk=medium] tag reinforces the operation 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?

Explains dry_run=True previews the inverse call and that a token can only be applied once. Sources undo_id from undo_list or a write result. Stops short of explicit when-not guidance, but gives clear context for use.

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

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

Beyond the readOnlyHint annotation, the description discloses non-obvious behavior: an extra row is read so ``truncated`` is measured rather than inferred, and ``effectVerified=false`` means the reversed change is probable, not confirmed. Neither fact is derivable from annotations or schema, and both affect how an agent interprets 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 core purpose, then behavior, then args — a logical order with no filler sentences. It is somewhat long and dense with backtick markup, but every clause carries decision-relevant information, so the length is justified.

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

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

No output schema exists, so the description carries the return-value burden and does: it enumerates the entry fields (original tool, inverse tool, human note, undoId, effectVerified) and explains the truncation signal. An agent has everything needed to call 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?

Schema description coverage is 0%, so the description must compensate, and it does: ``limit`` is documented as default 50, capped at 500, and ``target`` is explicitly flagged as unused/accepted only for CLI uniformity. That last point prevents an agent from wasting a call passing a meaningful-looking filter.

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 verb and resource — 'List recorded, not-yet-applied undo tokens' — plus ordering ('most recent first'), which immediately separates it from the write-side sibling undo_apply. An agent can tell what this returns without opening either schema.

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

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

It explicitly routes the agent to the alternative ('Use the ``undoId`` with ``undo_apply``') and adds a conditional warning — when ``effectVerified`` is false, check live state before applying and do not report it as a confirmed restore. When-to-use and when-to-be-cautious are both stated.

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

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

Annotations only declare readOnlyHint=true; the description goes further by defining which VDIs count as orphaned (no VBD) and by spelling out the truncation contract ('when truncated is true there are more disks than were returned'), which is the key pagination behavior. It stops short of noting cost, rate limits, or required permissions, so not a 5.

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

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

Front-loaded with the [READ] marker, purpose, and the filter semantics, then the return shape, then args. Mostly waste-free, though the Args block restates defaults already present in the schema (limit=200, null defaults), which is mild redundancy.

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

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

With no output schema, the description compensates by naming the returned keys (vdis, returned, limit, truncated) and all four parameters. A caller has enough to invoke and interpret a truncated result, with only minor parsing details left implicit.

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 largely meets it: it labels sr as an 'SR uuid', describes orphaned_only's meaning, gives the limit default, and explains where target's value comes from (config, omit for default). Minor gap: it doesn't clarify interaction between limit and truncation.

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 VDIs (virtual disks)') with two explicit scoping modes (per SR, orphaned-only). The resource is distinct from every sibling, so an agent can separate it from sr_list or vm_list 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?

The description explains what 'orphaned' means and calls the results 'candidates for reclaiming space', which implies when the filter is useful. However, it never states when to use vdi_list versus sr_list or vm_list, nor any exclusions or prerequisites, so routing 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?

The readOnlyHint annotation already declares the operation is safe, so the "[READ]" prefix is largely redundant. However, the description adds genuinely new context by naming the returned detail fields (state, host, OS, tools, tags) — valuable since no output schema exists — and clarifies the target-resolution fallback to config default.

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 one-line summary followed by two tight arg lines; nothing is padded. The bracketed "[READ]" tag is the only element that doesn't earn its place since the annotation already covers it.

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 single-object read with a 2-param schema and no output schema, the description covers purpose, both parameters, and the shape of the return payload. It stops short of describing not-found behavior or target-resolution errors, which an agent would need in edge cases.

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: vm_id is defined as the VM uuid with a pointer to vm_list, and target is defined as the Xen Orchestra target name from config with explicit omit-for-default behavior. It doesn't specify uuid format or what an unknown target does, keeping it short of a 5.

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 ("Detail for one VM by uuid") and even enumerates the fields the detail covers (state, host, OS, tools, tags). It explicitly cross-references the sibling vm_list for obtaining the uuid, making it distinguishable from vm_list, vm_stats, and vm_health_rca at a glance.

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: "see vm_list" tells the agent where the id comes from, and the target param explains omission falls back to the default. There is no explicit when-to-use/when-not guidance versus vm_stats or vm_health_rca, which also operate on a single VM.

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 burden for behavior beyond safety. It helpfully discloses what it checks and that output is cause + action per finding, but it does not state the time window for 'recent stats,' how halted/paused states are classified, or whether it requires guest tools to be present to reach a verdict. Useful but incomplete.

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

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

Front-loaded with the tag and purpose, then the flagged conditions, then args in a clean block. Slightly long due to the args section, but no sentence 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?

For a read-only RCA tool with no output schema and only two optional params, the description is nearly sufficient: it names what is analyzed, what conditions are flagged, and the one-VM vs. fleet switch. The remaining gap is operational detail (time window, output shape), which the agent would otherwise have to infer.

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. It does explain both params: vm_id as the optional single-VM selector and target as the Xen Orchestra config target name with a default when omitted. That is adequate coverage of intent, but it adds no format details (e.g., uuid format, available targets) beyond schema field 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?

Specific verb+resource: 'VM health root-cause analysis — cause + action per finding.' It explicitly lists the four failure conditions it flags (halted, paused/suspended, running without guest tools, CPU/memory pressure), which distinguishes it clearly from siblings like vm_stats (raw metrics) and vm_get (config detail).

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 states the scope choice explicitly: 'Analyze one VM (vm_id) or the whole fleet,' and explains that omitting vm_id analyzes everything. It does not name alternative tools (e.g., use vm_stats for raw metrics instead), so it stops 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?

Annotations only declare readOnlyHint=true, so the description carries the rest and does so well: it documents the exact return envelope (vms/returned/limit/truncated), the truncation pitfall, and the default limit of 200. It does not mention auth requirements or ordering/pagination behavior beyond limit, leaving a modest gap.

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

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

Front-loads the purpose, then the return shape and truncation caveat, then a compact args block. Every sentence adds information; nothing is redundant filler despite the multi-section layout.

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 steps in to describe the response envelope and the truncation flag, and it covers all four parameters. An agent has everything needed to call this correctly and interpret the result without opening a schema.

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% and no enums are declared, so the description does all the work: it supplies the accepted power_state values (Running/Halted/Paused/Suspended), explains pool as a uuid filter, states the limit default, and clarifies that target comes from config and may be omitted. This meaningfully exceeds what the bare 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?

States a specific verb and resource ('[READ] List VMs') and enumerates the returned fields (power state, host, tools status, sizing), which distinguishes it from vm_get, vm_stats and vm_health_rca at a glance. The [READ] marker reinforces the operation 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?

Gives clear operational guidance — re-run with a higher limit when 'truncated' is true rather than treating the result as the whole fleet — plus filter semantics for power_state and pool. It never names a sibling (e.g. vm_get for a single VM) or states when not to use this tool, so it stops short of full when/when-not coverage.

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=false and destructiveHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the live nature of the move, that the real source host is captured before the move, and that the recorded undo is replayable (and that dry_run records no undo). It stops short of stating failure behavior or disruption impact.

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 risk tag and core action, followed by the inverse/undo note and a compact args list. Every line earns its place, though the Args block is somewhat list-like rather than 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 mutation tool with no output schema, the description supplies the undo/replay semantics, the dry-run escape hatch, and parameter sourcing. Remaining gaps (failure modes, permissions, rate limits, return shape) are minor and partly covered by the destructive annotation.

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 it documents all four parameters with meaning: vm_id/host_id as uuids with pointers to vm_list/host_list, dry_run as a no-undo preview, and target as a config name that is omitted for the default. It lacks uuid format details but compensates well for the coverage gap.

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 and resource ('Live-migrate a VM to another host') with a risk tag, and it explicitly declares its inverse relationship ('migrate back'), which distinguishes it from lifecycle siblings like vm_start/vm_stop. An agent can tell what this tool does 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 explains when to use dry_run (preview with no undo recorded) and points to vm_list and host_list for sourcing the required ids. It does not name an explicit alternative or a when-not-to-use case, but the operational context is clear.

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

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

Annotations already mark this write/destructive/non-idempotent, so the bar is lower. The description adds real value beyond annotations: the [WRITE][risk=medium] tag, 'No undo', the note that prior power state is audit-only, and the dry_run preview option. It still omits the operational impact (guest downtime/service interruption) and any permission requirements.

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 [WRITE][risk] marker and the core action, followed by a clean Args list. The middle sentence about the absence of a meaningful inverse is somewhat verbose for the value it adds, but overall it is tight and well-organized.

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 destructive, parameterized mutation with no output schema, the definition covers purpose, all params, irreversibility, and the dry-run escape hatch. It is largely complete, with the only remaining gap being the runtime impact on a live guest.

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 documents all four parameters: vm_id as a VM uuid with a pointer to vm_list, force as hard vs clean, dry_run as preview, and target as the Xen Orchestra target with omission meaning default. It fully compensates, though it adds no format details for vm_id beyond 'uuid'.

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 — 'Reboot a VM' — and disambiguates the mode (clean vs hard with force), so an agent knows exactly what the tool does. It does not explicitly contrast itself against siblings like vm_start/vm_stop, so it lands at clear-but-no-sibling-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 description implies usage through the clean/force distinction and the 'see vm_list' pointer for the VM id, and it warns 'No undo'. However, it never states when to reboot versus stopping and starting, nor any preconditions or exclusions, so guidance is only implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: a medium risk rating and the fact that dry_run skips undo recording, which implies the tool participates in an undo/rollback system. It does not state what happens if the VM is already running.

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

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

Front-loaded with the action and inverse in one line, then a tight three-item args list. Nothing is padded, and the most routing-relevant information (what it does, what undoes it) comes first.

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

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

With no output schema and only three parameters, the description covers operation, inverse, alternative discovery path, and per-parameter meaning. Remaining gaps are minor: error behavior for an already-running VM and any required auth/permission context are 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 carries the full burden and does so: vm_id is defined as a VM uuid with a discovery pointer (vm_list), target is explained as a Xen Orchestra target name from config that defaults when omitted, and dry_run's semantics (preview, no undo recorded) are spelled out. No parameter is left 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 ('Start a VM') and immediately names the sibling it inverts ('Inverse: vm_stop'), letting an agent route between vm_start/vm_stop/vm_reboot without opening schemas. The [WRITE][risk=medium] prefix adds operation class and risk at a glance.

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 points to vm_list for resolving vm_id and to vm_stop as the inverse operation, and explains dry_run as a non-committing preview. It stops short of stating when not to use it (e.g. VM already running, or reboot being preferable to a stop/start cycle).

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?

readOnlyHint=true already declares the safe-read profile, and '[READ]' merely restates it. The description does add useful context beyond annotations: these are RRD-backed *averages* (aggregation semantics) and the granularity determines resolution. It still says nothing about latency, caching, or result 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?

Front-loaded with the purpose and a clear READ tag, then an Args block covering each parameter. Efficient and well-organized, with only minor redundancy between '[READ]' and the readOnlyHint annotation.

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

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

No output schema exists, yet the description never characterizes the returned stats (metric names, units, time-window shape). For a simple read tool with all params documented this is adequate but leaves the return value opaque.

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 burden and does so for all three parameters: vm_id as a VM uuid with a pointer to vm_list, granularity's value set (seconds/minutes/hours/days) and default, and target's meaning with the omit-for-default rule. The granularity value list is especially valuable since the schema has no enum.

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 (VM) and content (CPU/memory stats), further qualified as RRD-backed averages. This distinguishes it reasonably well from vm_get (full details) and vm_health_rca (health diagnosis), though it never names a sibling explicitly.

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 guidance on when to prefer this tool over vm_get, vm_health_rca, or vm_list. The '(see vm_list)' note is a cross-reference for obtaining a vm_id, not usage guidance, and no exclusions or prerequisites are given.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false. The description adds substantial extra behavior: it records the prior power state (implying an undo entry, consistent with the undo_list/undo_apply siblings), dry_run records no undo, and stopping the XO self VM is refused because it would cut the very API path needed for recovery. It also discloses that the IP-based selfVmHint is a non-blocking coincidence, not a verdict.

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 action and its risk tag, then layers semantics, the refusal guard, and the dry-run caveat in a logical order. Most sentences earn their place, but the passage on the IP-based selfVmHint is longer than strictly needed and repeats the 'not a verdict / not a block' idea.

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 four parameters, no output schema, and only coarse annotations, the description supplies the missing behavioral contract: refusal condition, undo/prior-state capture, dry-run semantics, and the force trade-off. It stops short of describing failure modes for a non-XO stop (e.g., guest tools absent) or what the return payload contains.

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 four parameters, and it does: vm_id (uuid, cross-referenced to vm_list), force (hard power-off vs. guest shutdown), dry_run (preview with no undo recorded), and target (XO target name from config, omit for default). This adds meaning well beyond the bare schema types.

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 ('Stop a VM') and immediately qualifies the two modes (clean shutdown vs. hard power-off with force). It also explicitly names its inverse sibling, vm_start, so an agent can distinguish it from vm_reboot and vm_start 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 clear conditions for choosing the two paths: clean shutdown requires guest tools, force maps to hard power-off. It also explains the dry_run path and the self-VM refusal. It does not, however, contrast with vm_reboot or state when a stop is preferable to a reboot, so usage guidance is strong but not fully exhaustive.

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