Skip to main content
Glama
CarlxsMG

UEAgent

by CarlxsMG
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

execute_python_file

Destructive

Execute a Python file inside the running Unreal Editor to automate Blueprint, material, or asset tasks, returning Python output and engine logs to verify results.

Instructions

Execute a Python (.py) file inside the running Unreal Editor. PIE TRAP: same hole as execute_python -- arbitrary Python is NOT covered by the plugin's PIE guard, so a script that compiles a Blueprint or saves an asset runs even with Play-in-Editor live, where compiling can KILL the editor (UREINST_* retains a world, CheckForWorldGCLeaks is Fatal) and saving reports success without writing (Editor.AllowSavingAssetsDuringPIE=0). Check is_play_in_editor_active first when the file compiles, saves or mutates a Blueprint; reading the live world during PIE is safe. WARNING: log_output IS NOT THE LOG OF THE CALL -- it is Python's own prints only (UE fills it from a delegate broadcast solely by unreal.log/log_warning/log_error), so every UE_LOG the ENGINE emits during your script is absent from it. Read engine_log instead: it is the GLog slice bracketed to this call, Warning+Error by default. Example: build_meta_human can run, return None, write zero assets and report a clean log_output while "LogMetaHumanCoreTechLib: Error: Texture Synthesis has not been initialized" sits in GLog. When a call reports success and NOTHING HAPPENED, engine_log is the first place to look; widen with engine_log_level=Log, or pass log_cursor_before to get_output_log_lines(since_sequence_id=...) for the unfiltered rest.

Returns: { file_path, python_success, command_result, output, log_output, log_line_count, engine_log, engine_log_count, engine_log_truncated, log_cursor_before }

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
file_pathYesAbsolute path to a .py file accessible from the editor host.
engine_log_maxNoMax lines in `engine_log` (default 50, 0 disables, hard cap 4096).
engine_log_levelNoMinimum severity of ENGINE log to return in `engine_log`: Error, Warning (default), Display, Log/All.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already mark this destructive and non-idempotent, yet the description adds substantial context the annotations cannot convey: the PIE guard gap that can kill the editor, the failure mode where saving silently reports success (Editor.AllowSavingAssetsDuringPIE=0), and the crucial warning that log_output contains only Python prints, not engine logs. This is exactly the beyond-structured-fields disclosure this dimension rewards, and it is consistent with the destructive annotation.

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 most sentences carry unique, actionable content (PIE trap, log_output vs engine_log, the MetaHuman example). It is dense and somewhat repetitive in pushing the log_output warning, but almost nothing is filler.

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 high-risk arbitrary-code tool with no output schema, the description supplies the safety caveats, the log-reading model, and an explicit enumeration of returned fields. An agent has everything needed to invoke it safely and to interpret results.

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 real meaning: it clarifies that log_output is NOT the call's log and directs the agent to engine_log and engine_log_level, including how to widen to Log level and use log_cursor_before with get_output_log_lines. That is genuine semantic value beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: executes a Python .py file inside the running Unreal Editor, and distinguishes itself from the inline-code sibling by referencing execute_python's behavior. The file-vs-string distinction is implied rather than spelled out as a routing rule, so it falls just short of a clean 5.

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?

Gives real operational guidance: check is_play_in_editor_active first when the file compiles, saves or mutates, and notes that reading the live world during PIE is safe. It names the relevant sibling tools, but never explicitly frames when to prefer this over execute_python or run_external_project_script, so it is context-rich without full alternative routing.

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