clear_scene

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

With no annotations, the description carries the burden and does substantial work: it discloses environment removal, defaultLight preservation with a rendering rationale, and the effect of both keep flags. It does not address reversibility, unsaved changes, or interaction with simulation state, but the main destructive behavior is clearly exposed.

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: a direct lead sentence, a focused paragraph explaining edge-case behavior, and a short Args block. Every sentence adds operational value, including the defaultLight rationale.

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, no-annotation tool, the description gives enough scenario context—environment reload cost, ground stacking, defaultLight behavior—and parameter guidance to call it correctly. It could mention unsaved-stage or simulation-state effects, but output schema and the clear core description reduce that 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?

Schema description coverage is 0%, and the description compensates for the two meaningful parameters by explaining keep_physics and keep_environment, including why keep_environment is worth passing. Generic command_id and idempotency_key are not documented, but their purpose is broadly inferable and they are not tool-specific.

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 action and resource: 'Remove all prims from the scene,' with clear qualifications about environment, defaultLight, and keep flags. It is distinct from per-prim deletion tools, but it does not explicitly distinguish itself from sibling tools like new_stage or delete_object.

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 concrete usage context: clearing prevents create_physics_scene(floor=True) from stacking a second ground, and recommends keep_environment=True 'when clearing objects between attempts.' It lacks explicit when-not-to-use guidance and named alternatives, but gives clear situational direction.

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