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

Annotations already declare destructiveHint=true, and the description adds that confirmation is required ('after explicit confirmation'). This introduces a behavioral requirement beyond the annotation, but it does not clarify the confirmation mechanism or consequences of not confirming. No contradiction exists with the annotations.

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

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

The description is a single, compact sentence with no redundant words. It is efficient and earns its place by stating the core purpose, though it omits necessary details.

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

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

For a destructive tool with four parameters and no schema description coverage, the description is insufficient. It does not explain the required parameters, the confirmation mechanism, or the expected output, leaving the agent without critical context to invoke it correctly.

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

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

The description provides no explanation of any parameters (vm, name, confirm, description). With 0% schema description coverage, the agent receives no additional meaning about these fields from the description. It only hints at the VM state, not the specific parameters.

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

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

The description clearly states the action ('create') and the resource ('snapshot of the current VM state'). It distinguishes itself from sibling tools like snapshot_delete, snapshot_revert, and snapshot_list by focusing on the creation aspect, leaving no ambiguity about the tool's purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or conditions beyond the confirmation note. The agent is left to infer that creating a snapshot is the intended use, but there is no explicit routing or 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?

The annotations already include destructiveHint=true, and the description adds that deletion is permanent, that delete_children removes descendant snapshots, and that confirm must be explicitly set to true. These details go beyond the schema and annotations without contradicting them.

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

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

The description is compact and front-loaded: one sentence states the purpose, followed by a terse Args list. It contains no filler and avoids repeating schema titles.

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 4-parameter destructive tool, the description covers purpose, parameter semantics, and a safety requirement. The presence of an output schema means return-value details are not needed, and nothing critical appears missing.

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

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

Schema description coverage is 0%, but the description documents all four parameters: vm and snapshot as name/UUID, delete_children with descendant semantics, and confirm as a mandatory explicit flag. This fully compensates for the lack of schema-level descriptions.

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 'Permanently delete a snapshot to free host disk space,' using a specific verb and resource and clearly stating the purpose. This differentiates it from sibling tools like snapshot_revert or snapshot_create, which have different operations.

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 'to free host disk space' establishes a clear use case, and the confirm parameter note adds an important precondition. It does not explicitly name alternatives or exclusions, but the context is sufficient for basic tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the no-side-effect behavior was already known. The description reinforces that trait but does not add new behavioral context such as ordering, error conditions, or permissions.

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

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

The description is one efficient sentence with no filler. The core action, resource, and read-only scope are front-loaded.

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

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

For a simple, one-parameter list operation with an output schema and read-only annotations, the description covers the essential use. It only falls short on parameter semantics, which is a minor gap here.

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

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

Schema description coverage is 0% and the only parameter, vm, gets no semantic detail beyond its name and string type. The description says 'for a VM' but does not clarify whether vm takes a name, UUID, or path, so it does not compensate for the missing schema 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 description uses a specific verb and resource: 'List snapshots for a VM'. It also distinguishes itself from the mutating sibling tools (snapshot_create, snapshot_revert, snapshot_delete) by noting it does so 'without changing 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?

The phrase 'without changing state' implies this is the inspection tool and not for mutation, but there is no explicit when-to-use guidance or mention of snapshot_create/revert/delete as alternatives. The intended context is clear but left 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 and readOnlyHint=false, covering the mutation and destructiveness. The description adds that the revert occurs 'after explicit confirmation', informing the agent that a confirmation step is required. This goes beyond the annotations by hinting at the confirm parameter and the need for explicit user consent, though it does not specify the mechanics.

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, tightly worded sentence with no extraneous content. It front-loads the action and the key condition (explicit confirmation), making it immediately scannable. It achieves maximum efficiency without losing essential meaning.

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

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

For a destructive operation with three parameters and no schema descriptions, the description is insufficiently complete. It omits critical operational details such as the requirement to set confirm=true to actually execute, the irreversible nature of reverting (data loss), and any information about the output. While the annotation flags destructiveness, the description fails to provide the practical guidance an agent needs 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?

The input schema has 0% description coverage, so the description must compensate for parameter meaning. The description only alludes to the confirm parameter via 'explicit confirmation' but does not explain the vm or snapshot parameters, nor does it clarify that confirm must be set to true for the operation to proceed. This leaves agents guessing about parameter usage.

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

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

The description uses the specific verb 'Revert' and identifies the resource as 'guest state to a snapshot', clearly indicating the action. It distinguishes from sibling tools like snapshot_create or snapshot_delete because it explicitly mentions reverting state, not creating or deleting snapshots. However, it does not explicitly differentiate from potential alternatives like vm_clone, so it earns a 4 rather than 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 description implies usage for restoring a VM to a previously captured state, which is a distinct operation among the snapshot and VM tools. It does not provide explicit when-to-use guidance or mention alternatives, nor does it state when not to use it. The phrase 'after explicit confirmation' hints at a prerequisite but does not elaborate on the condition.

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=true and idempotentHint=true, so the description does not need to restate the safety profile. It adds useful behavioral detail beyond the schema by explaining exactly how latest_only changes the output: latest section only versus the complete changelog.

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

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

The description is concise, front-loaded with the tool's purpose, and then uses a short Args block for parameter details. Every sentence adds value and there is no redundant or filler content.

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

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

For a simple read-only tool with one optional parameter and an output schema present, the description is complete. The agent knows what the tool does, how the flag affects the result, and that the operation is safe due to annotations.

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%, but the description fully explains the only parameter, latest_only, including the behavioral difference between true and false. This is exactly the kind of semantic clarification the schema alone does not provide.

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

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

The description uses a clear verb ('Read') and names the specific resource ('release notes, new features, and bug fixes for parallels-pro-mcp-server'). It is clearly distinct from the sibling VM management tools, which all deal with VM operations rather than the server's own changelog.

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

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

The description clearly implies this is the tool to use when the agent needs the Parallels MCP server's changelog or release notes, and there is no overlapping sibling tool that provides this information. It does not explicitly state when not to use it, but no alternative exists among the siblings, so the context is sufficiently 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 destructiveHint=true and readOnlyHint=false, covering the mutation aspect. The description adds detail about linked vs full clone (sharing base disk), which is a behavioral nuance. However, it does not disclose potential side effects like requiring the source VM to remain for linked clones or any cleanup implications, leaving some gap beyond annotations.

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

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

The description is front-loaded with purpose, then follows a tidy args block. Every sentence adds value: the purpose sentence, and each parameter's role. No fluff; compact and scannable.

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?

All parameters are explained, and an output schema exists to cover return details. It lacks explicit notes on prerequisites (e.g., source VM existence, disk space) or error conditions, but these are minor and can be inferred. Given the output schema and annotation coverage, this is nearly complete.

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

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

Schema description coverage is 0%, so the description fully compensates. Each parameter is explicitly explained: vm (source name/UUID), name (clone name), linked (default and its functional difference), dst (optional custom path). This goes well beyond the schema's bare type definitions.

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

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

Clearly states the action (clone), the resource (existing VM), and the purpose (sandboxes/disposable test environments). The verb is specific and distinguishes it from sibling tools like vm_start or vm_delete.

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

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

Provides explicit context for when to use: 'to quickly spin up sandboxes or disposable test environments.' Does not mention alternatives, but no sibling does an equivalent operation, so the guidance is adequate. Lacks explicit 'when not to use', but that is acceptable given the niche.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the baseline is lower. The description adds that the operation writes to a host path and supports an optional guest user, but it does not disclose overwrite behavior or prerequisites. This is adequate but not rich.

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

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

The description is concise and well-structured: a one-sentence purpose, a short use-case line, and a clean Args list. Every sentence adds value and the most important information is front-loaded.

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

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

For a 5-parameter tool with an output schema and annotations, the description covers the core purpose, all parameter semantics, and typical use cases. It does not mention overwrite behavior or guest prerequisites, but these are partially covered by destructiveHint and are not essential for basic invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains all five parameters with meaningful context: guest_path is 'inside the guest', host_path is 'on the host where file/folder will be written', user is 'optional guest user to read files as', and timeout_s has a default. This goes beyond 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?

The description states a specific action ('Stream a file or directory from a guest path back to the host filesystem') with a clear resource and direction. It distinguishes itself from the sibling vm_copy_to_guest by explicitly saying 'back to the host', making the direction unambiguous.

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

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

The description provides clear use cases: 'Extracts test reports, build artifacts, logs, or files produced inside the VM.' It does not explicitly name alternatives or exclusions, but the directionality and use cases make when to use this tool 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 destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds valuable behavioral detail beyond the annotations: it creates parent directories if absent, uses direct stream execution, and supports multiple guest OSes. It does not elaborate on overwrite behavior, but the annotation coverage lowers the burden and the provided details are meaningful.

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

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

The description is front-loaded with the core action, followed by two short contextual sentences, then a compact Args list. Every sentence adds useful information; there is no filler or repetition of schema-only trivia. The structure is easy to scan and parse.

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

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

Given the tool has five parameters, three required, an output schema, and mutation annotations, the description covers all necessary invocation details: parameter meanings, OS compatibility, automatic directory creation, and timeout behavior. An agent can confidently call this tool without additional external information.

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 Args list in the description is essential. It explains all five parameters, including the distinction between host_path and guest_path, gives guest_path examples, and clarifies that user is optional and timeout_s defaults to 300. This fully compensates for the schema's lack of descriptions.

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: 'Stream a file or entire directory from the host into a guest path.' This clearly distinguishes the direction of copy from sibling vm_copy_from_guest, and the title reinforces the same host-to-guest operation. No ambiguity about what the tool does.

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

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

The description clearly implies when to use the tool: whenever a file or directory needs to be transferred from host to guest. It adds context by stating it works across Windows, Linux, and macOS and that parent directories are created automatically. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for an agent to select it over vm_copy_from_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?

Annotations already mark the tool as destructive, so the bar is lower, but the description adds meaningful context: deletion is permanent, includes all associated disk images, and affects host storage. It also explains the confirm parameter's safety role, which helps the agent understand the operation's consequences.

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

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

The description is compact: a clear one-sentence behavioral summary followed by a two-item parameter list. Every sentence adds necessary information, and the most important fact (permanent deletion) is front-loaded.

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

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

For a destructive VM operation, the description covers the core action, the disk-image impact, and the confirmation requirement. It does not address whether the VM must be in a particular state before deletion, but the output schema and destructive annotations cover some of the surrounding context.

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

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

The input schema has 0% description coverage, but the description explicitly documents both parameters: vm accepts a name or UUID, and confirm must be set to true to prevent accidental deletion. This fully compensates for the schema's lack of detail and adds practical guidance beyond the raw property definitions.

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 ('delete') and resource ('VM'), and adds scope by saying the action permanently removes the VM and all associated disk images from host storage. This clearly distinguishes it from sibling tools like snapshot_delete and vm_stop.

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 about when to use this tool versus alternatives, such as when a snapshot should be deleted instead, or whether the VM must be powered off first. The only safety instruction is about the confirm parameter, which is not usage differentiation.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safe, non-mutating nature is covered. The description adds real behavioral context beyond those annotations by explaining the optional guest inspection path: checks guest OS, runtimes, and environment when a VM is specified.

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 a single sentence, and the Args block is compact and directly useful. There is no filler or repetition beyond the tool 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?

For a read-only diagnostic tool with only one optional parameter, an output schema, and strong annotations, the description is nearly complete. It covers host diagnostics, guest diagnostics when a VM is supplied, and the parameter format. It could be slightly more explicit about host-only behavior when vm is omitted, but that is reasonably inferred.

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 parameter meaning. It does: 'vm' is optional, accepts a VM name or UUID, and triggers guest-side inspection when provided. This adds meaning the bare schema lacks, though it does not detail behavior when the VM is invalid or not found.

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

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

The description clearly identifies the action ('Run diagnostic pre-flight checks') and the scope ('host macOS and Parallels setup, with optional guest inspection'). This distinguishes it from sibling mutations like vm_start or vm_delete and even from status-only tools like vm_status by emphasizing diagnostics and guest environment inspection.

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 term 'pre-flight checks' implies use before VM operations, but the description never explicitly says when to use this tool versus alternatives such as vm_status or vm_optimize_windows. It gives no when-not-to-use guidance or named alternative 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 flag destructiveHint=true and readOnlyHint=false, so the description does not need to restate those. It adds useful context about running inside the guest and the Windows desktop-user fallback, but it does not elaborate on side effects or failure behavior beyond what annotations convey.

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

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

The description is compact and front-loaded with a clear one-sentence purpose, followed by a concise Args list with defaults and examples. Every sentence adds useful information and there is no filler.

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

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

For a 4-parameter tool with an output schema and destructive annotations, the description covers all invocation details: VM identifier, command vector, user handling, and timeout. It lacks usage-alternative guidance, but that is already scored separately; for calling the tool correctly it is nearly complete.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It explains vm, command with concrete examples, the optional user with fallback behavior, and timeout_s with its default. This fully compensates for 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?

The description states a specific verb ('Execute') and a specific resource ('an explicit argv vector inside the guest'), which clearly identifies the operation. The title reinforces this, and the description is distinct from sibling tools like vm_send_keys or file-transfer tools.

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

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

The description explains what the tool does but gives no guidance on when to prefer it over alternatives such as vm_send_keys or vm_copy_to_guest. There are no exclusions, prerequisites, or context about when this tool is the right choice.

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=true and idempotentHint=true, so the read-only behavior is covered. The description adds useful context beyond annotations: it promises exhaustive enumeration ('every registered') and identifies 'current power state' as the data returned. This is adequate for a simple list operation.

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

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

The description is a single, front-loaded sentence with no filler. Every word adds meaning: 'every registered' defines scope and 'current power state' defines the output content.

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

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

For a zero-parameter, read-only listing tool with an output schema and idempotence annotations, the description is complete. It states what is listed and what field is included, so an agent has enough information to select and invoke it correctly.

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

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

The input schema has zero parameters, so there are no parameter semantics to document. The description need not add parameter details, and the baseline for a parameterless tool is appropriate.

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

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

The description uses a specific verb ('List') and a precise resource ('every registered Parallels VM') with an explicit detail ('current power state'). The phrase 'every registered' clearly establishes an inventory operation and distinguishes it from vm_status or single-VM action tools.

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

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

The description implies the tool is for enumerating all VMs and their power states, but it does not explicitly mention alternatives such as vm_status for a single VM or when not to use this tool. The use case is inferable but not 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 indicate destructiveHint: true and readOnlyHint: false, so the mutation is known. The description adds valuable behavioral context: it explains the purpose of the exclusions (preventing EPERM/EBUSY file locks) and the PowerShell ExecutionPolicy setting. It does not contradict annotations, and it provides reasoning for the side effects, enhancing transparency beyond the structured flags.

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

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

The description is structured with a summary paragraph followed by an Args list. It is front-loaded with the purpose and then details the parameters. Each sentence adds value; the inclusion of the specific error (EPERM/EBUSY) is useful context. It is slightly longer than strictly necessary but remains efficient.

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

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

The description covers the tool's purpose, the parameters, and the core actions. It does not mention prerequisites (e.g., VM must be running) or the return value, but an output schema exists. For a configuration tool with three simple parameters, the description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is 0%, so the description is the sole source of parameter meaning. It clearly defines vm (name or UUID), exclusion_paths (directory paths), and exclusion_processes (process binary names with defaults). This fully compensates for the schema's lack of descriptions, giving an agent everything needed to fill parameters correctly.

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

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

The description states a specific action (optimize) on a specific resource (Windows guest VM) for clear goals (automated tasks, testing, script execution). It explicitly lists the two main configuration changes (Defender exclusions and PowerShell ExecutionPolicy), making it distinct from any sibling tool like vm_start or vm_exec.

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

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

The description implies usage: it's for preparing a VM for automation. It clearly states the context (automated tasks, testing, script execution) but does not explicitly contrast with alternatives or state when not to use it. Given the sibling tools are all about VM lifecycle and operations, this is distinct enough that the usage 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 readOnlyHint=true and idempotentHint=true, so the description does not need to repeat that. It does add value by explaining the behavior when output_path is omitted (saved to default artifact directory), which is not captured in annotations or schema. However, it does not describe what the tool returns or any side effects beyond file saving, so a moderate score is appropriate.

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 extremely concise, with only two sentences that front-load the core purpose and then explain the optional parameter. Every word earns its place, and it is well-structured for quick scanning by an agent.

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

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

For a simple capture tool with an output schema, the description covers the essential behavior (capture and save) and the only optional parameter's handling. It does not explain the return value, but the presence of an output schema relieves that burden. The tool is straightforward, and nothing critical appears missing.

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

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

Schema description coverage is 0%, so the description must compensate. It clearly defines 'vm' as the VM name or UUID, and 'output_path' as an optional host path with a default behavior. This adds meaningful context beyond the bare property names, though it could be slightly more detailed (e.g., acceptable file extensions or path constraints). Overall, it sufficiently explains the parameters.

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

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

The description states a specific verb ('Capture') and a clear resource ('screenshot of the VM's current screen buffer'). It unambiguously differentiates from sibling VM management tools by focusing on image capture, so an agent can immediately identify its purpose without confusion.

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

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

The description implies when to use it (when a screenshot is needed) and is distinct from all sibling tools. However, it does not explicitly name alternatives or state 'use this instead of X' scenarios, though the purpose is so clear that no further guidance is necessary. It also provides a practical detail about the output_path default, which informs usage.

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 convey that this is a non-read-only, destructive, open-world operation, so the description does not need to repeat those warnings. It adds useful behavioral detail: keystrokes are 'synthetic', the target must be a 'running VM', multiple keys can be sent 'in order', and delay_ms controls delay 'between key events'. This goes beyond the structured fields without contradicting them.

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

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

The description is front-loaded with the core action and then uses compact bullet lists to enumerate supported inputs and parameters. Every listed example earns its place by illustrating valid input forms. It is detailed enough to be useful without being 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 3-parameter tool with an output schema, this description covers the operation, parameter semantics, accepted input shapes, and sequencing. It could be more complete by noting error conditions (e.g., VM not running) or clarifying that keystrokes go to the guest's active session, but these are minor gaps given the annotations and examples.

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 for explaining parameters. The Args section provides clear semantics for all three parameters: vm as name or UUID, keys as a key name/chord string/list of keys, and delay_ms as the inter-event delay with a default. This fully compensates for the otherwise 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?

The description opens with a specific verb and resource: 'Send synthetic keystrokes or hotkey combinations to a running VM.' It clearly distinguishes this from sibling tools like vm_exec and vm_copy_to_guest by focusing on keyboard input rather than command execution or file transfer. The supported input forms and examples further reinforce what the tool does.

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

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

The description implies usage through examples and supported input types, and the constraint 'to a running VM' gives some context. However, it does not explicitly state when to prefer this over vm_exec or when not to use it, nor does it mention prerequisites like the VM needing a visible desktop or the impact on foreground applications. Usage guidance is adequate but mostly implicit rather than explicit.

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

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

Annotations already mark this as mutable and destructive, and the description adds that it affects the VM's startup-view setting and the resulting rendered mode. It does not disclose whether the change applies immediately, requires a stopped VM, or what side effects occur, but it does not contradict the annotations.

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

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

The description is short, front-loaded with the main purpose, and each sentence serves a clear role. The parameter breakdown is compact, though the boolean explanation could be slightly tighter.

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 setter with an output schema and safety annotations, the description covers purpose and parameters adequately. However, it omits usage guidance and important runtime semantics such as whether the setting takes effect immediately or only after restart, leaving an agent to infer those details.

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

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

The schema has 0% description coverage, so the description carries the full burden. It specifies that 'vm' accepts a name or UUID and explains that 'enabled' maps to headless vs window startup-view, including the default true. This adds meaning that the bare schema does not provide.

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 ('Configure') with a specific resource (the VM) and states exactly what is changed: headless background vs GUI window. It is naturally distinguished from sibling VM operations like vm_start and vm_status because it is the only headless-mode setter.

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 about when to use this tool versus alternatives, nor any prerequisites or exclusions. The purpose implies usage, but the description never says 'Use when...' or mentions related tools that might be confused with it.

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

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

The description discloses the behavioral effect (simulating degraded network or offline state) and how to reverse it ('off' restores normal). Annotations already mark destructiveHint=true, and the description adds that the change is reversible via 'off', which is valuable context beyond the annotations.

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

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

The description is concise (two sentences plus a structured Args section). The purpose is front-loaded, and each line adds value—no filler or redundancy. The format is easy to scan and understand.

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

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

For a simple two-parameter tool, the description covers purpose, parameters, and the disabling behavior. It doesn't detail return values, but an output schema exists (indicated by context), so that is not required. It could mention immediate impact on connectivity, but that is not essential for correct invocation.

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

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

Schema description coverage is 0%, but the description compensates fully. It explains 'vm' as the VM name or UUID and lists all valid 'profile' values with the special meaning of 'off'. This is far more than the schema provides, which only shows types and default.

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

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

The description clearly states the tool's action: 'Simulate degraded network conditions or offline state for the VM.' It identifies the resource (VM) and the specific effect (network degradation or offline). It is distinct from sibling tools, none of which mention network manipulation, so purpose is unambiguous.

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

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

The description provides clear usage context: it simulates degraded network conditions and explicitly explains how to disable simulation using 'off' to restore normal conditions. While it doesn't name alternative tools or state when not to use it, the tool's unique purpose and the parameter guidance make usage clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds no further behavioral context such as overwrite behavior, permission requirements, or reversibility. It merely restates the action, providing minimal value beyond what annotations already 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 a single, front-loaded purpose statement followed by a structured Args block. There is no redundancy or fluff; every sentence earns its place.

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

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

All parameters and defaults are covered, and the output schema presumably defines return values. It lacks mention of prerequisites (e.g., host path existence) or error conditions, but for a straightforward share operation the information is sufficient for correct invocation.

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

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

The description includes an Args block that explains every parameter (vm, name, host_path, mode, description) with defaults, which the schema completely lacks (schema coverage 0%). This fully compensates for the missing schema descriptions and clarifies the mode options and default.

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

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

The description states a clear verb 'Mount' with a specific resource 'host directory' and destination 'Parallels Shared Folder'. This distinctly separates it from siblings like vm_copy_to_guest (copying files) and vm_unshare_folder (removing shares).

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

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

The description does not explicitly state when to use this tool versus alternatives. It implies usage through the action but provides no exclusions or comparisons. An agent would have to infer the appropriate context from the purpose 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?

The annotations already indicate a non-read-only, non-destructive operation, so the description does not need to restate that. It adds the 'registered VM' precondition, but it does not disclose whether starting is asynchronous, can fail if the VM is already running, or requires readiness checking.

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 eight words long, front-loaded with the action, and contains no filler. Every word contributes meaning.

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

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

For a one-parameter mutation tool with an output schema, this is largely complete: the action, target, and parameter format are clear. It would benefit from a note about asynchronous behavior or using vm_wait_ready, but that is not strictly required for correct invocation.

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

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

The input schema provides no description for the single 'vm' parameter, and coverage is 0%. The description compensates by specifying that 'vm' accepts either a name or a UUID, which is essential for correct invocation.

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 ('Start'), a clear resource ('a registered VM'), and the accepted identifier types ('by name or UUID'). It is easily distinguishable from sibling tools like vm_stop, vm_suspend, and vm_list.

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

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

Usage is implied by the tool's purpose: use it when the goal is to power on a VM. However, there is no explicit when/when-not guidance or mention of alternatives such as vm_status to check state or vm_wait_ready after starting.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the useful detail that the status returned is 'bounded', but it does not clarify what that bound is or describe any other behavioral nuances such as missing-VM handling.

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

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

The description is a single sentence with no filler, and the main purpose is front-loaded. It conveys the key scoping constraint ('VM name or UUID') without wasting words.

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

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

For a one-parameter read-only tool with an output schema and read-only/idempotent annotations, the description is largely sufficient to invoke the tool correctly. The main gap is that 'bounded' is vague and there is no guidance on failure or not-found behavior, but the output schema can reasonably cover return details.

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

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

Schema coverage is 0%, so the description carries the burden of explaining the single 'vm' parameter. It does this meaningfully by stating that the value can be a VM name or UUID, which is essential information an agent would not get from the bare schema title 'Vm'.

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

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

The description uses a clear verb ('Return') and resource ('status details'), and specifies that the target is identified by VM name or UUID. This distinguishes it from vm_list and other sibling tools at a basic level, though it does not explicitly contrast with siblings and the word 'bounded' is somewhat ambiguous.

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

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

The intended use is implied: call this when you have a VM name or UUID and need status details. However, the description gives no explicit guidance about when not to use it or which sibling tool to prefer for related needs like waiting for readiness or listing all VMs.

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 mutation nature is known. The description adds the behavioral detail that it never uses force-kill, which is useful context. However, it does not disclose potential side effects like losing unsaved guest OS data, nor does it mention if the operation is synchronous or asynchronous.

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, well-structured sentence that front-loads the primary action ('Request an ACPI shutdown') and immediately clarifies a key behavioral distinction (no force-kill). No wasted words.

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

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

For a destructive operation with a single parameter, the description is minimal but adequate for a basic stop action. It does not mention prerequisites (e.g., VM must be running) or explicitly state the result (VM powers off), but the output schema likely covers return values. The lack of side-effect detail is a moderate gap for a destructive 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?

The input schema has zero description coverage for the only parameter 'vm', and the description provides no explanation of what the parameter represents (e.g., VM name, UUID, or how to obtain it). The agent is left without any guidance on what value to supply.

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

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

The description clearly states the action ('Request an ACPI shutdown') and the resource (a Parallels VM), and specifies the method (ACPI, not force-kill). This distinguishes it from sibling tools like vm_suspend (suspend) and vm_delete (delete).

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

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

The description implies a graceful stop by stating 'never uses force-kill', but it does not explicitly name alternatives or provide when-to-use vs. when-not-to-use guidance. It leaves it to the agent to infer that this is the graceful shutdown option among stop-like operations.

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

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

Annotations already mark destructiveHint=true, and the description adds meaningful context by specifying that guest memory state is preserved. This clarifies the impact of the operation beyond the raw annotation, without contradiction.

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 zero wasted words. It states the action and the key side effect immediately.

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, an output schema exists (so return values are covered), and the description captures the essential behavior. It does not mention prerequisites like the VM being running, but for a straightforward suspend operation this is a minor 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?

With 0% schema description coverage and no parameter documentation in the description, the agent receives no guidance on the 'vm' parameter. Although the name is self-explanatory, the description fails to compensate for the missing schema documentation, violating the low-coverage rule.

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 ('Suspend') and resource ('VM') and adds the clarifying detail 'preserving its current guest memory state,' which distinguishes it from sibling tools like vm_stop. An agent can immediately understand the action and its effect.

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 explicit guidance on when to use this tool versus alternatives such as vm_stop or vm_start. The memory-preservation detail implies a specific use case, but it does not name alternatives or 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 the description adds context by specifying 'previously shared folder' and 'unmount and remove.' It does not disclose side effects or permission requirements, but the destructive nature is covered by annotations.

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

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

The description is extremely concise: one sentence explaining the action, followed by a two-line argument list. Every sentence earns its place, and the primary purpose is front-loaded.

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

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

For a simple two-parameter tool with an output schema, the description covers the essentials. It could mention that the share must exist or describe error behavior, but given the annotations and simplicity, it is sufficiently 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%, and the description compensates by explicitly defining both parameters: 'vm: The VM name or UUID' and 'name: Name of the share to delete.' This adds clear meaning beyond 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?

The description clearly states the action: 'Unmount and remove a previously shared folder from the VM.' This specifies a verb, resource, and scope, distinguishing it from vm_share_folder. The title reinforces the purpose.

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

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

The description implies usage for removing an existing share but does not explicitly state when to use this over alternatives or any exclusions. It lacks guidance on prerequisites like the share must exist or error handling.

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 declare readOnlyHint=true and idempotentHint=true, so the description correctly adds the blocking/polling behavior ('Poll the guest OS') without contradiction. It also gives a concrete readiness condition ('Parallels Tools and execution answering'), which adds value beyond annotations. However, it does not explain timeout behavior (what happens if the guest never becomes ready), which is a minor gap given the annotations already signal safety.

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

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

The description is a single sentence with no filler, front-loading the action ('Poll the guest OS'). It is concise but the phrase 'and execution answering' is awkward and could be clearer, though it does not add unnecessary length. Overall it is well-structured for a short description.

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

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

For a waiting tool, the description fails to explain critical behavior: what happens on timeout (does it return, raise an error?), whether it returns immediately if already ready, and the exact meaning of 'execution answering'. The output schema may define return values, but the timeout behavior is a key side effect that is unaddressed. Given the tool's purpose, 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 description coverage is 0%, so the description must explain the parameters, but it does not. It references the 'guest OS' but never explicitly states that 'vm' is the identifier or how to specify it, and it gives no meaning to 'timeout_s' beyond its name and default value. The agent must rely on parameter names and defaults, which is insufficient for parameters not self-explanatory (especially timeout_s 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 states a specific verb ('Poll') and resource ('guest OS') with a clear goal ('until Parallels Tools and execution answering'), and the title reinforces the intent. It is distinct from siblings like vm_status (which likely just reports state) and vm_exec (which runs commands), but it does not explicitly differentiate itself by naming alternatives.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention that it should typically be used after starting a VM, nor does it suggest using vm_status for a one-shot readiness check instead of a blocking wait. The lack of any usage context leaves the agent to infer when to invoke it.

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