Skip to main content
Glama

create_prim

Creates a USD prim at a given path—shape, Xform, camera, light, or file reference—with optional transforms and physics.

Instructions

Create a prim at prim_path: a shape, an Xform, a camera, a light or any USD type, or a reference to a file.

prim_type is a USD type name: Cube, Sphere, Cylinder, Cone, Capsule, Xform, Camera, DistantLight, DomeLight, SphereLight and the rest. Missing parents are made as typeless prims. A prim already at prim_path keeps its type: one of another type is refused, one of the same type takes the new transform, written as set_prim_transform writes it. A transform it can't write makes nothing. A usd_path file whose upAxis, metersPerUnit or kilogramsPerUnit isn't the stage's is brought to the stage as create_robot brings a robot file: turned upright, scaled, its physics values converted, and the answer says so; one that authors none is left as it is. usd_path adds its reference to a prim already there as the file is. A file that can't be opened is an error. enable_physics puts the RigidBody and Collision APIs on the prim itself, so a shape falls and collides while the simulation plays; the meshes under an Xform or a referenced file's root get no Collision API of their own: give each one with set_physics_properties' collision=True, which makes a static collider without a rigid body. To copy a prim, use clone_prim; for a robot, create_robot.

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": {
      "prim_path": "<prim_path>"
    },
    "name": "create_prim"
  }
}

Input Schema

NameRequiredDescriptionDefault
scaleNoA uniform scale, or [sx, sy, sz]
positionNo[x, y, z] relative to the parent prim, in the stage's units (get_sim_state's meters_per_unit)
rotationNoEuler angles [rx, ry, rz] in degrees, or a quaternion [w, x, y, z]
usd_pathNoA USD file to reference instead of a type: an absolute path on Kit's machine, or a URL
prim_pathYesWhere to create it, e.g. "/World/MyCube"
prim_typeNoUSD type name, e.g. Cube, Sphere, Xform, DistantLightXform
enable_physicsNoAdd the RigidBody and Collision APIs

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.2.3
    • changedInput schema / properties / position / description
      Previous value: -"[x, y, z] in the stage's units (usually metres)"New value: +"[x, y, z] relative to the parent prim, in the stage's units (get_sim_state's meters_per_unit)"
    • changedInput schema / properties / usd_path / description
      Previous value: -"A USD file to load as a reference instead"New value: +"A USD file to reference instead of a type: an absolute path on Kit's machine, or a URL"
  2. First observedv0.2.2

TDQS

A4.6/5.0
Behavior4/5

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

Annotations only declare non-readonly, non-destructive, closed-world; the description goes well beyond them by disclosing implicit parent creation, type-conflict refusal, that a failed transform write aborts creation, upAxis/metersPerUnit/kilogramsPerUnit conversion of referenced files, and unopenable-file errors. The one gap is that it never says what create_prim returns, though an output schema exists to cover that.

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 purpose is front-loaded in sentence one and each subsequent sentence carries distinct behavioral information, so nothing is filler. It is dense and some sentences chain several clauses (the reference-file conversion sentence especially), which costs a little readability.

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?

For a 7-parameter creation tool this covers the important surface: type resolution, transform writing, physics enablement, reference-file normalization, failure modes, and sibling alternatives. An output schema exists, so the absence of return-value prose is not a gap.

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?

With 100% schema description coverage the baseline is 3, but the description genuinely adds meaning: it enumerates valid prim_type values, explains that usd_path references a file instead of a type and how that reference merges into an existing prim, and clarifies that enable_physics applies only to the prim itself, not to descendant meshes.

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?

The first sentence gives a specific verb plus the full range of resources (shape, Xform, camera, light, any USD type, or a file reference) and names the exact creation location parameter. It is immediately distinguishable from clone_prim and create_robot because the description explicitly says what those are for.

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?

It routes the agent to alternatives by name: clone_prim for copies, create_robot for robots, set_prim_transform for rewriting a transform, and set_physics_properties' collision=True for meshes under an Xform or reference. It also states the condition under which a same-type prim is accepted versus refused, which is real when/when-not guidance.

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