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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real interpretive value beyond that: how domains are labeled, why several live paths on one appliance count as ONE domain, and what summary.out_of_band_live=false implies. It doesn't cover auth or rate limits, so not a 5.

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

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

Front-loads the core answer ('Which INDEPENDENT recovery paths are live') before elaborating. The domain and out_of_band_live sentences each carry weight, though the backtick-heavy, densely packed style is slightly harder to scan than necessary.

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

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

For a read-only analysis tool with no output schema, the description conveys what the result means (domain-labeled live paths, the out_of_band_live signal). It is complete enough to interpret the call, missing only explicit return-shape detail.

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

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

Only one parameter (profile) and schema description coverage is 100%, so the schema already fully documents it. The description adds nothing about the profile parameter, which is acceptable given the schema does the heavy lifting — baseline 3.

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 (which live recovery paths exist for a device) and frames it as 'the lockout view'. The failure-domain framing clearly differentiates it from sibling reachability checks like ssh_reachable or healthcheck, which report a single path rather than an independence rollup.

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 'lockout view' phrasing implies the context (assessing whether a hung box can still be recovered remotely), but no sibling is named and there is no explicit when-to-use vs when-to-use-alternative guidance. Usage is implied rather than stated.

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

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

Beyond the destructive/non-idempotent annotations, it discloses the approval gate, typed same-path denials, the KVM_PILOT_MCP_ALLOW_CONSENT_OFF operator gate, and — critically — that consent_off=true is a surveillance escalation. That is exactly the kind of consequence an agent cannot infer from annotations.

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

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

Front-loaded with purpose and mutation class, then structured per feature. Dense but nearly every clause carries signal; the '#234' tracker reference is the only marginal detail.

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 mutation with no output schema, the description covers what is changed, the approval requirements, and the consent_off escalation. Return-value detail is absent but not strictly required given the schema and annotations already cover safety.

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

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

Schema description coverage is 100%, so feature, consent_off, profile, and confirm are already documented in the schema. The description reinforces feature/consent_off meaning but mostly restates the schema (including the not_confirmed outcome and the operator gate), so baseline 3 applies.

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

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

States a specific verb (enable) and resource (Intel AMT redirection listener over WS-Man) and scopes it (Intel AMT/vPro only). No sibling in the list overlaps, and the CONFIG MUTATION label immediately frames the operation class.

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

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

Explains what each feature value selects and the gating conditions (config effect gate, per-invocation approval), giving clear context for when the call applies. It does not name a when-not or an alternative tool, but none exists among the siblings, so the gap is minor.

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, but the description adds rich context beyond them: ~60s loss of all KVM control, that target power is untouched, gating by the appliance effect gate plus per-invocation approval, typed same-path denials (#234), and the absence of out-of-band power (brick risk). This is exactly the behavioral detail an agent needs before a destructive act.

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

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

Front-loaded with the action, scope, and the DESTRUCTIVE warning in the first line, then supporting detail about the recovery scenario. Each sentence carries distinct information with no filler.

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

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

For a destructive two-parameter tool with full schema coverage and no output schema, the description covers the failure scenario, recovery rationale, downtime, gating, denial behavior, and brick risk. Nothing needed to invoke it safely is missing.

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

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

Schema description coverage is 100%, so both the confirm and profile parameters are fully documented in the schema, making 3 the baseline. The description's approval-gating context is tangentially relevant but adds no syntax or value semantics for the parameters themselves.

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 (Reboot) and resource (the KVM APPLIANCE), and explicitly disambiguates from the target with '(not the target)' and 'the target's power is untouched.' That contrast distinguishes it from sibling verbs like power, which act on the target.

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

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

Gives an explicit triggering condition ('to clear a wedged encoder', 'recovers the RV1126 encoder wedge — the only fix') and an explicit exclusion ('never in an automated loop', 'use this deliberately'). It states both when and when-not, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds important behavioral context beyond that: it operates over the appliance_ssh channel, not the managed host, reports specific OS-level diagnostics, and warns that idle load appears high due to driver-parked D-state threads.

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 definition is front-loaded with the target and purpose, then adds the metric details and the critical interpretation caveat. Every sentence adds distinct value, and the NOTE cleanly separates the health-signal warning.

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 a simple read-only diagnostic tool with annotations covering safety and no output schema, the description supplies the missing return-value context and interpretation warning. It is complete enough for an agent to call it correctly without additional inference.

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

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

Schema description coverage is 100% for the single optional profile parameter, and the schema already explains the profile/config selection. The description adds no parameter-specific semantics, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: read-only diagnostics from the KVM appliance's own OS over SSH. It explicitly contrasts this with the managed target and names the specific metrics returned (1-minute load and RV1126 video-pipeline D-state threads), so an agent can distinguish it from siblings like healthcheck and ssh_reachable.

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

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

It gives explicit routing guidance: target the appliance itself, not the managed target, and use the healthcheck encoder-wedge finding for the real health tell because load is not a reliable health signal. This names an alternative and the condition that selects it.

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

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

Annotations already establish readOnlyHint/idempotent/non-destructive, and the description adds real substance beyond them: it enumerates the returned fields, notes that 'mode' may be null when the BMC does not expose it, and that 'allowable' is BMC-advertised. Only the exact return shape/pagination is left unstated, which is minor here.

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

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

The core purpose and read-only nature are front-loaded in the first clause, followed by a compact enumeration of the returned fields and one forward-looking rationale. No sentence is filler.

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

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

There is no output schema, so the description correctly carries the burden of describing return values (enabled, target, mode, allowable) with enough nuance (null mode, advertised allowable) for correct use. Combined with annotations covering safety, nothing essential is missing.

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

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

Schema description coverage is 100% and the single 'profile' parameter is fully documented in the schema, so the description adds nothing about it. Per the high-coverage baseline, a 3 is appropriate for a one-parameter tool that needs no further elucidation.

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 ('Show the host's current boot override') and names the underlying Redfish property (BootSourceOverride), pinning the concept precisely. It contrasts implicitly with the sibling set_boot_device as the read-side counterpart, so an agent can tell the two apart immediately.

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

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

Gives a concrete use context: an actuator should consult this before calling set_boot_device to learn which target values the box accepts. That is a clear when-to-use signal, though it does not state explicit exclusions or other 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?

Goes well beyond the annotations: discloses that the live cursor visibly moves for ~10-30s, that it is gated by KVM_PILOT_MCP_ALLOW_HID with one approval covering the run, that results are stored per (host, capture resolution), and that a resolution change makes the calibration stale and it is never applied. This is exactly the extra behavioral context annotations cannot carry.

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

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

Front-loaded with the purpose, then gating, then preconditions, then persistence semantics — a sensible ordering. It is dense with parentheticals and an issue reference (#128) that costs a little space, but nearly every sentence carries decision-relevant 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?

With no output schema, the description still covers what an agent needs: preconditions, duration, approval/gating, side effects on the live cursor, and post-run state. The one failure mode it mentions (outcome=not_confirmed) is handled in the schema description, so nothing material is missing.

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

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

Schema coverage is 100%, so `confirm`, `profile`, and `tolerance` are already fully documented in the schema. The description only indirectly touches parameters ('stored per (host, capture resolution)') without adding syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Measure and store this host's mouse commanded→observed correction') with the effect spelled out (fixes 'clicks where the button should be and misses'). It is clearly distinguishable from the sibling `mouse` tool, which the description explicitly says consumes this calibration afterwards.

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

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

Gives explicit preconditions (live video signal, static screen, visible cursor), scope boundaries ('pointer moves only — no clicks, no keystrokes'), the approval model, and the relationship to the `mouse` tool. An agent can decide when to call this versus `mouse` or `type_text` without inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by stating it is 'structural — makes no network call and runs no preflight' and that output is returned in capability-enum declaration order for stability. That is genuine behavioral context not present in the annotations, though it doesn't cover latency or any failure modes.

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

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

The key statement is front-loaded in the first sentence and the rest is dense, differentiated content rather than filler. It is somewhat long with several parenthetical asides ('a Redfish BMC has no video; a PiKVM has no BootProgress'), which slightly taxes scanning, but every clause carries useful routing 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?

With no output schema, the description carries the return-value burden and does reasonably well: it explains the output is a capability list in enum declaration order and hints at items like video scope and live evidence. It stops short of describing the full returned structure or what a caller does with the result, so it is strong but not exhaustive for a no-output-schema tool.

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

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

Schema description coverage is 100% and the single `profile` parameter is fully documented in the schema, so the baseline of 3 applies. The description never mentions `profile` and instead discusses `video_scope`/`live_evidence`, which are not input parameters, so it adds no parameter-level meaning beyond the schema.

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

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

States a specific verb and resource ('List the capabilities the target's driver supports') and immediately scopes it as read-only and offline. It goes further than the sibling `info` by clarifying this is about *which interfaces a device can serve*, and differentiates concrete cases (Redfish BMC has no video; PiKVM has no BootProgress), so an agent can pick it apart from `info`, `healthcheck` and `support_matrix` without opening schemas.

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

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

Gives explicit usage context — 'so you can pick the right interface up front' — and names the alternatives with the conditions that select them: `support_matrix` for per-combo evidence, `healthcheck` for this exact device+firmware. It also draws a sharp boundary ('structural support is not live verification'), which is exactly the when-not-to-use guidance an agent needs.

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

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

With annotations already covering the safety profile, the description still adds substantial context: it discloses that cheap gates resolve with no credentials at all, that server vision is used only when configured, and that a caller-side fallback returns [json_text, Image]. This is exactly the auth/behavior/return-shape information the annotations do not carry.

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

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

Purpose is front-loaded, followed by mechanism and then return shapes in a bulleted structure. It is dense but every block earns its place given the dual-mode behavior; only minor tightening is possible.

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

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

For a two-optional-param tool with no output schema and an unusual dual-mode contract, the description does the needed work by spelling out both return shapes and the pending caller-side responsibility. It is nearly complete, missing only when-to-use guidance.

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

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

Schema description coverage is 100%, so the schema already documents both 'hint' and 'profile' fully. The description adds no parameter-level meaning beyond the schema (it references system_prompt/phases in the return payload, not the inputs), so the baseline 3 applies.

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

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

States a specific verb (Classify) and resource (the current screen's boot/run phase), and even parenthesizes scope with '(read-only)'. No sibling tool (power_state, snapshot, logs, etc.) overlaps this screen-classification role, so an agent can route to it unambiguously.

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

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

The description explains the internal mechanism and return shapes but never states when to reach for this tool over alternatives or what conditions trigger it. There is no 'use this when...' clause and no exclusion criteria; usage is only weakly 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 non-idempotent, but the description adds substantial value beyond them: the power_soft classification, the specific env gate required, the fact that the chord is unverifiable on a hung host, and that the typed act outcome should be confirmed with wait_for_state or snapshot.

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

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

Front-loaded with the action and its destructive nature, then layered with the gate requirement and alternative. Each sentence carries information, though the backticked formatting and gate discussion make it slightly denser than strictly necessary.

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

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

No output schema exists, and the description compensates by stating that the tool returns the typed act outcome and by naming the confirmation tools (wait_for_state, snapshot). For a single-action destructive tool, an agent has everything needed to call it correctly and verify the result.

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

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

Schema description coverage is 100% and both parameters (confirm, profile) are already fully documented in the schema, including the elicitation semantics and the not_confirmed denial outcome. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb+resource: sending the Ctrl+Alt+Del chord to the managed host over HID, and immediately classifies it as a destructive reboot. It distinguishes itself from siblings by naming power(action='reset') as the preferred alternative when out-of-band power exists.

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

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

Explicit when-to-use and when-not-to-use guidance: prefer power(action='reset') when the device has out-of-band power because that path is verifiable while this chord is not, since a hung host silently ignores it. It also states the required gate (KVM_PILOT_MCP_ALLOW_POWER) instead of the weaker HID gate.

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

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

Annotations already declare readOnlyHint, openWorldHint=false, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the doctrine is bundled/offline, explains the re-anchoring purpose, and distinguishes listing from full-text retrieval.

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 purpose and invocation rules are front-loaded and easy to scan. The rationale about compacted skill files is helpful but slightly verbose for a one-parameter read-only 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?

For a simple read-only lookup tool with full schema coverage and clear annotations, the description covers purpose, calling convention, and when to use key topics. No important agent decision 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 coverage is 100%, and the single optional topic parameter is already documented in the schema with examples. The description reinforces omit-vs-provide behavior but does not add syntax or constraints beyond the schema.

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

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

The description uses a specific verb and resource: "Re-serve the bundled operating doctrine" and clarifies that it returns bundled playbooks. It also distinguishes this offline, no-device-I/O tool from the sibling device-operation tools.

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

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

It explicitly states both invocation modes: no topic lists available topics, and a topic returns that playbook's full text. It further names concrete situations for recovery and interfaces, so the agent knows when to reach for it.

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

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

Adds substantial context beyond the annotations: the gating requirements, that the operation is reversible, the no-op edge case (returns detached=false rather than an error), and the side-effect boundary (does not touch power or boot order; a running host keeps running until reboot). This is exactly the kind of behavioral disclosure annotations like idempotentHint/destructiveHint cannot convey.

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

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

Front-loaded with the core verb+resource and the sibling relationship, then layered with gating, edge-case and side-effect notes in order of importance. Dense rather than padded, though the closing 'Returns the typed act outcome' is mildly redundant given the earlier detached=false explanation.

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

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

With no output schema, the description still conveys the return contract (typed act outcome, detached=false when nothing is attached), the auth/approval prerequisites, and the side-effect scope. An agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema description coverage is 100% and both parameters (confirm, profile) are fully documented in the schema, so the baseline is 3. The description mentions 'per-invocation approval', which loosely maps to ``confirm``, but adds no syntax, default, or interaction detail beyond the schema.

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

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

States a specific verb (detach) applied to a specific resource (virtual media presented to the host) and explicitly frames itself as the inverse of ``mount_iso``. An agent can distinguish it from mount_iso, list_virtual_media and set_boot_device without opening any schema.

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

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

Gives clear operative context: it is gated behind KVM_PILOT_MCP_ALLOW_MEDIA plus per-invocation approval, and it routes boot-order concerns to ``set_boot_device``. It stops short of an explicit when-not clause, but the inverse-of-mount_iso framing and the boot-order hand-off leave little ambiguity.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description still adds real value beyond them: the operation is bounded (up to count events or duration seconds, capped 30s), and follow mode is deliberately omitted due to synchronous stdio transport. That framing of boundedness and the CLI divergence is genuinely informative, though return-shape details are absent.

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

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

Front-loads the purpose and bounds before the sibling comparison and the #233 rationale. The CLI-twin and issue-reference aside is somewhat layered, but each sentence contributes routing or behavioral context rather than padding.

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

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

No output schema exists, yet the description explains what an event is (typed atx/msd/streamer state changes) and how the call terminates (count/duration). That covers most of what an agent needs to call it correctly; only explicit return formatting is left unstated.

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

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

Schema description coverage is 100%, and the schema already documents count, duration, and the 'whichever comes first' cap. The description restates the count/duration interaction and the 30s cap but adds no format or syntax detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Collect typed device events from the kvmd stream') and immediately scopes it with '(read-only, bounded)'. It also differentiates from siblings by contrasting with the CLI twin and naming the content of the stream (atx/msd/streamer state changes). An agent can distinguish this from logs and wait_for_state 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 routes the agent: '``logs`` is the better first diagnostic; events add the live typed stream ... to cross-check a vision wait against.' This states both the alternative and the conditions selecting each, which is exactly what usage guidance should do.

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?

Goes well beyond the annotations: discloses that it is an EXTERNAL WRITE, that filing is gated behind KVM_PILOT_MCP_ALLOW_EXTERNAL_WRITE plus per-invocation approval, that dry_run previews the payload, and that a missing/unauthenticated gh yields a graceful filed=false. It also explains the idempotent 'nothing to file' path, matching idempotentHint=true.

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

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

Front-loads the core action and trigger, then escalates to the EXTERNAL WRITE warning, then supplies the mechanics. Dense but every clause (gating, dry_run, failure mode) carries information an 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 no-output-schema mutation tool it covers the essentials: preconditions, approval gating, preview path, and the exact result signals ('filed=false', 'outcome=not_confirmed', 'nothing to file'). Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100% and the schema already documents each parameter richly, so the baseline is 3. The description still adds value by framing dry_run as a payload preview and confirming the confirm param's role in the external_write gating, tying the fields to the approval workflow.

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 ('File the device's firmware-currency report as a GitHub issue') plus the triggering condition ('when the registry is behind'). It also positions itself against the read half and against the CLI tool it mirrors, so an agent can distinguish it from the sibling firmware_check.

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

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

Clearly explains the condition for acting ('registry current → nothing to file') and the gating/approval flow, so the agent knows the preconditions. It stops short of explicitly naming firmware_check as the read-only alternative, but since it embeds the read half itself, the routing gap is minor.

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 real behavioral context beyond the annotations: 'nothing is filed, no gate is consulted' and that the write path is gated externally. It does not discuss failure modes or how the registry comparison is performed, but the annotation bar is lower here.

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

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

Front-loaded first line gives the essential purpose, and the follow-up explains the relationship to file_firmware_report. The internal reference '(#233)' and markdown backticks add minor noise that does not help an agent, but the text is otherwise tight.

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

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

There is no output schema, so the description carries some return-value burden; it does name the key signal ('registry_behind') and what the report tells you. Combined with rich annotations and full schema coverage, this is nearly complete, missing only explicit return shape details.

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

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

Schema description coverage is 100% for the single optional 'profile' parameter, and the schema already explains the config.toml selection and default. The description adds no parameter guidance, which is the expected baseline when the schema does the work.

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

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

The first sentence states a specific verb and resource with scope: 'Report the device's firmware currency vs the bundled registry (read-only).' It explicitly distinguishes itself from the sibling file_firmware_report by describing itself as 'the read half' of that tool.

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

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

It names the condition for escalation ('When registry_behind is true') and points to the alternative tool that performs the gated external write. The when/when-not split is explicit, so an agent can route without reading the sibling schema.

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 readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the tiered severity model, that results are served through the preflight cache so 'stable posture may come from the last assessment,' and that a firmware change injects a 'firmware-delta' finding. It also flags the single most valuable finding (recovery-path), which meaningfully changes how an agent should interpret results.

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

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

Content is front-loaded (purpose, then read-only, then return shape, then caching caveat) and each sentence carries real information. Minor waste in issue references (#80, #225) that mean nothing to an agent and a slightly verbose framing.

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

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

With no output schema, the description compensates by describing the return shape (per-check findings, tiered severity), the standout field (recovery-path), and the cache-driven caveat (firmware-delta, stale posture). Nothing an agent needs to call and interpret this read-only audit is missing.

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

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

The single 'profile' parameter is fully documented in the schema (100% coverage), including its config.toml origin and the KVM_PILOT_PROFILE default, and the description adds nothing about it. Per the high-coverage rule, baseline 3 is appropriate.

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

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

The description gives a specific verb ('Audit') and enumerates the resources covered (readiness/recovery, security posture, firmware), which is far more informative than the generic name 'healthcheck'. It does not explicitly contrast itself with near-neighbors such as firmware_check, info, or capabilities, so the sibling distinction is only implicit.

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 clearly states the operative context: a CRITICAL finding 'is what should gate a subsequent destructive op,' which tells the agent when this tool is relevant. However, it names no alternative tool and states no when-not-to-use conditions, so the routing guidance is contextual rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the '(read-only)' tag is partly redundant, but the description goes further by disclosing what the payload contains (host/driver plus an info block with model, vendor, firmware, hardware) and that the appliance vs. managed system distinction depends on whether it is a PiKVM/GLKVM or BMC. It does not cover error behavior, auth/profile resolution, or the cost of the call, so it stops short of a 5.

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

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

Purpose and the sibling-routing exclusions are front-loaded, and every clause does work. The parenthetical about PiKVM/GLKVM vs. BMC is useful but slightly expands the block; overall efficient rather than 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?

There is no output schema, so the description must describe the return payload, and it does so concretely (host, driver, info block fields, appliance vs. managed-system semantics). Combined with annotations covering safety and 100% schema coverage on the single parameter, an agent has everything needed to call this correctly.

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

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

Only one optional parameter (profile) and schema description coverage is 100%, so the schema already explains the profile lookup and the default fallback. The description adds nothing about profile selection, so baseline 3 applies.

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

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

States a specific verb and resource ('identify the device and the system behind it') and immediately names the shape of the answer (host/driver plus the driver's info block). It explicitly distinguishes itself from sibling informational tools (healthcheck, capabilities, power_state), so an agent can route without opening any schema.

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

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

Gives an explicit use case ('use it to confirm what you are talking to') followed by three named exclusions that each point at the right alternative: safety → healthcheck, capabilities → capabilities, power → power_state. This is a textbook when-to-use/when-not-to-use statement.

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

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

Annotations already cover the safety profile (readOnlyHint/idempotent/destructive=false), so the description's added value is in explaining the returned semantics: stored images, selected image, attach state ('online'), and what host_visible_as means for the target's boot menu. That is substantive behavioral context beyond the annotations, though it doesn't cover edge cases or pagination.

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

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

Front-loads the action and the pre-download check, then layers return-field semantics. Dense and mostly earning its space, though the parenthetical issue references (#127, #78) add mild noise without aiding invocation.

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

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

With no output schema, the description carries the burden of explaining returns and does so thoroughly, including the key host_visible_as interpretation for boot-entry matching. For a simple read-only list tool with one optional param, nothing an agent needs is missing.

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

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

There is a single optional 'profile' parameter with 100% schema description coverage, which already documents its config.toml origin and default fallback. The description adds no parameter-level meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Inventory the KVM's virtual-media (MSD) storage') with an explicit read-only scope. An agent can distinguish it from mount_iso/eject, which mutate media state, without opening any schema.

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

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

Gives a clear conditional trigger: 'Check this BEFORE asking the operator to download or upload an ISO — the image may already be on the device.' That is a concrete when-to-use rule. It does not name sibling tools (mount_iso/eject) as explicit alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds real context beyond that: the seek lookback semantics, the diagnostic rationale, and the deliberate omission of tail-follow because it would block the synchronous transport.

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

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

The core purpose is front-loaded in the first clause, and the diagnostic framing follows. The tail-follow note is arguably tangential but it explains a real design constraint, so it earns its place; overall tight with no filler.

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

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

With full annotation coverage, 100% schema description coverage, and no output schema required (the description states the return is text), an agent has what it needs. The only mild gap is that the profile parameter's effect on target selection is left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters in full. The description restates the seek semantics ('seconds of lookback (0 = the whole buffer)') without adding anything new, and never mentions the profile parameter, so this is baseline-level value.

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

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

The description opens with a specific verb and resource ('Return the device/host event log as text') and immediately marks it read-only. It also implicitly separates itself from siblings like snapshot by noting the log names a fault a screenshot cannot, so an agent can tell it apart without opening a schema.

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

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

It gives a concrete when-to-use trigger: 'go-to diagnostic when video/streamer/encoder or power behaviour looks wrong', with a supporting example (stuck encoder behind a snapshot 503). It lacks an explicit when-not or a named alternative tool (e.g. events) for the case where a structured log is preferred.

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 the mutation/safety profile (readOnlyHint=false, destructiveHint=false), and the description adds substantial non-structured context: the media-effect gate, the required env flag and approval flow, reversibility, and the critical side effect that mounting bumps frame generation, invalidating a previously planned mouse click. That is exactly the behavioral detail structured fields cannot carry.

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

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

Front-loads the action and gate status, then details parameters and side effects; every sentence carries information. The inline-code markup adds minor visual noise but no padding.

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

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

With no output schema, the description covers the gate, approval requirement, reversibility, and the frame-generation side effect an agent must account for. It omits edge cases such as what happens if media is already mounted, keeping it just short of fully complete.

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

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

Schema description coverage is 100%, so all five parameters are already documented (source, usb, name, confirm, profile). The description restates source semantics (local path or http(s) URL) and usb behavior without adding format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Mount an ISO as virtual media on the host") and is immediately distinguishable from siblings like list_virtual_media and eject. An agent can identify the action without opening the schema.

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

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

Gives concrete preconditions for use: it is a gated act requiring KVM_PILOT_MCP_ALLOW_MEDIA plus per-invocation approval, and notes the operation is reversible. It does not explicitly route the agent to alternatives (e.g., ejecting existing media first), so it falls short of a full when/when-not/alternative statement.

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

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

Far beyond the annotations (which only give destructiveHint=true), it discloses the exact refusal conditions (host reboot/media swap, ref older than KVM_PILOT_MCP_FRAME_MAX_AGE of 60s, foreign ref), the env gating (KVM_PILOT_MCP_ALLOW_HID) plus per-invocation approval, and the not_confirmed outcome. This is unusually rich behavioral disclosure.

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?

Purpose is front-loaded in the first sentence, followed by the click-vs-move constraint and coordinate semantics. It is dense with backtick-heavy detail but every sentence carries actionable information; only minor tightening is possible.

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, approval-gated HID tool with no output schema, it covers preconditions, gating, and one outcome value (not_confirmed). A little more on the returned result shape would fully close the loop, but the agent has what it needs to call correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds rationale and failure semantics the schema lacks: coord_space 'survives resolution changes', why the frame ref is needed, and the confirm/approval interaction. It reinforces rather than merely repeats the schema.

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

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

The first sentence states a specific verb and resource ('Move the mouse (and optionally click) on the host') and immediately flags the operation class ('DESTRUCTIVE (HID input)'). This is clearly distinguishable from siblings like calibrate_mouse or press_key.

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

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

It gives a clear conditional rule: a click requires an observed_frame_ref from a prior snapshot, while a move-only call needs none, and it directs the agent to re-snapshot and retry on refusal. It stops short of explicitly naming a sibling to use instead, but the snapshot-first workflow is unambiguous.

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, but the description adds substantial context the annotations cannot carry: the gating/approval flow, the typed outcome on denial, the tri-state verified effect report with null-plus-reason when no trustworthy power signal exists, and the generation-bump invalidation of prior snapshot frame refs. That last item is a non-obvious side effect an agent must know before calling.

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 purpose and the DESTRUCTIVE warning are correctly front-loaded in the first two lines. The remainder is information-dense but slightly cluttered by parenthetical issue references (#234, #168) and backtick-laden identifiers, which cost a little readability without adding agent-relevant meaning.

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

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

With no output schema, the description still covers what an agent needs to know: the approval/denial outcome model, the shape and tri-state nature of the effect report, and the snapshot-ref invalidation side effect. Nothing material for correct invocation or interpretation is missing.

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

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

Schema description coverage is 100%, so action, confirm and profile are already fully documented (including the enum's "use wake for Wake-on-LAN" pointer). The description reinforces the confirm/elicitation semantics but adds no syntax or format detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Change host power state") and flags destructiveness up front, which cleanly separates it from the read-only sibling power_state. It stops short of naming power_state/wake as the alternatives, so the agent must infer the read-vs-write split from sibling names 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?

Explains the approval path in detail (power effect gate, elicitation vs confirm=true, denial returns outcome=not_confirmed), which tells the agent how a call will be mediated. It never says when to prefer this over wake or power_state, so the selection guidance is only implied by the 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 readOnlyHint/idempotentHint and no destruction, and the description reinforces this with 'Changes nothing.' It goes further by disclosing return shape (powered_on bool, atx LEDs/buttons on PiKVM) and driver-dependent behavior (BMC/AMT answer from controller state), which matters because there is no output schema.

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

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

Front-loads the one-line purpose, then return values, then when-to-use, then sibling routing. Every sentence carries distinct information with no 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?

For a read-only one-parameter tool with no output schema, the description covers purpose, return contents including device-family variance, and sibling routing—everything an agent needs to call it correctly and interpret the result.

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

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

There is a single optional profile parameter whose schema description is fully covered (100%), so the schema carries the meaning. The description adds nothing about profile selection or defaults, which is acceptable at this coverage level but not additive.

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

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

Opens with a specific verb and resource: 'Report whether the managed host is powered on (read-only).' It also names the return field (powered_on) and distinguishes itself from the mutating siblings power and wake 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?

Gives explicit trigger conditions: the cheap check after power/wake when their 'verified' came back null, and before deciding whether a dark snapshot means off or asleep. It also states the exclusions directly—use power to change power, wake to wake a sleeping host.

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 destructive/non-idempotent, but the description adds non-structured context: no echo-back so 'snapshot after', the required env gate KVM_PILOT_MCP_ALLOW_HID plus per-invocation approval, and the return shape (receipt or denial reason). This goes well beyond what the annotations declare.

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?

Purpose and destructive warning are front-loaded, then routing guidance and behavioral notes follow in an ordered, skimmable block. Slightly dense with backticked literals, and 'DESTRUCTIVE (HID)' partly restates the annotation, but every sentence carries weight.

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

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

Despite no output schema, the description states what comes back (receipt or denial reason), documents the gating and approval flow, and covers the no-feedback follow-up. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100% and each parameter is fully documented there (key code format, confirm semantics, profile selection), so the baseline is 3. The description adds the 'not a chord' constraint for key but nothing new about confirm or profile.

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 ('Press and release one key on the managed host's console') and explicitly distinguishes itself from three siblings (send_shortcut for chords, type_text for words, ctrl_alt_delete for Ctrl+Alt+Del). An agent can route to it without opening any schema.

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

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

Gives concrete when-to-use examples ('Enter to submit, Escape, F2/F12 at POST, arrows and Tab in firmware menus') and names the alternative for each neighboring case, so the boundary with siblings is fully specified.

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 destructiveHint annotation, the description discloses the concrete gating model: chords are classified by effect (power_soft/power_hard vs hid_control) and require specific env vars (KVM_PILOT_MCP_ALLOW_POWER / KVM_PILOT_MCP_ALLOW_HID). This is real auth/permission context that annotations alone cannot convey.

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

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

Front-loads the action and the DESTRUCTIVE flag, then explains the gate. It is dense but every clause carries information; the only minor cost is a somewhat wordy second 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?

For a destructive, non-idempotent mutation with no output schema, the description covers the safety gate and the schema covers the confirm/profile mechanics. The main omission is the relationship to the near-duplicate siblings press_key and ctrl_alt_delete.

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

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

Schema coverage is 100% and every parameter (keys, confirm, profile) has its own description, so the schema does the heavy lifting. The description's example key chords add marginal reinforcement but no new syntax beyond what the schema already documents.

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

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

The description states a specific verb+resource ('Send a key chord') and specifies the exact input format (comma-separated kvmd key codes) with examples. It does not, however, distinguish itself from the very similar siblings press_key and ctrl_alt_delete, leaving an agent to guess which to use.

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 through the gating explanation (power vs hid chords). There is no explicit statement of when to reach for send_shortcut over press_key or ctrl_alt_delete, nor any exclusions, so the agent must infer the boundary itself.

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, but the description adds substantial context beyond them: it works offline and answers even when the device is down, effect gates are exposed by class name only (opening is operator-only, out of band), and journal/wait state is in-memory so a restart empties it and voids receipts and frame refs. This is exactly the kind of non-obvious behavior an agent needs.

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

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

Purpose is front-loaded, followed by usage triggers, a return-value enumeration, and restart caveats — every clause is load-bearing. It is dense but slightly long, keeping it short of a 5.

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

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

There is no output schema, so the description carries the return contract and does so thoroughly (target, dry-run state, effect gates, approval posture, standing approvals, act journal, last wait_for_state result), plus the restart caveat an agent would otherwise misread as 'nothing happened'.

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

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

Schema coverage is 100% and the single profile parameter is fully documented there (including the config.toml source and KVM_PILOT_PROFILE default). The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb (Report) and resource (the server's current operating posture) and immediately differentiates itself from siblings by pairing with healthcheck (device health) and doctrine (playbooks). An agent can tell exactly what class of information this returns without opening the schema.

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

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

Explicit when-to-use triggers are given: after a context compaction, when resuming a long flow, and before planning act calls. It also names the complementary tools (healthcheck, doctrine) so the routing decision is unambiguous.

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 destructive/non-idempotent, and the description adds substantial context beyond them: it is a config mutation subject to the config effect gate plus per-invocation approval, denials return a typed outcome on the same path, and unadvertised targets fail fast. This is exactly the extra behavioral detail annotations cannot convey.

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

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

Front-loaded with the mutation warning and quite dense for its length. The trailing issue reference '(#234)' is minor noise, and the clauses are packed, but nearly every sentence carries actionable content.

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

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

For a destructive mutation tool with no output schema, the description covers approval behavior, the denial outcome, override-clearing semantics, and the fail-fast condition. An agent has everything needed to invoke it correctly and interpret the failure path.

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

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

Schema description coverage is 100%, so once/uefi/device/confirm/profile are already fully documented in the schema. The description restates the none/once=false/uefi=false semantics, adding little beyond what the schema already says. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Set the next-boot (or persistent) boot device via BootSourceOverride') and immediately labels it a CONFIG MUTATION. It is clearly distinguishable from the read-only sibling boot_options, which it names 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?

Gives the prerequisite workflow clearly ('call boot_options first to see allowable') and explains the gating/approval path. It stops short of an explicit when-not-to-use statement, but the fail-fast note and the boot_options pointer cover the practical routing decision.

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

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

Even though annotations already declare readOnly/idempotent/non-destructive, the description adds substantial context the annotations cannot: the exact return shape, the frame_ref staleness-guard semantics, the live signal fields (online/resolution/fps/format), and the unchanged_since_last_snapshot failure mode with an explicit 'do NOT trust them as ground truth' instruction. That is exactly the behavioral disclosure annotations cannot carry.

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

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

Front-loaded with the core action, then organized into purpose, return contract, and caveat. Dense and mostly non-redundant, though the inline issue references (#143, #141) are low-value noise for an agent.

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

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

There is no output schema, so the description must explain the return value, and it does: the [json_text, image] tuple, the frame_ref format, and the signal/unchanged fields. It also warns about the stale-frame edge case, leaving nothing critical for an agent to guess.

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

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

Only one parameter (profile) and schema description coverage is 100%, so the schema already documents its meaning and default. The description adds nothing about profile or how it interacts with the returned frame, so the baseline 3 applies.

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

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

Opens with a specific verb+resource ('Capture the current KVM screen') and immediately qualifies it with '(read-only)', which cleanly separates it from the actuating siblings like mouse, type_text and power. The return contract ([json_text, image]) further pins down what the tool produces.

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

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

Gives explicit downstream usage: pass the returned frame_ref to the mouse tool as observed_frame_ref, and explains why (absolute clicks refused after host reboot/media swap). It also tells the agent what to do when pixels look stale (check signal and logs). It does not, however, state when to prefer snapshot over the sibling classify_screen or wait_for_state, so the alternative-selection guidance is incomplete.

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

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

Annotations cover the safety profile (readOnly, non-destructive, idempotent), and the description adds what they cannot: the scan is noisy, requires the user to own the range, demands confirm=true, and returns outcome=not_confirmed on denial. That is genuine operational context beyond structured fields.

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

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

The purpose and the RISKY flag are front-loaded in the first line, then authorization and the confirm requirement follow in descending priority. Slightly redundant with the schema's confirm description, but no sentence is wasted.

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

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

For a three-parameter discovery tool with no output schema, the description covers purpose, risk, authorization, and the failure mode of a missing confirmation. It does not indicate the shape of a successful result (host list, timing), a minor gap given there is no output schema to lean on.

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

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

Schema coverage is 100% and every parameter already carries a detailed description, including the nuanced confirm/elicitation behavior. The description restates that confirm=true is required but adds no syntax or format detail the schema lacks, so baseline 3 applies.

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

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

Opens with a specific verb+resource+scope: 'Scan a CIDR for hosts with an open SSH port.' That cleanly separates CIDR-wide discovery from the single-target check implied by the ssh_reachable sibling. It stops short of naming that sibling explicitly, so an agent must infer the routing rather than read 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?

Gives an explicit positive condition (only to find a target whose address the user doesn't know, after they confirm the range) and an explicit exclusion (never by default), plus the authorization precondition. This is exactly the when/when-not guidance an agent needs for a risky 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?

Beyond the annotations (destructive, non-idempotent), it discloses that the call is gated by a dedicated SSH effect gate rather than the HID gate, requires per-invocation approval, and can return typed same-path denials. This adds real behavioral context the annotations do not carry.

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

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

Short and front-loaded, leading with the core action and the DESTRUCTIVE tag. The issue-reference fragment '(#234)' and the parenthetical are somewhat cryptic and cost a little 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?

For a destructive no-output-schema tool, it covers the essential safety and approval model that an agent must know before invoking. It could say more about error/denial outcomes, but the confirm parameter's schema description already covers the not_confirmed case.

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

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

Schema coverage is 100%, so all four parameters are already documented. The description only re-explains the host override (already in the schema) and adds no semantics for command, confirm, or profile, so baseline 3 applies.

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

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

States a specific verb and resource ('Run a command on the managed host's OS over SSH') and flags the safety profile with 'DESTRUCTIVE / in-band'. It doesn't explicitly distinguish itself from close siblings like ssh_reachable or ssh_discover, so it falls just 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?

It names the gating mechanism (SSH effect gate, per-invocation approval, same-path denials), which implies the operational context, but there is no explicit when-to-use versus ssh_reachable/ssh_discover guidance or stated preconditions for the target host.

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 bar is lower, but the description adds real value: 'read-only, in-band' and the clarification that it targets a different machine than the KVM appliance, plus the runtime-override behavior of host. It doesn't cover timeout/latency behavior, but that's minor here.

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

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

Front-loads the core question, then layers scope, routing guidance, and the host override in a tight structured block. Every sentence carries information, though the host paragraph slightly restates the schema description.

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

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

For a read-only reachability probe with full annotation coverage and no output schema, the description is nearly complete: it states the operation, the distinct target machine, and when to prefer it. It could note failure semantics (what an unreachable result implies), but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, establishing the baseline of 3. The description reinforces the host override with a use case (install-time DHCP address), but adds no syntax or format detail beyond the schema.

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

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

Opens with a precise question ('Is the managed host's OS reachable over SSH?') that names a specific verb-like operation and resource, and explicitly disambiguates the target as the host *behind* the KVM, distinct from the appliance. This separates it cleanly from siblings like ssh_exec, ssh_discover, and healthcheck.

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 context ('use this to prefer remote recovery before asking a user to physically intervene'), which tells the agent when this probe is the right call. It does not explicitly name when-not or enumerate alternatives (e.g. ssh_discover/ssh_exec), so it stops short of a full routing rationale.

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/no-destructive, but the description adds substantial context beyond them: no device call is made, the data is a shipped ledger rather than a live probe, it is 'EVIDENCE, not a guarantee', and missing rows imply unverified alpha/mock-only status. It even explains the meaning of the `status` value ('fail' = every recorded live attempt failed).

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

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

The core definition is front-loaded in the first sentence and the rest earns its place by defining the evidence semantics. It is slightly cluttered by internal issue references (#98, #94/#95) and a wiki cross-reference that an agent does not need to invoke the tool.

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

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

With no output schema, the description does the work of explaining the return shape: rows per device+firmware+capability, a `status` field, and a `never_exercised` list. It stops short of describing the full field set or how maturity levels are derived, but an agent has enough to interpret results and act correctly.

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

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

Schema coverage is 100% and the schema descriptions already specify case-insensitive exact match for vendor and substring for product, so the description's 'Filters are case-insensitive; product matches as a substring' largely restates structured data. The phrase 'per device+firmware+capability' hints at how filters combine, but no syntax or edge-case detail is added, so the baseline 3 applies.

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

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

The opening line states a specific resource and scope: what has been exercised on real hardware, keyed by device+firmware+capability. It also distinguishes itself from live-query siblings by declaring 'read-only, offline — no device call', so an agent can tell it apart from `capabilities` or `healthcheck` 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?

Usage context is clear: consult this before treating a capability as verified, and 'confirm destructive steps with the user' when a combo is unverified. It does not explicitly name the sibling alternative (e.g. live `capabilities`) or state when this tool should not be used, so it stops short of a 5.

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

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

Annotations already flag destructiveHint=true, but the description adds genuinely new behavior: nothing echoes back, no Enter is appended, keystrokes land wherever the host's focus is, and it requires KVM_PILOT_MCP_ALLOW_HID plus per-invocation approval (elicitation or confirm=true). It even names the denial outcome. This is 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?

Front-loaded with the action and the DESTRUCTIVE label, then each subsequent sentence carries unique, non-redundant information (echo behavior, alternatives, focus, auth, return). No filler.

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

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

With no output schema, the description compensates by describing the return value (typed act outcome: receipt or denial reason) and the full auth/approval path. An agent has everything needed to invoke this destructive tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents text, confirm, and profile in detail. The description reinforces that text is typed verbatim with no Enter appended, but this largely restates what the schema's text description already says, so baseline 3 is appropriate.

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

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

States a specific verb (type) on a specific resource (a string on the managed host's console over the HID keyboard) and immediately routes non-text keys to press_key and chords to send_shortcut, so the agent can distinguish it from siblings 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 covers when to use (printable commands, installer fields, passwords), when not to (non-text keys -> press_key, chords -> send_shortcut), and the surrounding workflow (snapshot before to confirm focus, after to see effect). Prerequisites for approval are also 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?

Goes well beyond the annotations: bounded polling of cheap gates then vision, a 300s server-side cap with guidance to chain calls, timeout returns reached=false with last state and never hangs or raises, and it holds the driver open up to timeout. It also discloses the frame_ref handoff to mouse and the vision-credential dependency.

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

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

Front-loaded with the core behavior and dense with specifics; some content (the 300s cap, phase token naming) is echoed in the schema, but every sentence carries operational detail and none is filler.

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

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

With no output schema, the description carries the return contract itself: phase/confidence plus frame_ref on success, reached=false plus last state on timeout. Combined with the documented failure modes and credential caveat, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: phase is a classify_screen token with fail-fast validation on unknown tokens, timeout is capped server-side at 300, and frame_ref feeds mouse as observed_frame_ref. The phase-token relationship to a sibling tool is genuinely beyond the schema.

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

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

States a specific verb and resource: wait (bounded) until the screen reaches a boot/run phase, and marks it read-only. It is clearly distinguishable from siblings like classify_screen and power_state because it describes active waiting on a phase token rather than a one-shot classification or a state query.

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

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

Explains when to use this versus alternatives, naming classify_screen polling for non-cheap-gate phases and the no-vision-credentials exclusion. It's clear context, though it doesn't give an explicit 'prefer X over Y when Z' rule beyond those cases.

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 openWorldHint=false, so the safety profile is covered; the description adds genuinely new behavior: approval gating, the typed same-path denial mechanism, the not_confirmed outcome, and the fact that WoL is broadcast from the server's own host rather than through the KVM. It does not spell out side effects on an already-powered host, 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?

Front-loads the action in the first sentence, then adds gating and defaults compactly with no padding. The parenthetical issue reference ('#234') and 'POWER (soft)' tag are internal shorthand that costs a little clarity without earning much for an external agent.

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 five-parameter, no-required-args action tool with no output schema, the description covers the mechanism, approval flow, one return value (outcome=not_confirmed), and defaults, which is enough to invoke it correctly. It stops short of describing the full result shape or what happens if the host is already on.

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

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

Schema description coverage is 100%, so all five parameters including defaults are already fully documented in the schema. The description only restates the mac and broadcast defaults, adding no format, syntax, or constraint detail beyond what the schema provides — the correct baseline of 3.

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 ('Send a Wake-on-LAN magic packet to power the host on') and adds the mechanism detail that no KVM driver is contacted, which separates it from the sibling `power` tool. The trailing 'POWER (soft)' tag is unexplained jargon and the sibling `power` is never named directly, so the differentiation is implied 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?

The description explains the gating context (power effect gate plus per-invocation approval) and gives real guidance on the `confirm` flag, including that denials return outcome=not_confirmed. However it never states when to choose `wake` over the sibling `power` or `power_state` tool, leaving the primary routing decision to inference.

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