Skip to main content
Glama

add_node

Add a node to a Godot scene or instance another scene as a child, with type-checked property values saved automatically. Invalid types, parents, or properties error without adding anything.

Instructions

Add a node to a scene, or instance another scene when nodeType is a scene path. Saves automatically. Values in properties are checked against each property's declared type; a mismatch errors (Property Values in docs/tools.md). Returns: nodeName, nodeType and nodePath, read back after the add; warnings leads when Godot renamed the node or a value will not be saved. Errors and adds nothing if the type, parent or a property is invalid. Errors while a runtime session is live on this project.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "projectPath": "<projectPath>",
      "scenePath": "<scenePath>",
      "nodeType": "<nodeType>",
      "nodeName": "<nodeName>"
    },
    "name": "add_node"
  }
}

Input Schema

NameRequiredDescriptionDefault
scaleNoScale: {"x": 2, "y": 2} on a 2D node, {"x": 2, "y": 2, "z": 2} on a 3D node. Shorthand for properties.scale; properties wins on a conflict.
visibleNoWhether the node is visible. Shorthand for properties.visible; properties wins on a conflict.
modulateNoColor modulation (e.g. {"r": 1, "g": 0, "b": 0, "a": 1}). Shorthand for properties.modulate; properties wins on a conflict.
nodeNameYesName for the new node as it appears in the scene tree
nodeTypeYesGodot node class to instantiate (e.g. "Sprite2D", "CollisionShape2D", "Label"), or a project-relative scene path (.tscn or .scn, e.g. "scenes/enemy.tscn") to instance an existing scene as a child - instanced children serialize as `instance=ExtResource(...)` on save
positionNoPosition: {"x": 100, "y": 200} on a 2D node, {"x": 0, "y": 1, "z": 0} on a 3D node. Shorthand for properties.position; properties wins on a conflict.
rotationNoRotation in radians, for a 2D node. On a 3D node rotation is a vector: pass it as properties.rotation, {"x", "y", "z"} in radians. Shorthand for properties.rotation; properties wins on a conflict.
scenePathYesScene file path relative to the project
propertiesNoAdditional property values as a JSON object. A key here wins over the same top-level shorthand (position, rotation, scale, visible, modulate). An Object-typed property takes a res:// path, a {type: ClassName, ...props} dict that builds a Resource inline, or null; slash-suffixed keys like shader_parameter/<uniform> go inside that dict, not on the node; metadata/<name> and slash keys the node declares go straight into properties. Coercion and Packed*Array / Array[T] / Dictionary[K, V] element rules: Property Values in docs/tools.md.
projectPathYesPath to the Godot project directory
parentNodePathNoParent node path from scene root (e.g. "root/Player"). Defaults to the root node; an empty string also means the root.

Output Schema

NameRequiredDescriptionDefault
nodeNameYesName the node has after the add. Differs from the requested nodeName when Godot renamed it.
nodePathYesPath from the scene root in "root/..." form, usable as nodePath elsewhere.
nodeTypeYesClass of the added node, or of the root of an instanced scene.
warningsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv4.0.1
    • changedInput schema / properties / modulate / description
      Previous value: -"Color modulation (e.g. {\"r\": 1, \"g\": 0, \"b\": 0, \"a\": 1})"New value: +"Color modulation (e.g. {\"r\": 1, \"g\": 0, \"b\": 0, \"a\": 1}). Shorthand for properties.modulate; properties wins on a conflict."
    • changedInput schema / properties / parentNodePath / description
      Previous value: -"Parent node path from scene root (e.g. \"root/Player\"). Defaults to the root node."New value: +"Parent node path from scene root (e.g. \"root/Player\"). Defaults to the root node; an empty string also means the root."
    • changedInput schema / properties / position / description
      Previous value: -"Position: {\"x\": 100, \"y\": 200} on a 2D node, {\"x\": 0, \"y\": 1, \"z\": 0} on a 3D node"New value: +"Position: {\"x\": 100, \"y\": 200} on a 2D node, {\"x\": 0, \"y\": 1, \"z\": 0} on a 3D node. Shorthand for properties.position; properties wins on a conflict."
    • changedInput schema / properties / properties / description
      Previous value: -"Additional property values as a JSON object. Top-level params (position, rotation, etc.) take precedence over keys in this dict."New value: +"Additional property values as a JSON object. A key here wins over the same top-level shorthand (position, rotation, scale, visible, modulate). An Object-typed property takes a res:// path, a {type: ClassName, ...props} dict that builds a Resource inline, or null; slash-suffixed keys like shader_parameter/<uniform> go inside that dict, not on the node; metadata/<name> and slash keys the node declares go straight into properties. Coercion and Packed*Array / Array[T] / Dictionary[K, V] element rules: Property Values in docs/tools.md."
    • changedInput schema / properties / rotation / description
      Previous value: -"Rotation in radians"New value: +"Rotation in radians, for a 2D node. On a 3D node rotation is a vector: pass it as properties.rotation, {\"x\", \"y\", \"z\"} in radians. Shorthand for properties.rotation; properties wins on a conflict."
    • changedInput schema / properties / scale / description
      Previous value: -"Vector2 scale (e.g. {\"x\": 2, \"y\": 2})"New value: +"Scale: {\"x\": 2, \"y\": 2} on a 2D node, {\"x\": 2, \"y\": 2, \"z\": 2} on a 3D node. Shorthand for properties.scale; properties wins on a conflict."
    • addedInput schema / properties / scale / properties / z
      Added value: +{
      +  "type": "number"
      +}
    • changedInput schema / properties / visible / description
      Previous value: -"Whether the node is visible"New value: +"Whether the node is visible. Shorthand for properties.visible; properties wins on a conflict."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "nodeName": {
      +      "description": "Name the node has after the add. Differs from the requested nodeName when Godot renamed it.",
      +      "type": "string"
      +    },
      +    "nodePath": {
      +      "description": "Path from the scene root in \"root/...\" form, usable as nodePath elsewhere.",
      +      "type": "string"
      +    },
      +    "nodeType": {
      +      "description": "Class of the added node, or of the root of an instanced scene.",
      +      "type": "string"
      +    },
      +    "warnings": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "nodeName",
      +    "nodeType",
      +    "nodePath"
      +  ],
      +  "type": "object"
      +}
  2. Changed1 schema field changedv3.6.0
    • changedInput schema / properties / nodeType / description
      Previous value: -"Godot node class to instantiate (e.g. \"Sprite2D\", \"CollisionShape2D\", \"Label\"), or a project-relative scene path (.tscn or .scn, e.g. \"scenes/enemy.tscn\") to instance an existing scene as a child — instanced children serialize as `instance=ExtResource(...)` on save"New value: +"Godot node class to instantiate (e.g. \"Sprite2D\", \"CollisionShape2D\", \"Label\"), or a project-relative scene path (.tscn or .scn, e.g. \"scenes/enemy.tscn\") to instance an existing scene as a child - instanced children serialize as `instance=ExtResource(...)` on save"
  3. Changed4 schema fields changedv3.3.0
    • changedInput schema / properties / nodeType / description
      Previous value: -"Godot node class to instantiate (e.g. \"Sprite2D\", \"CollisionShape2D\", \"Label\")"New value: +"Godot node class to instantiate (e.g. \"Sprite2D\", \"CollisionShape2D\", \"Label\"), or a project-relative scene path (.tscn or .scn, e.g. \"scenes/enemy.tscn\") to instance an existing scene as a child — instanced children serialize as `instance=ExtResource(...)` on save"
    • changedInput schema / properties / position / description
      Previous value: -"Vector2 position (e.g. {\"x\": 100, \"y\": 200})"New value: +"Position: {\"x\": 100, \"y\": 200} on a 2D node, {\"x\": 0, \"y\": 1, \"z\": 0} on a 3D node"
    • addedInput schema / properties / position / properties / z
      Added value: +{
      +  "type": "number"
      +}
    • removedInput schema / properties / position3d
      Removed value: -{
      -  "description": "Vector3 position for 3D nodes (e.g. {\"x\": 0, \"y\": 1, \"z\": 0})",
      -  "properties": {
      -    "x": {
      -      "type": "number"
      -    },
      -    "y": {
      -      "type": "number"
      -    },
      -    "z": {
      -      "type": "number"
      -    }
      -  },
      -  "type": "object"
      -}
  4. Addedv3.1.1
  5. Removedv3.0.0
  6. Addedv1.0.0

TDQS

A4/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so well: it discloses automatic saving, type-checked property values that error on mismatch, atomic failure ('errors and adds nothing'), rename warnings via the warnings lead, and a hard precondition that a live runtime session on the project causes an error. This covers mutation semantics, validation, side effects, and prerequisites.

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

Conciseness4/5

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

Front-loaded with the core action and the dual mode, then behavior, returns, and error conditions in a compact block. The final sentences are dense and slightly run-on, but nearly every clause carries information.

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 an 11-parameter mutation tool with no annotations, the definition covers the action, the two nodeType modes, save behavior, validation and failure semantics, runtime-session precondition, and return shape. Nothing an agent needs to invoke it correctly appears to be missing.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all 11 parameters including shorthands and the properties precedence rule. The description adds only the type-validation consequence for properties and the nodeType-as-scene-path mode, both of which are largely restated from the schema, so baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource ('Add a node to a scene') and additionally clarifies a second mode where nodeType is a scene path, so the agent knows the tool both instantiates classes and instances scenes. It does not differentiate itself from siblings such as duplicate_node or move_nodes.

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

Usage Guidelines3/5

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

Usage is implied: use this to add a node, and the dual nodeType behavior is explained. There is no explicit when-to-use vs alternatives guidance (e.g. duplicate_node for copying an existing node, move_nodes for reparenting), leaving the agent to infer selection.

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