create-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 narrat