Skip to main content
Glama
CarlxsMG

UEAgent

by CarlxsMG
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

read_pie_widgets

Read-onlyIdempotent

Read live UMG widget trees from a running PIE session: enumerate viewport UserWidgets, descend nested Blueprints, and return visibility, text, values, and geometry.

Instructions

Read LIVE UMG from the running PIE session (game thread): enumerate the active UUserWidgets added to the viewport and walk each widget tree, emitting name/class plus optional visibility/hover/text/value/geometry as a parent/child tree. Reads only game-thread-safe widget-tree state (never the render thread). Errors clearly if no Play-In-Editor session is running. DESCENDS INTO NESTED WIDGET BLUEPRINTS: an AAA screen is a Widget Blueprint composed of Widget Blueprints, so everything interesting sits one level below the first. Cycles are handled with a visited set plus max_depth, and a subtree that IS cut says so in subtree_omitted instead of looking like a leaf. Rich text is read too (URichTextBlock does not derive from UTextBlock). Not implemented: include_bindings, which is accepted and flagged in bindings_note.

Returns: { widgets: [{ widget_name, class, is_any_animation_playing, visibility?, is_hovered?, children: [{ widget_name, class, visibility?, is_hovered?, text?, is_enabled?, value?, percent?, is_checked?, selected_option?, geometry?, children: [...] }] }], widget_count: int, scanned_viewport_widgets: int, include_text: bool, include_visibility: bool, include_bindings: bool, include_values: bool, include_geometry: bool, bindings_note?: string, world: string, 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/'pie' (default: PlayWorld, else the first PIE context) | 'server' (the PIE world with authority) | 'client' | 'pie:N' | 'game' (alias of 'pie'). In a 2-player PIE session EVERY client has its OWN widgets, so the default may well read the other player's HUD.
max_depthNoOptional recursion limit (-1 = unlimited, the default). Counts every level including the descent into a nested Widget Blueprint's own tree. A subtree cut by the limit reports subtree_omitted rather than passing for a leaf.
root_filterNoOptional case-sensitive substring; only top-level UserWidgets whose object name contains it are returned.
include_textNoOptional bool (default true): include UTextBlock text.
include_valuesNoOptional bool (default false): include is_enabled + widget-type-specific value (Slider.value / ProgressBar.percent / CheckBox.is_checked / ComboBoxString.selected_option).
include_bindingsNoOptional bool (default false): NOT implemented in this subset; sets bindings_note when true.
include_geometryNoOptional bool (default false): include GetCachedGeometry()-derived absolute_position/absolute_size, render_opacity, and render_transform.
include_visibilityNoOptional bool (default true): include visibility, is_hovered and has_keyboard_focus per widget. has_keyboard_focus is what tells you whether a navigation key will do anything at all: with nothing focused every key is a no-op, which reads exactly like broken navigation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior: reads only game-thread-safe state and never the render thread, cycle handling via a visited set plus max_depth, the subtree_omitted marker so a cut subtree isn't mistaken for a leaf, rich-text handling, and the fact that include_bindings is accepted but unimplemented and surfaces in bindings_note.

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 purpose and the return shape, which is efficient. Some passages are editorialized (the AAA Screen explanation, the keyboard-focus aside), which is helpful context but slightly padded. Overall well-structured with most sentences earning their place.

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, and the description compensates by enumerating the full return shape (widgets tree, counts, flags, bindings_note, world metadata, pie_instance). Combined with the world-selection caveat and error condition, an agent has everything needed to call and interpret it 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 semantic context beyond the schema: the nested-Widget-Blueprint descent model that gives max_depth its meaning, and the explicit note that include_bindings is a no-op accepted only for flagging. It does not re-explain each flag, which is fine given the rich schema.

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+resource with scope: 'Read LIVE UMG from the running PIE session ... enumerate the active UUserWidgets added to the viewport and walk each widget tree'. It explicitly frames itself as reading live runtime state (game thread) rather than design-time assets, which is what separates it from siblings like get_widget_hierarchy or get_widget_blueprint_tree.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear context for use: it operates on the running PIE session and 'Errors clearly if no Play-In-Editor session is running', which is an implicit when-not. The world parameter guidance warns the default may read another player's HUD in a 2-player session. It does not explicitly name sibling alternatives (e.g. get_pie_focused_widget, get_widget_hierarchy) or when to prefer them, so it stops short of 5.

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