execute_script

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

No annotations are provided, so the description carries the full behavioral burden, and it does so thoroughly: policy-gated execution, cooperative timing, output bounding, cwd restriction, code-hash auditing, and background scheduling denial. It also warns about the silent control-path breakage risk for ScriptNode/Action Graph articulations and identifies which diagnostics remain safe.

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 escape-hatch purpose and preferred alternatives, then moves to constraints, hazard warnings, and persistent-controller guidance. The Args section is telegraphic and directly maps to the schema. Every sentence earns its place despite the length.

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 powerful, risky arbitrary-code tool with no annotations, this is remarkably complete: it covers policy restrictions, runtime limits, safety hazards, alternatives, and the background scheduling edge case. An output schema exists, so not explaining return values is acceptable. The only minor omission is command_id/idempotency_key semantics, which is small relative to overall completeness.

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%, so the description must compensate, and it does for most parameters: code, cwd with sys.path behavior, timeout_s as a cooperative capped deadline, max_output_bytes as a per-stream capture limit, and allow_background with default/policy behavior. However, command_id and idempotency_key are not described; their names imply purpose but leave semantics to inference.

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?

Description states a specific action and resource: 'execute arbitrary Python code in Isaac Sim' and labels itself an 'Escape hatch.' It explicitly lists what it is not for by naming preferred sibling tools (set_joint_positions, get_prim_info, step_simulation, get_isaac_logs), making its purpose and scope unmistakable.

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 explicit when-to-use and when-not-to-use guidance: prefer named tools for joints, state inspection, stepping, and logs; use only when no named tool covers the operation. It also tells agents to use reload_script for persistent controllers and to stop_simulation before touching articulations with running graphs.

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