Godot MCP Runtime

Overview Schema Source Related Servers Discussions Admin

delete_nodes

Destructive

Remove one or more nodes and their descendants from a Godot scene file, saving after all deletions. Use an array of node paths; scene root cannot be removed.

Instructions

Remove one or more nodes (and their descendants) from a scene file. Always-array: pass a single-element nodePaths array for one-off deletes. Saves once at the end. Cannot delete the scene root - that entry returns an error and the rest still process. Returns: results array with one entry per nodePath in input order (success or error message). Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it.

Input Schema

TableJSON Schema

Name	Required	Description
`nodePaths`	Yes	Node paths from scene root to delete (e.g. ["root/Player/Sprite2D"])
`scenePath`	Yes	Scene file path relative to the project (e.g. "scenes/main.tscn")
`projectPath`	Yes	Path to the Godot project directory

Output Schema

TableJSON Schema

Name	Required	Description	Default
`results`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv3.1.1May 17, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the destructiveHint=true annotation, it discloses that descendants are removed, that the save happens once at the end, that a root-delete fails per-entry without aborting the batch, and that an active runtime session causes errors. These are meaningful behaviors an agent cannot get from annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then packs array semantics, failure behavior, return shape, and prerequisites into tight sentences with zero filler. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive batch mutation with an output schema already defined, the description covers the safety-relevant behaviors, partial-failure semantics, prerequisites, and return structure. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the baseline is 3, but the description adds the non-obvious always-array contract (single-element array for one-off deletes), which prevents a common invocation mistake. The per-entry results ordering also clarifies how nodePaths maps to output.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Remove) and resource (nodes and their descendants) plus scope (from a scene file). An agent can distinguish it cleanly from add_node, duplicate_node, and remove_autoload without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Adds operational guidance: always-array contract for one-off deletes, the scene-root exclusion, and the runtime-session prerequisite with concrete remedies (stop_project/detach_project). It stops short of an explicit when-to-use/when-not comparison against sibling mutation tools, but the context is otherwise clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.