Skip to main content
Glama

execute_script

Destructive

Run Python inside Omniverse Kit apps on the main thread to perform tasks no dedicated tool covers and return serialisable results, output, or errors.

Instructions

Run Python inside the Kit app (Isaac Sim, USD Composer, ...) on its main thread, for what no tool does.

Prefer a tool that does the job: it checks its input and bounds its waits. The script has omni, carb, Usd, UsdGeom, UsdLux, UsdPhysics, Sdf, Gf and mcp. Assign to 'result' to return JSON-serialisable data (anything else comes back as its str); stdout and stderr come back too, and an exception as an error with the traceback's last lines. A script that blocks freezes Kit: the call gives up after 120 s, and the script runs on. For work that may outlast 120 s, such as settling many objects under physics, use run_script_job: it runs as a job while Kit renders and other tools answer, and get_job reads its progress and result.

mcp calls the tools' handlers from the script, each returning a dict with "status" and "result". Await them, which makes the script async: bounds = await mcp.prim_bounds("/World/Cube"), then result = bounds["result"]. Its methods: capture_viewport(width, height, camera_path), set_camera(position, target), look_at(prim_path, distance, azimuth, elevation), inspect(prim_path, angles, width, height, zoom_offset=0.0, isolate=False), scene_tree(root, max_depth), prim_properties(prim_path), prim_bounds(prim_path), set_transform(prim_path, position, rotation, scale), create_prim(prim_path, prim_type, **kwargs), delete_prim(prim_path), set_material(prim_path, color, opacity, roughness, metallic), sim_control(action), sim_state(), get_logs(count, min_level, channel, search).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "code": "<code>"
    },
    "name": "execute_script"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeYesPython to run inside the Kit app; assign to result to return data

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.2

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond annotations: main-thread execution, a 120 s call timeout, the fact that the script keeps running after the call gives up, and that a blocking script freezes Kit. It also documents the return contract ('assign to result' for JSON-serialisable data, else str), stdout/stderr capture, and exception-as-error with the traceback's last lines. The destructiveHint/openWorldHint annotations are consistent with arbitrary code execution.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the primary constraint (prefer dedicated tools) before the escape hatches, and each paragraph maps to one decision: whether to use it, how results come back, timeouts, and the mcp bridge. The mcp method enumeration is long but is functional API reference the agent cannot get elsewhere; minor cost is dense backtick-cluttered prose.

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

Completeness5/5

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

Covers everything an agent needs for a powerful escape-hatch tool: safety framing, timeout and freeze semantics, return/error conventions, and an in-script tool bridge with exact call syntax and awaited-handler pattern. With an output schema and annotations already present, nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter, and schema coverage is 100%, so the baseline is 3; the description still adds real meaning by explaining the 'result' convention, what serialisation rules apply, and how stdout/stderr and exceptions surface. It does not restate the parameter needlessly, though it could say whether the code runs in a fresh namespace.

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

Purpose5/5

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

States a specific verb and resource ('Run Python inside the Kit app ... on its main thread') and gives a scope qualifier ('for what no tool does') that separates it from the ~45 siblings. It also names the environment variants (Isaac Sim, USD Composer) so the agent knows the runtime context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly prefers dedicated tools ('Prefer a tool that does the job') with a reason (validated input, bounded waits), making this the fallback. It also names the concrete alternative and the condition that selects it: work that may outlast 120 s, such as settling physics, should use run_script_job with get_job for progress.

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