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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is known. The description adds valuable behavioral context by explaining the aggregation logic across paths, the failure-domain labeling to avoid overstating redundancy, and the specific meaning of 'summary.out_of_band_live=false'. This goes well 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?

The description is well-structured and front-loaded with the core purpose. The supporting sentences add meaningful detail about path domains and output semantics without any fluff. Every sentence earns its place.

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

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

For a tool with no output schema, the description provides substantial context about the aggregated view and a specific output field. However, it does not fully enumerate all return fields or the exact structure of the summary, leaving some ambiguity about the complete response shape.

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

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

The sole parameter 'profile' has zero description in the schema, and the tool description does not mention it either. Since schema description coverage is 0%, the description fails entirely to explain what 'profile' does or how it affects the results. This is a critical gap for the only input.

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

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

The description clearly identifies the tool's function: reporting which independent recovery paths are live for a device. It lists the exact paths (REST API, appliance-SSH, target-SSH, out-of-band power, console-HID) and emphasizes the key distinction of failure domains, making it distinct from sibling tools like ssh_reachable or power_state.

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 provides clear context through 'the lockout view' and explains when redundancy matters, indicating this is for recovery planning when a device is hung or locked. However, it does not explicitly name alternative tools or state when not to use this tool, only implicitly differentiating 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?

The description goes well beyond the annotations by disclosing concrete effects: opening specific ports (16994, 5900), setting an RFB password, and the 'consent_off' option that disables the on-screen user-consent prompt (called a 'surveillance escalation'). It also mentions gating and approval requirements, adding rich behavioral context. No contradiction with annotations (destructiveHint true matches 'CONFIG MUTATION').

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

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

The description is front-loaded with a clear summary sentence, then uses structured details for each feature. Every sentence adds value: port numbers, gates, security implications, and operator-gate reference. No fluff or redundancy.

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

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

The description covers the main behavior, side effects, and special authorization needs, which is substantial given the tool's complexity. However, there is no return value info (no output schema) and the 'confirm' and 'profile' parameters are not explained, leaving minor gaps for an agent to fully predict invocation outcomes.

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

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

With 0% schema description coverage, the description compensates by explaining the key parameters: feature='sol' and feature='kvm' and their port implications, and consent_off=true as KVM-only with operator-gate requirement. However, it does not explain the 'confirm' or 'profile' parameters, leaving some ambiguity for those.

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 ('Enable') and resource ('Intel AMT redirection listener over WS-Man'), with clear scope ('Intel AMT/vPro only'). It distinguishes between the 'sol' and 'kvm' feature modes, making the tool's purpose unambiguous relative to sibling tools.

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

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

The description gives context about when the tool applies (Intel AMT/vPro only) and explains the two feature modes, but it does not explicitly state when to use this tool over alternatives or when not to use it. No sibling tool is named as an alternative. Usage is implied rather than explicit.

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

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

While annotations already declare destructiveHint=true, the description adds rich behavioral context: drops all KVM control for ~60s, leaves target power untouched, requires effect gate and per-invocation approval, and has no out-of-band power. This goes far beyond what annotations convey.

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

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

The description is compact and efficient, with each sentence serving a distinct purpose: action, rationale, impact, safety gates, and caution. It is front-loaded with the essential 'not the target' clarification and includes 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?

The description covers purpose, trigger, side effects, and safety precautions comprehensively. However, it omits direct guidance on the `confirm` and `profile` parameters, and there is no output schema to clarify return values. This leaves a small but important gap.

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

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

Schema description coverage is 0%, so the description must explain the parameters, but it does not explicitly. The 'confirm' boolean is only indirectly referenced via 'per-invocation approval', and 'profile' is never explained. This is a significant gap for a destructive tool.

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

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

The description clearly states the action: 'Reboot the KVM APPLIANCE (not the target) to clear a wedged encoder.' It specifies the verb, the resource (appliance vs target), and the purpose. This distinguishes it from sibling tools like power or wake that affect 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?

Explicitly states when to use: 'Recovers the RV1126 encoder wedge (the only fix — the stuck threads are unkillable kernel threads).' Also provides strong warnings: 'use this deliberately, never in an automated loop' and clarifies impact ('Drops all KVM control for ~60s'). This gives clear decision guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive, but description adds critical behavioral context: load sits at ~10 even when idle due to driver parking threads in D-state, so it is NOT a health signal. This goes beyond annotations and prevents misuse.

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?

Description is concise yet comprehensive: front-loaded with 'Read-only diagnostics', then specifies target, output, and a critical caveat. Every sentence serves a purpose, with no fluff or redundancy.

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

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

For a diagnostics tool with no output schema, the description sufficiently describes what it reports (1-minute load and D-state threads) and provides caveats. Minor gap: it doesn't describe the output format (e.g., numeric values vs. human-readable text), but the core usage context is complete.

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

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

There is one optional 'profile' parameter with no schema description (0% coverage). The description does not mention this parameter at all, leaving its purpose and accepted values unexplained. Since schema coverage is low, the description should compensate but does not.

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

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

Description uses specific verb 'Reports' and clearly identifies the resource (KVM appliance's own OS over SSH) and scope (appliance_ssh channel, not managed target). It distinguishes from siblings by explicitly stating it targets the appliance itself, not the managed 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?

Explicitly states when NOT to use this tool as a health signal and points to an alternative: 'use the healthcheck encoder-wedge finding for the real tell.' Also clarifies it targets the appliance, not the managed target, giving clear context.

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 tool as read-only, idempotent, and non-destructive. The description adds useful behavioral details beyond annotations, such as the specific fields reported ('enabled', 'target', 'mode', 'allowable') and the fact that 'mode' can be null if the BMC doesn't expose it. This gives the agent concrete expectations.

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

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

The description is well-structured and front-loaded: it starts with the core function, then details the output fields and their interpretation. Every sentence adds value, with no redundancy or wasted words.

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

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

Given the absence of an output schema, the description fully covers return values and their semantics. It also provides enough context for the agent to know when to call the tool and how to use the result, making it complete for its complexity.

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

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

The input schema has one optional 'profile' parameter with no description, and the description does not mention it at all. Since schema coverage is 0%, the description completely fails to explain what 'profile' means or how to use it, leaving a notable gap for the agent.

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

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

The description clearly states the tool's purpose with a specific verb ('Show') and resource ('host's current boot override (Redfish BootSourceOverride)'). It also explicitly notes it's read-only, distinguishing it from sibling tools like set_boot_device.

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 that an actuator uses this tool to know what set_boot_device values are acceptable before attempting a change. This provides a clear when-to-use context, though it doesn't explicitly enumerate alternative tools or when not to use this one.

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

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

The description discloses significant behavioral traits: visible cursor movement for 10-30s, gated like HID input requiring approval, pointer moves only, and persistence/staleness per host and resolution. This goes well beyond the sparse annotations.

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

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

The description is dense but well-structured, front-loading the purpose and then adding essential behavioral, prerequisite, and postcondition details. Every sentence adds value, and the length is justified by the tool's complexity.

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

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

The description covers purpose, behavior, preconditions, side effects, and persistence thoroughly. However, it omits any mention of return values, and the parameter semantics are absent, which leaves a gap for a tool with no output 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?

The schema has zero coverage (no descriptions) and the tool description does not mention any of the three parameters (confirm, profile, tolerance). The description fails to explain their purpose, leaving the agent without sufficient guidance for parameter selection.

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

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

The description clearly states the tool's function: 'Measure and store this host's mouse commanded→observed correction' and explains the problem it solves ('clicks where the button should be and misses'). It distinguishes from sibling tools like 'mouse' by emphasizing calibration rather than direct input.

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 preconditions are provided (live video, static screen, visible cursor, Pillow) and the effect on subsequent mouse coordinates is described ('Afterwards mouse percent coords apply it transparently'). It does not explicitly mention alternatives, but the context makes the ideal usage clear.

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

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

The description adds substantial context beyond annotations: it states the tool makes no network call and runs no preflight, returns in enum declaration order for stable output, and clarifies that live_evidence is not live verification. This is rich behavioral disclosure, fully consistent with the readOnly and idempotent annotations.

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

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

The description is front-loaded with a clear definition, then efficiently expands with structural details, examples, and tool comparisons. Every sentence earns its place, and the structure with line breaks aids readability without bloat.

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

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

The description covers the tool's purpose, output ordering, the meaning of live_evidence, and alternative tools, which is comprehensive for a simple query tool. However, it omits any explanation of the 'profile' parameter, and with no output schema, this is a minor incompleteness.

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

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

With 0% schema description coverage, the description needed to explain the 'profile' parameter, but it makes no mention of it. The parameter is optional with a default of null, yet the description provides no guidance on its meaning or effect, leaving a clear gap.

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

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

The description clearly states the tool 'List the capabilities the target's driver supports' with a specific verb and resource. It distinguishes itself from siblings by contrasting with support_matrix and healthcheck, making the tool's unique role obvious.

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 provides explicit usage context: 'so you can pick the right interface up front' and gives concrete examples (Redfish has no video, PiKVM has no BootProgress). It also names alternatives for different needs, telling users to call support_matrix for per-combo evidence and healthcheck for this exact device+firmware.

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 read-only annotation, the description discloses mode-dependent behavior (server-side versus on-device gates), credential requirements, and return shapes. This adds meaningful context about how the tool behaves in different configurations, though not every edge case is covered.

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

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

The description is well-structured: purpose first, then behavior, then return shapes in bullet form. Every sentence contributes new information, and it avoids repetition or filler.

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

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

For a tool with no output schema, it explains the two possible return types (dict and fallback list) and the fallback classification instructions. However, it omits parameter meaning and specific phase fields, leaving some gaps for a tool with optional params.

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

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

The schema has two parameters (hint, profile) with zero description coverage. The tool description does not mention or explain either parameter, so it adds no semantic value. With 0% coverage, the description was expected to compensate but did not.

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

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

The description starts with a specific verb and object: 'Classify the current screen's boot/run phase', making the purpose clear and distinct from sibling tools like boot_options or power_state. It also adds the 'read-only' qualifier, reinforcing scope.

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

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

Provides clear context on when to use: it states it classifies boot/run phase and explains two modes (server-side vs on-device gates) with credential implications. It does not explicitly name alternatives or exclusions, but the usage context is strong.

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

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

Annotations already flag destructive=true, but the description adds that this is a keyboard-delivered reboot, classifies it as power_soft, and requires the KVM_PILOT_MCP_ALLOW_POWER permission. This goes beyond the annotation by specifying the permission model and the nature of the operation (power control vs. HID input).

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

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

Three compact sentences that front-load the action, then explain the destructive nature and permission requirement. No wasted words; all information is relevant.

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 power tool, the description covers the core behavior and permissions, but lacks essential parameter semantics. Given the absence of an output schema and the simplicity of the tool, the major gap is the unexplained parameters, preventing full autonomous use.

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

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

Schema description coverage is 0% and the description provides no explanation of the 'confirm' or 'profile' parameters. Since both are optional but could affect behavior (e.g., confirmation for destructive action), the agent has insufficient information to use them correctly.

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?

Clearly states 'Send Ctrl+Alt+Del to the managed host' — a specific verb and resource. It further clarifies this triggers a reboot and distinguishes it from regular HID shortcuts by referencing the power gate and classification as power_soft, differentiating it from sibling tools like send_shortcut.

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

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

Provides clear context that this is a power-related operation requiring the same permission gate as the 'power' tool, and warns against using the weaker HID gate. However, it doesn't explicitly name alternative tools or state when not to use it, though it implies that regular HID shortcuts are not equivalent.

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. The description adds context: 'offline, no device I/O', that data comes from bundled playbooks, and that it can be called repeatedly to refresh knowledge. This goes beyond annotations without contradicting them.

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

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

Three sentences, each earning its place: first defines function and safety, second explains rationale, third gives specific usage guidance. No redundant phrasing or filler.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, usage, parameter semantics, and decision guidance. It even includes situational triggers for specific playbooks. 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 has no description for the optional 'topic' parameter (0% coverage). The description fully compensates by stating: 'Call with no topic to list the topics; call with one for that playbook's full text.' This precisely defines null vs. provided behavior.

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

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

The description identifies a specific verb+resource: 'Re-serve the bundled operating doctrine' with clear read-only and offline behavior. It distinguishes from sibling tools (all hardware/IPMI/control actions) by being the only documentation/playbook tool, and explains its purpose of re-anchoring sessions.

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 usage triggers are provided: 'Read recovery the moment a host goes dark or a snapshot fails, and interfaces before picking how to do an action you haven't done this session.' It also instructs how to choose between no topic (list) and with topic (full text), which is actionable guidance.

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

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

Reveals behavioral traits not present in annotations: it is a 'GATED act' requiring 'KVM_PILOT_MCP_ALLOW_MEDIA + per-invocation approval', and notes it is reversible. This significantly exceeds the annotation's idempotence/destructive hints with concrete operational constraints.

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

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

The description is compact and immediately states the operation, followed by essential gating/permission details. Every sentence adds value, with no fluff.

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

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

The description covers purpose, relationship to mount_iso, reversibility, and required permissions, which is strong for such a simple operation. However, it leaves both parameters completely unexplained and gives no hint of expected response or side effects beyond detachment, creating a noticeable gap given the schema's lack of descriptions.

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?

Neither the description nor the input schema explains the purpose of the 'confirm' or 'profile' parameters. With schema description coverage at 0%, the description fails to add any semantic meaning to the parameters, making it unusable for deciding how to fill them.

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?

Clearly states the action: 'Detach virtual media', and reinforces with 'inverse of mount_iso', which also differentiates it from the sibling tool mount_iso. The verb+resource is specific and unambiguous.

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

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

Provides context by explicitly naming mount_iso as the inverse operation, signaling when to use this tool. However, it does not offer explicit when-not-to-use guidance or alternative tools for failure scenarios, so it falls short of a 5.

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

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

The description goes well beyond the annotations. While readOnlyHint and idempotentHint already indicate safety, the description reveals concrete behavioral constraints: no follow mode, bounded to 'count' or 'duration' seconds (capped at 30s), and suitability for sync stdio transport. This adds materially to what annotations alone provide.

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

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

The description is compact and front-loaded with the primary purpose. Every sentence earns its place: the first states the action, the second explains the bounded behavior and the reason for divergence from the CLI version, and the third provides usage context. No fluff or redundancy.

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

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

The description is largely complete for tool selection: it covers purpose, behavior, and usage context relative to siblings. The absence of an output schema makes return value description less critical, but a bit more detail on what constitutes a 'typed device event' (e.g., sample events) would make it fully self-contained. The unexplained 'profile' parameter also slightly reduces completeness.

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

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

The input schema has 0% description coverage, so the description compensates partially by explaining 'count' and 'duration' semantics ('returns up to count events or duration seconds' worth'). However, the 'profile' parameter remains undefined, with no hint in the description about its role or accepted values, leaving a gap that the schema does not fill.

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+resource ('Collect typed device events') and clearly identifies the source (kvmd stream) and nature (read-only, bounded). It also distinguishes itself from the sibling tool 'logs' by framing events as a live typed stream for cross-checking vision waits, which is more than enough to differentiate it from the broader sibling set.

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

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

Explicit guidance is given: 'logs is the better first diagnostic; events add the live typed stream... to cross-check a vision wait against' clearly instructs when to use events versus an alternative. It also explains the bounded behavior (count/duration cap) which informs practical usage, satisfying the 'when-to-use' requirement.

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

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

The description discloses external-write behavior, gating via KVM_PILOT_MCP_ALLOW_EXTERNAL_WRITE and approval, dry-run preview, and graceful degradation when gh is missing/unauthenticated. These details go well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false) and provide actionable context. No contradictions with annotations.

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

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

The description is compact and front-loaded, with each sentence contributing value. The CLI twin reference and issue numbers add some noise, but overall it is efficient and logically structured.

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

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

The description covers core behavior, external-write gating, dry-run, and failure modes, which is useful for a complex tool. However, since there is no output schema, it does not explain the return structure beyond a mentioned 'result' and 'filed=false reason.' The lack of parameter documentation leaves notable gaps, making it adequate but not fully complete.

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

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

Schema description coverage is 0%, yet the description only explains dry_run. The other four parameters (repo, source, confirm, profile) are not described. Even confirm is only obliquely tied to 'per-invocation approval.' This is insufficient for an agent to correctly set these parameters.

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

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

The description opens with a precise verb and resource: 'File the device's firmware-currency report as a GitHub issue when the registry is behind.' This clearly distinguishes it from the sibling firmware_check (which only checks) and specifies the condition for action.

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

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

It states the trigger condition explicitly ('when the registry is behind') and notes that a current registry results in 'nothing to file.' It also recommends dry_run=true for previews. However, it does not explicitly name firmware_check as the read-only alternative, so exclusions are implied rather than fully spelled out.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds that the tool reconciles state against the registry SSoT, does not file anything, does not consult a gate, and how it relates to file_firmware_report's write action. This goes beyond annotations and provides useful behavior context.

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

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

The description is two concise sentences with no filler. It front-loads the core purpose in the first sentence and uses the second to clarify behavioral boundaries and sibling relationship. Every word adds value.

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

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

For a simple read-only checker, the description covers the main function and its integration with file_firmware_report. However, it omits explanation of the 'profile' parameter and provides only a vague hint about the return value ('says whether the registry is behind'), leaving some ambiguity for the agent.

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

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

The schema describes one optional 'profile' parameter with no description (0% coverage), and the tool description does not mention the parameter at all. The agent receives no guidance on what 'profile' means or how to use it.

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

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

The description clearly states 'Report the device's firmware currency vs the bundled registry (read-only)' and further explains it is the read half of file_firmware_report, distinguishing it from the sibling and specifying its scope.

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

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

It explicitly names file_firmware_report as the write counterpart and contrasts behavior by saying 'nothing is filed, no gate is consulted' while noting when registry_behind is true the sibling contributes the report. This clearly indicates when to use this tool versus the alternative.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals caching behavior via the preflight cache, potential for stale results, and firmware-delta findings. It also explains the severity tiering and how CRITICAL findings should gate operations, adding meaningful context.

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

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

The description is concise and well-structured: it opens with the purpose, then covers read-only behavior, returns, and caching, with each sentence adding distinct value. No unnecessary words or repetition.

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

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

For a relatively simple read-only tool with one optional parameter, the description covers the return format (per-check findings with severity), the gating semantics, the cache behavior, and firmware-delta scenario. It is comprehensive enough for an agent to select and invoke it correctly.

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

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

The input schema has one optional 'profile' parameter, but the description gives no explanation of what it does or how to use it. Since schema description coverage is 0%, the description should compensate, but it remains undocumented and ambiguous.

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

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

The description uses the specific verb 'Audit' and clearly states the resource scope: device readiness/recovery, security posture, and firmware. This distinguishes it from sibling tools like power_state or firmware_check, and the added context about gating destructive operations makes its role clear.

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

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

The description explicitly states when to use this tool: before a subsequent destructive operation, especially when a remote KVM hangs. It also highlights the most important finding (recovery-path). It doesn't name alternative tools, but the context is sufficiently clear to guide selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description merely restates 'read-only' and adds no new behavioral context such as auth requirements, rate limits, or what exactly is returned.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the verb, the resource, and the read-only nature efficiently.

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

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

While the tool is simple (one optional parameter, no nested objects), the description is too vague to be complete. It does not explain what 'device/system info' includes, how the 'profile' parameter affects the result, or what the return format is, especially given the absence of an output 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?

The schema has one optional parameter 'profile' with 0% description coverage, and the description does not mention it at all. The description fails to compensate for the low coverage, leaving the meaning of 'profile' entirely to the schema's minimal string/null type.

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 the specific verb 'Return' and identifies the resource as 'device / system info', making the core purpose clear. However, it does not distinguish this from sibling tools like healthcheck, logs, or appliance_status, which also return information.

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 offers no guidance on when to use this tool versus alternatives. The only hint is 'read-only', which implies safe usage, but there is no explicit context, exclusions, or mention of sibling tools.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: the return payload includes stored images, selected image, and attach state, and explains the meaning of host_visible_as. This helps the agent understand the tool's output without an 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?

The description is front-loaded with the primary purpose, followed by actionable guidance, return details, and a pointer to further documentation. It is somewhat noisy with issue reference numbers (#127, #78), but overall each sentence contributes useful 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?

For a simple read-only list tool, the description covers purpose, usage, and key return fields. However, it omits any explanation of the 'profile' parameter and does not fully describe the output structure beyond a few fields. The missing parameter documentation creates a notable gap in completeness.

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

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

The schema has one optional parameter 'profile' with no description (0% schema coverage), and the description does not mention any parameter. The agent is left without any guidance on what 'profile' refers to or how to use it, so the description fails to compensate for the schema gap.

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

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

The description clearly states the tool's function with a specific verb ('Inventory') and resource ('KVM's virtual-media (MSD) storage'), and explicitly notes it is read-only. This distinguishes it from sibling tools like mount_iso and eject, which perform mutations.

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

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

The description gives explicit guidance on when to use the tool ('Check this BEFORE asking the operator to download or upload an ISO') and explains how to interpret host_visible_as to pick the correct boot entry. It lacks explicit exclusions or alternatives, but the context is clear and actionable.

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 read-only, idempotent, and non-destructive. The description adds behavior beyond that: `seek` semantics, the deliberate lack of tail-follow, and the diagnostic context. This goes beyond the annotation baseline, though it doesn't discuss return format or error behavior.

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

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

The description is front-loaded with the core purpose and then adds exactly the information an agent needs: seek meaning, use-case context, and the tail-follow limitation. Every sentence earns its place, and it's concise without being terse.

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 log tool, the description covers the core function, usage context, and a key parameter. The unexplained `profile` parameter and lack of output schema leave some gaps, but the overall context is sufficient for selecting and invoking the tool in most scenarios.

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 `seek` parameter is explained as 'seconds of lookback (0 = the whole buffer),' which adds meaning beyond the bare schema. However, `profile` is entirely unexplained and schema description coverage is 0%, leaving half the parameters semantically opaque.

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 action and resource: 'Return the device/host event log as text (read-only).' It clearly distinguishes from screenshot-based tools by noting the log 'names a fault...that a screenshot cannot,' making its niche 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?

Explicitly states when to use it: 'This is the go-to diagnostic when video/streamer/encoder or power behaviour looks wrong.' It also gives an alternative comparison (screenshot) and warns that tail-follow is intentionally omitted due to transport constraints, setting clear expectations.

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 annotations, the description discloses important behavioral traits: it is a gated action, reversible, requires KVM_PILOT_MCP_ALLOW_MEDIA plus per-invocation approval, and invalidates planned mouse clicks due to frame generation bump. This goes well beyond the annotations' basic flags.

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

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

The description is front-loaded with the core purpose, then adds parameter detail and caveats efficiently. It uses concise formatting with backticks for variables and line breaks to separate key ideas, with no unnecessary words.

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

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

Given the tool has 5 parameters, no output schema, and moderate complexity, the description covers the main operational aspects (source types, usb mode, permissions, side effect on frame generation). It omits explanations for three auxiliary parameters, but the core usage is well covered.

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

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

The schema has 0% description coverage, so the description must compensate. It explains 'source' (local path or URL) and 'usb' (USB flash drive vs CD-ROM), but does not clarify 'name', 'confirm', or 'profile'. This partial compensation is useful but incomplete.

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 ('Mount') and resource ('ISO as virtual media on the host'), clearly distinguishing it from sibling tools like 'eject' or 'list_virtual_media'. It also notes the tool is reversible, further clarifying its purpose.

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

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

Provides clear context on when to use the tool: it is gated, requires specific environment variable and approval, and has a side effect on frame generation. It does not explicitly name alternative tools for when not to use it, but the context is sufficient for most use 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?

Beyond the destructiveHint annotation, the description discloses critical behaviors: click refs are enforced with refusal conditions (host reboot, media swap, age >60s, foreign ref), move-only bypasses the ref requirement, coord_space affects coordinate interpretation across resolution changes, and the tool is gated by a runtime flag plus per-invocation approval. This is substantive transparency about side effects and preconditions.

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

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

The description is front-loaded with the core purpose, then organized into precise technical constraints with no wasted words. It is dense but readable; each statement adds value. Slightly long, but acceptable given the safety-critical details.

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 mutating HID tool with no output schema, the description covers what an agent needs to know: destructive classification, ref staleness rules, coordinate space semantics, move-only behavior, and gating conditions. The only minor omission is the meaning of 'confirm' and 'profile', but the overall context is robust for correct invocation.

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

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

With 0% schema description coverage, the description compensates by clarifying key parameters: coord_space values and default, observed_frame_ref requirements for clicks, and button omission meaning move-only. However, 'confirm' and 'profile' are not semantically explained, so the agent still has to guess their effects — leaving a meaningful gap.

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

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

The description opens with a clear, specific verb+resource statement: 'Move the mouse (and optionally click) on the host.' It immediately distinguishes this from sibling input tools (press_key, type_text, send_shortcut) by the target device and action, and mentions the DESTRUCTIVE HID input nature, giving the agent a strong cue for when to select this 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 explains when a click requires an observed_frame_ref and when move-only is permissible, and notes the tool is gated by KVM_PILOT_MCP_ALLOW_HID and approval. This is clear usage context, though it does not explicitly name alternative tools or state 'use this instead of X' — the context alone is sufficient to differentiate.

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

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

Annotations already mark this as destructive and non-idempotent. The description goes far beyond that by disclosing approval gating, per-invocation confirmation, the honest effect report with verified true/false/null semantics, and invalidation of snapshot frame refs. This is rich, non-redundant behavioral context.

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

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

Concise and well-structured: opens with a one-line purpose, then adds critical caveats (destructive, gating) and behavioral details. Every sentence carries distinct value with no repetition or filler. Dense but organized.

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

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

Given the tool's complexity (destructive, approval-gated, side-effectful), the description covers the essential operational context: how approval works, what the result indicates, and side effects on snapshots. It does not fully describe the return format or the exact semantics of off-hard vs reset, but the enumerated action values and partial result coverage make it largely complete for an agent.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain the confirm parameter meaningfully (used for approval under standing policy). The action enum values are self-explanatory, but the profile parameter is left undocumented. The description partially compensates but not fully.

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: "Change host power state." This clearly differentiates from sibling tools like power_state (read-only state inspection) and wake (power-on via network). The DESTRUCTIVE warning further reinforces the tool's intent.

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

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

The description clearly conveys that this tool is for changing power state, but it does not explicitly mention when to use it over alternatives or provide exclusions. Usage context is implied (change vs. read), but no direct comparison to power_state or other siblings is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's 'read-only' is redundant. It adds the conditional 'ATX detail where the driver has it', but this is vague and does not explain what the detail contains or how the profile parameter affects behavior.

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

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

The description is a single sentence with 19 words, front-loaded with the main action. However, 'read-only' at the end is redundant given the annotations, making it slightly less earned than a fully optimized concise 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 simple read tool, the description gives the core behavior but omits the meaning of the 'profile' parameter and any description of the return format, especially since there is no output schema. The ATX detail is ambiguous, leaving the agent uncertain about what to expect.

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

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

There is one parameter, 'profile', with no schema description (0% coverage). The description does not mention the parameter at all, leaving its meaning and effect completely undocumented. This fails to compensate for the schema's lack of detail.

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

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

The description clearly states the tool returns the host's power state, using the verb 'Return' to indicate a query operation. It also mentions ATX detail, distinguishing it from control tools like 'power' or 'wake'. The read-only qualifier reinforces its query-only purpose.

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

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

The read-only parenthetical implies it is for checking state rather than changing it, but the description does not explicitly say when to use this tool versus alternatives like 'power' or 'wake'. It lacks direct exclusionary guidance or named sibling alternatives.

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

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

Annotations already declare destructiveHint=true, and the description reinforces 'DESTRUCTIVE'. More valuably, it discloses the HID gating and approval requirement, which is not present in annotations. It also clarifies the expected key format (kvmd). No contradiction with annotations.

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

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

The description is two concise sentences, front-loaded with the verb and object. It includes a clear warning (DESTRUCTIVE) and a reference to gating, with no unnecessary words or repetition.

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

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

For a tool with 3 parameters and no output schema, the description covers the key format and the operational gating, but omits the roles of `confirm` and `profile`. The overall picture is adequate for a safe invocation, but understanding all parameters requires 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 0%, so the description must compensate. It explains the `key` parameter with syntax examples and the kvmd code concept, but leaves `confirm` and `profile` undocumented. Since `key` is the primary required parameter, partial compensation is achieved, but gaps remain.

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

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

The description clearly states the action ('Press a single key') and specifies the resource (a kvmd key code) with concrete examples (Enter, Escape, F2). This distinguishes it from sibling tools like type_text and send_shortcut, which handle text strings or shortcuts.

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

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

The description implies usage for pressing single keys and provides gating conditions (KVM_PILOT_MCP_ALLOW_HID + approval). However, it does not explicitly compare with alternatives or state when not to use this tool, leaving the context for selection largely 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 mark destructiveHint=true, and the description reinforces this with 'DESTRUCTIVE.' It adds valuable context by explaining that power chords are classified separately and require a different environment variable, ensuring a reboot cannot slip through the HID gate. This goes beyond the structured annotation data.

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

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

The description is two short paragraphs, front-loaded with the action and example, then adds gating context. Every sentence carries meaningful information, with no filler or redundancy.

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

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

For a destructive tool, the description covers the essential syntax and permission gating, but leaves confirm and profile semantics unexplained. Since there is no output schema, return behavior is not described, which is acceptable for this tool type. The gaps are mainly parameter-related, not overall completeness.

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

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

Schema description coverage is 0%, so the description must explain parameters. It explains 'keys' with examples of valid key chords, but entirely omits 'confirm' and 'profile'. These parameters remain undefined in both schema and description, creating ambiguity about confirmation behavior and profile selection.

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

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

The description clearly identifies the action ('send a key chord') and the resource (comma-separated kvmd key codes), with concrete examples. It distinguishes itself from siblings like press_key and ctrl_alt_delete by explaining effect-based gating, making the purpose specific and unambiguous.

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

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

The description provides context on when the tool applies by explaining the effect-based gating (power vs. HID) and required environment variables. It doesn't explicitly name alternatives like type_text or press_key, but the gating clarifies the conditions for use and exclusion, which is sufficient for most agents.

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 (readOnly, idempotent, non-destructive), the description reveals critical behavioral details: it works offline with no device I/O, answers even when the device is down, and its journal/wait state is in-memory and resets on restart. This goes far beyond what annotations provide.

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

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

Though moderately long, every sentence carries unique value: main purpose, usage triggers, content summary, data-reset caveat, and sibling differentiation. It is well structured and front-loaded, 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?

The description comprehensively covers the tool's output components (target, dry-run state, effect gates, approvals, journal, wait_for_state result) and the critical in-memory caveat. The only gap is the unexplained 'profile' parameter, preventing a perfect score.

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

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

Schema coverage is 0% and the description does not mention the 'profile' parameter at all. While the parameter is optional, its meaning is completely unexplained, leaving an agent to guess whether it selects a target, a profile, or something else.

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+resource: 'Report this server's current operating posture.' It clearly distinguishes itself from siblings by explicitly pairing with 'healthcheck' for device health and 'doctrine' for playbooks, making its niche obvious.

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

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

The description gives explicit guidance on when to call: 'after a context compaction, when resuming a long flow, or before planning act calls.' It also names complementary tools (healthcheck, doctrine), effectively steering an agent toward the right choice without 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 indicate destructiveHint and non-readonly, but the description adds significant context: approval gating, typed outcome on denial, 'none' clearing behavior, persistence via 'once=false', legacy BIOS via 'uefi=false', and fast-fail on unadvertised targets. This goes well beyond the structured hints.

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

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

The description is compact and front-loaded with purpose, then packs relevant behavioral details into a short paragraph. No wasted words.

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

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

Given the tool's complexity (5 params, mutation, approval flow) and lack of output schema, the description covers the key behaviors, prerequisites, and failure modes. Gaps remain around the 'confirm' and 'profile' parameters and exact return shape, but the overall guidance is strong.

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 descriptions are absent (0% coverage), so the description carries the burden. It explains the semantics of 'none', 'once', and 'uefi' in plain language, but leaves 'confirm' and 'profile' unexplained. Partial compensation only.

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

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

The description opens with a specific verb and resource: 'Set the next-boot (or persistent) boot device via BootSourceOverride.' It clearly distinguishes itself from sibling tools like boot_options by emphasizing mutability ('CONFIG MUTATION') and mentions the mechanism.

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 actionable guidance by telling users to 'call boot_options first to see allowable' targets, establishing a clear precondition. However, it does not explicitly contrast when to use this tool versus alternative mutation tools or describe exclusions, so it's slightly below the top tier.

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 (readOnly, idempotent, non-destructive), the description reveals critical behavior: the return format, frame_ref semantics, live signal state, and the warning that byte-identical frames may be stale/cached and should not be trusted. It also references issue numbers for context, adding depth.

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

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

The description is moderately long but each sentence contributes: return format, frame_ref usage, signal state, and staleness warning. Minor clutter from issue numbers (#143, #141) slightly distracts but overall is well-organized.

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

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

With no output schema, the description compensates by explaining the return tuple and key edge cases. The only notable gap is the undocumented 'profile' parameter, which prevents full completeness for a tool with this richness.

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

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

The schema has one optional 'profile' parameter with no schema description and 0% coverage. The tool description never mentions this parameter, leaving its purpose and possible values completely undocumented. The agent has to guess what 'profile' means.

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 'Capture the current KVM screen (read-only)', which is a clear verb+resource statement. It distinguishes this from siblings by explicitly framing it as a screen capture returning image and JSON, and by contrasting with the 'mouse' tool's use of the returned frame_ref.

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 guidance on using the returned frame_ref with the mouse tool and instructs to check 'signal' and 'logs' instead when unchanged_since_last_snapshot is true. While it doesn't explicitly state 'use this instead of classify_screen', the alternative actions are clear for the described scenario.

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 read-only, idempotent, non-destructive, but the description adds important behavioral context: it is an 'active network scan' that is 'noisy', requires user confirmation and authorization, and is 'RISKY — opt-in'. It also discloses the mandatory confirm=true requirement, which goes beyond annotation metadata.

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

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

The description is compact and front-loaded: the first sentence states the core function, followed by a single warning paragraph. Every sentence contributes either to purpose, risk, or usage constraints. No redundancy.

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

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

The tool is well-contextualized: purpose, risk, authorization, and confirmation are all covered. However, with no output schema, the description does not specify what the tool returns (e.g., list of hosts, IPs). Despite that, the name 'discover' and the goal 'find a target' imply the result, so it is nearly complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains confirm's role ('confirm=true is required'), and cidr is implicitly defined by 'Scan a CIDR'. However, the port parameter is not addressed beyond its default, leaving potential ambiguity about whether it is the SSH port or a custom scan port. Some meaning is added but not enough for a 0% coverage schema.

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

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

The description opens with a specific verb+resource: 'Scan a CIDR for hosts with an open SSH port.' This clearly distinguishes the tool from siblings like ssh_reachable (checking a single host) or ssh_exec (running commands). It further narrows the purpose with 'Use it ONLY to help find a target whose address the user doesn't know'.

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

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

The description gives strong when-to-use guidance ('help find a target whose address the user doesn't know') and when-not-to-use ('never by default', only on authorized networks). It stops short of naming alternative tools explicitly, but the exclusionary conditions make the intended usage 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?

Beyond the annotations, the description reveals the SSH effect gate and per-invocation approval requirement, as well as the typed same-path denials (#234), which are not present in the annotations. It also documents the 'host' override behavior. It does not elaborate on the consequences of destructive commands, but the 'DESTRUCTIVE' label and destructiveHint annotation cover this.

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

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

The description is three sentences, front-loaded with the primary purpose, followed by the gating detail and parameter clarification. Every sentence adds value, and there is no redundancy.

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

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

Given the tool's modest complexity (4 parameters, no output schema), the description covers the core purpose, the safety mechanism, and the host override. It omits explicit return-value behavior and the role of 'confirm,' but these are partially inferable from the destructive context and typical SSH behavior.

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

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

With 0% schema description coverage, the description compensates by explaining the 'host' parameter via the override statement and relates 'profile' to the profile/env ssh_host. However, it does not explain the 'confirm' parameter's purpose or the format of the 'command' value, leaving some semantics implicit.

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

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

The description begins with a clear verb-resource combination: 'Run a command on the managed host's OS over SSH,' which immediately distinguishes it from sibling tools like ssh_reachable and ssh_discover. The additional 'DESTRUCTIVE / in-band' qualifier further clarifies its operational scope.

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

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

The description implies when to use this tool (whenever an OS command must be executed) and includes a when-not signal: 'never the HID gate', indicating it should not be used for HID interactions. It does not explicitly name alternatives like ssh_reachable or power_state, so it falls 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 read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it targets the host behind the KVM (a different machine), and the host parameter overrides the profile/env ssh_host at runtime. This goes beyond the annotations and clarifies the operational scope. It doesn't mention timeout or failure return format, but for a reachability check the disclosed traits are sufficient.

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

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

The description is three short paragraphs, front-loaded with a direct question that captures the tool's essence. Every sentence provides distinct value: the question, the target machine clarification, and the host override explanation. There is no filler or redundant phrasing.

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 reachability check with no output schema and only two optional parameters, the description gives enough context to invoke correctly. It explains the target machine, the difference from the KVM appliance, and the host override use case. The tool's complexity is low, and the description covers operational aspects without missing critical 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?

The description explains the 'host' parameter clearly with an example (install-time DHCP address), adding meaning beyond the schema's nullable default. It indirectly implies the 'profile' parameter selects the profile/env ssh_host, but doesn't fully explain its behavior or default resolution. With 0% schema description coverage, the description compensates for one parameter but leaves the other under-specified.

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

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

The description clearly states the tool checks SSH reachability of the managed host's OS as a yes/no question. It distinguishes itself from siblings like ssh_exec and ssh_discover by focusing purely on reachability detection. The phrase 'Is the managed host's OS reachable over SSH?' is a specific verb+resource pairing.

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 provides clear context: use this to prefer remote recovery before physical intervention, and it targets the host behind the KVM rather than the appliance. However, it doesn't explicitly name alternative tools when not to use it, relying on implicit distinction from siblings. Still, the usage context is actionable.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral detail beyond those: it aggregates from a test-run ledger, joins derived maturity levels, defines the 'fail' status for all live attempts failed, and clarifies that absence of a row means unverified. This is rich, non-redundant 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?

The description is information-dense with no wasted words. It leads with the core purpose, then explains provenance, adds necessary caveats, defines special status values, and notes filter behavior. Every sentence earns its place and the structure is logical.

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 essential return semantics: status 'fail', never_exercised list, derived maturity level, and the meaning of absent rows. It also gives source context and safety caveats. It is slightly incomplete in not describing the exact output shape or how filters combine, but it is sufficient for an agent to understand and use the tool correctly.

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

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

The input schema has 0% description coverage for its three optional parameters, so the description must compensate. It does add meaningful filter semantics: filters are case-insensitive and product matches as a substring. However, it does not clarify how vendor and firmware_version are matched (e.g., exact vs substring) or how multiple filters combine, leaving a partial gap.

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

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

The description states exactly what the tool does: reports what has been exercised on real hardware per device+firmware+capability. It also distinguishes itself from sibling tools by explicitly noting it is read-only, offline, and makes no device call, unlike tools such as healthcheck or ssh_exec.

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 provides clear context for when to use the tool: checking hardware-compatibility evidence before relying on a capability. It gives cautionary guidance (never_exercised means mock-only/alpha, confirm destructive steps) but does not explicitly name alternative tools or state when not to use it, 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 destructiveHint=true, and the description repeats 'DESTRUCTIVE' without adding new safety info. However, it discloses important behavioral context beyond annotations: the need to enable HID via KVM_PILOT_MCP_ALLOW_HID and the per-invocation approval mechanism (human or confirm=true). This adds meaningful transparency about invocation requirements and side effects (typing on the console is disruptive).

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

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

The description is efficient: the first sentence states the purpose, 'DESTRUCTIVE' is a clear warning, and the second sentence details prerequisites and approval flow. No wasted words; each sentence serves a distinct role. The structure with a newline separating action from requirements aids readability.

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

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

The description covers the tool's purpose, destructive nature, and key prerequisites. However, it does not explain the 'profile' parameter, and since there is no output schema, it also omits what the caller should expect in response (e.g., success/failure or confirmation). Given the tool's complexity (HID typing, approvals), a bit more detail about return behavior or error cases would improve completeness.

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 description gives some meaning to 'text' by embedding it in the action, and explains 'confirm' as an explicit approval path ('explicit confirm=true'). However, the 'profile' parameter is not mentioned at all, and with 0% schema coverage, the description should compensate more fully. It partially adds value but leaves a significant parameter unexplained.

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

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

The description clearly states the verb ('Type') and resource ('text on the managed host's console over the HID keyboard'). It is specific about the delivery mechanism, distinguishing it from siblings like press_key or send_shortcut. The 'DESTRUCTIVE' label is a warning, not the purpose, so the core action is unambiguous.

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

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

The description implies usage for typing arbitrary text on a console, which distinguishes it from key-specific tools like press_key. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. The prerequisites (HID enabled, per-invocation approval) provide context for when it can be invoked, but not selection guidance relative to siblings.

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

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

Beyond the readOnlyHint and destructiveHint annotations, it discloses that the tool holds the driver open, never hangs or raises on timeout, fails fast on unknown tokens, and has credential-dependent behavior. It also clarifies the return contract (success vs. `reached=false`), which is not visible in annotations. No contradiction with annotations is present.

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

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

The description is dense and front-loaded with purpose, then layers mechanics, parameter semantics, edge cases, and credential constraints. It is longer than the two-sentence ideal but every sentence adds information; no fluff or repetition beyond a minor restatement of read-only near the end.

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

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

With no output schema, the description fully covers the return contract, failure modes, timeout behavior, credentials scenario, and even points to a doctrine topic for details. It is complete for a tool with this complexity and provides all necessary context for an agent to invoke it correctly.

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

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

The description adds crucial meaning to `phase` (a classify_screen token, unknown tokens fail with the valid list) and `timeout` (seconds, capped at 300, chain for longer). It does not explain the optional `hint` and `profile` parameters, but coverage of the required parameter and the key timeout parameter is strong enough to compensate.

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: "Wait (bounded) until the screen reaches a boot/run phase (read-only)." It clearly distinguishes from siblings like classify_screen by explaining it polls until a target state is observed rather than capturing the current state. It also notes it is the server-side twin of CLI `watch`, further anchoring its unique purpose.

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

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

The description explicitly frames when to use this tool: for waiting on a phase, with `timeout` capped at 300 seconds and guidance to chain calls for longer waits. It also explains the alternative path when server-side vision credentials are missing, pointing to `classify_screen` polling. The `frame_ref` handoff to `mouse` is an actionable usage detail.

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=true, not read-only), the description discloses gating via 'power effect gate + per-invocation approval,' defaulting behavior for mac and broadcast, and the fact that no KVM driver is involved. It does not contradict annotations and adds meaningful behavioral context about how the action is performed.

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

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

The description is reasonably concise and front-loaded, with the core purpose in the first sentence. Some parts are cryptic ('POWER (soft)', 'typed same-path denials, #234'), but the main behavior, gating, and defaults are covered without excessive verbosity.

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

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

The description covers purpose, mechanism, gating, and default values, but it lacks guidance on the count and confirm parameters, expected results, and explicit comparison to sibling power tools. Given no output schema and moderate parameter complexity, the description is adequate but has clear gaps.

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

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

With 0% schema description coverage, the description is the only source of parameter meaning. It explains mac and broadcast defaults, and references profile indirectly, but count and confirm are left undefined. This is inadequate for a five-parameter tool.

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

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

The description uses a specific verb and resource: 'Send a Wake-on-LAN magic packet to power the host on.' It clearly distinguishes this from sibling tools by noting it is 'POWER (soft)' and that 'No KVM driver is contacted,' clarifying it is a WoL-based power-on action rather than a direct power or KVM operation.

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

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

The description gives useful context for when this tool is appropriate: it is a WoL broadcast from the server's own host onto the target's L2 segment, and it mentions the power effect gate and per-invocation approval. It does not explicitly name alternative tools or state exclusions, but the context clearly distinguishes it from KVM-driven power actions.

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