Skip to main content
Glama

viewport_light

Read or set the viewport's lighting mode without changing the scene, then fix black captures or lighting warnings by choosing stage, camera, off, or a light rig.

Instructions

Read or set the viewport's lighting mode, which decides how the viewport and its captures are lit, without changing the scene.

Use it when a capture comes back black, or warns that the lighting lights nothing (mode off, or stage with no scene lights, though Kit's grid shows), then capture again. "get" (the default) answers the mode, the modes on offer, and the stage's own lights with their intensity, inside instances too, the first 20 listed; a light rig's lights are the viewport's, not the stage's, and aren't among them. "set" takes a mode "get" lists: "stage" (the stage's own lights), "camera" (a light that follows the camera), "off", or a light rig such as "Default", "Colored Lights" or "Grey Studio"; rigs need Kit's lighting menu, omni.kit.viewport.menubar.lighting, and a mode not on offer is an error. "set_camera_light" is the older switch, turning the camera light on or off with enabled. To add a light to the stage itself, use create_prim (DistantLight, DomeLight), then set_prim_attribute for its intensity: a DistantLight comes at 50,000, which washes a capture out.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "viewport_light"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoFor "set": "off", "camera", "stage", or a light rig "get" lists, e.g. "Default"
actionNo"get" the mode, "set" one, or the legacy "set_camera_light"get
enabledNoFor "set_camera_light": turn the camera light on or off

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.2

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare non-read-only, non-destructive, closed-world; the description adds far more: 'set' does not alter the scene, rig modes require the omni.kit.viewport.menubar.lighting extension, an unavailable mode is an error, and 'get' truncates to the first 20 lights and omits rig lights. These are exactly the failure modes an agent needs.

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?

Purpose is front-loaded and every paragraph carries information, but the second and third sentences are long run-ons that chain several clauses with parentheticals, making them slower to parse than needed.

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, yet the description still sketches what 'get' returns (mode, modes on offer, stage lights with intensity) and flags the DistantLight 50,000 intensity pitfall. Nothing an agent needs to call this correctly in a lighting/capture workflow 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 would be 3, but the description adds real semantics: the accepted mode values and their meanings ('stage', 'camera', 'off', named rigs), that an unlisted mode errors, and that 'enabled' applies only to the legacy set_camera_light action.

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?

Opens with a specific verb pair and resource: "Read or set the viewport's lighting mode," and immediately scopes it ("without changing the scene"). It is clearly separable from siblings like create_prim and set_prim_attribute, which the description explicitly routes stage-light work to.

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 a concrete trigger condition: use it when a capture comes back black or warns that lighting lights nothing. It also states which tool to use instead for adding stage lights (create_prim then set_prim_attribute), and calls out the legacy set_camera_light alternative.

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