HoudiniMCP

Overview Schema Source Related Servers Discussions Admin

stage_inspect

Read-onlyIdempotent

Read a USD stage from a LOP node in Solaris to inspect prims, layers, composition, attributes, variants, lights, and transforms.

Instructions

Read the USD stage at a LOP node. This cooks the node.

Use it in a Solaris (LOP) network to see the prims, the layers and the
composition that a node produces.

Do not use it for SOP geometry: geometry_inspect does that.

mode:
    "stage"       — the stage: prim count, layers, the default prim.
    "prims"       — the prim tree from `root_prim`, `max_depth` deep.
    "prim"        — one prim at `prim_path`. include_attrs=True adds its
                    attributes.
    "search"      — prims whose path matches `pattern`, filtered by
                    `type_name` such as "Mesh" or "SphereLight".
    "layer"       — the layer stack, and the layer at `layer_index`.
    "attribute"   — the value of `attr_name` on `prim_path`.
    "composition" — where the opinions on `prim_path` come from.
    "variants"    — the variant sets on `prim_path` and the selection.
    "stats"       — counts under `prim_path`.
    "modified"    — the last `count` prims that this node changed. Use it
                    to see what one LOP did.
    "lights"      — the lights on the stage.
    "transform"   — where `prim_path` is in the world: translate, rotate
                    and scale composed through every parent. With
                    `frames`, the path of a moving prim.

Returns JSON.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`mode`	No	One of "stage", "prims", "prim", "search", "layer", "attribute", "composition", "variants", "stats", "modified", "lights", "transform".	stage
`path`	Yes	The LOP node whose stage to read.
`count`	No	modified: how many prims come back.
`frames`	No	Read at another frame, or at several: one frame, a list, or {"start": 1, "end": 10, "step": 2}. The playbar goes back after.
`pattern`	No	search: the prim path to match, with * as a wildcard.
`attr_name`	No	attribute: the attribute to read, for example "points".
`max_depth`	No	prims: how many levels of the tree come back.
`prim_path`	No	prim, attribute, composition, variants, stats, transform: the prim, for example "/world/geo/rock".
`root_prim`	No	prims: the prim where the tree starts.	/
`type_name`	No	search: keep the prims of this type, for example "Mesh" or "SphereLight".
`layer_index`	No	layer: which layer of the stack, from 0 (the strongest).
`include_attrs`	No	prim: also return the attributes of the prim.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed51 schema fields changedv0.7.3Oct 4, 2026

removedInput schema / properties / attr_name / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / attr_name / default
```
Removed value: -null
```

addedInput schema / properties / attr_name / description

Added value: +"attribute: the attribute to read, for example \"points\"."

removedInput schema / properties / attr_name / title
```
Removed value: -"Attr Name"
```
addedInput schema / properties / attr_name / type
```
Added value: +"string"
```

removedInput schema / properties / count / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / count / description

Added value: +"modified: how many prims come back."

removedInput schema / properties / count / title
```
Removed value: -"Count"
```
addedInput schema / properties / count / type
```
Added value: +"integer"
```

changedInput schema / properties / frames / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "items": {
-      "type": "number"
-    },
-    "type": "array"
-  },
-  {
-    "additionalProperties": {
-      "type": "number"
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "number"
+  },
+  {
+    "items": {
+      "type": "number"
+    },
+    "type": "array"
+  },
+  {
+    "additionalProperties": {
+      "type": "number"
+    },
+    "type": "object"
+  }
+]

removedInput schema / properties / frames / default
```
Removed value: -null
```

addedInput schema / properties / frames / description

Added value: +"Read at another frame, or at several: one frame, a list, or {\"start\": 1, \"end\": 10, \"step\": 2}. The playbar goes back after."

removedInput schema / properties / frames / title
```
Removed value: -"Frames"
```

removedInput schema / properties / include_attrs / anyOf

Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / include_attrs / description

Added value: +"prim: also return the attributes of the prim."

removedInput schema / properties / include_attrs / title
```
Removed value: -"Include Attrs"
```
addedInput schema / properties / include_attrs / type
```
Added value: +"boolean"
```

removedInput schema / properties / layer_index / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / layer_index / description

Added value: +"layer: which layer of the stack, from 0 (the strongest)."

removedInput schema / properties / layer_index / title
```
Removed value: -"Layer Index"
```
addedInput schema / properties / layer_index / type
```
Added value: +"integer"
```

removedInput schema / properties / max_depth / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / max_depth / description

Added value: +"prims: how many levels of the tree come back."

removedInput schema / properties / max_depth / title
```
Removed value: -"Max Depth"
```
addedInput schema / properties / max_depth / type
```
Added value: +"integer"
```

removedInput schema / properties / mode / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / mode / description

Added value: +"One of \"stage\", \"prims\", \"prim\", \"search\", \"layer\", \"attribute\", \"composition\", \"variants\", \"stats\", \"modified\", \"lights\", \"transform\"."

removedInput schema / properties / mode / title
```
Removed value: -"Mode"
```
addedInput schema / properties / mode / type
```
Added value: +"string"
```

addedInput schema / properties / path / description

Added value: +"The LOP node whose stage to read."

removedInput schema / properties / path / title
```
Removed value: -"Path"
```

removedInput schema / properties / pattern / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / pattern / default
```
Removed value: -null
```

addedInput schema / properties / pattern / description

Added value: +"search: the prim path to match, with * as a wildcard."

removedInput schema / properties / pattern / title
```
Removed value: -"Pattern"
```
addedInput schema / properties / pattern / type
```
Added value: +"string"
```

removedInput schema / properties / prim_path / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / prim_path / default
```
Removed value: -null
```

addedInput schema / properties / prim_path / description

Added value: +"prim, attribute, composition, variants, stats, transform: the prim, for example \"/world/geo/rock\"."

removedInput schema / properties / prim_path / title
```
Removed value: -"Prim Path"
```
addedInput schema / properties / prim_path / type
```
Added value: +"string"
```

removedInput schema / properties / root_prim / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / root_prim / description

Added value: +"prims: the prim where the tree starts."

removedInput schema / properties / root_prim / title
```
Removed value: -"Root Prim"
```
addedInput schema / properties / root_prim / type
```
Added value: +"string"
```

removedInput schema / properties / type_name / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / type_name / default
```
Removed value: -null
```

addedInput schema / properties / type_name / description

Added value: +"search: keep the prims of this type, for example \"Mesh\" or \"SphereLight\"."

removedInput schema / properties / type_name / title
```
Removed value: -"Type Name"
```
addedInput schema / properties / type_name / type
```
Added value: +"string"
```
removedInput schema / title
```
Removed value: -"toolArguments"
```

Addedv0.1.1Oct 4, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, closed-world, but the description adds two non-obvious behaviors: "This cooks the node" (a read that triggers evaluation and can have side effects) and "The playbar goes back after" for frame reads. These are real behavioral facts not derivable from the annotations, though return-shape and cost details are absent (partly covered by the output schema).

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-loads the core purpose and the SOP exclusion before the long mode enumeration, and each mode entry is one tight clause. The twelve-mode block is lengthy but the entries carry distinct semantics; only light redundancy with the schema's own mode prefixes keeps it from a 5.

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 so return values need not be explained, and the description covers everything else an agent needs: LOP vs SOP routing, the cooking side effect, playbar restoration, and a complete mode-to-parameter contract. Nothing required for correct invocation 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further by mapping each mode to the parameters it consumes (e.g. "search" pairs with pattern and type_name, "modified" uses count, "prim" pairs with include_attrs) and clarifying semantics like the recursive world transform composed through every parent. This is mode-routing meaning beyond the flat per-param schema text.

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 ("Read the USD stage at a LOP node") and immediately scopes it to Solaris/LOP networks. It explicitly names the sibling it is not (geometry_inspect) so an agent can separate it from the SOP-geometry inspection tool without opening a 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?

Gives positive context ("Use it in a Solaris (LOP) network to see the prims, the layers and the composition") plus an explicit exclusion ("Do not use it for SOP geometry: geometry_inspect does that"), naming the alternative. The mode list further tells the agent which selection to make for each intent.

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

Deploy Server