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

No annotations are supplied, so the description carries the entire burden of behavioral disclosure. It does not say whether cancellation is immediate or cooperative, whether it is idempotent on an already-finished command, whether partial output remains retrievable via get_command_output, or what the response contains. For a state-mutating tool this is a substantial gap, though the word 'Cancel' does at least convey the mutation intent.

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 short, front-loaded sentence with no redundant clauses or filler. It is efficient, though the efficiency comes at the cost of the detail the description should have carried.

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 mutation tool with no annotations, no output schema and an undocumented required parameter, the definition leaves out everything an agent needs to call it safely and interpret the result. The one identifier it consumes is unexplained, and the effect on subsequent calls to get_command_output or get_command_status is unstated.

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

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

The single parameter 'id' has zero schema description coverage, and the description adds no meaning beyond the bare schema. It never states that the id is the command identifier returned by execute_command or execute_command_async, which is the one clarification an agent actually needs.

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: 'Cancel a running command.' An agent can immediately tell this is the command-termination tool, distinct from execute_command or get_command_status by verb alone. It stops short of 5 because it never names the neighbours it is meant to be chosen over.

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 cancel rather than wait (wait_for_command) or poll (get_command_status), and no mention of preconditions such as the command still being in a running state. The agent must infer the selection rule from the tool name alone.

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

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

With no annotations supplied, the description carries the full disclosure burden. It usefully reveals that recursive and protected-path deletes require approval, implying an approval gating flow, but it never states whether deletes are permanent, what constitutes a 'protected system path', or how an approvalId is obtained. Behavioral context is partial for a destructive tool.

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

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

Two short sentences, front-loaded with the core action and followed by the safety constraint. No filler and nothing redundant repeats the schema.

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

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

For a 5-parameter destructive operation with no annotations, no output schema, and only 40% schema coverage, the description is minimally adequate: the approval gate is surfaced, but the directory flag, irreversibility, and approvalId acquisition path are left for the agent to infer.

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?

At 40% schema description coverage, the description must compensate and only partly does: 'file or directory' loosely maps to the undocumented 'directory' boolean, 'recursive deletes' maps to 'recursive', and the approval sentence hints at 'approvalId'. It still leaves the semantics of the 'directory' flag and the approval workflow 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?

States a specific verb and resource ('Delete a file or directory in the guest'), which clearly separates it from the read-only siblings list_guest_files and read_guest_file. It does not explicitly name those siblings, but the mutation vs. read distinction is unambiguous from the verb 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 when to use it (removing files/directories inside a guest) and adds a key precondition: recursive deletes and protected system paths require approval. It does not name alternatives (e.g., write_guest_file for overwriting) or explain that non-recursive single-file deletes need no approval, so routing guidance remains partial.

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 supplied, so the description carries the full burden, yet it only restates what is returned. It does not disclose whether the VM must be running, whether Guest Additions must be installed for detection to succeed, what happens on failure, or whether the call is read-only and safe to repeat.

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

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

A single front-loaded sentence with no filler. It is efficiently sized, though its brevity edges into under-specification rather than pure conciseness.

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 detection tool with no output schema and no annotations, the description should say what OS families may be reported, what Guest Additions status values mean, and whether the VM must be running. Without those, the agent lacks enough context to interpret results or predict failures.

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

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

There is a single parameter with 100% schema coverage, where 'vm' is documented as a name or UUID, so the schema already does the work. The description adds no additional meaning about the parameter, which meets the 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 names a specific verb (Detect) and a specific resource (guest OS family and Guest Additions status), which clearly separates it from siblings like get_vm_info or get_vm_state. It stops short of explicitly naming an alternative, so it is clear but not fully differentiated.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_vm_info. The agent must infer that this tool is appropriate when guest-level OS or Guest Additions details are needed.

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 supplied, so the description carries the full burden. 'Discard' implies destruction, but the description does not state irreversibility, required approvals, VM power-state constraints, or what happens to the saved state after the call.

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

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

The definition is a single front-loaded sentence with no wasted wording. It is terse but structurally clean and immediately readable.

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

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

For a destructive state mutation with no annotations and no output schema, the description is too thin. It omits approval requirements, side effects, error conditions, and confirmation behavior that an agent would need before invoking it.

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

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

Schema description coverage is 100%, with both 'vm' and 'approvalId' documented in the input schema. The description adds no additional parameter meaning beyond the schema, so the baseline 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 states a specific verb and resource: 'Discard' a VM's 'saved state.' This clearly distinguishes it from save_vm_state by naming the opposite operation, though it does not further differentiate scope or conditions.

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 save_vm_state or start_vm, nor any prerequisites such as whether the VM must be powered off. The presence of an approvalId parameter hints at a gated destructive workflow, but the description itself provides no usage 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?

With no annotations, the description carries the full burden and delivers only the blocking/waiting trait. It says nothing about what happens on timeout, whether a destructive command requires the approvalId flow, how backend selection (auto/guestcontrol/ssh/winrm) affects behavior, or what permissions are needed to reach the guest OS.

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

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

A single front-loaded sentence with no wasted words, which is good structurally. However, the brevity is achieved by omission rather than by efficiency, leaving blocking semantics as the only fact conveyed.

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 an eight-parameter command-execution tool with no annotations and no output schema, the description should explain return shape (exit code, stdout/stderr), timeout behavior, and the approval path hinted at by approvalId. None of that is present, so an agent must guess at execution semantics.

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

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

Schema description coverage is only 38%: vm, shell, and approvalId are documented in the schema while cwd, env, backend, command, and timeoutMs are not, and the description adds no meaning for any of them. Given eight parameters, including a nested env object and two enums, the description does not compensate for the coverage 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+resource ('Run a command in the guest OS') and adds the synchronous qualifier 'wait for its result', which implicitly distinguishes it from the execute_command_async sibling. It does not name that sibling or get_command_output explicitly, so differentiation is left 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?

There is no explicit guidance on when to use this versus execute_command_async, wait_for_command, or get_command_output, nor any note about prerequisites such as guest tools, credentials, or approvals. The only cue is the word 'wait', which implies blocking behavior but never states when a non-blocking alternative should be preferred.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It correctly conveys the asynchronous/non-blocking nature and that a command ID is returned, but says nothing about the approvalId workflow for destructive operations, what happens if the command exceeds timeoutMs, or whether the process survives client disconnection. For a remote command-execution tool with zero annotation coverage, that is a substantial 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, front-loaded with the action and the immediate-return semantics, with the polling hint appended. No filler or redundant restatement of the name.

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

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

This is an 8-parameter, mutation-capable tool with a nested env object, an approval gate, two enum-constrained params, and no output schema and no annotations. A single sentence cannot cover the approval flow, timeout semantics, or backend selection, so an agent would have to open the schema to call it safely.

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 only 38% across 8 parameters; cwd, env, backend, command and timeoutMs are all undocumented in the schema, and the description adds nothing about any of them. The approvalId parameter in particular ('Approval ID issued for a previously requested destructive operation') signals a safety workflow that the description never mentions. With low coverage the description should compensate, and it does not.

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

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

States a specific verb and resource ('Start a command in the guest') plus the key behavioral differentiator 'return immediately with a command ID', which implicitly separates it from the synchronous execute_command sibling. It does not explicitly name execute_command or wait_for_command as the contrasting alternatives, so the differentiation is inferential rather than stated.

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

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

The parenthetical 'poll with get_command_status' gives a concrete follow-up path, which is genuine usage guidance. However, it never says when to pick this over the synchronous execute_command, nor any prerequisites (approval requirements, shell availability on the guest).

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 supplied, so the description carries the full burden and mostly drops it. It discloses only that the result set can be narrowed to a single VM, leaving unstated the ordering of results, the recency window implied by "recent," the default behavior across all VMs, and any result cap.

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 phrase is front-loaded and free of filler, but it is under-specified rather than genuinely concise — six words cannot cover ordering, scope defaults, and the undocumented limit parameter. It sits in an awkward middle ground between the terseness of a bare label and a usable 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?

With no annotations, no output schema, and a 50%-covered input schema, the description needed to carry substantial weight and does not. An agent knows it gets "recent commands" but not how many by default, in what order, whether history is host-wide or per-VM when vm is omitted, or how this differs from the other command-inspection tools.

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

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

Schema coverage is 50%: the vm parameter is documented in the schema as "VM name or UUID," while limit has only a default and maximum and no explanation anywhere. The description's "for one VM" merely restates the schema's vm field and does nothing to explain what limit controls or what happens when it is omitted, so it fails to compensate for the coverage 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?

"Recent commands" identifies the resource being retrieved, and "optionally for one VM" hints at scope, so an agent can roughly tell this returns a command log rather than a single command's status. But it is a noun fragment with no verb, and it never distinguishes itself from near-siblings like get_command_status or get_command_output, which an agent could easily confuse with it.

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

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

There is no when-to-use guidance, no exclusions, and no naming of alternatives such as get_command_status or get_command_output. The only usage signal is the word "optionally," which implies the vm filter is not required, but nothing tells the agent when to prefer this tool over the other command-related siblings.

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

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

No annotations are supplied, so the description carries the full behavioral burden, and it discloses almost nothing. It does not say whether output is buffered/retained after completion, what happens when offset exceeds the output length, whether reading is a blocking or point-in-time snapshot, or whether output can be truncated or expired.

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 single sentence is front-loaded and free of padding, so it is not bloated. However, brevity here comes at the cost of substance: one short clause cannot carry the paging contract, and the near-total absence of detail reads as under-specification rather than concision.

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 zero annotation coverage, no output schema, and 0% parameter documentation, this tool's description is the only source of behavioral information available, and it provides a single clause. An agent cannot determine the paging protocol, stream selection defaults, or error conditions from it.

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

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

Schema description coverage is 0%, and the description only implicitly covers two of the four parameters ('page' implies limit/offset, 'stdout or stderr' matches the stream enum). It never clarifies that 'id' is a command identifier, nor that limit is a byte count, which is the key fact given the 65536 default and 1 MiB cap.

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 verb 'Page through' plus the resource 'a command's stdout or stderr' tells an agent exactly what the tool returns: a chunked read of a command's output stream. It is clear but does not name its siblings (get_command_status, wait_for_command, get_command_history) or explain how it differs from them, so the agent must infer the boundary.

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

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

There is no guidance on when to call this versus get_command_status or wait_for_command, no statement that the command must exist (or be finished) first, and no explanation of the paging loop (read, then advance offset until exhausted). The agent must derive the entire workflow from the word 'Page'.

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 and does disclose the key behavioral trait: this returns output sizes only, not the content. It says nothing about read-only nature, behavior for unknown/expired ids, or whether status is a live poll, leaving meaningful gaps for a polling 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?

A single front-loaded sentence with the disambiguation placed immediately after the purpose, and zero wasted words. Everything the reader needs to orient is in the first clause.

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

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

No output schema, no annotations, one undocumented parameter, so the description must cover return values and does so only partially via 'output sizes only'. What a status actually looks like (running, done, failed) and the fields returned remain unstated.

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

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

Schema coverage is 0% and the lone 'id' parameter is undocumented, but the phrase 'a command started earlier' implies the id is the handle returned by execute_command/execute_command_async. That is useful added meaning, though the description never states the id's origin or format explicitly.

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 resource and action: status lookup for a previously started command, and explicitly contrasts with get_command_output. It stops short of naming the status values returned or the shape of the payload, so the agent knows the category but not the content.

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 parenthetical 'use get_command_output for content' is an explicit routing rule to a sibling for the most likely confusion case. It gives no guidance versus wait_for_command, which is the other plausible alternative when polling for completion.

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, and it does convey that this is a non-mutating informational read by naming only returned data. However, it says nothing about cost, permissions, side effects, or whether the call is slow, so behavioral coverage is only adequate for a trivial zero-parameter query.

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 phrase with zero filler, and the parenthetical listing of returned fields earns its place. It is clipped enough to read as a label rather than a complete sentence, but nothing is redundant.

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

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

With no output schema, the description usefully names the categories of data returned (CPU, memory, VirtualBox version), which is the main thing an agent needs to decide whether to call it. Given the tool's zero-parameter simplicity and lack of annotations, remaining gaps are minor.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a parameterless tool applies. The description correctly does not spend words on nonexistent inputs.

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

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

States the specific resource (VirtualBox host information) and enumerates what it covers (CPU, memory, VirtualBox version), which distinguishes it from the sibling get_vm_info that targets a single VM rather than the host. The verb is only implied by the name, but the resource 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?

Usage is only implied: an agent can infer this is for checking host capacity/version rather than VM-specific data, and no alternative or exclusion is named. There is no explicit when-to-use or when-not-to-use guidance beyond the contrast with get_vm_info carried by the wording 'host information'.

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 disclosure burden, yet it says nothing about error behavior for unknown VM names, required permissions, or whether this is a cheap or expensive call. Only the fact that it reads (rather than mutates) one VM is implied by the wording.

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 noun-phrase sentence with zero filler, and the scope qualifier 'one VM' is placed before any secondary detail. Nothing could be removed without losing information.

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

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

With no output schema and no annotations, the description should indicate what 'detailed configuration and state' actually includes, since the sibling get_vm_state may return a subset. For a tool whose entire value is the shape of its response, this is a significant omission.

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

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

Schema coverage is 100% and the single parameter is already documented as 'VM name or UUID' in the schema. The description adds no further meaning about identifier formats, ambiguity resolution, or whether name lookup is case-sensitive, so the baseline 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 phrase 'Detailed configuration and state of one VM' identifies the resource (a single VM) and the kind of data returned (configuration plus state), which separates it from list_vms by scope. It never names or contrasts with get_vm_state, which sounds nearly identical, so the distinction is left 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?

There is no when-to-use guidance, no statement of prerequisites (must the VM exist, must it be running?), and no mention of the obvious alternative get_vm_state. The agent must guess which of the two VM-inspection tools to call.

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 supplied, so the description carries the full disclosure burden, yet it says nothing about this being a non-destructive read, whether it errors on an unknown VM, or whether state is cached/fetched live. For a simple read tool this is a modest gap, but it is entirely unaddressed.

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

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

A single short clause with zero filler and the key concept front-loaded. It is efficient, though it reads as a fragment rather than a complete sentence with an explicit verb.

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

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

There is no output schema, so the description should indicate what the return looks like, e.g. the set of possible power states (running, paused, saved, stopped). Without that, the agent knows the purpose but not the shape of the answer, which is the main thing missing for a one-parameter query 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 100% and the single parameter already documents that it accepts a VM name or UUID, so the description adds no meaning beyond the schema. Baseline 3 applies when the schema does all the parameter work.

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

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

The description names a specific resource (a VM's power state) with an implicit read verb, which is enough to separate it from siblings like start_vm, get_vm_info, or list_vms. It does not explicitly contrast with wait_for_vm_state, which also reports state, so it falls short of a 5.

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

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

There is no guidance on when to call this versus wait_for_vm_state (which polls until a state is reached) or get_vm_info (which likely includes state among other data). The agent must infer the distinction 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?

No annotations exist, so the description carries the full behavioral burden, yet it discloses nothing about permissions, whether the call is a cheap read, whether results are cached, or what happens if the guest agent is unreachable. The only implicit signal is that it is a non-destructive lookup.

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?

Five words with zero redundancy, but it is a bare noun phrase rather than a structured definition, and the terseness reflects under-specification rather than discipline.

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 with no output schema, the description is minimally sufficient to identify the operation. It is still missing the refresh semantics and the guest-agent prerequisite an agent needs before calling 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 coverage is 50%: 'vm' is documented as 'VM name or UUID', but 'refresh' has no description in the schema and none in the description. The description adds no meaning about what refresh invalidates or when the caller should set it, leaving half the parameters opaque.

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

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

The fragment 'Shells available in the guest' conveys that the tool enumerates shells inside a guest VM, which is slightly more than the name alone. However, it reads close to a restatement of the tool name and never names the sibling it complements (e.g. execute_command) or what a 'shell' means here (bash, sh, powershell).

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

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

There is no when-to-use guidance at all: no statement of prerequisites (guest OS detected, guest agent running), no mention of using the result with execute_command, and no exclusions. The agent must infer the workflow from the 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 says only that it lists a directory and does not describe permissions, error behavior, path resolution, hidden-file behavior, or any other operational trait beyond the basic action.

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

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

The description is a single front-loaded sentence with no wasted words. However, its extreme brevity comes at the cost of under-specification rather than achieving useful conciseness.

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 has three parameters, no annotations, no output schema, and low schema description coverage. The one-sentence description is not complete enough for an agent to understand how to invoke the tool correctly, particularly regarding path handling and the showHidden parameter.

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

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

Schema description coverage is only 33%, with the path and showHidden parameters undocumented in the schema. The description adds no parameter-level meaning at all; it does not explain the vm identifier, path semantics, or the showHidden flag.

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

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

The description states a specific verb and resource: 'List a directory in the guest.' This clearly identifies a directory-listing operation scoped to the guest filesystem. It does not explicitly differentiate this tool from siblings such as read_guest_file or execute_command, which prevents a full score.

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 instead of alternatives such as read_guest_file, execute_command, or other guest-file tools. It only implies that it is for directory listing, leaving the agent to infer all usage 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?

With no annotations, the description carries the full disclosure burden and provides almost none. It does not say whether results are a point-in-time snapshot, whether the call is read-only (implied by "List" but unstated), or what identifying information is returned for each VM.

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

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

A single front-loaded sentence with no filler. It is terse to the point of under-specification, but no wording is wasted.

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

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

For a simple zero-parameter listing tool this is the minimum viable definition, but with no output schema the agent has no idea what the response looks like (VM names, IDs, states?) or whether pagination applies. A sentence on the return contents would close the 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?

The tool takes zero parameters, so there is no parameter meaning to convey and the baseline is 4. The description correctly implies no filtering arguments are needed.

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

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

States a specific verb and resource ("List ... VMs") and the qualifier "running" narrows the scope, which implicitly separates it from the sibling list_vms. It stops short of explicitly saying how it differs from list_vms or get_vm_state, 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?

No when-to-use guidance is given: the description never says to prefer this over list_vms when only active VMs matter, nor does it mention any prerequisites. The agent must guess at the intended situation.

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 behavioral burden. It adds only the policy-visibility constraint; it does not state return shape, pagination, ordering, or whether inaccessible VMs are omitted.

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?

Single front-loaded sentence with no redundant wording. It is appropriately sized for a list tool, though its brevity contributes to gaps scored 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 four-parameter list tool with no annotations and no output schema, the description is too thin. It omits filter semantics, return contents, and policy implications that an agent needs to invoke it confidently.

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

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

Schema coverage is 50%: query and state are documented in the schema, while tag and group are not. The description's 'optionally filtered' does not explain any parameter's meaning or accepted values, so it adds little beyond the schema.

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

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

States a specific verb ('List') and resource ('VirtualBox VMs'), plus scope ('visible under the current policy') and optional filtering. It does not explicitly distinguish itself from sibling list_running_vms, so it falls short of a 5.

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

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

Mentions optional filtering but gives no when-to-use guidance, no exclusions, and does not point to list_running_vms or get_vm_info for narrower queries. An agent must infer tool selection 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?

No annotations are supplied, so the description must carry the full behavioral burden. It says only that the VM must be running and does not explain what pausing does to CPU or memory state, whether it is reversible via resume_vm, required permissions, or errors if the VM is not running.

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 a single front-loaded sentence with no redundant wording. Brevity is appropriate here, though the omitted detail is penalized under other dimensions.

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 mutation tool with no annotations and no output schema, the description is too thin about the operation's effect and lifecycle relationship. It tells the agent the action but not enough about state preservation or resume behavior to use it confidently alongside save_vm_state and shutdown_vm.

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%; the vm parameter is already documented as a VM name or UUID. The description adds no parameter-level detail, which is the expected baseline when the schema is complete.

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 (Pause) and resource (VM) and adds the precondition 'running'. It does not explicitly contrast with sibling lifecycle operations such as save_vm_state or shutdown_vm, so it falls short of a 5.

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

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

Use is implied by 'running VM', giving a basic precondition. It does not state when not to use it or name resume_vm or save_vm_state as alternatives, so routing guidance remains implicit.

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 and clearly discloses the destructive, data-losing nature of the operation. It does not mention approval requirements or permissions, but the core risk is stated plainly.

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 immediately followed by the critical risk. There is no 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 simple destructive VM operation with no output schema, the description covers the essential risk. The approvalId workflow is left to the schema, which is acceptable given full schema coverage.

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

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

Schema description coverage is 100%, so the vm and approvalId parameters are already documented in the schema. The description adds no additional parameter meaning beyond the schema baseline.

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: "Force power-off" a VM, and clarifies the force semantics with "like pulling the plug." It does not explicitly name the graceful alternative shutdown_vm, so sibling differentiation is implied rather than stated.

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

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

The warning that unsaved guest data is lost implies this is for forced termination rather than graceful shutdown, but it gives no explicit when-to-use guidance or comparison to shutdown_vm, reset_vm, or other siblings.

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

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

With no annotations provided, the description carries the full behavioral burden but only states that it reads a file. It does not disclose permission requirements, error handling, what happens when the file is too large, how encoding is applied, or whether reads are non-destructive. The read implication is useful but far from complete.

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

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

The description is a single short sentence with no wasted words, but its brevity reflects under-specification rather than effective conciseness. There is no structure or front-loaded detail to help an agent understand the operation beyond the bare verb and resource.

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 four parameters, no annotations, and no output schema, the description is completely inadequate. It omits essential context about VM prerequisites, file path semantics, encoding and size handling, and return behavior, leaving the agent unable to call the tool confidently.

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

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

Schema description coverage is only 25%, and the description does not compensate. It vaguely maps 'guest' to the vm parameter and 'file' to path, but says nothing about path format, the encoding default and base64 behavior, or what maxBytes does when a file exceeds the limit.

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: 'Read a file from the guest.' It clearly indicates a read operation on a guest file, which distinguishes it from siblings such as write_guest_file and delete_guest_file. However, it does not clarify whether 'guest' means VM guest OS or something else, leaving minor ambiguity.

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

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

The description provides no guidance on when to use this tool versus alternatives like list_guest_files or execute_command. It does not mention prerequisites such as the VM needing to be running or guest tools being available, so the agent must infer usage 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?

With no annotations, the description carries the full burden, and it does disclose the key consequence: unsaved guest data is lost. It omits other important behavior for a destructive power operation — that an approvalId may be required, whether the reset is reversible, and what state the VM is left in — so the safety profile is only partially covered.

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

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

Two short sentences, action front-loaded and the destructive consequence immediately after. No filler or redundancy.

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

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

For a destructive power operation with no annotations and no output schema, the description covers the primary risk but leaves the approval flow and post-reset state unaddressed. It is 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 coverage is 100%, so both the vm identifier and the approvalId semantics are already documented in the schema. The description adds nothing about either parameter; the baseline 3 applies when the schema does all the work.

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

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

States a specific verb and resource ("Hard reset a VM") and the word "hard" signals it differs from a graceful shutdown. However, it never names the sibling it is distinct from (shutdown_vm, poweroff_vm, discard_saved_state), so an agent must infer the boundary from the adjective 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 warning that unsaved guest data is lost implies this is the abrupt, last-resort option, but the description gives no explicit when-to-use versus shutdown_vm or poweroff_vm and no preconditions. Usage is inferable rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not disclose permissions required, whether the operation is idempotent, what happens if the VM is not paused, or what side effects occur, leaving significant gaps for a mutation tool.

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

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

The description is a single, front-loaded sentence with no unnecessary wording. It communicates the core action efficiently, though its brevity contributes to gaps assessed in other dimensions.

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 mutation tool with no annotations and no output schema, the description is too sparse. It omits prerequisites such as the VM needing to be paused, expected effects, and error conditions, which an agent would need to invoke it correctly.

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

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

The input schema fully documents the single parameter as 'VM name or UUID' with 100% coverage. The description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: resume a VM. It also narrows the target to a paused VM, which helps distinguish it from start_vm, but it does not explicitly name or contrast with sibling tools such as start_vm or pause_vm.

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

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

Usage is only implied by the phrase 'paused VM'; there is no explicit guidance on when to use this instead of start_vm, nor any stated exclusions or prerequisites. An agent must infer the correct context from the tool name alone.

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

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

With no annotations supplied, the description carries the full burden; it does disclose the key side effect that the VM is stopped and its state persisted. It omits important behavior: whether the saved state can later be resumed via start_vm, whether it frees host memory, and any preconditions (VM must be running, guest-tools needs).

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

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

A single front-loaded sentence with zero filler, immediately conveying action and effect. It is efficient, though its brevity leaves little room for the contextual guidance an agent would benefit from.

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 state-changing operation with a fully described schema and no output schema, the essential information (persist state and stop) is present. Missing are restore/resume semantics and preconditions, which are relevant but secondary for calling the tool correctly.

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

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

The single 'vm' parameter is fully documented in the schema as name or UUID, so the description need not repeat it. It adds no extra meaning such as accepted identifier formats, ambiguity resolution, or error behavior for unknown VMs, leaving the baseline.

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 (save) and resource (VM state), plus the concrete effect ('to disk and stop it'), which separates it from shutdown_vm, poweroff_vm, and pause_vm in the sibling list. It does not name those siblings explicitly, so differentiation is inferential rather than spelled out.

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 the alternatives an agent must choose between (pause, shutdown, poweroff, discard_saved_state). Usage is only implied by the stated effect.

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 present, the description carries the full burden and does disclose the important trait that this is a graceful, non-forcing operation via ACPI. It does not say what happens if the guest ignores the request, whether a timeout produces an error or a returned state, or what permissions are 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?

Two short sentences with zero filler, and the key behavioral constraint (graceful, never forced) is front-loaded where an agent will see it first.

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 action with no output schema and no annotations, the description covers the essentials: what it does and how it differs from a forced power-off. The remaining gap is post-call behavior on timeout, which the agent would need to infer.

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

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

Schema coverage is 100%, so both vm and waitMs are already documented in the schema, which sets the baseline at 3. The description adds no extra meaning about waitMs, e.g. whether 0 means fire-and-forget or whether a timeout causes a failure.

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 (shut down) and resource (VM) and adds the mechanism, ACPI power button, which makes it clearly distinct from a hard power-off. It stops short of naming the sibling poweroff_vm, so differentiation is implied rather than explicit.

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

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

The clause 'Never forces power-off' gives a usable selection rule: pick this for an OS-cooperative shutdown and something else when a forced kill is required. It never names poweroff_vm or reset_vm as the alternative, and gives no prerequisites such as guest tools or ACPI support being required.

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 supplied, so the description carries the full behavioral burden, yet it discloses nothing about the mutation: no statement of what state the VM must be in, whether the call blocks until the VM is running, whether it is idempotent, or what errors occur on an already-running VM.

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?

At three words there is no wasted text, but this is under-specification rather than conciseness. The single sentence does not front-load any information an agent could not already get from the tool name.

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

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

For a state-changing VM lifecycle tool with an enum-typed mode parameter and no annotations and no output schema, the definition is completely inadequate. Nothing tells the agent how to choose between headless, gui, and separate, or what to expect after the call.

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%: the 'vm' parameter is documented in the schema, but the 'type' enum (headless/gui/separate) has no description anywhere. The description adds zero meaning about either parameter, so the undocumented enum mode — arguably the most consequential choice here — is left 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?

"Start a VM." restates the tool name and nothing more; it is a tautology of start_vm. It gives no indication of how this differs from siblings such as resume_vm, save_vm_state, or reset_vm, all of which also change VM power state.

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

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

There is no when-to-use guidance, no prerequisites (e.g. the VM must be stopped or suspended), and no pointer to the alternative tools in the sibling list. The agent must infer the selection rules entirely from tool 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 full burden, yet it only discloses that the call blocks until completion. It does not say what happens on timeout (a real risk given timeoutMs, which has a 600000 ms maximum), whether a timeout raises an error or returns partial status, or how this differs behaviorally from polling.

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 single sentence is front-loaded with the blocking action and contains no filler or redundancy. It is efficient, though its brevity is partly under-specification rather than disciplined conciseness.

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 operation with no annotations, no output schema, and zero parameter documentation, this description is too thin. It should at minimum explain the id's referent and what a timeout returns, since nothing else in the definition does.

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

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

Schema description coverage is 0%, so the description must compensate, and it does not. 'id' is never explained as a command identifier, and timeoutMs is not mentioned at all, leaving the agent to infer both the meaning of the id and the timeout's effect from the bare schema types and defaults.

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

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

The description gives a specific verb and resource: wait for an async command to finish and return its result. It implies a blocking wait, which is distinct from the polling implied by siblings such as get_command_status and get_command_output, but it never names or differentiates itself from those siblings explicitly.

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

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

The phrase 'async command' hints that this follows execute_command_async, but there is no explicit when-to-use guidance. Nothing says whether to prefer this blocking call or the get_command_status/get_command_output polling siblings, and no conditions or prerequisites are stated.

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

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

With no annotations, the description carries the full behavioral burden, yet it omits critical traits: polling interval, timeout failure behavior (throw vs. return), whether the call blocks the request, and what is returned on success or timeout. Only the basic wait-until semantics are stated.

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 single sentence is front-loaded and waste-free, but for a blocking tool with three parameters and no annotations it is under-specified rather than concise. It would benefit from one or two additional sentences covering timeout and return behavior.

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?

A wait/polling tool with an undocumented timeout parameter, no output schema, and no annotations is not adequately described by one generic sentence. The agent cannot know expected timing, failure modes, or what result to expect after the wait resolves.

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 only 33% — only 'vm' has a description. The description does not compensate: it never explains the 'states' array (valid values, whether partial matching applies), nor the 'timeoutMs' parameter (default 60s, max 600s, and what happens on expiry). 'One of the given states' adds only a small hint about OR 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 uses a specific verb-resource pair ('Wait until a VM reaches one of the given states'), which is more informative than the name alone. It does not explicitly distinguish itself from the sibling get_vm_state (one-shot read), leaving the agent to infer that this is the blocking/polling variant.

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 instead of get_vm_state or how it relates to other waiting siblings such as wait_for_command. No exclusions, preconditions, or notes about calling it when the VM is already in a terminal state are provided.

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 discloses that the tool writes or appends and that protected paths require approval, which is useful, but it does not explain overwrite behavior, whether approvalId is needed for all writes or only protected paths, encoding behavior, or the impact of createParents.

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 wasted words, and the primary purpose is front-loaded before the approval caveat.

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 seven-parameter mutating tool with no annotations, no output schema, and low schema description coverage. The description gives only the basic action and an approval caveat, leaving important behavior and parameter details unexplained for an agent to invoke it safely and 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 only 29%, so the description needs to compensate for undocumented parameters. It adds some meaning for append and protected-path approval, but says nothing about vm, path, content, encoding, or createParents, leaving most parameter semantics to sparse schema names and defaults.

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

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

The description states a specific verb and resource: write or append to a file in the guest. This distinguishes it from sibling tools such as read_guest_file, list_guest_files, and delete_guest_file without ambiguity.

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

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

The description gives one useful usage condition: protected system paths need approval. However, it does not explain when to use append versus overwrite, how to obtain the approval, or any explicit alternatives or exclusions beyond what is obvious from the sibling tool names.

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