---

name: create-toolset description: "Use this skill when authoring or extending an Unreal Engine toolset, a class of static, AI-callable functions registered with ToolsetRegistry and exposed through the unreal-mcp server. Trigger when the user wants to add, expose, or register a new tool method, create a new toolset, or extend an existing one such as BlueprintTools, StaticMeshTools, ObjectTools, LevelTools, or MaterialTools. Concrete triggers: 'add a tool to X', 'expose this via MCP', 'register a function so Claude/the agent can call it', 'wire this into the toolset registry', 'create a new toolset for Y', 'add a Python toolset', 'make this AI-callable'; adding a static method to a *Tools.cpp/.h/.py file; editing files under a Toolsets/ folder; designing tool parameters, return types, or struct schemas for a toolset. SKIP for: invoking existing tools at runtime (use unreal-mcp instead), authoring an Agent Skill (use unreal-skill), generic refactors that happen to touch a toolset file but don't add or redesign a tool, or unrelated uses of the word 'toolset'."

Create Toolset

You are authoring or extending an Unreal Engine toolset: a collection of static, AI-callable functions registered with the ToolsetRegistry and exposed through the MCP server. The goal is to expand the surface of things Claude can do inside the editor.

Principles

A good toolset is:

Clean: Design the simplest API that can do useful work in the domain. Don't mirror Unreal's existing APIs directly; they're often unnecessarily complex. A good heuristic: would a technical artist understand this without reading the implementation?

Complete: Support CRUD symmetry. If you can set a thing, you should be able to get it. If there's a create, there should be a delete. Getters without setters are fine when mutation isn't possible or useful.

Composable: Use consistent types for the same kinds of operation across the toolset. If get_graph() returns a Graph, then get_graph_nodes() should accept a Graph. Functions should combine naturally to produce more complex results.

DRY: No duplication within a toolset, and no duplication across toolsets. ObjectTools already provides generic UObject property get/set. Don't reimplement it. If functionality lives elsewhere, call it or point to it.

Before You Write

Work through these questions in order before touching any code.

1. Does the functionality already exist? If the editor is running, call list_toolsets via MCP, then describe_toolset on anything relevant. If MCP isn't available, search the codebase for folders named Toolsets and read the C++ headers or Python toolset files there. If the capability is already exposed, there's nothing to do. Tell the user and point them to the right tool.

2. Is the request more general than it sounds? Users often ask for something domain-specific that is actually an instance of a broader pattern. Before looking for a domain toolset, ask whether the capability truly belongs to that domain or whether it applies more widely. For example, a request for "read blueprint asset metadata" sounds like it belongs in BlueprintTools, but metadata applies to all assets, so the right place is AssetTools. Solving it generically is almost always better than solving it narrowly.

3. Does a toolset for this domain already exist? If the functionality is missing but a toolset already covers the same domain (e.g. you're adding a mesh query to StaticMeshTools), add to that toolset rather than creating a new one.

4. Does a new toolset need its own plugin? If you're creating a new toolset and it's closely related to an existing plugin, add it there. If it's a distinct enough domain, it may warrant its own plugin. Ask the user if it isn't obvious.

5. Choose the implementation language. This is the user's call, but help them make an informed one. Python is generally preferred: it's faster to iterate and easier to change. Assess both options:

• Python: Check what's available in the Python stubs (<project_root>/Intermediate/PythonStub/unreal.py; search it, don't read it wholesale). If the file doesn't exist, the user needs to enable Developer Mode in Edit → Project Settings → Plugins → Python and restart the editor. This is worth doing for any toolset work, so recommend it proactively. If the necessary APIs are all there, Python is the right choice. If most of the functionality is available but something small is missing, flag the gap to the user; a minor engine tweak may still make Python the better option overall.
• C++: The right choice when Python coverage is thin or non-existent. Most of what you need simply isn't in the stubs.

Summarize what's available in each and let the user decide before writing any code. If the APIs needed aren't available in either language, don't work around it. Stop and tell the user so they can extend the engine. Workarounds create fragile tools that break silently.

Shared Conventions

These apply in both C++ and Python:

• Don't duplicate existing tools. For example, ObjectTools already handles generic UObject property get/set.
• Documentation is required. Every toolset and every tool call must be documented. See the Documentation section below.
• Use real types. Parameters and return values should be the actual type (int32, FVector, TArray<FString>, a struct, etc.). The ToolsetRegistry handles serialization automatically. Converting to or from a JSON-formatted string inside a tool call is a code smell. A string type should mean it's genuinely a string, not structured data in disguise.
• Return values carry data, not status. Returning normally means success; raising means failure. Never return a boolean, error string, or result wrapper to communicate an error. Raise instead.
• All tool methods are static. No instance state.
• Tests are mandatory. Every tool must have test coverage. See the Testing section below.

Documentation

Good documentation is required at every level. It's not optional polish. Don't go into too much detail; a short, precise description is better than a long one. If a sentence doesn't add meaning beyond what the code already says, cut it.

Toolset class: Write 1-3 sentences describing what the toolset does and the domain it covers. An LLM will often see only the toolset name and this description without ever loading its tools, so it needs to stand on its own. Describe the domain and the kinds of operations the toolset supports. Don't enumerate tool names; the tools speak for themselves.

Each tool: Write a clear description of what the tool does, document every parameter, and document the return value. Focus on meaning and units.

The test for every line: could a competent reader infer this from the signature, names, and types alone? If yes, cut it. LLMs over-document by default; resist it. A doc line earns its place only by stating what the code cannot. So cut signature restatement (types, defaults, optionality), usage and chaining narration (how tools combine is visible in the signatures), worked examples of the obvious, and speculation about what a field might contain instead of what it is.

Document what the code does, not why you wrote it that way. "Iterates the subclasses directly because the asset registry misses unloaded types" is implementation rationale, not contract. Say what the tool does; cut the reasoning.

Keep what can't be inferred: units, ranges, non-obvious encodings (e.g. "a single space-separated string"), what an empty or null result means, and domain meaning the name doesn't carry.

// Over-documented: every line restates the signature or narrates usage.
/**
 * Runs a cheat. @param CheatName The cheat name (case-insensitive), pass it to run the cheat.
 * @param Args Optional arguments; fill in the slots from the Args hint (e.g. "<float F>" -> "2.0",
 *             "<float A> <float B>" -> "1 2"). Empty string for no arguments.
 */
// Trimmed: only the non-inferable facts remain.
/**
 * Runs a cheat on the local player, as if typed into the console.
 * @param CheatName The cheat command name.
 * @param Args Arguments as a single space-separated string. Empty for none.
 */

Structs: Document the struct itself (what it represents and when it's used) and every field (meaning and units where applicable). UPROPERTY metadata such as ClampMin and ClampMax is extracted automatically and included in the schema. Use it rather than restating constraints in the doc comment.

C++ Specifics

Structure

• Derive from UToolsetDefinition (from ToolsetRegistry/ToolsetDefinition.h).
• One toolset class per .h / .cpp file.
• All AI-callable tools are static methods marked with UFUNCTION(meta = (AICallable)). The function's doc comment becomes the AI-visible tool description. Write it clearly.
• Private helpers are static methods without UFUNCTION(meta = (AICallable)). Simply omit the macro and they won't be exposed.

/**
 * Snapshot of a MyThing's current state, returned by GetThingInfo.
 */
USTRUCT(BlueprintType)
struct FMyThingInfo
{
    GENERATED_BODY()

    /** How thing-like this thing is. */
    UPROPERTY(meta=(ClampMin="0.0", ClampMax="1.0")) float Thinginess;

    /** Things that belong to this thing. */
    UPROPERTY() TArray<UMyThing*> SubThings;
};

/**
 * Manages MyThings in the current level. Covers the full lifecycle of these objects:
 * querying by name, reading their state, and performing operations on them.
 */
UCLASS(BlueprintType, MinimalAPI)
class UMyToolset : public UToolsetDefinition
{
    GENERATED_BODY()

public:
    /**
     * Returns all things whose name matches the given pattern.
     * @param NamePattern Substring to match against thing names.
     * @return Matching things, or an empty array if none are found.
     */
    UFUNCTION(meta = (AICallable), Category = "MyToolset")
    static TArray<UMyThing*> FindThings(const FString& NamePattern);

    /**
     * Returns detailed info about the given thing.
     * @param Thing The thing to read state from.
     * @return The thing's current state.
     */
    UFUNCTION(meta = (AICallable), Category = "MyToolset")
    static FMyThingInfo GetThingInfo(UMyThing* Thing);

    /**
     * Performs the primary operation on the given thing.
     * @param Thing The thing to perform the operation on.
     */
    UFUNCTION(meta = (AICallable), Category = "MyToolset")
    static void DoTheThing(UMyThing* Thing);
};

Async Tool Calls

Most tools are synchronous: they run on the game thread and return a value directly. Use async for long-running operations such as capturing a screenshot or waiting for an editor state change.

Async tools return a subclass of UToolCallAsyncResult instead of the value directly. Many result types already exist, and new ones can be created by subclassing UToolCallAsyncResult for any value type. Check the existing types before creating a new one.

The declaration looks like any other tool, just with an async result return type:

/**
 * Renders an image of the given thing.
 * @param Thing The thing to capture.
 * @return An image of the thing.
 */
UFUNCTION(meta = (AICallable), Category = "MyToolset")
static UToolCallAsyncResultImage* CaptureThingImage(UMyThing* Thing);

Unlike synchronous tools, success and failure are both communicated through the result object. Call SetValue() on success and SetError() on failure.

UToolCallAsyncResultImage* UMyToolset::CaptureThingImage(UMyThing* Thing)
{
    UToolCallAsyncResultImage* Result = NewObject<UToolCallAsyncResultImage>();

    if (!IsRenderingEnabled())
    {
        Result->SetError(TEXT("Rendering is not enabled."));
        return Result;
    }

    // Initiate the capture; call Result->SetValue(image) on completion.
    return Result;
}

The right implementation approach depends on the system being exercised. Lo