Tools Reference

Tools are the AI's hands inside Unreal Engine. Every action the agent takes -- reading files, writing Blueprints, compiling code, executing Python scripts -- happens through one of 31 built-in tools. Each tool has a defined schema, safety classification, and threading model that determines how and when it can run.

When you send a message, the AI model decides which tools to call, in what order, and with what parameters. The agent loop executes them, collects results, and feeds those results back to the model for the next decision. This cycle repeats until the task is complete or the turn limit is reached.

Tool Categories

FileSystem Tools

Tools for reading, writing, searching, and navigating the project file system.

Tool	ReadOnly	Destructive	ThreadSafe	Description
read_file	Yes	No	Yes	Read file contents with optional line range support
write_file	No	No	No	Write or create files with path traversal protection and protected path enforcement
edit_file	No	No	No	Exact string replacement in files with diff preview for approval
apply_patch	No	No	No	Apply unified diff patches to existing files
list_files	Yes	No	No	List directory contents (up to 10,000 results)
search_files	Yes	No	No	Search for files by name pattern across the project
search_in_files	Yes	No	No	Search inside file contents (grep-style, up to 2,000 results)

Shell Tools

Tools for executing scripts, running shell commands, and interacting with version control.

Tool	ReadOnly	Destructive	ThreadSafe	Description
execute_python	No	Yes	No	Execute Python with full import unreal access to the entire UE Editor API
execute_shell	No	Yes	No	Run shell commands (with a blocklist preventing dangerous operations like rm -rf, format, diskpart)
git_query	Yes	No	Yes	Read-only git operations: status, diff, log, branch listing
git_commit	No	Yes	Yes	Create git commits with optional git add -A staging

Editor Tools

Tools for compiling, querying the Unreal Engine reflection system, and capturing editor state.

Tool	ReadOnly	Destructive	ThreadSafe	Description
compile_and_check	No	No	No	Compile a single Blueprint and return errors inline
compile_blueprints	No	No	No	Batch-compile multiple Blueprints at once
query_ue_api	Yes	No	No	Query the UE reflection system for classes, functions, enums, and structs by name
capture_viewport	Yes	No	No	Capture the editor viewport as a base64-encoded PNG for AI vision analysis
live_coding_compile	No	No	No	Trigger a Live Coding C++ compilation
hot_reload	No	No	No	Trigger Hot Reload of editor modules

Agent Tools

Tools for controlling the agent loop, managing tasks, delegating work, and persisting memory.

Tool	ReadOnly	Destructive	ThreadSafe	Description
attempt_completion	Yes	No	No	Signal that the current task is complete (stops the agent loop)
ask_followup_question	Yes	No	No	Ask the user a clarifying question (pauses the loop until answered)
delegate_to_agent	No	No	No	Delegate a sub-task to a specialized agent profile (max nesting depth 3)
fork_conversation	No	No	No	Fork the conversation at a given point to create a branched task
update_todo_list	Yes	No	No	Maintain a structured TODO list for tracking progress on the current task
und_remember	No	No	No	Store a persistent memory entry with a key and content
und_recall	Yes	No	No	Recall stored memory entries by keyword search
und_forget	No	No	No	Remove a persistent memory entry by key
save_project_knowledge	No	No	No	Save or update a project-specific knowledge module
list_project_knowledge	Yes	No	No	List available knowledge modules with optional keyword filtering
delete_project_knowledge	No	Yes	No	Delete a knowledge module from the project

Search Tools

Tools for semantic and keyword-based code search across the project.

Tool	ReadOnly	Destructive	ThreadSafe	Description
semantic_search	Yes	No	No	BM25 and vector-based search across the indexed project codebase
index_project_for_search	No	No	No	Build or rebuild the BM25 code search index

Web Tools

Tool	ReadOnly	Destructive	ThreadSafe	Description
fetch_url	Yes	No	Yes	HTTP GET request returning the page content as plain text or markdown

Safety Classification

Each tool carries three safety flags:

• ReadOnly -- The tool has no side effects. It only reads data and never modifies files, state, or the editor.
• Destructive -- The tool can cause significant changes that may be difficult to reverse. These tools receive extra scrutiny in the approval flow.
• ThreadSafe -- The tool can safely execute on a background thread without needing the Game Thread. This allows parallel execution when multiple tools are called in the same turn.

Tools that are not read-only and are destructive (like execute_python and execute_shell) will always prompt for approval unless an auto-approval rule has been configured in Settings.

The execute_python Tool

execute_python is the single most powerful tool in the system. It provides full access to the Unreal Engine Editor API via import unreal, which means every operation that the UE Editor can perform is available to the AI agent programmatically.

This includes:

• Creating and modifying Blueprint assets
• Spawning actors and configuring components
• Setting up materials, textures, and material instances
• Building levels and placing geometry
• Configuring Gameplay Ability System (GAS) abilities
• Setting up Enhanced Input mappings
• Creating and editing UI widgets (UMG/CommonUI)
• Modifying project settings
• Running asset validation and cleanup

The tool wraps user code in error handling, captures stdout/stderr, and returns the output. It also runs garbage collection before each execution to prevent UE5 world leak detector asserts. Output is truncated at 50,000 characters.

Output Limits

All tool output is subject to limits that prevent context window overflow:

Limit	Value
Global tool output	100,000 characters
list_files default results	2,000
list_files max results	10,000
search_in_files default results	50
search_in_files max results	2,000
semantic_search default results	5
semantic_search max results	20
execute_python output	50,000 characters
query_ue_api results	50

Tool Execution Flow

When the AI decides to call a tool:

1. The Approval Manager checks whether the tool call matches any auto-approval rules or requires user confirmation.
2. If approved, the Tool Executor dispatches the call -- either on the Game Thread or a background thread depending on the tool's IsThreadSafe() flag.
3. Results are checked against the LRU cache (64 entries, 60-second TTL) for read-only tools to avoid redundant work.
4. The result is returned to the agent loop, which feeds it back to the AI model as a tool result message.
5. The cycle continues until attempt_completion is called or the max turn limit (default 100) is reached.

MCP Tools

In addition to the 31 built-in tools, UND supports external tools via the Model Context Protocol (MCP). MCP servers run as subprocesses communicating over stdio with JSON-RPC 2.0. Their tools are registered in the tool registry with the naming convention mcp__{ServerName}__{ToolName} and appear alongside built-in tools in the AI's tool list.

See the MCP Support documentation for details on configuring external tool servers.