Skip to main content
Glama

set_material

Create or update an OmniPBR material, set color, opacity, roughness, and metallic values, then bind it to a USD prim to control its appearance.

Instructions

Colour a prim with an OmniPBR material: make the material, or update the one at its path, set its colour and surface values, and bind it to the prim in place of its binding.

opacity, roughness and metallic are set on every call, each to its default when left out, so a call without opacity makes the material opaque. Without material_path the material is /World/Looks/_Mat, so prims of the same name share one and colouring one recolours the rest: give material_path to keep them apart, or to share one on purpose. The binding reaches the prim's children unless they have bindings of their own. For friction and bounce, use set_physics_properties; to repoint bindings after materials move, update_material_paths.

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>",
      "color": "<color>"
    },
    "name": "set_material"
  }
}

Input Schema

NameRequiredDescriptionDefault
colorYes[r, g, b] diffuse colour: 0-1 floats (e.g. [1, 0, 0] for red) or 0-255 ints
opacityNo0 transparent to 1 opaque
metallicNo0 plastic (dielectric) to 1 metal
prim_pathYesFull USD path of the prim, e.g. "/World/Robot"
roughnessNo0 glossy (mirror) to 1 rough (matte)
material_pathNoThe material prim's path; made under /World/Looks/ when empty

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.2

TDQS

A4.9/5.0
Behavior5/5

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

With annotations covering safety hints, the description adds substantial non-obvious behavior: opacity/roughness/metallic reset to defaults on every call, default material naming at /World/Looks/<prim name>_Mat with name-based aliasing, replacement of the existing binding, and inheritance to children unless they have their own bindings. The aliasing/overwrite risk is disclosed even though destructiveHint is false, so there is no contradiction, just useful context.

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

Conciseness5/5

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

Two tight paragraphs: the action summary is front-loaded, then the gotchas (default reset, shared material naming, child inheritance) and sibling routing. No filler sentences; every clause contributes a constraint or a caution.

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 6-parameter mutation tool with an output schema already defining return values, the description covers the risky behaviors (binding replacement, default reset, material aliasing) that an agent must know before calling. Nothing material is left to inference.

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 per-parameter formats (e.g. [r,g,b] scaling) are already documented. The description still adds real meaning beyond the schema by explaining implicit-default semantics for omitted optional params and the sharing consequences of the material_path default, which the schema only states as an empty string.

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 names a specific verb and resource ('Colour a prim with an OmniPBR material') and enumerates the sub-actions taken (create or update material, set colour/surface values, bind). It is clearly distinguishable from siblings like set_physics_properties and update_material_paths, which are named as out of scope.

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 gives explicit routing: use set_physics_properties for friction/bounce and update_material_paths to repoint bindings after materials move. It also states the decision rule for material_path (omit to share by name, supply to keep prims apart or share intentionally), which is exactly the when-to-use guidance an agent needs.

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