Tools and RQL

This page explains what the AI agent can do in your Unity project once Unity MCP is connected: which tools it sees, how RQL lets it read and change almost anything in the Editor, and which tools are installed but hidden. The full, searchable list with parameters is in the Unity tool catalog, and the query language is documented in the RQL reference.

The tools the agent sees by default#

Since version 1.0.0 the plugin keeps the agent's tool list short. These seven tools are visible after installation:

A short list costs fewer tokens and leaves the model more room to reason. The other tools are still installed; see Hidden tools.

RQL: one language for the whole Editor#

RQL is a query language over the Editor's live data. A query starts with a source and passes the result through stages separated by |, such as where, select, get, set and call. Instead of one tool per action (the old gameobject-create, scene-save, console-get-logs and dozens more), the agent writes one query.

Read the whole hierarchy of the open scenes:

roots | recurse children | select name active

Find the player:

objects | where name == "Player" | select path name active

Create a ground plane:

editor | call CreateGameObject({name: "Ground", primitive: "Plane"})

Add a component and save:

objects | where name == "Player" | call AddComponent("Rigidbody")
editor | call SaveScenes()

Read only the errors from the Console:

console | where logType == "Error"

Each rql-mutate call is one Undo group, so Ctrl+Z reverts it, and changed assets, scenes and the open prefab are saved after the mutation. rql-mutate also accepts dry_run to preview what would change and max_targets to cap how many objects one mutation may touch.

RQL sources in Unity#

Assets are addressed by path with unity.asset("Assets/…") or searched with unity.assets("t:Material"). Every installed extension adds its own sources and types, for example tilemap or cinemachine.

Because RQL works through reflection, the agent can read and set members of your own components too, not just Unity's built-in ones. You can teach RQL about your own types with custom adapters.

Scripts and C# execution#

script-execute compiles a C# snippet with Roslyn and runs it in the Editor. It takes the code plus optional className, methodName, extra usings and helper files to include. It is the escape hatch for anything RQL does not cover. From a terminal, unity-mcp-cli exec calls the same tool:

unity-mcp-cli exec 'Application.unityVersion'

To write files instead of running code, the hidden tools script-read, script-update-or-create and script-delete manage .cs files in the project. Unity recompiles after a change; the connection drops briefly during the domain reload and comes back on its own.

Tests#

tests-run runs EditMode or PlayMode tests (testMode, default EditMode). Filter by assembly, namespace, class or method, or pass an RQL selection over the tests source to run exactly the tests you choose as one run. Results can be filtered with RQL over testResults. Options control whether passing tests, messages, stack traces and Console logs are included, which keeps the output small.

unity-mcp-cli run-tool tests-run ./MyUnityProject --input '{"testMode":"EditMode"}'

Screenshots#

screenshot-isolated is visible by default. Three more are hidden: screenshot-scene-view, screenshot-game-view and screenshot-camera. Images are capped at 3840 pixels on the longest edge so they fit through the MCP transport. Screenshots need a graphics device: an Editor started with -nographics returns an error instead of a blank image.

Hidden tools#

These are installed but not in the agent's list. A hidden tool still runs when called by name.

• Screenshots: screenshot-scene-view, screenshot-game-view, screenshot-camera.
• Scripts: script-read, script-update-or-create, script-delete.
• Packages: package-list, package-search, package-add, package-remove for the Unity Package Manager.
• Tool management: tool-set-visibility, and its deprecated alias tool-set-enabled-state.

Show them in the AI Game Developer window (Tools > Open), with the tool-set-visibility tool, or with:

unity-mcp-cli configure ./MyUnityProject --enable-tools package-add,package-list

Prompts and skills#

The plugin also ships 46 MCP prompts (slash-command templates such as setup-basic-scene or add-event-system) in six groups: scripting, GameObjects and components, scenes, debugging and testing, asset management, animation and timeline. They are hidden by default; enable the ones you want in Prompts > Open.

Skills are Markdown files the plugin generates into your agent's skills folder. They include the unity-rql guide with the RQL syntax for Unity and every installed extension, plus setup and CLI notes. Turn them on with Skills > Auto-generate in the window, or run unity-mcp-cli setup-skills <agent>.

Tool names from older tutorials#

Version 1.0.0 removed the one-tool-per-action tools. If a tutorial mentions one of them, use RQL instead:

• gameobject-create, gameobject-find, gameobject-modify, gameobject-destroy, gameobject-component-*: RQL on objects, roots and selection with set and call.
• scene-create, scene-open, scene-save: editor | call NewScene(…), OpenScene(…), SaveScenes().
• assets-*, assets-prefab-*, assets-material-create: unity.asset(…), unity.assets(…) and editor calls such as CreateMaterial, CopyAsset, InstantiatePrefab.
• console-get-logs, console-clear-logs: the console source and editor | call ClearConsole().
• editor-application-*, editor-selection-*: editor members such as isPlaying and selection.
• reflection-method-find, reflection-method-call, type-get-json-schema: RQL call and rql-schema.
• profiler-*: the profiler source.

Related pages#

• Unity tool catalog and RQL reference.
• Custom tools to add your own.
• Unity best practices for prompting.