Skip to main content
Glama

get_lighting_in_area

Read-onlyIdempotent

Queries every light actor within a radius of a world point, returning type, intensity, color and distance to diagnose dark or blown-out spots.

Instructions

Light-only spatial query: every actor carrying a LightComponent within radius cm of a world point, reporting light_type, intensity, color and distance. Use it to answer "why is this spot dark / blown out" without walking the whole outliner (get_actors_in_radius returns everything and no light data). World-aware: world='editor' (default) | 'pie' | 'server' | 'client' | 'pie:N', which is what lets you see lights attached to actors that only exist at runtime (a torch on a spawned character, a muzzle flash), and the reply stamps world_name/world_package/net_mode/pie_instance so lights_count:0 is readable as "not in THIS world".

Returns: { center_x: number, center_y: number, center_z: number, radius: number, world: string, lights: [{ actor_name: string, light_type: string, intensity: number, light_color: string, distance: number, location: { x: number, y: number, z: number } }], lights_count: number, world_name: string|null, world_package: string|null, world_type: string|null, net_mode: string|null, pie_instance: number }

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
worldNoOptional world selector: absent/'editor' (default) | 'pie' (ambiguous: PlayWorld, else the first PIE context) | 'server' (the PIE world with authority) | 'client' | 'pie:N' | 'game' (alias of 'pie'). An unrecognised value FAILS naming the worlds that exist; it never falls back to another world in silence.
centerNoWorld-space center, ARRAY form only: [x, y, z]. Omitted -- or given as an object, or with fewer than 3 numbers -- it silently becomes the origin [0,0,0], which reads exactly like "there are no lights here".
radiusYesSearch radius in centimetres (Unreal units), measured to each light actor's origin.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already mark it read-only/idempotent/non-destructive, and the description layers on substantial behavioral context the annotations don't cover: world-selector semantics (editor/pie/server/client/pie:N), that it surfaces runtime-only lights (muzzle flash, spawned torch), and that world stamps make lights_count:0 readable instead of ambiguous.

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-loaded with the core purpose and the sibling contrast, and the returns block is placed last. It is dense and somewhat long, but nearly every clause carries new information; a little tightening is possible.

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?

No output schema exists, so the description inlines the full return shape (lights array fields, world stamps, lights_count). Combined with world-mode semantics, an agent has everything needed to call and interpret results correctly.

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 adds the intent behind the world parameter (seeing lights attached to runtime-only actors) that the schema only enumerates mechanically. The center/radius semantics are largely mirrored from the schema, so it slightly exceeds baseline without fully replacing it.

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 (query), resource (actors carrying a LightComponent) and scope (within radius cm of a world point), plus the reported fields. It explicitly contrasts with get_actors_in_radius, so an agent can distinguish it from siblings without opening schemas.

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 an explicit use case ("why is this spot dark / blown out") and names the alternative (get_actors_in_radius returns everything and no light data). The condition that selects this tool over its sibling is spelled out.

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

Deploy Server

Other Tools