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

No annotations are provided, so the description must disclose behavioral traits. It states that the tool saves a PNG and returns a path, optionally returning base64. This adequately describes the primary behavior. However, it does not mention side effects (e.g., whether it changes VM state) or any prerequisites (like VM must be running). Given the simplicity of the operation and the clear output, this is sufficient but not rich. A cautious agent might want to know if this is read-only, but the description implies a non-destructive capture.

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, concise sentence that states the action, the output type, and the optional mode (base64). It is front-loaded with the main action, and every word earns its place. 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 simple tool with 2 parameters (1 required, 1 optional) and no output schema, the description is fairly complete. It specifies the output format (PNG path, optionally base64) and the parameter semantics. It could have benefited from mentioning whether the VM needs to be running or if it captures the current console state, but these are minor gaps given the tool's simplicity. The agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both 'vm' (VM name) and 'base64' (return as base64). The description's mention of 'base64 on request' adds meaning to the 'base64' parameter, confirming its purpose)Skip. The 'vm' parameter is standard. Since the schema does the heavy lifting, this is a solid baseline 3.

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

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

The description uses a specific verb 'Save' with a clear resource ('a PNG of the VM console'), and states the output ('return its path (base64 on request)'). It clearly distinguishes itself from siblings like 'snap_take' or 'vm_state' by focusing on the console screenshot. This is unambiguous and actionable.

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 does not explicitly state when to use this tool versus alternatives, but the purpose is obvious enough that an agent can infer it is for capturing a console image. No exclusions or alternative tools are mentioned, but given the tool's specificity, this is adequate. However, it could have noted that this is not a VM snapshot but a console capture, which would help differentiate from 'snap_take'.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the copy action and does not mention whether an existing local file is overwritten, whether directories are created, or what happens on failure. This is a meaningful gap for a mutating file operation.

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

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

The description is a single clear sentence with no filler. The essential direction and action are front-loaded, and every word contributes to understanding the tool's purpose.

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 purpose and all three required parameters are fully specified, which is adequate for a basic copy invocation. However, with no annotations and no output schema, the lack of behavioral details such as overwrite semantics and error handling leaves a small but real 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 100%, so the schema already defines vm, local, and remote with adequate descriptions. The tool description restates the guest/host mapping that is already present in the parameter descriptions and adds no new parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb, 'Copy', and clearly identifies both source ('guest') and destination ('host'). This directionality distinguishes it from the sibling file_push, which is the reverse operation, so an agent can immediately understand what the tool does.

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 'from the guest to the host' phrasing provides clear operational context and implicitly separates this tool from file_push. However, it does not explicitly state when not to use it or mention alternatives, so it stops just short of full 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It explicitly states the verification step ('verify it' and the 'verify' parameter description 'Compare SHA-256 after the copy'), which is a positive behavioral detail. However, it doesn't mention potential side effects like overwriting existing files, permission requirements, or what happens on failure.

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

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

The description is one sentence that efficiently communicates the core function and the verification aspect. No filler, front-loaded with the verb and resource, and immediately understandable.

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 copy tool with 4 parameters and full schema coverage, the description is mostly sufficient. It explains the operation and the verify flag, but lacks guidance on edge cases (e.g., glob expansion, directory behavior, error handling) and any prerequisite conditions (e.g., VM must be powered on) that an agent would need to know for successful invocation. The sibling tools list suggests a VM management context, but the description doesn't leverage that to add operational context.

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

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

Schema description coverage is 100%, so the schema already documents each parameter (vm, local, remote, verify) adequately. The description adds slight nuance ('remote' as directory when local is several files) and the verify parameter's purpose is echoed in the description, but it doesn't add significant detail beyond the schema.

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

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

The description states a clear action ('Copy') and the resources involved ('file, directory or glob from the host into the guest') with a verification step. It distinguishes itself from the sibling 'file_pull' which copies in the opposite direction, though it doesn't explicitly name that sibling.

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

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

The description implies usage context: transferring files from host to guest. It does not explicitly state when to prefer this over file_pull or other tools, but the directionality makes it obvious. There's no mention of prerequisites (e.g., guest running) or constraints like needing the VM to be active.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does state the default blocking behavior ('by default wait until the target connects'), which is useful. However, it doesn't disclose what happens on timeout, whether the tool returns immediately after starting kd.exe, what side effects occur (e.g., does it modify VM state?), or whether it requires the VM to be running. The description is honest but thin.

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 that front-loads the core action and default behavior. It's efficient and doesn't waste words. It could add a bit more context, but for its length it's well-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?

For a tool with 6 parameters and no output schema, the description is somewhat thin. It doesn't explain what happens after the target connects, what the return value looks like, or what prerequisites exist (e.g., VM must be running, kd_setup_host/guest must have been run). The sibling tools suggest a workflow (kd_setup_host, kd_setup_guest, kd_attach, kd_break, kd_go), but the description doesn't situate itself in that workflow. However, the schema covers parameters well, and the core behavior is stated.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds minimal value beyond the schema—it doesn't explain how parameters like key, port, or symbol_path override vms.yaml settings, or how timeout interacts with wait_for_target. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb ('Start kd.exe') and resource ('for the VM'), and mentions the default wait behavior. It's clear enough to distinguish from siblings like kd_break or kd_go, though it doesn't explicitly name an alternative or elaborate on what 'attach' means in this context.

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: call this to start kd.exe and wait for the target. It doesn't explicitly state when to use this vs alternatives like kd_setup_host or kd_setup_guest, nor does it mention prerequisites like the VM needing to be running. The wait_for_target parameter is described in the schema, but the description doesn't add context about when you'd want to disable 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?

No annotations are provided, so the description carries the full burden. It discloses the core behavior (halting the target and waiting for the prompt), but omits failure modes such as behavior when the target is not running, whether the break is idempotent if already at the prompt, what happens on timeout expiry, or whether detachment of the break is automatic.

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

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

A single front-loaded sentence that states the action and the awaited outcome with zero filler. Every word earns its place for a tool of this simplicity.

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

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

For a two-parameter debugger-break command with full schema coverage and no output schema, the description is reasonably complete: it states the action and the expected end state. Missing details like timeout failure behavior and prerequisite state (already attached vs. not) are minor given the tool's simplicity.

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

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

Schema description coverage is 100%: 'vm' and 'timeout' are both described in the schema. The description adds little parameter nuance beyond the schema, except that 'wait for the kd> prompt' reinforces what the timeout parameter measures. This meets the baseline for full schema coverage but adds no extra semantic value.

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

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

States a specific verb ('Break into') with a clear resource ('the running target') and the expected outcome (the kd> prompt). The action is clear and the intent is distinguishable from siblings like kd_go (resume), kd_attach, and kd_detach, though it doesn't name which sibling it differs from.

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

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

No guidance on when to use this tool versus alternatives. With siblings kd_go (resume execution), kd_attach, and kd_state, an agent would benefit from knowing that kd_break halts a running target and should later be paired with kd_go to resume. Nothing about prerequisites (e.g., must already be attached) or exclusions 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?

With no annotations provided, the description carries the behavioral burden. It does disclose the normal sequence—resume the target if needed, then stop kd.exe—and the force parameter documents the kill-without-resume path. However, it does not state whether force leaves the target suspended, what happens if no debugger is attached, or any permission or side-effect implications.

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 no filler. 'Resume the target if needed' and 'stop kd.exe' are both load-bearing, and the description is appropriately sized for a simple two-parameter tool.

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

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

For a simple two-parameter tool with no output schema, the inputs are fully covered by the schema and the description explains the primary action and normal behavior. It is not fully complete because it lacks explicit when-to-use context and leaves some force-path consequences to the parameter description rather than the main description, but it is adequate for correct invocation in most cases.

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

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

Schema description coverage is 100%, so the vm and force parameters are already fully documented in the input schema. The tool description adds no additional parameter-level meaning beyond implying the conditional behavior of the non-force path, which is also covered by the schema.

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

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

The description names a concrete action—'stop kd.exe'—and adds the key conditional 'Resume the target if needed,' which clearly identifies this as the detach/cleanup operation. It distinguishes itself from sibling tools like kd_attach, kd_break, and kd_go without relying on the tool name alone.

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

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

The purpose is implied by 'stop kd.exe' and the sibling context, but the description does not explicitly say when to use this tool versus alternatives like kd_go or kd_break. There is no guidance on when the force option is appropriate or how this relates to the rest of the kd_* workflow.

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

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

With no annotations, the description bears the full burden of behavioral disclosurecars. It states that output is returned, but it does not disclose that debugger commands can mutate kernel/VM state, that commands may depend on an attached debugger session, or that timeout/size caps affect behavior. This is a meaningful gap for a generic command-execution tool.

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

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

The description is a single front-loaded sentence with no filler. It states the action, the target environment, and the expected result immediately, earning every word.

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

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

The schema is rich and covers all parameters, and the description supplies the essential execution context. However, with no annotations and no output schema, the definition is incomplete for safe invocation: it omits side-effect warnings, prerequisites like an active attach, and any guidance about choosing kd_exec over shell execution. It is minimally viable for basic use but not fully robust.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only the relationship between one or more commands and per-command output, which the schema's cmd/cmds descriptions already convey. No novel parameter-level meaning is added.

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

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

The description names a specific verb ('Run'), a specific resource ('debugger commands at the kd> prompt'), and a clear result ('return each command's output'). It also distinguishes kd_exec from the specialized kd_* siblings by positioning it as the generic command execution entry point.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives such as kd_break, kd_go, or term_exec. The reader must infer that this tool is for arbitrary debugger commands rather than shell commands, and the description never directs the agent toward or away from 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?

No annotations are provided, so the description carries full responsibility. It only says 'Resume', implying a state change, but does not disclose side effects, prerequisites, required VM state, or whether it affects a debug session. No behavioral detail beyond the verb.

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 brief sentence, which is concise. However, it lacks structure and clarity: 'target (g)' is cryptic, and the sentence does not front-load useful information. It is concise but not effective.

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 one parameter and no output schema, the description is grossly incomplete. It does not explain what 'go' does, the expected VM state, or how it relates to other kd_* or vm_* tools. An agent would need to guess the purpose and usage.

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 parameter 'vm' with description 'VM name as registered in vms.yaml', which is clear and self-explanatory. Schema coverage is 100%, so the baseline is 3. The description adds nothing about the parameter beyond the schema, so it earns the baseline score.

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 'Resume the target (g)' states a verb ('Resume') but the resource is vague: 'target (g)' could mean guest, but it's not explicit. It does not distinguish from sibling tools like vm_resume, which likely also resumes a VM. No clear resource or scope is defined, making it ambiguous.

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

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

There is no guidance on when to use this tool vs alternatives. The sibling list includes vm_resume, kd_attach, kd_break, etc., but the description offers no conditions or exclusions. An agent cannot determine whether to call kd_go or vm_resume without additional 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?

No annotations are provided, so the description carries the full burden of explaining behavior. It implies a read-only operation but does not state whether it blocks, what happens if no transcript exists, whether the output is raw text or paginated, or whether it affects the debugging session in any way.

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, tight sentence with no filler. It is appropriately sized for a simple tail operation, though it sacrifices useful structural elements such as an explicit return-value word or usage context.

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

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

For a simple two-parameter read tool, the description plus schema is minimally sufficient to understand invocation. However, with no output schema and no annotations, an agent is left to infer how the bytes are delivered, what encoding or format to expect, and what error conditions may occur.

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

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

Schema coverage is 100%, and both 'vm' and 'bytes' are already described with defaults and constraints. The description adds the useful context that the target is the kd.exe transcript, but it does not materially enrich the meaning of the individual parameters beyond what the schema already provides.

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

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

The phrase 'Last bytes of the kd.exe transcript' clearly identifies the resource being read (the kd.exe transcript) and the operation (retrieving its tail end). It is meaningful and distinct enough from kernel-debugging siblings like kd_state or kd_exec, though it lacks an explicit verb like 'read' or 'return'.

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 no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of whether it requires an attached or active kernel session. The sibling list shows many kd_* tools, but the description does not place kd_log_tail in that workflow.

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

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

With no annotations provided, the description carries the full burden and does a good job: it discloses the mutation ('Enable kernel debugging'), the mechanism ('bcdedit over SSH'), the transport alternatives, and a concrete side effect ('store the KDNET port and key in vms.yaml'). It does not mention prerequisites like SSH reachability or whether a reboot is required, but the core behavioral profile is clear.

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 efficient sentence that front-loads the main verb and resource, then provides mechanism and persistence detail in order of importance. There is no filler or repetition of schema fields.

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 setup tool with no annotations and no output schema, the description covers the main action, mechanism, and persistence, but omits operational prerequisites such as the guest being reachable over SSH, whether the debugger becomes active immediately, or how this interplays with kd_setup_host/kd_attach. It is adequate for basic selection but not fully complete for a safe, correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that key and port are KDNET parameters that get persisted to vms.yaml, which clarifies why the agent should care about them and how they relate to the overall setup flow. It does not add detail about the vm parameter, but the schema already describes it sufficiently.

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

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

The description names a specific action and resource: 'Enable kernel debugging in the guest' via bcdedit over SSH. The 'guest' qualifier distinguishes this from the sibling kd_setup_host, and mentioning 'serial or KDNET per kd_transport' shows the transport modes it handles. This is specific and actionable, not a tautology.

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 the tool is for guest-side kernel debugging setup and references kd_transport as the transport selector, but it does not explicitly say when to choose this over kd_setup_host or when not to use it. No alternative tactic or exclusion condition is given, so the agent must infer the intended context from sibling names.

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

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

With no annotations, the description carries the behavioral burden. It does disclose a real side effect: modifying the vmx by adding a COM port, plus the VM-off prerequisite. However, the net path is vague—'reports the one-time firewall step' could mean it merely prints instructions or that it actually performs a firewall change—and there is no mention of idempotency, permissions, or return 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 one dense sentence that front-loads the main purpose and then compresses the serial and net variants. It is reasonably concise, though the compact split between serial and net creates mild ambiguity about how the mode is selected.

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 one-parameter tool, the description includes the essential purpose, a concrete file modification, the VM-off prerequisite, and an output-like behavior for net. It is incomplete because it does not explain how the serial versus net path is chosen or whether the net step actually modifies the firewall or only reports the command, and there is no output schema or annotation to fill those 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?

The input schema already fully documents the single 'vm' parameter with 'VM name as registered in vms.yaml', so the description contributes no additional parameter-level meaning. With 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly states that this tool prepares the host side of the kd transportched and gives concrete detail for both serial ('adds the named-pipe COM port to the vmx') and net ('reports the one-time firewall step'). It is distinguishable from sibling kd_setup_guest because the host side is explicit, though the mode-dependent behavior could be spelled out more clearly.

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 it: host-side kd transport setup. It also discloses the important prerequisite that the VM must be off for the serial path. However, it does not explicitly name kd_setup_guest as the alternative or state when this tool should not be used, so the guidance is more implied 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not explicitly state that the tool is read-only, whether a debugger session must be attached, or what happens if the VM is not reachable. The listed fields imply a snapshot, but the ambiguity about side effects and prerequisites is a significant gap.

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

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

The description is a short, front-loaded noun phrase with no filler words. It is concise and conveys the main topics immediately, but the verbless structure leaves just enough ambiguity that it falls short of a fully polished summary.

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

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

For a single-required-parameter tool with no output schema, the description identifies the major content areas (state, transport, target info, event, log path) but does not explain the return shape or behavior when conditions change, such as when no debugger is active. It is minimally adequate for a simple read state but leaves the syntaxy details unspecified.

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

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

Schema coverage is 100% because the only parameter, vm, already has the description 'VM name as registered in vms.yaml'. The tool description adds no additional meaning about the parameter, so the baseline score of 3 is appropriate.

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

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

The description lists the information the tool exposes: debugger state, transport, target info, last event, and log path. This clearly signals a query/status tool rather than an action tool, which helps differentiate it from siblings like kd_break or kd_go. It lacks an explicit verb such as 'get' or 'show', so it stops short of the ideal 'specific verb + resource' formulation.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance, and no sibcoproducts are mentioned. The intended use (query debugger info for a VM) is only implied by the tool name and noun-phrase description, so an agent gets no concrete criteria for choosing this over kd_log_tail, sys_state, or other read-oriented 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?

With no annotations, the description carries the full burden. It discloses that the tool blocks and may timeout, but does not mention side effects (e.g., whether it changes debugger state), whether multiple calls are safe, or how the timeout interacts with ongoing sessions. For a blocking operation, more explicit behavioral context is needed.

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

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

One sentence, no filler, and the core action and condition are front-loaded. It is concise and to the point.

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 blocking tool with no output schema and no annotations, the description is thin. It does not state what happens on return (e.g., reason for break), nor does it clarify prerequisites like being attached to a target. A more complete description would explain the return or typical usage flow.

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

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

Schema description coverage is 100%, and both parameters are described in the schema. The description's 'timeout expires' hints at the timeout parameter, but it adds no new meaning beyond what the schema already specifies. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Wait until') and resource ('the running target'), clarifying that it blocks until a debugger event or timeout. It does not explicitly distinguish it from siblings like kd_break or kd_go, but its purpose is clear enough for basic selection.

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 (when you need to block until a break event), but provides no guidance on when to use this vs. alternatives like kd_break, kd_go, or kd_state. There is no mention of prerequisites (e.g., target must be attached) or conditions that would make it inappropriate.

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

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

With no annotations, the description carries the burden of disclosing destructive behavior. It does say 'Delete' and 'Needs confirm=true,' which conveys that this is a destructive action requiring confirmation. However, it doesn't explicitly state irreversibility, that confirm=false means no deletion occurs, or the side effects mentioned in the allow_suspend parameter 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 two short sentences with no filler. It front-loads the core action ('Delete a snapshot') and immediately gives the critical invocation requirement ('Needs confirm=true'). Every part is useful.

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 rich input schema that documents every parameter, the description covers the essential purpose and the destructive confirmation gate. It doesn't mention return values or error behavior, but with no output schema and a clear destructive action, the missing pieces are minor and can be inferred from the schema.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds emphasis on 'confirm=true' and 'optionally its children,' but these map directly onto existing schema parameters and don't provide substantial new semantic 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 states a specific verb and resource: 'Delete a snapshot (and optionally its children).' It clearly distinguishes this from sibling tools like snap_take, snap_revert, and snap_list by naming the deletion action and the optional subtree 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?

There is no guidance on when to use this tool versus alternatives such as snap_take or snap_revert. The mention of 'Needs confirm=true' is a prerequisite for invocation, not a usage rule that helps an agent choose between sibling snapshot 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?

There are no annotations, so the description carries the burden of behavioral disclosure. It communicates the read-oriented nature and the content returned (tree, current snapshot, stored metadata), but does not mention failure modes, output formatting, or any side effects. This is adequate but not highly detailed.

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 concise sentence that front-loads the resource and result components. It is compact and free of filler, though the phrasing 'Snapshot tree of a VM' is slightly awkward as an imperative.

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 one-parameter list tool, the description is mostly complete: it names the target VM and the expected output contents. However, there is no output schema and no explanation of return format or error conditions, leaving some gaps in what an agent should 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?

Schema description coverage is 100%, and the vm parameter is already well-described as 'VM name as registered in vms.yaml'. The tool description adds no additional parameter semantics beyond confirming the operation is for a single VM, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as returning the snapshot tree of a VM plus the current snapshot and stored metadata. It is distinguishable from sibling snapshot tools like snap_take, snap_revert, and snap_delete, though it lacks an explicit verb such as 'list'.

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 the tool is for viewing snapshot state for a specific VM, but it does not explicitly state when to prefer this tool over alternatives or mention any exclusions. Usage context is inferable from the tool name and sibling set, not directly stated.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It does reveal the multi-step side-effect sequence: detach kd, revert, start, reattach kd, reopen terminals. However, it omits the destructive nature of reverting the VM state and the conditional behavior when start, reattach_kd, or reopen_term are set to false.

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 compact sentence with a colon-separated workflow. It is front-loaded with the core action and contains no filler or redundant 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 6-parameter mutation tool with no output schema and no annotations, the workflow summary is helpful but incomplete. It lacks guidance on failure/timeout behavior, what the return signals are, and how setting optional flags like start=false changes the workflow.

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

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

Schema description coverage is 100%, so the input schema already explains each parameter. The description adds procedural context that loosely maps to parameters like reattach_kd and reopen_term, but it does not provide additional parameter-level detail beyond the schema.

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

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

The description clearly states a specific verb and resource ('Revert to a snapshot') and enumerates the concrete steps involved. This distinguishes it from snapshot-related siblings such as snap_take and snap_delete.

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 purpose 'Revert to a snapshot' implies when to use the tool, but there is no explicit guidance about when not to use it or how it compares to alternatives like snap_delete or snap_list. The step list is procedural rather than decision-guiding.

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

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

With no annotations provided, the description carries the full burden. It discloses that snapshots include memory while running, which is a key behavior. The allow_suspend parameter description reveals a significant behavior: it can suspend the VM, briefly pause the guest, drop terminal sessions, and reattach the debugger. This is excellent behavioral transparency for a mutation tool, going beyond just saying 'snapshot.'

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

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

The description is concise, a single sentence. It is front-loaded with the main purpose. However, the sentence is somewhat terse and does not elaborate on the 'kd state' recording mentioned in the description; it says 'record description and kd state' but doesn't explain what kd state is or how it's recordedikuha, which could be confusing. It earns a 3 for being appropriately brief but not fully clarifying the tool's full scope.

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

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

Given the tool's complexity (4 params, a special allow_suspend behavior, and a described side effect of reattaching the debugger), the description and schema together cover the essentials. There is no output schema, so the description doesn't need to explain return values. The allow_suspend behavior is fully explained in the schema. What's missing is a mention of the kd state recording specifics, but the tool is still sufficiently documented for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds slight context: 'memory included while running' relates to the purpose of including memory, and the allow_suspend parameter is described in detail within the schema itself. However, the description above the schema does not add much beyond what the schema already explains, so a baseline 3 is appropriate.

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

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

The description states a specific action: 'Take a snapshot' of a VM, and includes a key nuance: 'memory included while running.' This clearly distinguishes it from snapshot operations that might not include memory, and the context of sibling tools (snap_list, snap_revert, snap_delete) makes the purpose clear. However, it does not explicitly differentiate from a hypothetical 'snap_create' sibling, but given the listed siblings, it is sufficiently distinct.

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 it: when you need a snapshot with memory while the VM is running. However, it does not explicitly state when not to use it or mention alternatives like snap_revert for reverting. The parameter 'allow_suspend' hints at a special case (encrypted VM refusal), providing some context, but there is no explicit guidance on choosing this tool over others.

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

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

With no annotations provided, the description carries the full burden. It discloses the tool's scope (checking binaries, config, backend, VMs) and implies a read-only health check, but it doesn't state whether it has side effects, how long it might take, or what the output format is. The description is honest but not deeply transparent about behavior beyond the listed checks.

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

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

Two sentences, no filler. The first sentence lists the full scope of checks, and the second delivers a clear directive. Every word earns its place.

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

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

For a zero-argument health-check tool, the description is nearly complete: it tells the agent what will be checked and when to run it. It doesn't describe the return format or how to interpret results, but with no output schema and no annotations, a brief note on what the output contains would push it to 5. Still, the core context for invoking it correctly is present.

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

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

The tool has zero parameters and the schema already states 'Tool without arguments.' The description adds no parameter-specific meaning because there are none to document. Baseline 4 for zero params is appropriate.

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

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

The description uses a specific verb ('Check') and names the exact resources: binaries, config, backend capabilities, and every VM's power, guest SSH port, and debugger transport on the host. It clearly distinguishes itself from sibling tools like sys_state or vm_state by covering a broader health-check 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 phrase 'Run this first' explicitly tells the agent when to use this tool, establishing it as the initial diagnostic step before other operations. This is strong usage guidance, though it doesn't explicitly name alternatives or exclusions, the directive is unambiguous.

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

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

With no annotations, the description carries the transparency burden. It signals a non-mutating snapshot through 'state' and 'last events', but does not disclose output shape, freshness, limits, or how the optional vm filtering affects results. It provides modest but not rich 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?

One sentence, no filler, with the four data domains front-loaded before the 'one answer' payoff. Every word contributes to the description's purpose.

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 aggregates multiple subsystems and there is no output schema or annotations, so the description must carry more weight. It lists the included categories but does not explain how they are structured, whether the optional vm filter affects all categories, or what 'last events' covers. This is adequate for selection but leaves invocation details to 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 coverage is 100%, so the only parameter (vm) is already described as 'Limit to one VM'. The overall description adds no parameter-specific meaning beyond this baseline; it does reinforce that the result is an aggregate answer.

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 as a consolidated read/state query returning VM power status, debugger state, terminal sessions, and recent events. The listed domains distinguish it from narrower sibling tools such as vm_state, kd_state, and term_list.

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 implies use when a single consolidated state answer is desired ('in one answer'), but gives no explicit when-not conditions or pointers to alternatives. There are many overlapping sibling tools, and the description does not explain how sys_state relates to them.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It only states that a session is closed, leaving unspecified whether this kills the underlying process, invalidates the session_id, affects buffered output, or is idempotent. For a state-changing tool this is a meaningful gap.

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

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

The description is a single clear sentence with no wasted words. It is appropriately front-loaded, though its brevity is partly responsible for the missing behavioral detail penalized elsewhere.

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

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

For a simple one-parameter action, the description plus schema identify the input and the intended operation. However, the absence of annotations, output schema, and lifecycle context make it only minimally complete for an agent deciding when and how to call it.

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

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

The schema fully documents the only parameter as 'Session id from term_open,' so the description does not need to repeat it. The tool description adds no parameter-level meaning, but the schema already provides complete coverage.

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

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

The description names a precise action ('Close') and a clear resource ('a session'), so an agent can tell it is the counterpart to term_open. It is less explicit about how it differs from other terminal lifecycle tools, but the verb-resource pair is sufficient for basic distinction.

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

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

No usage guidance is provided: it does not say to invoke this after term_open, whether it should precede other operations, or what conditions make closing appropriate. The lifecycle implication is present but left entirely to inference.

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

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

With no annotations, the description must carry the behavioral burden. It does disclose the core behavior: runs one command and returns output and exit code, implying a non-interactive, synchronous execution. However, it does not mention blocking behavior, timeout effects, output truncation, or potential side effects on the session.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to understanding what the tool does and returns.

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

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

The tool is simple, but the description omits any mention of timeout or max_bytes semantics, and there is no output schema to clarify the return format beyond 'output and exit code'. It also lacks guidance about appropriate use cases relative to siblings, leaving the agent to guess on edge cases.

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

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

Schema coverage is 50%, with cmd and session_id documented in the schema but timeout and max_bytes not described in either schema or description. The description adds no parameter-level meaning and fails to compensate for the gaps in the schema.

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

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

The description states a specific action ('Run one command'), a resource ('in the session'), and the exact return ('only its output and exit code'). This clearly distinguishes it from sibling tools like term_send or term_read, which handle streaming or interactive I/O.

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

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

The description gives no guidance on when to use this tool versus term_send, term_read, kd_exec, or other siblings. There is no mention of alternatives or conditions for choosing this tool, leaving the agent to infer usage from the name and schema alone.

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

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

No annotations are provided, so the description must carry the full burden. It states 'List terminal sessions and their state' which implies a read-only operation, but it doesn't disclose whether it's safe, whether it requires authentication, or what 'state' means (e.g., active, idle). The description adds minimal behavioral context beyond the obvious.

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, concise and directly states the action. It's front-loaded with the verb. However, it is so short that it misses opportunities to provide useful context, but conciseness itself is good. It earns a 4 for brevity.

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 is a list operation with an optional filter, the description is minimal. It doesn't explain what 'state' includes, how to interpret the output, or typical use cases. With no output schema and no annotations, the description should provide more context to help the agent know what to expect, but it doesn't. It is functionally minimal but incomplete for a tool in a terminal context.

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

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

The schema has one optional parameter 'vm' with a description 'Only sessions of this VM', and schema coverage is 100%, so the schema already documents the parameter. The description doesn't add any additional meaning about the parameter (e.g., format, default behavior, or what happens if null). Given high coverage, a baseline of 3 might be expected, but the description adds no value beyond the schema, and the parameter is not explained in the description at all, so a 2 is more appropriate.

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

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

The description states a clear verb and resource ('List terminal sessions and their state'), so the purpose is identifiable. However, it does not distinguish it from related terminal tools like term_open, term_close, term_read, etc., and the sibling set includes many session-related tools. It is minimally clear but lacks differentiation.

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

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

No guidance on when to use this tool versus alternatives. It doesn't mention that it only lists sessions (not content or control) or that it can be filtered by VM. The distinction from term_read (which probably reads session output) or sys_state is not provided, leaving the agent to infer when to call 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?

With no annotations, the description carries the full burden of behavioral disclosure. It states the primary action and output, but omits important lifecycle consequences: the session persists until closed, consumes guest resources, and should be cleaned up with term_close. This makes the behavioral transparency incomplete for a stateful operation.

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

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

The description is a single, focused sentence with no filler. The core action is front-loaded, and every remaining word contributes meaning, making it highly efficient.

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

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

Because there is no output schema and no annotations, the description must cover more ground. It mentions the returned session_id but does not explain how to use it with sibling tools, that sessions remain open until term_close, or any guest/SSH prerequisites. This is a meaningful gap for an agent managing an interactive session lifecycle.

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 some parameter context: 'SSH' clarifies the transport parameter and 'real-time PTY' implies that cols and rows are terminal dimensions. However, most parameter meaning is left to the schema, and the schema's transport description is only 'Transport' while cols/rows lack semantic descriptions, so the description only partially compensates.

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 ('Open'), names the resource ('real-time PTY session (SSH) on the guest'), and states a concrete return value ('session_id'). This clearly distinguishes it from sibling tools like term_close, term_send, term_read, term_exec, term_resize, and term_list, which act on an already-open session.

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

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

No explicit usage guidance is provided. The description does not say when to prefer term_open over term_exec, that term_open should precede term_send/term_read/term_close, or mention prerequisites such as the VM being running and SSH being available. Usage context is only weakly implied by the word 'Open'.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions waiting for a regex (implying blocking) but does not disclose cursor advancement, cleanup behavior, non-destructive nature, or what happens on timeout. The description is too terse to convey side effects or operational semantics.

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 that captures the core functionality with no redundant words. It is appropriately sized for a simple summary, though it sacrifices depth for brevity.

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 (7 params, no output schema, no annotations), the description is incomplete. It omits return format, blocking behavior, cursor semantics, and when to use which mode. An agent would need to rely heavily on the schema and prior experience to use it correctly.

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

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

Schema description coverage is 71%, so the schema already documents most parameters. The description adds meaning by linking 'delta' and 'until' to modes, and 'screen' to rendering, which helps interpret mode and until. However, it does not explain cursor, timeout, or max_bytes beyond their schema descriptions, so it only partially compensates.

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 reads new output (delta), waits for a regex (until), or renders the screen (mode=screen), giving a specific verb and resource. It distinguishes between three modes but does not explicitly tie it to a terminal session, though the name and session_id parameter imply it.

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

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

The description implies usage for reading terminal output but does not explain when to prefer this over siblings like term_list (list sessions) or term_send (write). No exclusions or alternative routing are provided, leaving an agent to infer when this is the appropriate tool.

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

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

No annotations are provided, so the description carries full responsibility for disclosing behavior. It only states 'Resize the PTY,' revealing nothing about side effects (e.g., changing terminal dimensions, possible disruption of output), permissions, or reversibility. For a mutation tool with no annotation safety signals, this is a critical gap.

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

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

The description is a single sentence with zero structural organization. While it is short, this is under-specification rather than conciseness—vital information about the session and effect is omitted. It is not front-loaded with key constraints or usage context.

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 moderate complexity (3 required params, no output schema, no annotations), the description is grossly incomplete. It omits the session dependency, the meaning of cols/rows, and any behavioral side effects. An agent cannot reliably invoke this tool correctly based solely on the definition.

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 covers only session_id with a description, leaving cols and rows undocumented. The description 'Resize the PTY.' adds no meaning about what cols and rows represent or how they relate to the session. With schema coverage at 33% (below 50%), the description should compensate but fails entirely to explain parameter semantics.

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

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

The description 'Resize the PTY.' identifies a specific verb and resource, but it is extremely terse. It does not mention that this applies to an existing terminal session, nor does it distinguish from siblings like term_open or term_send. The verb is clear but the context is minimal, so an agent could guess the purpose but lacks precision.

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

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

There is no guidance on when to use this tool versus alternatives. No mention of prerequisites (e.g., a session from term_open), no exclusions, and no reference to sibling tools. The implication that it is for resizing an existing PTY is implicit at best, but the description leaves the agent without actionable 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?

No annotations are provided, so the description must fully disclose behavioral traits. It only says what the tool does and lists tokens; it does not mention side effects, failure modes, whether it blocks, or if it requires a prior open session. For a mutation operation, this is a significant gap.

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

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

One sentence with the action front-loaded, followed by a compact token list. No filler; every word contributes meaning.

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

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

With no output schema and no annotations, the description should explain return behavior and interaction between parameters (e.g., whether text and keys are combined, if enter defaults to true). It does not describe what happens when invoked or how the outcome is reported, leaving an agent uncertain about post-call behavior.

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

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

Schema description coverage is 100%, so the schema already documents all parameters including the token expansion in 'text'. The description adds a token list, but that largely duplicates what the schema already states. Baseline 3 is appropriate.

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

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

States a specific action (type) and target (a session), and distinguishes from siblings by focusing on input rather than reading or resizing. The listed tokens clarify the input format. This is unambiguous.

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

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

No explicit when-to-use or when-not-to-use guidance. It does not contrast with term_exec, term_read, or other siblings, nor does it mention prerequisites like an active session from term_open. The usage context is only implied by the description.

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

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

With no annotations, the description must carry the behavioral burden. 'List' implies a read-only operation and the mention of state categories adds context, but it does not explicitly state that the tool is non-mutating, how 'registered' is defined, or what happens when no VMs exist. For a simple list tool this is acceptable but not fully transparent.

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 entire description is one short, front-loaded sentence that states the action, resource, and output scope without any filler. Every word earns its place.

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

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

This is a low-complexity, no-argument tool, and the description covers its main purpose and output categories. It lacks a stated return format or edge-case behavior, but for a tool this simple the missing details are unlikely to prevent correct invocation or interpretation.

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

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

The tool has zero parameters and 100% schema coverage, so there is no parameter information the description needs to add. The description appropriately focuses on what the tool returns, which is the only meaningful semantic content for this 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 clear verb ('List') with a specific resource ('registered VMs') and names the key output dimensions: power, debugger, and terminal state. This clearly differentiates it from sibling tools like vm_state or sys_state by indicating a multi-state listing behavior.

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

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

The description gives no explicit guidance on when to use vm_list versus sibling tools such as vm_state, vm_start, or sys_state. It implies a listing use case, but there are no exclusions, prerequisites, or alternative tool references, leaving the agent to infer routing from the name alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does clearly state the main action and that kd and terminals are restored, but it omits the destructive nature of hard reboots and the need to set confirm=true. The schema's confirm parameter hints at destructiveness, but the description itself remains thin on side effects.

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 filler. Every phrase contributes meaning, and it avoids repeating parameter names or schema details, making it an efficient and well-structured definition.

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 moderately complex tool with 6 parameters and no output schema, the description plus the well-detailed input schema is nearly complete. The core behavior is fully described, though explicit usage guidance and a destructive-action warning would make it fully self-sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by linking the mode options to soft/hard/kd and by framing reattach_kd and reopen_term as 'bring kd and terminals back,' providing useful semantic context that is not explicit in the parameter names alone.

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 ('Reboot'), the resource ('guest'), and enumerates the available modes ('soft, hard or from the debugger'). It also adds the distinctive effect of bringing kd and terminals back, which clearly differentiates it from sibling tools like vm_stop, vm_start, and vm_suspend.

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

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

The description gives no explicit guidance on when to use this tool over alternatives such as vm_stop/vm_start or kd_attach. There are no when-to-use or when-not-to-use instructions, nor any named alternatives, leaving the agent to infer usage context from the tool name and sibling list.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action (resume) and equivalence to vm_start, but it does not disclose side effects, prerequisites, whether the VM must already be suspended, or what happens if the VM is not suspended. For a state-changing VM operation, this is a meaningful gap.

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

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

The description is a single short sentence with a useful parenthetical clarification. Every word earns its place, and the key action is front-loaded.

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 one-parameter tool with full schema coverage, the description is mostly complete. However, it lacks behavioral context such as whether the VM must be in a suspended state, whether the operation is asynchronous, or what errors might occur. The equivalence to vm_start helps, but the description could do more to make the tool safely invocable.

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

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

Schema description coverage is 100%, so the schema already documents the single 'vm' parameter as 'VM name as registered in vms.yaml'. The description adds no additional parameter meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Resume a suspended VM', and it explicitly equates the behavior with vm_start, which helps distinguish it from other VM lifecycle tools. It is clear but relies on the parenthetical to differentiate it from vm_start rather than fully standing alone.

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

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

The description implies the tool is for resuming a suspended VM, which gives clear context for when to use it. It does not explicitly state when not to use it or name alternatives beyond the parenthetical equivalence to vm_start, so usage guidance is adequate but not fully 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?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does convey the headless-by-default behavior, but it does not specify what happens if the VM is already running, whether the operation can fail due to VM state, or what output is returned. The 'or resume' hint is vague about state handling.

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, compact sentence with the primary action front-loaded. It wastes no words, though it could have been slightly more informative about state behavior or sibling relationship without becoming verbose.

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 start tool, the description gives the core purpose, but it omits important contextual details: how to handle an already-running VM, the distinction from vm_resume, and any prerequisites beyond the schema-documented 'vm' parameter. Since there is no output schema and no annotations, these gaps leave the agent with material uncertainty.

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

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

Schema description coverage is 100%, so both parameters (vm and gui) are already documented in the input schema. The description adds no new parameter-level detail beyond reinforcing that GUI is off by default, which is already encoded in the schema's default value. A baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Power on (or resume) a VM'. It clearly indicates the tool's action, but the phrase '(or resume)' overlaps semantically with the sibling tool vm_resume, so differentiation from that sibling is not fully addressed.

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 that this tool starts a VM headlessly, which is a clear usage context, but it provides no explicit guidance on when to use vm_start versus sibling tools like vm_resume, vm_stop, or vm_suspend. No exclusions or alternative conditions are given, leaving selection partly to inference.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only lists the data domains covered and does not explicitly state that the operation is read-only, whether a VM must be running, or what failure modes exist. A 'state' query is plausibly safe, but the agent must infer that from the name rather than from stated 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 concise phrase that front-loads the three state categories and contains no filler or repetition. It is appropriately sized for a one-parameter state inspection tool.

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

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

For a simple, read-like tool with full schema coverage, the high-level scope is minimally viable. However, with no output schema or annotations, the agent still lacks information about the response format and any prerequisites such as VM power state or guest agent availability. The sibling tool names provide context but do not make the description self-sufficient.

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 already documents the single parameter vm as 'VM name as registered in vms.yaml,' giving 100% schema description coverage. The tool description adds no additional parameter-level meaning. With the schema fully covering the parameter, the baseline score of 3 is appropriate.

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

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

The description names a specific resource ('one VM') and enumerates the three state aspects covered: 'Power, debugger and terminal state.' This distinguishes it from broader state tools like sys_state or kd_state. It lacks an explicit verb such as 'retrieves' or 'gets,' but the intent is still 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?

No guidance is given on when to use vm_state versus related siblings such as kd_state, term_list, sys_state, or vm_list. There are no exclusions, alternatives, or contexts mentioned. The only implied scoping is 'one VM,' which is insufficient for an agent to confidently route among the 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?

With no annotations, the description carries the safety burden. It clearly discloses that soft asks the guest to shut down while hard cuts power, and that hard needs explicit confirmation. This is meaningful behavioral context, though it does not describe side effects like possible data loss from hard power-off or whether the call waits for shutdown completion.

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

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

A single, compact sentence that front-loads the main operation and packs the mode distinction and confirmation requirement into minimal words. No filler or redundant restatement.

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 straightforward three-parameter tool with no output schema, the description provides enough context to invoke it correctly: the VM name comes from vms.yaml, mode is soft or hard, and confirm is required for hard. It does not explain return behavior, but that is not essential here.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explicitly tying confirm=true to hard mode, a relationship the schema only implies through separate field descriptions. This helps an agent understand how the parameters interact.

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 ('Shut down' / 'cut power') against a clear resource (the guest VM) and distinguishes the two stopping modes. This separates it from sibling tools like vm_start, vm_reboot, and vm_suspend without needing to open the schema.

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

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

The description gives useful within-tool guidance: soft mode is a graceful shutdown, hard mode cuts power and requires confirm=true. However, it does not explicitly state when to prefer this tool over alternatives like vm_reboot or vm_suspend, or mention any preconditions.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. 'Suspend the VM to disk' does reveal that the VM's state is persisted to disk, which is useful, but it does not mention side effects like pausing execution, whether the operation is reversible, or whether it requires a subsequent vm_resume to restore operation.

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

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

The description is a single five-word sentence with no filler. It front-loads the action and the persistence detail, making it easy to parse and scan.

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 one-parameter lifecycle tool, the description is minimally adequate: it names the operation and the persistence behavior, and the schema supplies the parameter meaning. However, with no annotations, no output schema, and no mention of postconditions or consequences, it leaves some gaps that an agent must infer from the tool name and siblings.

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 already documents the only parameter, 'vm', as a name registered in vms.yaml, giving 100% schema description coverage. The tool description adds no extra parameter-level meaning, such as whether the VM must be in a particular state, so the baseline score of 3 applies.

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

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

The description clearly states the action ('Suspend') and the target ('the VM'), and 'to disk' adds meaningful specificity about persistence. It does not explicitly differentiate from vm_stop or vm_reboot by naming them, but 'suspend' is a well-defined lifecycle verb that separates it from those siblings.

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

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

There is no guidance about when to use this tool versus alternatives like vm_stop, vm_reboot, or vm_resume. The description also omits prerequisites, such as whether the VM must currently be running, so an agent has to infer the proper usage context.

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