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

Far exceeds the supplied annotations (destructive/openWorld/non-idempotent), which say nothing about mechanics: the description discloses pre-flight validation behavior (FileNotFoundError naming param and path, ValueError for append/initrd without kernel, hostfwd port bind probe), that QEMU's own accelerator or image-locking failures surface through the generic boot-error path, and that serial output is captured continuously. It also gives the extra_args conflict rules in detail, including the deliberate exemptions for -drive, -chardev and -netdev. The only untold element is why the tool is flagged destructive, which is a minor omission against this volume of disclosure.

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

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

The content is dense and largely earns its place, but it is delivered as a single undifferentiated wall of prose with heavy parenthetical nesting, making it hard to scan for a specific parameter. The extra_args conflict rules are restated three times in near-identical shape for -drive, -chardev/-serial and -netdev, which could be compressed into one rule plus a table of exceptions.

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 20-parameter tool with an output schema and annotations already present, the description covers the remaining gaps: prerequisites, cross-parameter validation, error surfacing, conflict rules, and lifetime/cleanup expectations. An agent has everything needed to invoke it correctly on the first attempt.

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

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

Schema description coverage is 0% across 20 parameters, so the description carries the entire burden and does: name charset restrictions, iso/kernel/disk existence requirements, memory_mb and smp* positivity, arch-to-binary mapping, machine/-M semantics per arch, accel fallback syntax ('kvm:tcg'), cpu examples, hostfwd rule grammar, and what each timeout actually bounds. This is meaning well beyond type/default information.

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

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

States a specific verb and resource ('Boot a QEMU VM headless and register it under `name`') and immediately establishes the registration role that links it to every other qemu_* sibling. An agent can tell this apart from qemu_disk_create (image creation) and qemu_stop (teardown) without opening any schema.

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

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

Gives concrete selection rules: at least one of iso/kernel/disk must be supplied, append/initrd require kernel, qcow2 is needed for snapshot save/load, and machine is required on aarch64/riscv64. It also implies the ordering contract ('identifies this VM in all later calls', 'keeps running until qemu_stop') and hints that disk images must be made elsewhere. It never explicitly names a sibling as the alternative for creating images, so it stops short of a 5.

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

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

Even though annotations already declare destructiveHint and idempotentHint, the description adds real behavior: force=True ejects despite a guest tray lock while the default refuses, format defaults to auto-probing, and the call wraps QMP blockdev-change-medium. It does not explain what happens to the previously attached medium or the failure mode if path is invalid.

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

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

Purpose is front-loaded in one sentence, then parameter guidance follows in a logical order. Some phrasing is conversational and slightly padded ('qemu-mcp can't guess it for you, since it depends on the machine type/QEMU version'), but each clause still conveys actionable 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 QMP wrapper with an output schema already documenting return values, the description covers what the agent needs: device identification, path precondition, format default, and the safety-relevant force behavior. The unexplained 'name' parameter is the sole omission and is likely a cross-tool convention.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does well for four of five params: device sourcing, path existence requirement, format auto-probe default, and force semantics. The required 'name' parameter is never explained, which is the only notable gap.

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

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

The opening sentence states a specific verb and resource ('swap the medium in a removable drive') plus an example and the key benefit ('without rebooting'). The parenthetical mention of qemu_boot's iso/disk params makes the distinction from the boot-time media path explicit, so an agent can separate this from qemu_boot or qemu_qmp without reading schemas.

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

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

It gives concrete preconditions (path must already exist), tells the agent where to obtain the device value (query-block's 'qdev' field) and why it can't be guessed, and states the default vs forced behavior on guest-locked drives. What's missing is a crisp statement of when not to use this tool versus alternatives such as qemu_qmp blockdev-change-medium or rebooting via qemu_boot.

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

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

Annotations only say it is non-read-only, non-idempotent and non-destructive; the description adds the crucial failure mode (fails if path already exists instead of overwriting, consistent with idempotentHint=false) and warns that qemu_boot's format auto-detection only distinguishes qcow2 from raw, so other formats silently degrade. That is real behavioral context beyond the annotation block.

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

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

Front-loaded with purpose and the qemu_boot dependency, then parameters, then the failure mode. Slightly redundant in the middle - 'qemu_boot never creates a disk image itself' and 'This closes that gap: create one here, then boot straight into it' say overlapping things - but nothing is wasted overall.

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

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

An output schema exists, so return values need not be described; with purpose, sibling relationship, parameter grammar, format constraints and the existing-path failure all covered, an agent has everything needed to invoke it correctly on the first attempt.

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

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

Schema coverage is 0%, so the description carries the full burden and does: it spells out qemu-img size grammar with unit suffixes and examples ('10G', '512M'), restricts format to exactly two valid values with a default, and implies path must not exist. All three parameters gain meaning absent from the bare schema.

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

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

States a specific verb and resource ('Create a fresh disk image via qemu-img create') and immediately ties it to the sibling that needs it (qemu_boot's `disk` param), which lets an agent place it among the qemu_* tools without opening the schema.

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

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

Explains exactly when to use it: qemu_boot never creates images, so create here first, then boot. It also routes the format choice to siblings - 'qcow2' is required for qemu_snapshot_save/qemu_snapshot_load, 'raw' otherwise - which is explicit alternative-selection guidance.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is partly carried structurally. The description goes beyond them by explaining that 'sysrq' triggers the Linux Magic SysRq key and that 'alt-sysrq-c' can force a crash dump, implicitly warning that this can disrupt the guest kernel. It does not state error behavior for unrecognized key names, but the sysrq disclosure is substantive added context.

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

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

The core concept and the sibling steer are front-loaded in the first two sentences, and the remaining text is dense with concrete syntax rules rather than filler. The multi-line layout is slightly harder to scan than a single tight paragraph, but no sentence is wasted.

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

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

An output schema exists, so return values need not be described. For a two-parameter tool, the combo grammar and sysrq special case are well covered; the main remaining gap is that the description never says what 'name' identifies (the target VM), which an agent must infer from the qemu_ prefix.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does this thoroughly for 'combo': parts joined with '-', pressed together, literal '-' written as '--', and a documented 'sysrq' token with examples. The 'name' parameter is never explained, leaving one of two parameters undocumented, which prevents a 5.

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

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

The description opens with a specific verb+resource ('Press a key or chord') and immediately grounds it with concrete examples ('enter', 'ctrl-alt-f2', 'ctrl-c'). It also distinguishes itself from the sibling qemu_type by name, so an agent can pick the right tool without inspecting either schema.

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

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

It gives an explicit routing rule: use qemu_type for plain text, this tool for key/chord input. That is a real when-to-use signal against a sibling. It does not cover when-not-to-use in a risk sense (e.g. avoid combos that could interrupt the guest), which keeps it below a 5.

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

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

Despite annotations already indicating destructive behavior, the description adds important lifecycle detail: exited VMs appear once as exited(...), then are reaped and their workdir and handles are freed before the call returns. This explains a non-obvious side effect that annotations alone would not convey.

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

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

The description is front-loaded with the main purpose, then adds a necessary caveat about exited VMs. Every sentence contributes useful information without unnecessary wording.

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-parameter list tool with an output schema and annotations, the description is complete enough. It covers what is listed, the fields available, and the important reaping behavior before the call returns.

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

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

There are zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and it appropriately stays focused on the result and lifecycle behavior.

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

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

The description uses a specific verb and resource: 'List all VMs managed by this server,' and names the fields returned (arch, machine, hostfwd, pid, uptime, state). It is clearly distinguishable from snapshot-oriented siblings like qemu_snapshot_list, though it does not explicitly contrast with them.

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

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

Usage is implied by the listing purpose, but the description does not state when to use qemu_list versus alternatives such as qemu_snapshot_list or qemu_version. There are no explicit when-not conditions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description is not carrying the full burden. It still adds useful context the annotations cannot: the guest must expose an absolute pointer (USB tablet or PS/2 mouse), and side buttons require the guest's PS/2 driver in IMEX mode. What it does not do is warn that a click can trigger irreversible guest-side actions, which would explain the destructive flag.

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

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

The purpose is front-loaded in the first sentence and the rest is dense, non-redundant detail about coordinates and button values. It is longer than average but nearly every clause carries information an agent needs; only the parenthetical driver caveat is borderline expendable.

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?

Return values are covered by the output schema, so the description needn't explain them. The remaining gap is the unexplained required 'name' parameter and the absence of any note on click irreversibility despite destructiveHint=true. For a 4-parameter input tool, that leaves the definition adequate but not complete.

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

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

Schema description coverage is 0%, so the description has to compensate, and it does well for x, y (fractions of screen size) and button (enumerating left/right/middle, wheel directions, and side/extra). However, the required 'name' parameter is never mentioned, leaving one of three required inputs entirely unexplained.

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

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

The opening sentence gives a specific verb and resource: 'Move the absolute pointer and optionally click.' It immediately separates the tool from siblings like qemu_key and qemu_type, which handle other input devices, so an agent can pick it without inspecting 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 tells the agent to read x/y coordinates 'off a qemu_screenshot', which is a concrete workflow pointer to the sibling tool that produces the needed input. It also states that omitting button just moves the pointer. It stops short of explicit when-not guidance (e.g., use qemu_key for keystrokes), so it is strong but not exhaustive.

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

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

Annotations only declare the generic profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description adds real behavior: guest CPUs stop, RAM and device state are preserved unchanged, guest time does not advance, and that state persists until qemu_resume. It also discloses a useful side effect for snapshotting (guaranteed-consistent snapshot rather than one taken mid-instruction).

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

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

Front-loads the core action in the first sentence and follows with use cases; every sentence carries information. It is slightly long, and the trailing "qemu_stop still works on a paused VM" sentence is a little ambiguous in placement rather than a crisp exclusion rule.

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

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

With an output schema present, return values need not be explained, and the state/consistency semantics are covered well. The only real omission is the meaning of the `name` argument, which is a modest gap for an otherwise simple one-parameter tool.

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

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

Schema description coverage is 0% and the single required parameter `name` is described nowhere in the description. The text never says whether `name` is the VM name, an instance label, or something else, so the description does not compensate for the schema gap.

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

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

States a specific verb and resource ("Pause the VM's execution") and even names the underlying QMP primitive (`stop`). The clause "without exiting QEMU" immediately separates it from qemu_stop, so an agent can distinguish it from siblings without opening any schema.

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

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

Gives concrete when-to-use scenarios: inspecting a VM via qemu_screenshot or qemu_qmp query-* without guest time advancing, and pairing with qemu_snapshot_save for a consistent snapshot. The note that "qemu_stop still works on a paused VM" hints at the boundary with qemu_stop, but the description never states plainly what qemu_stop is for or when to prefer it, so the alternative routing is only implied.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond that: this is an untyped pass-through whose behavior depends entirely on the caller-supplied command and its arguments, and the command grammar lives in an external reference. It still omits what state can be corrupted or whether errors are surfaced, so a 3 is warranted.

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

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

Two short sentences, front-loaded with the framing ('Escape hatch') before the examples. Every element earns its place, though the trailing 'See the QEMU QMP reference' is a pointer rather than substantive guidance.

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

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

An output schema exists, so return values needn't be described, and the annotations cover the safety profile. For a maximally generic destructive tool, though, the description should steer the agent toward dedicated siblings first and note that arbitrary commands can alter or break VM state — neither is present, and one required parameter goes unexplained.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it only partly does. It clarifies that 'command' is a QMP command name and that arguments are command-specific ('commands and their arguments'), but the required 'name' parameter is never explained as the VM identifier, leaving a required parameter ambiguous.

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

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

The description states a specific verb and resource ('run a raw QMP command on the VM') and frames it as an 'escape hatch', which distinguishes it from the typed siblings like qemu_pause or qemu_snapshot_save. Example commands (query-status, system_reset, memsave, device_add) make the scope concrete, though it never names the siblings it substitutes for.

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 word 'escape hatch' implies usage in cases the dedicated tools don't cover, and the pointer to the QEMU QMP reference implies the agent must look up syntax externally. However, there is no explicit statement of when to prefer a typed sibling tool over this one, nor any exclusion or warning about conditions where it should not be used.

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

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

Goes beyond the annotations by disclosing that the call silently succeeds when the VM was never paused — a behavior that idempotentHint only hints at, and which matters for verifying state. The QMP `cont` mapping also tells the agent what happens underneath. It does not describe the response payload, but annotations plus the output schema cover the safety profile.

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

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

Two sentences, front-loaded with the primary action and the sibling reference, then the one caveat that changes agent behavior. Nothing is padded.

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

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

For a low-complexity state-transition tool with an output schema and rich annotations, the description covers the action, precondition, and no-op edge case. The only missing piece an agent needs is what `name` refers to.

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

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

Schema description coverage is 0% for the single required `name` parameter, so the description carries the full burden and provides nothing: it never says whether `name` is the VM identifier from qemu_list, a domain name, or a UUID, nor whether it must match a running/paused VM. This is the definition's clearest gap.

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

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

States a specific verb (resume) plus resource (a paused VM) and anchors it to the sibling that creates the state it undoes ('previously paused with qemu_pause'), even citing the underlying QMP command `cont`. An agent can distinguish this from qemu_boot and qemu_stop without opening any schema.

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

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

Gives a clear precondition (VM was paused via qemu_pause) and an edge case (no-op if not paused). It does not explicitly contrast with qemu_boot, the alternative for a non-running VM, but the pairing with qemu_pause makes the intended usage unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful behavior: it works headless via the VGA framebuffer, and it raises a clear error rather than an opaque decoding failure if the VM exits mid-capture. It does not say where the resulting image goes (returned inline vs. written to disk), which is the main remaining behavioral 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?

Two short sentences, front-loaded with the core action and output format, followed by usage cases and error behavior in descending priority. The parenthetical about error messaging is slightly verbose but still earns its place.

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

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

With no output schema, the description could say more about the return value (image content vs. file path), but "Capture the VM's display as a PNG image" implies an image is returned. For a single-parameter read-only tool, the coverage of purpose, use cases, and failure mode is close to complete.

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

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

Schema coverage is 0%, so the description must carry the burden for the single "name" parameter — but it never mentions it. An agent can infer it identifies the target VM from the sibling qemu_* tools, but this is left to inference rather than stated.

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 ("Capture the VM's display as a PNG image") and names the mechanism (QMP screendump), which distinguishes it from the adjacent qemu_serial / qemu_wait_screen tools. An agent can identify the tool's function without opening the schema.

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

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

It gives concrete when-to-use cases: boot screens, kernel panics, GUIs, and a text console that doesn't write to serial. The serial-based alternative is implied but not named explicitly, and no when-not-to-use case is given, so it falls short of a 5.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, but the description adds real lifecycle context not present in them: the console remains readable after the VM has exited and stays visible only until qemu_list reaps it. That reaping dependency is the key behavioral fact an agent would otherwise miss; return format is left to the output schema.

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

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

Three short sentences, front-loaded with the operation, then the non-obvious lifecycle behavior, then the one parameter constraint. Nothing is redundant and nothing is buried.

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

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

An output schema exists, so return values need not be described, and the description covers the non-obvious lifecycle and the tail_lines constraint. The remaining gap is what `name` refers to and how to obtain it, which matters for a required parameter with no schema description.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does add a real constraint for tail_lines ('must be positive', beyond the schema's default of 50), but the required `name` parameter is never explained or tied to the VM identifiers returned by qemu_list.

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: reading the tail of the VM's serial console output on COM1, with the scope ('tail') made explicit. It implicitly separates itself from qemu_serial_send (writes) and qemu_wait_serial (blocks for a pattern), but never names those siblings, so the differentiation is left partly to inference.

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

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

It gives a clear use case: retrieving output after a guest crash or `quit` via qemu_qmp, when the VM is no longer live. It does not state when to prefer qemu_wait_serial or qemu_screenshot instead, nor any exclusions, so the when-to-use guidance is strong but incomplete.

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

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

Annotations only declare that this is a non-idempotent, destructive write; the description adds substantially more: input is sent verbatim, the caller must supply "\n" for Enter, a single persistent connection is held for the VM's lifetime, reconnection happens once automatically, and failure raises with a retry-once-the-socket-is-back instruction. That is exactly the operational context an agent needs before invoking a destructive console write.

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

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

The purpose and the discriminating condition are front-loaded in the first two sentences, and the reconnection/error guidance is grouped at the end where it belongs. The second paragraph is slightly meandering, but every sentence carries real operational information rather than filler.

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

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

Because an output schema exists, return values do not need explaining, and the description covers the behaviors that matter for a stateful serial write: verbatim transmission, line-persistence, single auto-reconnect, and failure semantics. The only real gap is the unexplained name parameter and nothing about size/throughput limits.

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

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

Schema description coverage is 0%, so the description must supply meaning. It does explain the text parameter well (sent exactly as given, newline required) but never clarifies what the required name parameter refers to — presumably the VM identifier, but the agent must infer it. Partial compensation for a two-parameter schema with no field documentation.

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

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

The first sentence states a precise verb and resource: write text to the guest's serial console (COM1). It explicitly positions itself as the bidirectional counterpart to the read-only qemu_serial sibling, so an agent can separate the two without consulting either schema.

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

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

It names the qualifying condition for use — guests that expose a shell only over serial, with no VGA console or a serial-only debug shell — and points at qemu_serial for the read-only case. It stops short of contrasting with qemu_type/qemu_key, which is the other plausible alternative for delivering input, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description earns credit for adding what is destroyed (space inside the qcow2 disk is freed) and the error contract (a failing delvm surfaces as failure rather than silent success). The mention of QEMU's delvm rejecting an unknown tag is real behavioral context not present in the annotations. It does not discuss the interaction between idempotentHint=true and erroring on an unknown tag, which is a minor omission.

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

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

Two short sentences with the action front-loaded and the effect and error behavior following. No filler, no restatement of the title.

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

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

The tool is simple and an output schema exists, so return values need no explanation. However, with zero schema coverage, the unexplained 'name' parameter leaves an agent guessing about scope (which VM the snapshot belongs to), which is a meaningful gap for a destructive operation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it largely does not. "Unknown tag" hints that 'tag' identifies the snapshot, but the required 'name' parameter (presumably the VM name) is never explained, and there is no format guidance for either.

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

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

Specific verb plus resource ("Delete a snapshot") with an explicit lineage tie to qemu_snapshot_save, so the agent knows this is the inverse of the save tool. It does not explicitly distinguish itself from qemu_snapshot_load or qemu_snapshot_list, so the sibling separation stops just short of a 5.

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

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

The phrase "previously saved with qemu_snapshot_save" implies a precondition (the snapshot must already exist), and the failure note implies a guard, but there is no explicit when-not or direct comparison to qemu_snapshot_load for removing vs. reverting. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds materially useful behavior: the result is QEMU's raw table output with the 'exact column layout isn't parsed here,' and the snapshots are 'internal' on the qcow2 disk rather than external. The one omission is what happens for a VM whose disk is not qcow2, so it falls just short of full transparency.

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

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

Three short sentences: what it does, why it exists relative to the load/delete tools, and the return-format caveat. The purpose is front-loaded and every sentence earns its place with no filler.

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

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

An output schema exists, so the description needn't detail return fields, and the raw-HMP-output caveat covers the one thing the schema can't express. The remaining gap is the unstated meaning of the 'name' parameter for an otherwise very simple tool.

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

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

Schema description coverage is 0% for the single required parameter 'name', so the description carries the burden, and it only implicitly conveys that 'name' identifies the VM via the phrase 'the VM's qcow2 disk.' It never says whether 'name' is a VM name, a disk path, or a libvirt domain, so the meaning is inferable but not stated.

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

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

The description opens with a specific verb and resource ('List internal snapshots saved on the VM's qcow2 disk') and goes on to name the sibling tools it complements (qemu_snapshot_load, qemu_snapshot_delete) together with the implementation it wraps (HMP `info snapshots`). An agent can distinguish it from other snapshot tools without opening any schema.

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

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

It states exactly when to call it: 'so you can see what tags already exist before calling qemu_snapshot_load or qemu_snapshot_delete, instead of finding out only from a failure afterward.' That is an explicit precondition plus the alternatives it supports, leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is covered structurally. The description supplies a genuinely non-obvious precondition, that the snapshot must be on the same qcow2 disk, which is not encoded anywhere in the schema and is the main reason a load would fail. It does not say what happens to current in-memory/disk state, though destructiveHint partially covers that.

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

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

Two short sentences, front-loaded with the action and followed by the prerequisite. Nothing redundant; every sentence carries information.

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

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

An output schema exists, so return-value explanation is unnecessary, and the destructive/reversible profile is in annotations. However, with two required, fully undocumented parameters, the description leaves the agent guessing about argument semantics for a destructive operation, which is a substantial omission for a restore tool.

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

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

Schema description coverage is 0% and both parameters (name, tag) are bare strings with no titles beyond the field names. The description adds no meaning at all about what 'name' identifies versus what 'tag' identifies, or whether tag refers to the snapshot tag created by qemu_snapshot_save. This is the definition's largest gap.

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

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

The description gives a specific verb+resource ('Restore a VM to a snapshot') and names the complementary sibling qemu_snapshot_save, which distinguishes it from snapshot_save/delete/list. It stops short of explaining the difference from other state-changing siblings like qemu_boot or qemu_resume.

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 the tool is used after qemu_snapshot_save and pairs with it, which is useful sequencing context. It does not state when not to use it (e.g., paused/running VM, VM already in target state) or point to alternatives such as qemu_snapshot_list for discovering valid 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?

Annotations already declare destructiveHint=true, but the description adds the concrete behavior behind it: a repeated save with the same tag destroys the previous snapshot, and the snapshot lives inside the disk image via savevm. It stops short of saying whether the VM must be running/paused or how long a save blocks the guest, which matters for a live-save operation.

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

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

Three short sentences, front-loaded with the action, followed by mechanism/constraint and then the tag rule. No filler and every clause adds usable information.

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

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

An output schema exists, so return values need no explanation, and the storage-location and format constraints are covered. The unexplained `name` parameter and the absence of any note about required VM state are the remaining gaps for a destructive snapshot operation.

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

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

Schema description coverage is 0%, so the description carries the full burden. It defines `tag` well (allowed characters, overwrite semantics) but says nothing about the required `name` parameter, leaving half the inputs to inference.

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

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

States a specific verb and resource (save a full VM snapshot of RAM + device state under `tag`) and implicitly separates itself from qemu_snapshot_load/delete/list by describing the save direction and the internal savevm mechanism.

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

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

Gives a hard prerequisite (disk must be qcow2, raw images unsupported) and the overwrite condition, which tells the agent when the call is valid. It does not explicitly point at siblings such as qemu_snapshot_list to check existing tags or qemu_snapshot_load as the counterpart, so there are no named alternatives.

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

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

The description carries real behavioral information beyond the annotations: an ACPI powerdown is attempted first, then a kill fallback after graceful_timeout_s, then a process force-kill after kill_timeout_s. It also warns that many hobby kernels will end up force-killed, which is exactly the side-effect disclosure an agent needs for a destructiveHint=true tool.

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

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

Front-loaded with the core action and the fallback behavior, then parameter detail. Slightly wordy in the parenthetical about large RAM and the "or will be killed ... anyway" clause, which partly repeats the timeout explanation, but nothing is filler.

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

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

An output schema exists, so return values needn't be described, and the behavioral and timeout semantics are thoroughly covered for a destructive stop operation. The only missing piece is the meaning of the required `name` argument, which leaves a small hole for a 4-parameter tool.

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

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

Schema coverage is 0%, so the description must do the work, and it does for three of four parameters: force, graceful_timeout_s and kill_timeout_s each get defaults, meaning and a constraint ("both must be positive"). The required `name` parameter is never explained (presumably a VM name from qemu_list), which is the one remaining gap.

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

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

Opens with a specific verb and resource: "Stop a VM." That is clearly distinguishable from qemu_pause/qemu_resume siblings, and the grace-then-kill detail further pins the semantics. It doesn't explicitly name an alternative tool, so it falls just short of a 5.

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

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

Gives concrete when-to-use guidance: guests without ACPI handling need force=True, and graceful_timeout_s should be raised for large-RAM or slow-ACPI guests. It lacks an explicit when-not or a pointer to qemu_pause for a reversible suspend, but the operational context is clear.

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

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

Annotations already declare destructive=true, readOnly=false and idempotent=false, so the safety profile is covered. The description adds genuinely new behavior: US keyboard layout only, shifted symbols supported, '\n' translates to Enter, and a documented failure mode (dropped characters during early boot) with the remedy. It stops short of saying that repeating the call types the text again.

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

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

Front-loaded with the core action, then constraints, then parameter tuning — nothing superfluous. The escaped-quote rendering of the newline instruction ('"\n" presses Enter') is slightly garbled and costs a bit of readability.

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

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

An output schema exists, so return values need not be described, and annotations cover the risk profile. Combined with the layout/keystroke/failure-mode detail, the definition is nearly complete for a typing tool; only the meaning of the required 'name' argument is left unexplained.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does well for two of three params: text semantics (layout, shifted symbols, newline behavior) and delay_ms (gap between keystrokes, default tuning advice, must be non-negative). The required 'name' parameter is never explained, which is the main remaining ambiguity.

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

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

States a concrete verb and resource ('Type text into the guest as keyboard input') and implicitly separates itself from the sibling qemu_key by operating on whole text rather than single keys. It does not name qemu_key explicitly, so the differentiation is inferred rather than stated.

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

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

Usage context is implied (typing strings rather than individual keystrokes) and there is useful conditional advice for delay_ms ('raise it ... if the guest drops characters during early boot'). However, it never explicitly says when to prefer qemu_key or qemu_serial_send, and gives no when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the important operational fact that no VM is booted, meaning the call is cheap and has no side effects on running guests. It does not mention output format, but an output schema exists.

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

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

Front-loaded with the core action, then rationale, in two short sentences with no filler. The line wrapping is slightly awkward and the phrase 'its own output' is a touch redundant, but nothing wastes the reader's time.

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 simple, single-optional-parameter, read-only diagnostic tool with an output schema, so return values need no explanation. The description covers what it does, when it is useful, and how arch relates to the rest of the toolset, which is everything an agent needs 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 0%, so the description must carry the meaning of 'arch', and it does partially: arch selects the qemu-system-<arch> binary, matching what qemu_boot would launch. However, it gives no hint at valid architecture values or the x86_64 default, leaving the agent to guess acceptable strings.

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

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

States a specific verb and resource ('Report qemu-system-<arch> --version's own output') and immediately bounds the scope with 'without booting a VM'. This clearly separates it from the sibling qemu_boot, which is the tool an agent might otherwise confuse it with.

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

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

Gives a concrete when-to-use scenario: diagnosing unexpected QMP command or machine type behavior by checking what is actually installed. It also links arch to 'the same qemu-system-<arch> binary qemu_boot would use.' No explicit when-not conditions are stated, so it falls short of a 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds behavioral detail beyond the annotations: it polls at a set interval, requires consecutive stable frames, always polls at least once even with a zero or negative timeout, and rejects a non-positive poll_interval_s. The explanation of why max_changed_pixels defaults to 64 (a blinking cursor flips about 18 pixels, while boot output changes hundreds) is a concrete detail about how the tool behaves that the annotations do not provide.

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

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

The purpose is front-loaded in one sentence, then the mechanism and the sibling routing follow in a logical order. The long parenthetical about pixel counts is dense but pays for itself by explaining the default, though the paragraph could be split for easier scanning.

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

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

An output schema exists, so return values need not be described. For a five-parameter blocking wait tool, the description covers the mechanism, defaults, edge cases, and the sibling alternative, leaving nothing an agent needs in order 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 0%, so the description has to carry the full load for parameter meaning, and it does for stable_polls, poll_interval_s (must be positive), timeout_s (edge case of zero or negative), and max_changed_pixels (default 64, use 0 for identical frames). The only gap is the required 'name' parameter, which is never described, though its meaning (VM name) is obvious from the qemu_* tool family.

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

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

The first sentence gives a specific verb and resource: 'Block until the VM's display stops changing, or time out.' It also names the sibling it is not (qemu_wait_serial) and the condition that selects it, so the agent can distinguish it from alternatives without opening any schema.

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

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

The description states explicitly when to use this tool (a VGA-only guest with no serial output that must finish a BIOS splash or boot animation before screenshotting or typing) and when to use the alternative instead ('For guests with serial output, prefer qemu_wait_serial - it doesn't need a fixed number of polls to decide').

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

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

Annotations already cover the safety profile (read-only, non-destructive), and the description adds substantial behavior beyond them: incremental search cursor semantics, from_start reset, FOUND/TIMEOUT prefixing of the returned tail, guaranteed single check for non-positive timeouts, and per-poll incremental I/O. The main gap is that `name` (the target VM) is never explained, so the agent must infer which guest is being waited on.

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?

It is front-loaded with the core contract in the first line, then layers on cursor semantics and parameter constraints in short, purposeful sentences. The closing note on per-poll incremental I/O is informative but is the one sentence least relevant to deciding whether to call the tool.

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

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

An output schema exists and the description still usefully signals the FOUND/TIMEOUT prefix shape, and it covers timeout and cursor behavior thoroughly for a blocking tool. The unexplained `name` parameter is the only meaningful omission for a 5-parameter 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?

Schema coverage is 0%, so the description carries the load and does well: it constrains `text` to be non-empty, defines from_start as re-searching the whole log, clarifies that timeout_s of 0 or negative still yields one check, and pins poll_interval_s's default and positivity requirement. Only `name` receives no semantic explanation.

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

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

The opening sentence states a specific verb and resource: block until `text` appears on the serial console, or time out. It is immediately distinguishable from the sibling qemu_serial (non-blocking read) and qemu_wait_screen (screen rather than console text) because the blocking-on-console-text behavior is explicit.

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

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

It gives a clear when-to-use rule: the reliable way to know a guest reached a boot stage before typing or screenshotting. It does not explicitly name the alternative (e.g. qemu_serial for a non-blocking read) or state when not to use it, which keeps it below a 5.

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