Skip to main content
Glama

set_variant_selection

Selects a variant in a prim's variant set or clears a layer's selection, then waits until the viewport reflects the change.

Instructions

Select a variant in a prim's variant set, or clear a layer's selection, and wait until the viewport shows it.

By default the selection goes to Kit's session layer: it shows at once over what the files select, and save_scene leaves it out of the file, so a check leaves every file as it found it; it lasts until it is cleared or the stage is opened again. To keep one in the stage's file, use layer="edit_target", where edits go: the root layer, which save_scene writes, unless Kit's Layer window made a sublayer the edit target, which save_scene doesn't write; the answer names the layer. It is refused while the session layer holds a selection for the set, since that would hide it: clear that first with variant_name="". An extension older than the server writes every switch at the edit target and can't clear, and the answer warns. get_prim_properties' variant_sets line lists a prim's sets, their options and the layer holding each selection. A selection on an instance prim gives it a prototype of its own; a prim inside an instance is refused, naming the instance. An unknown set or variant is refused, listing those there (create_variant_structure makes them). Switch variants with this rather than execute_script: with Fabric Scene Delegate on before Kit 110 (Isaac Sim 5.x), it deactivates and reactivates the prim in the session layer around the switch, some 40 app updates, so the viewport drops the old geometry; otherwise it waits 5. compare_prims measures two variants and leaves the selection as it was.

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>",
      "variant_set": "<variant_set>",
      "variant_name": "<variant_name>"
    },
    "name": "set_variant_selection"
  }
}

Input Schema

NameRequiredDescriptionDefault
layerNosession: Kit's session layer, which no save writes, so every file stays as it is; edit_target: where edits go, the stage's root layer, which save_scene writes, unless Kit's Layer window made a sublayer the edit targetsession
prim_pathYesThe prim with the variant set
variant_setYesThe variant set's name, e.g. "model"
variant_nameYesThe variant to select, e.g. "shell"; "" clears the layer's selection, so the one beneath shows again

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.4.1
    • addedInput schema / properties / layer
      Added value: +{
      +  "default": "session",
      +  "description": "session: Kit's session layer, which no save writes, so every file stays as it is; edit_target: where edits go, the stage's root layer, which save_scene writes, unless Kit's Layer window made a sublayer the edit target",
      +  "enum": [
      +    "session",
      +    "edit_target"
      +  ],
      +  "title": "Layer",
      +  "type": "string"
      +}
    • changedInput schema / properties / variant_name / description
      Previous value: -"The variant to select, e.g. \"shell\""New value: +"The variant to select, e.g. \"shell\"; \"\" clears the layer's selection, so the one beneath shows again"
  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?

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes far beyond by explaining persistence semantics (session layer never written by save_scene, lasts until cleared or stage reopened), refusal rules, the extension-version caveat that warns instead of clearing, and the 40-app-update deactivate/reactivate path under Fabric Scene Delegate.

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 action is front-loaded, but the prose is dense and run-on, packing several conditionals into single sentences. Nearly every sentence carries information, yet it would be far more scannable as bulleted points or short clauses.

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 an output schema and partial annotations, the description covers the edge cases an agent needs: layer persistence, clearing, refusals, instance behavior, delegate-specific timing, and sibling alternatives. Nothing essential 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 baseline is 3, but the description adds parameter-level consequences not present in the schema: that edit_target may resolve to a sublayer and the answer names it, and that variant_name="" is required to clear before switching layers. This meaningfully raises it above baseline.

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 states a specific verb and resource: 'Select a variant in a prim's variant set, or clear a layer's selection.' It also distinguishes itself from the related siblings create_variant_structure (which makes sets/variants) and compare_prims (which measures variants without changing selection).

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 explicitly states when to use which mode: session layer by default for a non-persistent check, edit_target when the selection must be saved. It also enumerates when-not conditions (clear with variant_name="" first if the session layer holds a selection, prim inside an instance refused, unknown set refused) and says to use this rather than execute_script.

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