step_simulation

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It explains that step is self-contained, initialises physics on first call, operates on a paused/stopped timeline, always advances exactly N frames, and returns an error if the timeline is already playing. This is strong behavioral context, though it does not address all possible side effects or failure cases.

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 purpose, then provides a concise warning about play_simulation, a practical debug loop, and a short parameter list. Every section earns its place; there is no filler or redundant repetition of schema 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?

For a complex simulation stepping tool, the description gives essential operational context, alternative routing, and parameter semantics. The presence of an output schema covers return value details, and the description explains enough for typical use. The only gap is the undocumented command_id and idempotency_key, which prevents a perfect score.

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 adds meaningful semantics for num_steps, observe_prims, and observe_joints, all of which have no schema descriptions. However, command_id and idempotency_key are left completely unexplained, and with 0% schema description coverage the description must compensate more fully. It covers the main functional parameters but misses two potentially relevant ones.

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: 'Advance the simulation by exactly N physics frames on a FROZEN timeline.' It clearly distinguishes this tool from play_simulation and other simulation controls, and the purpose is immediately obvious without needing to inspect the schema or siblings.

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 explicitly states when to use and not use this tool: 'Do NOT call play_simulation before or during the debug loop' and 'Use play_simulation ONLY for a final continuous run / ScriptNode-driven demo, never for debugging.' It also provides a numbered debug loop showing exactly how to combine it with sibling tools.

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