# Tools

The Godot MCP tools AI agents use in the Godot editor, RQL queries for nodes, scenes and resources, C# and GDScript scripts, screenshots and in-game tools.

_Last updated: 2026-11-04_

Godot MCP ships 24 built-in tools in 9 families. Most editor work goes through three RQL tools, so the agent uses one query language for nodes, scenes, resources, files and editor state instead of dozens of separate tools. This page explains each family and when the agent uses it. The searchable list with parameters and example prompts is the [Godot tools catalog](https://ai-game.dev/docs/tools/godot).

## Tool families

| Family | Tools | What it is for |
| --- | --- | --- |
| rql | `rql-query`, `rql-mutate`, `rql-schema` | Read and change the live editor: nodes, Godot properties, scenes, resources, files, project settings, input map, autoloads, groups, signals and editor state. |
| script | `script-read`, `script-create`, `script-update`, `script-delete`, `script-attach-to-node`, `script-validate`, `script-build`, `script-execute` | C# and GDScript files, attaching scripts, validating GDScript, building the C# project and running C# in the editor. |
| screenshot | `screenshot-viewport`, `screenshot-camera`, `screenshot-isolated` | PNG images of the editor viewport, a camera, or a node rendered on its own. |
| console | `console-get-logs`, `console-clear-logs` | Logs of a running game. In the editor, the RQL `console` source. |
| reflection | `reflection-method-find`, `reflection-method-call` | Find and call C# methods in a running game. In the editor, RQL `call`. |
| runtime-errors | `runtime-errors-get`, `runtime-errors-clear` | Errors raised inside a running game. Off by default. |
| ping | `ping` | Readiness probe. A system tool, not shown to agents. |
| skills | `godot-skill-create`, `godot-skill-generate` | Write a new tool file, regenerate skill files. System tools. |
| session | `session-close` | Save and quit an editor that `godot-cli` started. System tool. |

System tools are reached over the server's `/api/system-tools/` route (for example with `godot-cli run-system-tool ping`) and are not listed to AI agents. The console, reflection and runtime-errors families serve a running game that you connected yourself; see [Custom tools](https://ai-game.dev/docs/wiki/godot/custom-tools#runtime).

## RQL: one query language for the editor

RQL (Reflection Query Language) is the data layer of the editor tools. A query starts from a source, filters and shapes it with stages separated by `|`, and in `rql-mutate` ends with `set` or `call`. Some examples the agent might send:

```text
nodes | where class == "OmniLight3D" | select name props["light_energy"]
nodes | where name starts-with "Enemy" | set Visible = false
root | call AddChild("Node3D", "Props")
project | call AddInputAction("jump", ["Key:Space"])
files | sort size desc | first 5 | select path size importedSize
editor | call SaveScene()
```

- `rql-query` is read-only and returns compact rows.
- `rql-mutate` changes things. Every target and value is checked first, so a failing query changes nothing. `dry_run` previews the change. Each call is one undo step (Ctrl+Z in the editor).
- `rql-schema` lists the sources, functions and node classes in the edited scene, or the members, methods and Godot properties of one type. With an extension name it prints that extension's guide.

Sources include `nodes`, `root`, `selection`, `scenes`, `files`, `folders`, `classes`, `console`, `editor`, `project`, `settings`, `inputActions`, `autoloads`, `groups`, `layers` and `tools`. Godot properties are reachable as C# members (`Position`, `Visible`) or by their Godot name in `props["snake_name"]`, which includes GDScript variables. RQL also handles signals, groups, TileSets, Themes, ShaderMaterial parameters and MeshLibraries.

Editor calls cover scene and file work: `NewScene`, `OpenScene`, `SaveScene`, `SaveAllScenes`, `ReloadScene`, `CreateResource`, `MoveResource`, `DeleteResource`, `CreateFolder`, `DeleteFolder`, `Reimport`, `Undo`, `Redo`, `PlayScene` and `StopScene`. The `gameLog` source reads what a game started from the editor printed.

Scene edits mark the scene unsaved, like your own edits. Edited resource files and `project.godot` are saved immediately.

## Scripts: C# and GDScript

- `script-read`, `script-create`, `script-update`, `script-delete` work on `.cs` and `.gd` files.
- `script-attach-to-node` attaches a script to a node.
- `script-validate` returns parse and compile diagnostics for GDScript files; without a path it checks every `.gd` file under `res://`.
- `script-build` runs `dotnet build` (Debug) so new C# scripts load. Godot then reloads the C# assembly and the addon reconnects, and the build result (warnings or errors) arrives after the reload.
- `script-execute` compiles and runs C# in the editor with Roslyn. Write plain statements; the last expression is the result. It returns the value and what the code printed. Snippets time out after 30 seconds by default (at most 4 minutes), and an endless loop returns a timeout error instead of freezing the editor.

You can call `script-execute` from a terminal too:

```bash
godot-cli exec 'EditorInterface.Singleton.GetEditedSceneRoot()?.Name' --path ./MyGodotProject
```

## Screenshots

The screenshot tools return PNG images the model can inspect: `screenshot-viewport` captures the editor viewport, `screenshot-camera` renders from a camera node, and `screenshot-isolated` renders one node on its own from a chosen angle. Ask for a screenshot after visual changes so the agent can check its own work.

## In-game tools

`console-*`, `reflection-*` and `runtime-errors-*` run inside your game, not in the editor. A game exposes nothing until your code opts in and connects; `runtime-errors-get` additionally needs `WithRuntimeErrorCapture()`. It captures GDScript runtime errors, `push_error` and `push_warning`, shader errors (Godot 4.5 and newer) and unhandled C# exceptions, so an agent can run the game and see what actually broke. Setup: [Custom tools](https://ai-game.dev/docs/wiki/godot/custom-tools#runtime).

## Choosing which tools the agent sees

Every tool has a **Visible** switch in the dock (MCP features, Tools, Open) and in `godot-cli configure`. Hiding a tool removes it from the agent's tool list, which saves context, but does not block it. See [Configuration](https://ai-game.dev/docs/wiki/godot/configuration#mcp-features).

## More tools

- [Extensions](https://ai-game.dev/docs/wiki/godot/extensions) teach RQL about AnimationPlayer, CSG, GridMap, navigation, particles, TileMapLayer and the Beehave, Dialogic, Phantom Camera and Terrain3D addons.
- [Custom tools](https://ai-game.dev/docs/wiki/godot/custom-tools) shows how to write your own tools in C#.
- [Best practices for Godot](https://ai-game.dev/docs/best-practices/godot) has prompt patterns that use these tools well.

---

Source (HTML): https://ai-game.dev/docs/wiki/godot/tools