# Tools and RQL

What an AI agent can do in the Unity Editor with Unity MCP - RQL queries and mutations, screenshots, C# scripts, tests, packages and profiling.

_Last updated: 2026-11-04_

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](https://ai-game.dev/docs/tools/unity), and the query language is documented in the [RQL reference](https://ai-game.dev/docs/rql).

## 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:

| Tool | What it does |
| --- | --- |
| `rql-query` | Reads Editor data with an RQL query: scenes, GameObjects, components, assets, the Console, settings, tests, the profiler. |
| `rql-mutate` | Changes Editor data or calls Editor operations with RQL: create, modify, move and delete objects and assets, open and save scenes. |
| `rql-schema` | Describes the sources, types, members and calls RQL can use, and prints topic guides. The agent starts here when unsure. |
| `script-execute` | Compiles and runs C# code in the Editor with Roslyn and returns the result. |
| `screenshot-isolated` | Renders one GameObject in isolation from a chosen angle, optionally as a 2x2 composite, so the model can look at it. |
| `tests-run` | Runs EditMode or PlayMode tests and returns per-test results. |
| `unity-tool-list` | Lists every tool and whether the agent sees it. |

A short list costs fewer tokens and leaves the model more room to reason. The other tools are still installed; see [Hidden tools](https://ai-game.dev/docs/wiki/unity/tools-and-rql#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:

```text
roots | recurse children | select name active
```

Find the player:

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

Create a ground plane:

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

Add a component and save:

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

Read only the errors from the Console:

```text
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

| Source | Contents |
| --- | --- |
| `scenes`, `roots`, `objects` | Loaded scenes, their root GameObjects, and every GameObject in them. |
| `selection` | The current Editor selection. |
| `prefab` | The prefab open in prefab mode. |
| `editor` | Editor operations: create GameObjects, materials, folders and scenes; open and save scenes and prefabs; copy, move and delete assets; execute menu items; play mode state. |
| `settings` | Project settings. |
| `console` | Captured Editor log entries. |
| `shaders`, `componentTypes` | Available shaders and component types. |
| `tests`, `testResults` | The test tree and the last results. |
| `profiler` | Memory, rendering, script and frame data; start, stop, save and load captures. |
| `lighting` | The active scene's environment (ambient, fog, skybox, sun, reflections), Lighting Settings and the bake. |

Assets are addressed by path with `unity.asset("Assets/…")` or searched with `unity.assets("t:Material")`. Every installed [extension](https://ai-game.dev/docs/wiki/unity/extensions) 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](https://ai-game.dev/docs/rql/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:

```bash
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.

```bash
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:

```bash
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](https://ai-game.dev/docs/tools/unity) and [RQL reference](https://ai-game.dev/docs/rql).
- [Custom tools](https://ai-game.dev/docs/wiki/unity/custom-tools) to add your own.
- [Unity best practices](https://ai-game.dev/docs/best-practices/unity) for prompting.

---

Source (HTML): https://ai-game.dev/docs/wiki/unity/tools-and-rql