Skip to main content
Glama

new_scene

Destructive

Discard the current stage and unsaved changes, then open an empty USD stage with a chosen up axis and meters-per-unit scale. Save first to keep your work.

Instructions

Discard the open stage, unsaved changes included, and open an empty one in the up axis and units asked for, with a /World Xform as its default prim.

The stage is Z-up in metres when left out: the frame of Isaac Sim's own new stage, its robots, SimReady assets and most robotics scenes, so scripts, payloads and physics written for them need no conversion. up_axis="Y" makes a Y-up stage, as USD Composer's are, and meters_per_unit=0.01 one in centimetres. The answer gives the stage's up_axis and meters_per_unit as read back. Kit places the viewport's camera for the units of its app's own new stages, so in other units place it with set_camera. Call save_scene first to keep the old one. The new stage has no file, so save_scene needs a file_path for it. A recording that runs stops taking frames, and draw_debug's drawings go.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "new_scene"
  }
}

Input Schema

NameRequiredDescriptionDefault
up_axisNoThe stage's up axis: Z, as Isaac Sim's robots and stages are, or YZ
meters_per_unitNoThe stage's metres per unit: 1.0 for metres, 0.01 for centimetres

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.4.1
    • addedInput schema / properties / meters_per_unit
      Added value: +{
      +  "default": 1,
      +  "description": "The stage's metres per unit: 1.0 for metres, 0.01 for centimetres",
      +  "exclusiveMinimum": 0,
      +  "title": "Meters Per Unit",
      +  "type": "number"
      +}
    • addedInput schema / properties / up_axis
      Added value: +{
      +  "default": "Z",
      +  "description": "The stage's up axis: Z, as Isaac Sim's robots and stages are, or Y",
      +  "enum": [
      +    "Z",
      +    "Y"
      +  ],
      +  "title": "Up Axis",
      +  "type": "string"
      +}
  2. First observedv0.2.2

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already flag destructive=true, but the description adds real substance: unsaved changes are lost, the default prim is /World Xform, the new stage has no file so save_scene requires a file_path, an active recording stops taking frames, and draw_debug drawings are cleared. That is concrete disclosure of side effects beyond the annotation.

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?

The destructive action and default prim are front-loaded, then defaults and caveats follow logically. It is dense but almost every sentence carries information; the viewport camera and recording/debug side-effects could be tightened but are not filler.

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?

An output schema exists, and the description still states what is returned (up_axis and meters_per_unit read back). For a destructive two-parameter tool with defaults, everything needed to call and follow up correctly is present.

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?

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining why the defaults matter (Z-up metres matching Isaac Sim robots/SimReady assets and physics) and what Y or 0.01 implies (USD Composer-style Y-up, centimetres). Minor extra value over the enum and default already in the schema.

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 (discard and open) on a specific resource (the open stage), and explicitly says the result is an empty stage with a /World Xform default prim. This is distinguishable at a glance from open_scene (opens a file) and save_scene (persists).

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

Usage Guidelines4/5

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

Gives clear when-to-use context: it names save_scene as the prerequisite to keep the old stage and set_camera as the follow-up when units differ from the app's own. It does not explicitly contrast with open_scene for loading an existing file, which is the one sibling an agent might confuse it with.

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