Skip to main content
Glama

get_actors_in_level

Read-onlyIdempotent

Dump all actors in an Unreal level with names, classes, and transforms, capped by max_results. Use it for a full world census when you don't know the class, name, or location yet.

Instructions

Dump EVERY actor of a world (name, class, transform), capped by max_results at 5000, with total_actors_in_level and results_truncated so you know if you saw all of it. The unfiltered census: reach for get_actors_by_class when you know the class, find_actors_by_name for a name/label substring, get_actors_in_radius for a place. Its world selector is the canonical one: 'editor' (default), 'pie'/'game', 'server', 'client' and 'pie:N' all resolve for real, an unrecognised value FAILS naming the worlds that exist instead of quietly answering from the editor world, and every reply carries world_package/world_type/net_mode/pie_instance so you can see WHICH world answered rather than assuming.

Returns: { actors: [actor JSON], actors_count: int, total_actors_in_level: int, results_truncated: bool, max_results: int, world: string (the normalized selector that resolved), world_name: string, world_package: string (in World Partition the UEDPIE_N prefix lives HERE, not in world_name), world_type: string, net_mode: string, pie_instance: int }

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
worldNoOptional world selector: absent/'editor' (default) | 'pie' (ambiguous: PlayWorld, else the first PIE context) | 'game' (alias of 'pie') | 'server' (the PIE world with authority, GetNetMode() != NM_Client) | 'client' | 'pie:N' (the PIE context whose PIEInstance is N). Case-insensitive; an unrecognised value is a clean error listing the worlds present, never a silent fallback to the editor world.
max_resultsNoOptional cap on returned actors (default 5000). Must be > 0. Truncation is reported, never silent.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely non-obvious behavior: truncation is reported via results_truncated never silently, an unrecognised world selector fails with an error listing available worlds rather than falling back to editor, and every reply carries world_package/world_type/net_mode/pie_instance. This is substantive beyond the safety hints, though return formatting details remain partial.

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 purpose, then alternatives, then selector semantics, then the return shape. Every section is useful but there is noticeable overlap with the schema's own parameter descriptions, which costs a point on tightness.

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?

With no output schema, the description compensates by enumerating the full reply payload (actors, counts, truncation flag, normalized world fields). Purpose, alternatives, parameter behavior, and error behavior are all covered, leaving nothing an agent needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already fully documented in the schema; the description largely restates the selector semantics. The only marginal addition (World Partition UEDPIE_N prefix location) concerns output, not parameters, so baseline 3 applies.

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 (dump every actor of a world) with the returned fields (name, class, transform) and the cap behavior. It explicitly distinguishes itself from get_actors_by_class, find_actors_by_name, and get_actors_in_radius, so an agent can separate it from the crowded siblings without reading 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?

Provides an explicit decision rule: use get_actors_by_class when the class is known, find_actors_by_name for a substring, get_actors_in_radius for a place, and this tool as the unfiltered census otherwise. Alternatives and the conditions that select them are named.

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