Run a guest command

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

Annotations already cover the safety profile, yet the description adds substantial behavior: automatic before/after snapshots, a step derived from the call, the pending imageId download lifecycle, timeout bounds (default 120000, max 3600000), VM retention on refused/uncertain/nonzero results, and what diagnostic mode does and does not record. That is rich context beyond the structured fields.

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?

Dense but front-loaded: the core one-command rule and the evidence model come first, then optional enrichments and the result lifecycle. Every clause carries information, though the single-paragraph density makes it slightly harder to scan than a bulleted structure.

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

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

For a 6-parameter nested-schema tool with no output schema, it covers execution bounds, snapshot timing, result shape, and the imageId handoff to relay_image, plus the diagnostic variant's distinct output. The main gap is the absence of explicit contrast with relay_run/relay_script for choosing between command execution modes.

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 83%, so baseline is 3, but the description adds real meaning: reason is 'intent, never authorization', step fields enrich/derive the record, snapshots.group phases govern which sides get snapshots, and diagnostic is 'never visual verification' with a single combined output field. This exceeds what the schema alone conveys.

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

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

Opens with a specific verb+resource and a distinguishing scope rule ('Run one guest command (`argv`) as one recorded operation; never hide several interactions in one call'), which separates it from batch/script siblings. It also names adjacent tools (relay_image, relay_stage) so the agent can place it in the workflow.

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 clear routing rules: call relay_image with the pending imageId to see the after-snapshot, use diagnostic:true for diagnosis/repair even before relay_stage, and never replay input whose effect is uncertain. It lacks an explicit when-to-use-this-vs-relay_run/relay_script/relay_code comparison, so it stops short of full alternative coverage.

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