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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the mutation risk profile is covered structurally. The description adds the authorization gating context, but says nothing about resource cost, what a checkpoint consumes on the host, or whether repeated calls with the same name collide.

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

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

Two short sentences with the action front-loaded ahead of the precondition. The second sentence is terse to the point of using unexplained internal flag names, but nothing 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?

An output schema exists, so return values need no explanation, but the definition leaves the two required parameters completely undocumented and refers to 'ALLOW_CHECKPOINTS' and 'an allowlist' without saying how they are satisfied. For a destructive write tool with zero schema coverage, that is a meaningful 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 description coverage is 0% for both required parameters, so the description must carry the meaning of vm_name and name but mentions neither. An agent must infer that vm_name selects the target VM and name labels the checkpoint, with no guidance on naming rules or uniqueness.

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 ('Create a manual checkpoint'), which distinguishes it from checkpoint_list, checkpoint_restore and checkpoint_delete by name. It does not explicitly explain how 'manual' differs from an automatic checkpoint, so it falls short of full 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?

Names two preconditions (ALLOW_CHECKPOINTS and an allowlist) that must hold before calling, which is a real usage gate. However, it never says when to choose this over checkpoint_restore/delete or what to do if the gate fails, and neither flag is explained.

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-idempotent, so the safety profile is covered. The description adds genuine behavioral context beyond that: disks are merged as a side effect, child checkpoints are deliberately left behind, and exact confirmations are enforced — all of which matter for a destructive operation.

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

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

Three short sentences, front-loaded with the action and its scope, then the non-recursion caveat, then the confirmation requirement. 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 annotations covering safety and an output schema covering returns, the description is nearly complete for a 4-required-param destructive tool. The remaining gap is how an agent obtains a valid snapshot_id and the precise confirmation-matching rule.

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% across 4 parameters, so the description must compensate. 'Requires exact confirmations' signals that confirm_vm and confirm_snapshot_id are echo-checks of the identity parameters, but it never states they must match vm_name/snapshot_id or what happens on mismatch, leaving the mechanism to inference.

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 one checkpoint') with a stated scope boundary ('one checkpoint', 'child checkpoints are not recursively included'). It effectively separates the tool from checkpoint_create/checkpoint_restore by implication, but never names an alternative explicitly, so it falls short of full 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 destructive-delete context is implied by 'Delete one checkpoint', and 'Requires exact confirmations' flags a prerequisite, but the description never states when an agent should choose this over checkpoint_restore or checkpoint_list, nor any when-not condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful return-field detail (parents, creation times) but says nothing about scope (per-VM vs global), ordering, or pagination 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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though it is terse to the point of omitting scoping and usage information that would cost only a few words.

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 an output schema present, return values needn't be described, and annotations cover the safety profile. For a one-parameter read tool this is minimally adequate, but the absence of any usage guidance or vm_name semantics leaves 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 is the only place vm_name could be explained — and it never mentions it. The parameter is self-evident from its name, so the omission is minor rather than damaging, but no added meaning is provided.

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 (list) and resource (checkpoints), and enumerates the fields returned: IDs, names, parents, creation times. It is easily distinguished from checkpoint_create/restore/delete by the verb, but the description never explicitly contrasts with those siblings.

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

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

There is no statement of when to use this versus checkpoint_create, checkpoint_restore, or checkpoint_delete, and no prerequisites or exclusions. The agent must infer usage entirely 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 flag destructiveHint=true, so the bar is lower, but the description adds real value by naming what is destroyed ('discarding later guest state') and by disclosing the double-confirmation guardrail. It stops short of saying what state the VM is left in after restore or whether the operation is recoverable.

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 sentences, front-loaded with the action and its destructive consequence, then the confirmation constraint. 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?

Output schema exists and annotations carry the safety profile, so the description only needs the hazards and the guardrail, which it supplies. Minor gaps remain around prerequisite state and post-restore VM power state for a destructive 4-parameter tool with no documented params.

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

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

With 0% schema description coverage the description must compensate, and it does for the critical part: confirm_vm and confirm_snapshot_id must match exactly, implying they must equal vm_name and snapshot_id respectively. It leaves vm_name and snapshot_id themselves unelaborated, but those are largely self-evident.

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 ('Restore') and resource ('checkpoint') plus scope ('discarding later guest state'), which cleanly separates it from checkpoint_create/delete/list siblings in the same family. It is clear without needing to open the schema, though it doesn't explicitly contrast with sibling tools by name.

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 statement of when to use this versus checkpoint_create or checkpoint_delete, and no prerequisites such as 'the checkpoint must already exist' or 'vm_name must be a listed VM'. Usage is only inferable from the destructive verb.

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, so the safety profile is covered. The description adds meaningful behavior beyond annotations by disclosing ordering and, importantly, that execution stops at the first failure. It does not explain authentication or exact failure semantics, but the key behavioral trait is present.

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

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

Two short sentences, front-loaded with the core capability and capped with the failure behavior. Every clause carries information; nothing is redundant.

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

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

The output schema exists, so return values need not be explained. However, for a destructive batch tool with an untyped nested actions array and 0% schema documentation, the description leaves a critical gap: an agent still cannot determine how to shape individual action objects or why vm_name is required.

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 lists possible action types for the 'actions' array, which adds some value, but it never describes the object structure needed to encode each action and never mentions the required 'vm_name' parameter at all.

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: run up to 32 ordered actions of enumerated types on a console. It clearly distinguishes itself as a batch executor from the single-action siblings such as console_type_text or console_click, though it does not name those alternatives 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?

The phrase 'up to 32 ordered' and 'stops at the first failure' implies this is for multi-step sequences rather than single actions, but it never says when to prefer this over the individual console_* tools or when not to use it. Usage is inferable but not 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 destructiveHint=true and readOnlyHint=false, so the description's job is to explain consequences — e.g. that a click lands inside the guest UI and can trigger real, irreversible actions. It says nothing about that risk, nor about required console session state, coordinate origin, or coordinate units, so it adds no behavioral context beyond 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?

Two short, front-loaded sentences with no filler; the primary action comes before the optional positioning step. It is efficient, though brevity here comes at the cost of the missing details noted elsewhere.

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?

An output schema exists, so return values need not be described, and the four parameters are few and mostly simple. What is still missing for a destructive interactive tool is console session prerequisites and the meaning/units of the guest-display coordinates. Note: the rubric's scoring for this dimension is applied leniently here because an output schema is present and the parameter set is small; the core gap remains the destructive-action and session-state context.

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 the description partially compensates by naming the three button values and clarifying that x/y are guest-display coordinates applied before the click. It still leaves vm_name unexplained, gives no units or origin for x/y, and does not note that x and y must be supplied together or that button defaults to left.

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?

It states a concrete verb (click) and the selectable resource (left/right/middle mouse button), but it never distinguishes itself from its close siblings console_mouse_buttons and console_mouse_move, which appear to cover overlapping ground. An agent cannot confidently pick console_click over those without guessing.

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 'use this when' guidance, no prerequisites (must the console be connected? must the guest display be active?), and no mention of the sibling tools that perform similar mouse operations. The only implicit guidance is the word 'Optionally', which hints that x/y are unnecessary.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful specificity by naming the exact Hyper-V secure-attention sequence, but it does not explain the guest-side consequences, authentication implications, or session effects beyond that.

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

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

The description is a single front-loaded sentence with no wasted language. It gets directly to the operation and target.

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

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

Given the simple one-parameter action and the presence of an output schema, the description is adequate to identify the operation and target. However, for a destructive guest-level action it lacks practical context about consequences and parameter expectations.

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 would need to compensate by explaining the vm_name parameter. It only says 'to the guest' and does not clarify expected format, whether a name or ID is accepted, or whether the VM must be running.

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: it sends the Hyper-V secure-attention sequence to the guest. This clearly identifies the operation as Ctrl+Alt+Delete-style attention, though it does not explicitly distinguish it from sibling console_press_keys or say when that specialized tool is preferred.

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 explicit guidance on when to use this tool, when not to use it, or which sibling to use instead for key sequences. The description implies a use case through the term 'secure-attention sequence,' but it provides no actionable selection criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds what the read yields (video-head resolutions) and why, but says nothing about failure modes (guest off, unsupported VM) or the shape/ordering of the multiple heads, which matters for a tool whose whole purpose is coordinate math.

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 sentence, front-loaded with the action and resource, with the use case appended. No filler or redundancy.

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

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

An output schema exists, so return values needn't be described, and the tool has only one obvious required parameter. However, for a tool whose output feeds coordinate planning, the description omits any hint about how heads map to coordinates or the prerequisite guest state, leaving it merely adequate.

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 the description never mentions the single parameter vm_name, so it does not compensate for the gap. The name is largely self-explanatory, but nothing clarifies accepted formats (VM name vs ID) or what happens when the VM is not found.

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 guest video-head resolutions") plus the downstream reason ("for mouse coordinate planning"), which distinguishes it from siblings like console_screenshot or console_mouse_move. It does not explicitly name the siblings it complements, so differentiation is implied rather than stated.

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 phrase "for mouse coordinate planning" implies the tool should be called before issuing mouse moves/clicks, but there is no explicit when-to-use, when-not-to-use, or prerequisite (e.g. guest must be running, which hypervisor/console backend). Usage must be inferred.

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 destructiveHint=true and idempotentHint=false; the description adds the crucial non-obvious behavior that keys can remain held across calls and must be explicitly released. It does not discuss per-VM scoping risk or what state is left behind if a release is skipped.

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 tight sentences, front-loaded with the action and followed by the two operational caveats. No filler or redundant 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?

An output schema exists, so return values need not be explained, but for a destructive, non-idempotent, 3-parameter stateful tool the description omits supported key vocabulary and key-name syntax. Adequate at the conceptual level, incomplete for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it largely does not. The press/release wording weakly implies the down flag, but key naming format, supported key vocabulary, and vm_name targeting are never explained.

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 concrete verb pair and resource ('press or release one supported key'), so an agent knows exactly what the tool does at the key level. It distinguishes itself from the chord-oriented sibling by name, though it never says what 'supported key' means, leaving key-domain ambiguity.

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

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

Explicitly routes ordinary chords to console_press_keys, which is the key selection rule versus the most similar sibling. It also gives a lifecycle rule (release held keys when finished), but does not state when direct key-state control is genuinely required over the alternatives.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds nothing about the critical behavior of a state-setter: whether the button stays held across calls and that it must be reset to false to release, which is exactly the failure mode an agent would hit during a drag.

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?

A single front-loaded sentence with no filler, which is the right shape for a low-complexity setter. It is perhaps too terse for the behavioral gaps, but nothing in it 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?

Output schema exists, so return values need no prose. What remains missing — button-state persistence/release semantics and the vm_name parameter — is real but modest against annotations that already signal a non-idempotent mutating operation.

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 names three of the four parameters (left/right/middle) but not vm_name, and it never explains that true means "held down" versus false meaning "released", nor mentions the defaults. Partial compensation only.

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 ("Set") and a specific resource ("explicit left, right, and middle synthetic-mouse button states"), and the phrase "for drag operations" hints at its niche versus console_click and console_mouse_move. It stops short of naming those siblings explicitly, so an agent must infer the boundary.

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?

"For drag operations" implies when to reach for this over console_click (discrete click) or console_mouse_move (positioning only), but no alternative is named and no exclusions or prerequisites are given. Usage is inferable 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?

The annotations already declare destructiveHint=true and idempotentHint=false, so the agent knows this is a non-idempotent, potentially destructive operation. However, the description adds no behavioral context beyond the coordinate system: it does not explain what could be disrupted, whether an active console session is required, or how the move interacts with subsequent clicks.

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?

A single well-structured sentence with no wasted words. The most important clarification (guest-display vs host-window coordinates) is front-loaded and explicit.

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 three-parameter tool with an output schema and annotations covering safety, the description is minimally adequate. It still lacks the operational context an agent might need: console-session prerequisites, interaction with click/button tools, and the meaning of vm_name.

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 meaningfully clarifies that x and y are absolute guest-display pixel coordinates, not host-window coordinates, which is valuable. It does not address the vm_name parameter at all, leaving part of the input semantics 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 and resource ('Move the synthetic mouse') and adds a crucial scope clarification about absolute guest-display pixel coordinates. It does not differentiate itself from sibling tools like console_click or console_mouse_buttons, so it is clear but not fully disambiguated.

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 no indication of when to use this tool versus alternatives such as console_click (which likely combines movement with clicking) or console_mouse_buttons. Usage is only implied by the word 'move'.

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, idempotentHint=false, and destructiveHint=true, so the safety profile is covered structurally. The description adds that keys are pressed and released via Hyper-V virtual-key codes, but it does not explain the destructive potential, required console state, or what guest actions might be triggered.

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

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

The description is a single, front-loaded sentence with no wasted words. The key behavior and an example parameter format are delivered immediately.

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?

An output schema exists and annotations cover the destructive/non-idempotent profile, reducing the burden on the description. However, with 0% schema parameter coverage, the description leaves gaps around vm_name, valid key naming, prerequisites, and when this tool should be chosen over sibling console-input tools.

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 parameter meaning. It partially compensates by showing the keys array as a chord (['ctrl','s']) or single key (['enter']) and mentioning Hyper-V virtual-key codes, but vm_name is undocumented and it does not clarify whether listed keys are pressed simultaneously or sequentially.

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: 'Press and release a key chord,' with concrete examples like ['ctrl','s'] and ['enter']. It does not explicitly differentiate this from sibling tools such as console_type_text or console_ctrl_alt_delete, but the key-chord framing is clear enough to distinguish the operation.

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 explicit guidance on when to use this tool versus alternatives like console_type_text, console_batch, or console_ctrl_alt_delete, nor are prerequisites such as requiring a connected console or running VM stated. The examples imply shortcut/key input, but usage remains inferred rather than directed.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that this is experimental, gated by an environment flag and allowlist, and depends on an existing visible interactive session rather than the guest framebuffer. It does not state failure behavior when no window exists, which keeps it from a 5.

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

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

Two sentences with zero filler, front-loading the operation and following immediately with the critical scoping caveat and prerequisites.

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 read that returns a PNG, the description covers the operational caveats and the output medium. With no output schema, it could say more about the returned image (dimensions, how it is delivered), but the essential call-path information is present.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it never mentions vm_name, region, or max_width. The only hint is the word 'window' in prose, which loosely gestures at the region enum at best.

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 (PNG capture of a visible VMConnect window) and adds a key disambiguator: it does not read the guest framebuffer, which separates it from other capture paths. It does not name a specific sibling alternative, 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?

Prerequisites are stated explicitly (ALLOW_SCREENSHOTS plus an allowlist), which tells the agent when the call will succeed. However, there is no guidance on when to prefer this over other console_* tools or what to do when the window is not open.

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 mark this as non-idempotent and destructive, but the description gives no explanation of what side effects make it destructive or what state it alters. It adds useful scroll-direction semantics for delta but omits prerequisites such as an active console/VM session.

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 compact sentences with the action front-loaded and no wasted words. The hedge 'normally' slightly weakens precision but the structure is efficient.

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

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

For a destructive, non-idempotent console mutation with an output schema, the description is too thin. It does not cover required session state, the effect of delta magnitude, or why the operation is considered destructive.

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

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

With 0% schema description coverage, the description must compensate for both parameters. It explains that delta is relative and that positive values normally scroll up, but vm_name is entirely unexplained and no units or magnitude guidance are provided.

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: applying a relative synthetic-mouse wheel delta. It is distinct from siblings like console_mouse_move and console_click, though it never states that the target is a VM console session.

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 explicit guidance about when to use this versus console_mouse_move, console_click, or console_mouse_buttons. The intended scrolling use is only implied by 'wheel delta'; no preconditions or exclusions 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 already declare readOnlyHint=false and destructiveHint=true, so safety is covered; the description adds that no VMConnect focus is needed and that non-ASCII input is rejected — useful operational context. It does not warn that typed text may execute commands in the guest (the source of the destructive hint), nor describe pacing/timing behavior, which is the main remaining 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?

Three tight sentences, front-loaded with the capability, then the constraint, then the practical note about focus. 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 an output schema present, the description needn't explain returns; it covers character set, alternative tool, and focus requirement. The one missing piece is typing speed/ordering guarantees, which matters for a keyboard-input tool but is not covered elsewhere.

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 for the critical 'text' parameter by enumerating exactly what bytes are accepted and what is rejected. 'vm_name' is left undefined but is self-evident.

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 (type text), the exact transport used (Msvm_Keyboard), and the accepted character set. It also names the sibling to use for Unicode input (guest_exec), so an agent can distinguish this from console_press_keys and guest_exec 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?

Explicitly sets the boundary: use this for printable ASCII/tab/CR/LF, use guest_exec for Unicode, and match the guest keyboard layout. It lacks an explicit when-not regarding console_press_keys for non-text keys, but the primary routing decision is stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context the annotations cannot: the host must have ALLOW_DEBUGGER set, guest credentials are needed, the VM must be Running, and the change only takes effect after a deliberate reboot. That post-state disclosure is exactly the kind of side-effect information a mutation tool needs.

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

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

Three short sentences, front-loaded with the capability, then prerequisites, then the reboot consequence. No filler; only minor friction from the dense phrasing of the first clause.

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 annotations covering the destructive profile and an output schema covering return values, the description fills the remaining gaps well: host precondition, VM state, credentials, and the deferred reboot. Left unstated are whether the prior debug configuration is overwritten and how to undo the change.

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, but it only names confirm_vm (already marked required in the schema) without explaining its expected value or how it relates to vm_name. It also surfaces ALLOW_DEBUGGER, which is not a parameter, potentially confusing an agent about what to pass.

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 (Enable) and a precise resource (fixed COM1/115200 guest BCD debugging via PowerShell Direct), plus the required VM state (Running). It does not explicitly contrast itself with the sibling debug_serial_prepare, so the agent must infer which debug variant to pick from the channel name alone.

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?

"while the VM is Running" and the requirement list (ALLOW_DEBUGGER, guest credentials, confirm_vm) give gating preconditions, and "a deliberate later reboot is required" signals follow-up work. However, there is no explicit alternative or when-not guidance, so routing between this and debug_serial_prepare is left implied.

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

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

Annotations already flag destructiveHint=true and non-idempotent, so the mutation risk is covered structurally. The description adds genuinely useful context beyond that: it requires the VM be Off, never stops or reboots the VM, and needs ALLOW_DEBUGGER plus confirmation. It does not say what existing COM1/serial configuration gets overwritten, which is the remaining 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?

Four short sentences, front-loaded with the scope and VM-state constraint before the exclusions and requirements. 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?

An output schema exists, so return values need not be described, and the Off-state requirement plus auth gates cover the essentials for this mutation. Still missing details on what happens to prior serial settings and acceptable VM states (e.g., Saved vs Off).

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 only explains that a local named pipe is used and that confirm_vm is an authorization gate. Neither the pipe name format (e.g., \\.\pipe\name) nor the expected confirm_vm value semantics are described.

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 (configure COM1 kernel debugging over a local named pipe) plus the required VM state (Off). It distinguishes itself from the sibling debug_guest_prepare by noting that guest BCD settings are a separate Running-VM operation.

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

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

Explicitly states the precondition (VM must be Off) and routes the guest-BCD case elsewhere, but never names the alternative tool (debug_guest_prepare) or debug_serial_status for verification. Prerequisites ALLOW_DEBUGGER and confirm_vm are given as gates, which is clear guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to explain safety. It adds useful scope by saying it reads both Hyper-V COM port debug configuration and local WinDbg/KDNET availability, but it does not mention prerequisites, permissions, or what the output represents.

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?

A single front-loaded sentence with no wasted wording. It names the operation and both resource domains efficiently.

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

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

The presence of an output schema and read-only annotations means the description does not need to explain return values or safety. However, it leaves the only parameter entirely undefined and does not clarify when this status tool should be chosen over related debug/serial sibling tools.

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 there is one required parameter, vm_name, which the description does not explain at all. It does not state whether vm_name must be an exact Hyper-V VM name, how to discover it, or how the debug configuration is scoped to that VM.

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 ('Read') and two concrete resources: Hyper-V COM port debug configuration and local WinDbg/KDNET availability. It is clearly a status/read tool and implicitly distinct from debug_serial_prepare, but it does not explicitly differentiate itself from sibling tools like serial_status or debug_guest_prepare.

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 this is a diagnostic/status read rather than a setup action, but it never states when to use it versus debug_serial_prepare, serial_status, or debug_guest_prepare. The agent must infer the correct routing from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description does add genuinely useful disclosure beyond that: events are redacted of commands, passwords, typed text and file contents, which tells the agent what it can safely log or replay. However, 'recent' is never bounded — no retention window, event cap, or truncation behavior — and it doesn't say the read requires an authenticated local MCP session.

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 sentence, front-loaded with the verb and resource, with zero padding or restatement of the title. It is efficient, though the space saved could have been spent on the cursor parameter.

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?

An output schema exists, so return values need not be explained. Against that lower bar the definition is still missing two things an agent needs to call it well: what 'recent' bounds (count or time window) and how after_sequence drives incremental reads.

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 meaning of after_sequence, and it says nothing about it. The cursor semantics that matter most for a snapshot tool — pass the last seen sequence to get only newer events, 0/default returns the current buffer — are left entirely to inference from the parameter name.

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 operation lifecycle events') and scopes it to 'this MCP instance', which implicitly separates it from the guest-level event tools in the sibling list. It does not name guest_events explicitly, so the agent must infer the split, but the object of the read 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?

No when-to-use guidance, no mention of guest_events as the alternative for guest-side events, and no polling/cursor guidance despite after_sequence existing. The agent is told what it reads but not when to prefer it over guest_events.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that results are 'recent' and filterable, but never discloses the actual time window default (72 hours) or the result cap (max_events 30), which are meaningful behavioral traits for an agent deciding whether this query is broad enough.

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?

A single front-loaded sentence with the resource and scope stated first. Efficient, though it spends words enumerating enum values the schema already declares.

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?

An output schema and read-only annotations reduce the burden, but for a 6-parameter tool with zero schema descriptions, the definition omits the required vm_name, the lookback default, and the event cap, leaving an agent to infer how to scope the query.

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, yet it only gestures at log_name, event_id, and level. The required vm_name, the hours lookback window, and max_events are left entirely unexplained beyond bare titles and defaults.

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 concrete verb (Read) and resource (event records) scoped to guest VM logs, and names the four supported log channels. It does not distinguish itself from the sibling events_snapshot, which an agent could reasonably confuse with it.

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 mention of the obvious alternative events_snapshot. The phrase 'recent ... with optional filters' only implies usage rather than directing it.

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

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

Adds real context beyond the annotations: credentials come only from the server environment (no per-call auth params), and a host-side timeout may leave the guest command still running — a genuine hazard the annotations don't express. The destructiveHint is not explained in terms of what arbitrary PowerShell could do, which is the remaining 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?

Four tight sentences, front-loaded with the mechanism, then auth, then return values, then the timeout caveat. The return-value sentence is partly redundant with the output schema but is short enough not to 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?

Output schema covers returns and annotations cover the safety profile, so the description is close to sufficient. It still leaves undocumented parameters and no explanation of the destructive flag's practical implications for a tool that executes arbitrary code.

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 description never mentions vm_name or command — no naming convention for the VM, no shell/quoting syntax, no size limits on the command string. With two opaque parameters, the description should compensate and does not.

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: run PowerShell inside a guest VM via PowerShell Direct. That clearly separates it from the console_type_text/serial_send siblings, though it never names those alternatives 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 use this versus guest_read_file, guest_write_file, guest_processes, or the console keystroke tools. An agent has to infer that this is the generic arbitrary-command escape hatch.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds real behavioral context beyond them: a 200-result cap and the ALLOW_GUEST/credential requirement. It does not mention ordering or truncation behavior, but the annotations plus output schema cover most of the safety profile.

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

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

Two short sentences with zero waste; the core action and limit are front-loaded, followed by the access requirement.

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 an output schema and read-only annotations available, the description supplies the important prerequisites, result cap, and filtering behavior. The only meaningful omission is the meaning of the required vm_name parameter.

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 explains that name_contains acts as an optional substring filter, which is more than the schema's bare title, but vm_name is never described despite being required, leaving a key 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?

States a specific verb and resource ('List ... guest processes') plus scope details (up to 200, optional name filter) that distinguish it from guest_services. An agent can tell what it 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?

Names the prerequisite gate ('Requires ALLOW_GUEST and guest credentials') and describes the optional filtering condition. It does not point to alternatives or say when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low. The description still adds substantive behavior: output is base64 with a SHA-256 digest, plus hard size ceilings (64 KiB default, 8 MiB maximum) and a context-budget warning that no annotation conveys.

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

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

Three sentences, front-loaded with what the tool does and the output format, followed by limits and then the large-file caveat. No filler or restatement of the 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?

An output schema exists, so return structure needn't be spelled out, and the size/encoding behavior is covered. The remaining gap is parameter-level clarity for vm_name and the named max_bytes parameter, minor for a 3-parameter tool.

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

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

Schema description coverage is 0%, so the description carries the burden. It partially compensates by specifying that guest_path must be absolute and by documenting the byte limits that map to max_bytes (default 64 KiB, max 8 MiB), but it never names max_bytes or explains vm_name, leaving the mapping implicit.

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 an absolute guest file path) and the return encoding (base64 plus SHA-256), which an agent can immediately distinguish from guest_write_file. It does not explicitly name or exclude any sibling, which keeps it from 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?

It gives one real usage rule — for large files, use bounded chunks rather than inflating model context — which is genuinely actionable. But 'the lab APIs' is vague; the concrete siblings lab_stage/lab_collect are never named, so the agent must guess which route to take.

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 read-only/idempotent/non-destructive profile, and the description adds real behavioral context beyond them: a hard 200-item cap and the fact that stopped services are excluded unless overridden. It does not address ordering or what happens when more than 200 services match.

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

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

A single sentence with the verb, resource, cap, and default behavior front-loaded. Nothing is redundant or padded.

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?

An output schema exists, so return shape needn't be explained, and the description covers the two behaviorally significant parameters and the result cap. The omission of vm_name is the main remaining gap for a small three-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the name filter and the include_stopped default, but the required vm_name parameter is never mentioned, leaving one of three parameters undocumented in both places.

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 ... guest services") plus key scope details: a 200-item cap and name-based filtering. It does not name any sibling (e.g. guest_processes, guest_status) to differentiate itself, 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?

There is no explicit when-to-use guidance or routing to alternatives such as guest_processes or guest_status, which an agent could easily confuse with this tool. Usage is only implied by the resource name and the filtering/default behavior described.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context by stating the data is read through PowerShell Direct, implying guest integration requirements, though it does not spell out those prerequisites or authentication needs.

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

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

A single front-loaded sentence that lists the returned data without filler or redundancy. Every clause contributes to identifying the tool's scope.

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?

An output schema exists, so return values need not be explained in the description. The description covers what is read and the transport mechanism; the remaining gaps are PowerShell Direct preconditions and vm_name semantics.

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 should compensate for the undocumented vm_name parameter, but it never mentions the parameter, its expected format, or how to identify the VM. The parameter name is fairly self-explanatory, preventing a score of 1.

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

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

The description uses a specific verb ('Read') and enumerates the exact guest data returned: OS, boot time, memory, system-drive free space, and kernel debug settings. It also distinguishes itself from host-oriented siblings by specifying 'guest' and 'through PowerShell Direct'.

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 this is the tool for guest-level OS/status inspection, but it does not explicitly state when to use it instead of hyperv_host_status or guest_processes/guest_services/guest_events. No prerequisites or exclusions 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 already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety bar is lower. The description adds real value beyond that by disclosing the double-confirmation safeguard (overwrite + confirm_path) needed to clobber existing files, though it says nothing about permissions or error 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?

Two sentences, zero filler, with the core action front-loaded and the safety constraint second. Every clause carries information the agent needs.

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, non-idempotent write tool with six parameters at 0% schema coverage, the safety guard is covered and an output schema exists to handle returns. The unaddressed create_parent flag and the lack of any note on failure modes keep it only adequate.

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 clarifies guest_path, overwrite, and the overwrite/confirm_path coupling well. However, it is silent on create_parent, vm_name, and content_base64, leaving a meaningful gap for a 6-parameter tool.

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 ('Write base64 content to an absolute guest path') and includes the content encoding, so an agent immediately knows what it does. It is implicitly the write counterpart of guest_read_file, though it never names the sibling.

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

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

It gives a concrete conditional: existing files require overwrite=true plus confirm_path equal to guest_path, which tells the agent when a naive call will fail and how to proceed. It stops short of naming alternatives or stating when not to use the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the scope note that health covers both the host and its services; it says nothing about whether this targets the local host or a configured remote, or about latency/retry 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?

A single short sentence with the action front-loaded and no filler. Every word earns its place.

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

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

An output schema exists, so return values need no explanation, and the empty input schema plus annotations mean safety and inputs are covered. What is missing is a hint about which host is probed when multiple hosts or labs are in play, which matters in this sibling set.

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

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

The tool takes zero parameters, so there are no parameter semantics for the description to explain; baseline 4 applies. Nothing in the description misleads about inputs.

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

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

The description states a specific verb ("Read") and a specific resource ("Hyper-V host and service health"), which is enough to separate it from VM-level siblings like vm_get or checkpoint_list. It stops short of naming the adjacent diagnostic siblings (lab_diagnostics, lab_verify) it might be confused with.

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 statement of when to reach for this tool versus alternatives such as lab_diagnostics or lab_verify, and no prerequisites or exclusions are given. The agent must infer the invocation context entirely 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?

The description adds real context beyond the annotations: it names the evidence root as the write destination, flags the kernel dump as opt-in, and rules out starting a new test. But the annotations declare destructiveHint=true and idempotentHint=false, and the description never explains what may be overwritten or whether repeated collects on the same run_id clobber prior evidence — a notable omission 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?

Two tightly packed sentences with the action and destination front-loaded and the two key constraints (opt-in dump, no test started) following. Nothing is redundant or padded.

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?

An output schema exists, so return values need not be described, and the destination and opt-in behavior are covered. But for a destructive, non-idempotent mutation with four wholly undocumented parameters, the description leaves too much unsaid about the required identifiers and the overwrite semantics of the evidence root.

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, yet it only touches include_kernel_dump indirectly via 'a kernel dump is opt-in'. The three required parameters (vm_name, package_id, run_id) receive no explanation of meaning, format, or where the package_id/run_id values originate.

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

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

The description uses a specific verb ('Collect') on a specific set of resources (logs, events, diagnostics, dumps) and names the destination (HYPERV_MCP_EVIDENCE_ROOT). The clause 'no new test is started' implicitly distinguishes it from lab_verify/lab_stage, though it stops short of naming those siblings.

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

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

The scope note 'a new run's logs' plus 'no new test is started' tells the agent the precondition (a run must already exist), and 'kernel dump is opt-in' clarifies the option. However, there is no explicit guidance on when to choose this over lab_diagnostics or lab_verify, so the agent must infer the boundary from sibling names alone.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive operation, so the safety profile is fully covered. The description adds useful scope about which configuration areas are inspected, but it does not disclose anything further about return format, required guest state, or availability constraints; with annotations carrying the safety burden, a 3 is appropriate.

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?

A single tightly written sentence with zero filler. The resource scope is front-loaded and every listed domain earns its place.

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

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

With an output schema present, the description need not explain return values, and the annotations fully cover the safety profile. The one-parameter schema is trivial. The remaining gap is the absence of selection guidance against sibling diagnostic tools, which is minor for such a straightforward 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?

There is only one parameter, vm_name, and schema description coverage is 0%. The parameter name is self-explanatory, but the description does not mention it or clarify whether it refers to a running VM, a guest identifier, or a host-side object. Baseline 3 for a single obvious parameter.

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

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

The description uses a specific read verb and enumerates the exact configuration domains covered: boot, Secure Boot, VBS/HVCI, test-signing, debugger, disk, and crash-dump. This makes the purpose distinct from general runtime-status siblings like guest_status, though it does not explicitly name the sibling tools it differs from.

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 no explicit guidance on when to use this tool versus alternatives such as lab_verify, guest_status, or debug_guest_prepare. The scope implies diagnostic inspection, but the agent must infer selection conditions from the field list alone.

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-idempotent; the description adds genuinely new behavioral context beyond them — that the tool never executes a payload and that a confirmation gate (confirm_vm) is mandatory. It stops short of saying what existing state gets overwritten in C:\DriverLab or whether re-running is safe.

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

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

Three short, front-loaded sentences with no filler; the scope of the action comes first and the safety constraint ('Never executes a payload') immediately after. Could be marginally tighter by folding the confirm_vm requirement into the same sentence.

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?

Output schema exists, so return values need no explanation, but as a destructive, non-idempotent mutation tool with two undocumented parameters, the description should say more about side effects on existing C:\DriverLab contents and about the confirm_vm contract. 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% for both parameters, so the description must compensate. It only flags that confirm_vm is required; it never explains the expected value/format of confirm_vm (e.g., a confirmation token or a match to vm_name) or what vm_name identifies, so the semantics remain unclear.

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 verbs plus resource: installs/verifies fixed lab tools in a named directory and creates package/run/evidence subdirectories. It is distinguishable from lab_diagnostics, lab_stage and lab_verify by describing a concrete setup/verification action, though it never explicitly names those siblings as alternatives.

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?

Implied as a setup/precondition step via 'Install or verify' and the 'Requires confirm_vm' prerequisite, but there is no explicit when-to-use versus lab_stage/lab_verify/lab_collect, and no when-not-to-use guidance.

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

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

Annotations flag this as non-idempotent and destructive, so the safety burden is partly covered; the description still adds real value by disclosing hash verification, chunked transfer for large files, and that staged content is never executed. It omits what happens to a pre-existing package with the same package_id and whether failures are partially applied.

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

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

Two short sentences, front-loaded with the action and scope, and every clause (hash-verified, chunked, never executes) carries information an agent cannot get from 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?

An output schema exists, so return values need not be explained, and the destructive/non-idempotent profile is in annotations. However, for a 3-parameter mutation tool with zero schema coverage, the missing package_id semantics and overwrite behavior leave meaningful 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. It only clarifies that source_directory must be a subdirectory of HYPERV_MCP_LAB_ROOT; vm_name and especially package_id (optional, default null) are given no meaning, format, or reuse semantics.

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

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

States a specific verb (stage) and resource (a hash-verified package) plus the source constraint (subdirectory of HYPERV_MCP_LAB_ROOT). It does not name or contrast with siblings such as guest_write_file, lab_init, or lab_verify, so an agent must infer the boundary itself.

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?

Implied usage is staging content prior to running it, reinforced by 'never executes staged content' and the note about chunked large files. There is no explicit when-to-use/when-not guidance or named alternative (e.g., directly writing files with guest_write_file).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds one genuinely non-obvious trait — verification happens in the guest without executing the package — but is silent on what happens on hash mismatch, whether all file mismatches are reported, or any cost/latency of scanning package contents.

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?

A single tight sentence with the distinguishing constraint ('without executing') placed at the end where it lands as the key differentiator. No filler or redundant restatement of the 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?

Output schema and annotations cover return shape and safety profile, so the main remaining gaps are the undocumented parameters and the absence of failure/mismatch semantics or relationship to the lab_init/lab_stage/lab_collect pipeline. Adequate but noticeably thin for a three-required-parameter verification tool.

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

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

Schema description coverage is 0%, so the description must carry the burden and it does not: vm_name is never mentioned beyond the vague 'in the guest', and no format expectations (hex digest casing/length, package_id shape, whether the hash covers the whole manifest) are given for any of the three required parameters.

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

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

States a specific verb ('re-verify') and concrete resources (package files and the manifest SHA-256) scoped to the guest. It is distinguishable from mutation siblings like lab_stage or lab_collect, though it never names those siblings to make the contrast explicit.

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 phrase 'without executing the package' implies the verification-only use case, but the description never states when to pick this over lab_diagnostics, lab_stage, or lab_collect, nor what precondition ('re-'verify implies a prior stage) must hold.

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, so the description's value is the extra preconditions it supplies: VM power state and the ALLOW_MEDIA capability requirement. The confirm_vm==vm_name guardrail is a genuine safety disclosure not present in the schema. It doesn't say what happens on a mismatched confirm_vm or an empty drive.

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 compact sentences with the action first and constraints second — no filler. Slightly compressed phrasing ("confirm_vm equal to vm_name") reads awkwardly but costs no clarity.

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?

An output schema exists, so return values need not be described, and annotations cover the destructive/idempotency profile. For a mutating tool with 4 parameters the description is nearly sufficient, missing only the controller-location addressing semantics.

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 explains confirm_vm's required value (must equal vm_name) and vm_name is self-evident, but controller_location is required yet never explained, and controller_number's default/role is unaddressed — a real gap for targeting the right drive slot.

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 ("Eject an existing VM DVD drive") plus a hard precondition (VM must be Off), which distinguishes it from media_mount/media_list by implication. It never names the sibling it pairs with, so differentiation is inferential rather than explicit.

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 when-to-use context: the VM must be Off, ALLOW_MEDIA must be granted, and confirm_vm must match vm_name. It stops short of naming media_mount as the inverse operation or stating what to do if the drive is already empty.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds useful field-level context about what is inspected (ISO paths, controller location, power state), but does not mention per-VM scoping or any behavioral constraints beyond that.

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?

A single front-loaded sentence with no wasted words. It efficiently enumerates the relevant media attributes an agent would want from a list operation.

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

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

The tool is simple and has both annotations and an output schema, so the description need not explain return structure. However, it omits parameter semantics and does not clarify how this differs from media_mount/media_eject, leaving some gaps for correct tool selection.

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?

There is one required parameter, vm_name, and schema description coverage is 0%. The description does not explain what vm_name refers to, its expected format, or whether it is a name or identifier, so it fails to compensate for the missing schema documentation.

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

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

The description uses a specific verb ("List") and a well-defined resource set (VM DVD drives, mounted ISO paths, controller locations, generation, power state). It is clearly a read/inspection operation, though it does not explicitly distinguish itself from siblings like media_mount or media_eject.

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 read-only listing verb, but there is no explicit guidance on when to use this versus media_mount, media_eject, or vm_get. No prerequisites or exclusions are stated.

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

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

Annotations already flag destructiveHint=true and non-idempotent, and the description adds real context beyond them: the safety gate ALLOW_MEDIA, the confirm_vm echo requirement, and the explicit no-auto-stop behavior. It stops short of saying what happens to an already-mounted ISO (the likely source of the destructive hint) or what occurs on failure.

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

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

Three short sentences, front-loaded with the action and the hard precondition, followed by the effect and the auth gates. No filler and nothing buried.

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?

An output schema exists, so return values need no explanation, and the description covers the critical safety gates. But for a 6-parameter mutation tool with 0% schema coverage, the unexplained controller_number/controller_location pair and the silence on overwriting existing mounted media leave meaningful 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 all param meaning, and it only clarifies confirm_vm (must equal vm_name) and boot_first (first boot device). vm_name, iso_path, and especially controller_number vs controller_location remain undocumented in both schema and description.

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 (mount a host ISO into a VM DVD drive) plus the required pre-state (VM must be Off) and the optional boot_first effect. That is enough to distinguish it from media_list and media_eject 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?

Explicitly states when the tool is valid (VM Off) and an important boundary: it never stops the VM automatically, so the caller must power it off first via vm_power. It does not name media_eject or media_list as the counterpart/alternative for changing or removing media, so routing is clear but not fully 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 already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered; the description adds genuinely new context the annotations cannot carry — the environment-variable prerequisite, the mandatory confirm_vm string, and the side effect of appending to a local log file. The word "dedicated" hints at exclusive pipe ownership, which is the likely reason for the destructive hint, though it could state outright that an existing reader will be displaced and that no port or guest configuration is performed as a remedy.

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 dense sentences with zero filler, ordered so the action and its side effect come first and the prerequisites/exclusions come second. Every clause (ALLOW_DEBUGGER, confirm_vm, log append, no port/guest config) carries distinct information.

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

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

An output schema exists, so return values need no explanation, and the description covers the action, the side effect, the auth gate, and scope limits for a 4-required-param tool. The remaining shortfall is operational: it omits the teardown path (serial_disconnect) and the consequences of a failed attach, which matter for a tool flagged destructive.

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% (bare titles only), so the description must compensate and only partly does: it maps vm_name to "Running VM", log_path to the ".log file", and calls out confirm_vm as a requirement. It leaves genuine ambiguity — if the pipe is fixed at COM1, what value does the required pipe_name accept, and what must confirm_vm contain (presumably the vm_name echoed back)? Those two required params remain unexplained anywhere.

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: attach a dedicated reader to the existing COM1 named pipe of a Running VM and append output to a local .log file. This is far more concrete than the sibling names serial_read/serial_status imply, though it never explicitly says how it differs from serial_read or debug_serial_prepare, leaving that inference to the agent.

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 front-loads a real gate ("Requires ALLOW_DEBUGGER and confirm_vm") and a scope exclusion ("does not configure the port or guest"), which tells the agent when this tool is applicable. However, it never names the obvious alternatives or counterpart — serial_disconnect to tear the reader down, or serial_read/serial_status if a full log capture is not needed — so the when-to-use-vs-alternatives guidance is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful detail beyond that: it clarifies exactly what is torn down (the server-side reader and pipe handle) and what is deliberately preserved (the VM COM port). It stops short of describing error cases or the return payload.

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 sentence, front-loaded with the action and resource, with the non-obvious constraint ('without changing the VM COM port') placed immediately after. No wasted words.

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?

An output schema exists and annotations already flag destructiveness, so the description need not explain returns or safety. However, for a destructive mutation with a wholly undocumented required parameter, it omits preconditions (e.g. what happens if no reader is attached) and the VM scoping of the operation.

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 single parameter (vm_name) is undocumented in structured data and must be compensated for in the description. The description never mentions vm_name or whether the disconnect is scoped per-VM, leaving the only parameter entirely uninterpreted.

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

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

Names a specific verb+resource pair ('Detach ... serial reader and close its pipe handle') and implicitly contrasts with serial_connect. It doesn't explicitly name sibling tools like serial_status/serial_read, so differentiation is inferred rather than stated.

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 name and the 'detach' verb, and the 'without changing the VM COM port' clause hints at the boundary of the operation. There is no explicit guidance on preconditions (must a reader be connected first?) or failure behavior, and no alternatives are named.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds meaningful context beyond them: a required capability flag and the fact that only the retained buffer tail is returned (implying older output is lost). It stops short of describing truncation/rotation behavior explicitly.

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 sentences, no filler, with the purpose stated first and the gating condition immediately after. Every clause carries information.

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

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

Has an output schema so return values needn't be explained, and the prerequisite is stated. But with 0% schema coverage on two parameters and no routing to sibling tools, an agent still has gaps before calling it confidently.

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 the description never explains vm_name or tail_chars. The word "tail" hints at the truncation parameter's meaning, but its default of 32768 and the format/identity expectations for vm_name are left entirely to the schema's 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?

Specific verb+resource: "Read the retained tail of an attached serial console." Scope (retained tail) is precise, so it's distinguishable from console_* siblings, though it doesn't explicitly contrast with serial_status or debug_serial_status.

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 one real precondition ("Requires ALLOW_DEBUGGER"), which is useful gating, but never says when to choose this over serial_status, debug_serial_status, or serial_connect, nor what happens without the flag.

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 non-read-only, non-idempotent and destructive, and the description adds genuine context by disclosing that CRLF is appended by default (explaining the append_newline default). However, it says nothing about the destructive implications of sending arbitrary text to a console (e.g. interrupting a bootloader or feeding input to a live shell), which is exactly what the destructiveHint warrants explaining.

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 with zero filler; the format and default behavior are stated up front. It is efficient, though brevity here edges toward under-specification for a destructive write 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?

An output schema exists, so return values need not be described. But for a destructive, non-idempotent three-parameter mutation with 0% schema coverage, the description omits prerequisites (connection state), the meaning of vm_name, and any warning about the effect of injecting text into a live console.

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 clarifies 'text' as UTF-8 and confirms the append_newline default of CRLF, but 'vm_name' is never explained — notably whether the VM must already have an attached serial connection.

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 (write), the payload format (UTF-8 text) and the exact target (attached COM1 serial console), which is enough to separate it from serial_read and serial_connect. It does not explicitly distinguish itself from console_type_text, which writes text via the VM keyboard, so sibling differentiation is only partial.

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/when-not guidance: nothing says a connection must first be established (serial_connect exists as a sibling) or when to prefer this over console_type_text. The only implied usage comes from the phrase 'attached COM1 serial console', which an agent must infer.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds a useful piece of substance beyond that — it discloses that the result includes whether a serial-console reader is attached — but says nothing about failure modes (e.g., VM not running, COM1 absent) or cost.

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?

A single tight, front-loaded sentence with no filler or redundancy. It is perhaps too short given the unresolved target ambiguity, but there is not a wasted word.

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?

An output schema exists so return values need not be explained, and annotations carry the safety profile, which lowers the burden. However, the meaning of the required vm_name argument and the state in which the call is valid are left unaddressed, leaving a real gap for a one-parameter tool with zero schema coverage.

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 the single parameter vm_name is never mentioned in the description; 'this server' actively conflicts with a VM-scoped parameter, so an agent cannot tell from the description whether vm_name is a VM identifier or a host. This is precisely the case where the description needed to compensate and did not.

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

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

The description names a specific verb and resource ('Read COM1 configuration' plus attached serial-console reader status), which clearly separates it from the mutating siblings serial_connect/serial_send/serial_disconnect. The only weakness is that it says 'this server' without tying the operation to the vm_name parameter, leaving the target slightly ambiguous.

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 statement of when to use this versus serial_connect, debug_serial_status, or console_info, all of which are plausible alternatives in the sibling list. An agent must infer that this is a pre-flight check before connecting, and nothing excludes misuse.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is fully covered externally. The description adds the useful scope note that it aggregates several facets including checkpoint count, but says nothing about cost, latency, or what happens when the VM is off/missing.

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 sentence, front-loaded with the verb and resource, listing only the facets that matter. No filler or redundant 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. For a one-parameter read tool the description is close to sufficient; only the vm_name format is left 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% and the single required parameter vm_name is undocumented in both schema and description. The description does not say whether a name, ID, or fully-qualified path is expected, leaving an inference the agent must make.

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

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

States a specific verb (get) and resource (VM) and enumerates the facets inspected: state, devices, memory, network, checkpoint count. That clearly separates it from vm_list (enumeration) and the checkpoint_*/guest_* families, though no sibling is named 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?

Usage is only implied: this is the per-VM inspection call, taking a single vm_name. There is no explicit statement of when to prefer it over vm_list, vm_wait, or the guest_* tools, and no preconditions (VM must exist, host reachable) are mentioned.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, so the safety profile is clear. The description adds one useful behavioral detail, that results are scoped by an "optional allowlist," but it does not explain what that allowlist is or how visibility is determined beyond that.

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

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

The description is a single short sentence with no wasted words, and the core purpose is front-loaded. Its brevity does not create structural issues for such a simple no-argument 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 parameters, full annotation coverage, and an output schema, the description only needs to identify the listing operation and scope. It does that adequately, though the undefined "optional allowlist" leaves a small ambiguity about what determines visibility.

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?

There are zero parameters, so parameter semantics are not a burden on the description. The mention of an "optional allowlist" is not a schema parameter and is slightly ambiguous, but it does not affect invocation correctness.

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 VMs." It also adds scope with "visible through the optional allowlist," but it does not explicitly distinguish this from siblings such as vm_get or vm_wait.

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 no explicit guidance on when to use this tool versus alternatives like vm_get for details or vm_wait for state changes. The listing purpose is implied, but there is no 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 destructiveHint=true and readOnlyHint=false; the description goes beyond them by distinguishing graceful shutdown from forced turn_off/reset and by disclosing the confirm_vm guard and the ALLOW_POWER/allowlist gating. It does not say what unsaved state is lost on turn_off/reset or whether pause requires a running VM, which is the remaining gap for a destructive mutation 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?

Two sentences, no filler, and the destructive-action guard plus auth requirement are front-loaded right after the action list where an agent will see them before calling. Every clause carries information the schema does not.

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?

An output schema exists, so return values need no explanation, and the description covers the risky path (forced power-off/reset) and auth gating. It stops short of stating per-action preconditions or whether the operation blocks until the VM settles, which matters for a multi-action power tool with an associated vm_wait sibling.

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

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

Schema description coverage is 0%, so the description must carry the parameter load, and it does explain the non-obvious one: confirm_vm must equal vm_name and is required for turn_off/reset. It also implicitly mirrors the action enum. vm_name's expected format (name vs. ID) is never clarified, which is the only real omission.

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

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

The description opens with a full enumeration of the concrete state operations (start, graceful shutdown, save, pause, resume, forced power-off, reset) applied to a named resource, so the verb+resource pairing is unambiguous. It is clearly distinguishable from siblings like vm_list, vm_get, or vm_wait, which read state rather than mutate it.

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 names the preconditions required to call it (ALLOW_POWER permission plus allowlist membership) and the special guard for turn_off/reset, which is real routing guidance. There is no explicit statement of when to prefer this over siblings or which action to choose for a given VM state, so it stops short of fully prescriptive usage.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuine context on top: timeout behavior returns matched=false rather than raising, and the tool is guaranteed not to mutate power state. It does not say whether it blocks for the full timeout or what happens on an invalid VM name, but the key behavioral traits are disclosed.

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 tight sentences with zero filler, and the core action is front-loaded before the timeout and no-mutation guarantees.

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?

An output schema exists, so return-value explanation is not owed, and the safety profile is covered by annotations. The real gap is the complete absence of parameter guidance at 0% schema coverage, which for a polling tool with interval and timeout knobs leaves the agent guessing about cost and behavior.

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 mostly does not. 'states' is only indirectly explained as target states, while 'timeout_seconds' and 'poll_interval_ms' (including their defaults of 60 and 500) are never discussed in terms of tradeoffs or units.

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: poll a named VM until it reaches one of the requested states. The closing clause 'never changes power state' distinguishes it from vm_power, and 'reaches one of the requested states' distinguishes it from a one-shot vm_get, so an agent can route correctly without opening schemas.

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

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

The waiting semantics are clear, but the description never names an alternative or states when not to use it. The 'never changes power state' clause implicitly points at vm_power for state changes, but this is inference rather than explicit guidance about when to wait versus poll manually.

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