vm_boot

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 does real work: it discloses that the VM runs headless, that the call blocks and waits before reporting status, and that a full Windows install under pure TCG can take 30-90+ minutes. It omits any statement about required permissions or whether the boot state change is reversible, which keeps it from a 5.

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

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

The core action and the boot-code mapping are front-loaded in the first sentence, and the second paragraph is short. The screenshot and TCG timing advice is useful but reads as slightly incidental rather than tightly integrated.

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

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

An output schema exists, so return values need not be described, and the description covers the hard parts: boot-code semantics and realistic timing expectations. The gap is the unexplained wait_seconds parameter and the absence of a stated prerequisite that the VM must already be created and running.

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 there is no enum on 'boot', so the description's decoding of 'd' = CD-ROM first and 'c' = disk is the only place that meaning exists and is genuinely load-bearing. However, 'name' and 'wait_seconds' (the default 45s wait) are left entirely undocumented in both schema and description, so only one of three parameters is explained.

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

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

States a specific verb and resource ('Boot the VM headless') and immediately disambiguates the cryptic 'boot' values, which separates it cleanly from siblings like vm_create, vm_status and vm_restore. An agent knows exactly what this call does without opening the schema.

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

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

Gives concrete follow-up routing: 'Take a screenshot afterwards' points to vm_screenshot and 'snapshot right after setup milestones' points to vm_snapshot. It does not state prerequisites (VM must already exist) or when not to use it, so it stops short of full when/when-not guidance.

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