Skip to main content
Glama

clone_prim

Copy a USD prim and all its children to a new path, optionally creating multiple copies spaced by an offset in the parent space.

Instructions

Copy a prim with everything under it to a new path, once or as a row of count copies.

The first copy sits on the source and each next one moves by offset from the one before, so a single copy is never moved: move it with set_prim_transform. With offset, copy n moves n times offset from the source in the parent's space, through its own translate op or matrix, its other ops and placement kept; the first copy, and a single copy, are left as copied. A source whose position can't be written copies nothing. It copies what the stage's root layer holds at source_path, its references included, so a prim from a sublayer, or from inside a referenced asset, can't be copied whole. A target path that already holds a prim is refused before anything is copied. For a new prim, use create_prim.

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": {
      "source_path": "<source_path>",
      "target_path": "<target_path>"
    },
    "name": "clone_prim"
  }
}

Input Schema

NameRequiredDescriptionDefault
countNoHow many copies: one goes to target_path, more to target_path_001, _002, ...
offsetNo[x, y, z] in the parent's space: each copy after the first sits this far from the last
source_pathYesThe prim to clone, e.g. "/World/MyCube"
target_pathYesWhere the copy goes, e.g. "/World/MyCube_Copy"

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.2.3
    • changedInput schema / properties / count / description
      Previous value: -"How many copies; paths get _001, _002, ..."New value: +"How many copies: one goes to target_path, more to target_path_001, _002, ..."
    • changedInput schema / properties / offset / description
      Previous value: -"[x, y, z] each copy moves from the one before"New value: +"[x, y, z] in the parent's space: each copy after the first sits this far from the last"
  2. First observedv0.2.2

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations (which only say it is a non-readonly, non-destructive, closed-world write), the description discloses exactly what is copied (root-layer contents including references), what silently fails ('a source whose position can't be written copies nothing'), and that target collisions are rejected before any copying happens. The offset naming scheme and the fact that the first/single copy is never displaced are also spelled out.

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

Conciseness3/5

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

The core behavior is front-loaded, but the offset rules are stated twice in slightly different wording ('each next one moves by offset from the one before' vs. 'copy n moves n times offset from the source'), and the opening sentence's clause about a single copy never being moved is syntactically tangled. Trimming the duplicated offset explanation would make it sharper.

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 mutation tool with four parameters and an output schema, this covers purpose, alternatives, failure modes, and transform semantics without needing to describe return values. An agent has everything required to call it correctly and to know when it will not work.

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 the baseline is 3, but the prose adds genuine meaning: offset is applied cumulatively through the copy's own translate op or matrix while all other ops and placement are preserved, and the schema's _001/_002 naming for count is reinforced. It does not restate every parameter, which is appropriate given the schema already documents them.

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 opening sentence gives a specific verb (copy) plus resource (prim) and scope ('with everything under it', 'once or as a row of count copies'), which no sibling does. The closing sentence explicitly separates it from create_prim, so an agent can route without inspecting either schema.

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 names concrete alternatives and the conditions that select them: set_prim_transform for moving a single copy, create_prim for a new prim. It also states hard when-not conditions (sublayer or referenced-asset prims can't be copied whole, existing target paths are refused), so the agent can predict failures before calling.

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