Run the runtime

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It fully discloses execution mode (real-time, paced), stopping conditions (all scripts finish or budget), and the comprehensive return payload (sprite positions, variables, lists, monitors, bubbles, pending questions, thread count, errors, and an ordered events timeline). It also hints at internal behavior like waits, timers, and glides functioning correctly. No contradictions with annotations (none exist).

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 moderately long but every sentence earns its place. It opens with the primary action and return, then explains default execution, then enumerates the return contents, then highlights the unique events timeline. The front-loaded structure delivers the core purpose immediately, and the rest is organized logically. Minor redundancy in listing return fields twice (state snapshot and then details) but it 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?

For a tool with no output schema, the description provides a thorough explanation of what is returned and when execution stops. It mentions the events timeline and its purpose (to assert sequence), which is valuable for an agent. It does not specify the exact JSON shape of the output, but given the descriptive list of contents, an agent can infer the general structure. The absence of explicit error-handling details or partial-state semantics is a minor gap, but overall the description is complete enough for effective use.

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 covers all four parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds semantics beyond the schema by explaining how the default behavior relates to parameters (e.g., 'runs in real time' ties to paced/seconds, 'budget elapses' ties to seconds/frames, 'until every script finishes' ties to untilIdle). This contextualization helps an agent reason about parameter combinations without opening 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?

The description states a specific verb and resource: 'Advance the headless VM' and 'return a state snapshot'. It clearly differentiates from siblings like vm_state (which likely returns state without advancing) by emphasizing progression and returning a timeline of events. The wording is not a tautology and precisely captures the tool's role.

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 details default behavior (real-time execution until scripts finish or budget elapses) and what the tool returns, making its purpose self-evident. It does not explicitly name alternative tools or state 'when not to use', but the clear semantics of advancing vs. inspecting (siblings vm_state, vm_green_flag) make the usage context obvious. A slight deduction for lacking explicit disambiguation.

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