Skip to main content
Glama

Node Set Property

node_set_property

Set a property on a Godot scene node, coercing values to the expected type. Verify the exact property name first to avoid write failures.

Instructions

Set a property on a node.

Overrides on an instance's internal nodes require Editable Children to be explicitly enabled; otherwise the call fails before mutation.

Verify the property name first — call node_get_properties (or read godot://node/{path}/properties) to confirm the exact name and type before writing. Guessing common Godot names often fails with PROPERTY_NOT_ON_CLASS because Godot's actual properties differ from intuition (e.g. Camera3D uses fov/current, not field_of_view; Sprite2D uses texture, not image; Node3D uses position/rotation/scale, not transform.origin).

Coerces value to the property's type:

  • Vector2/Vector3: dict with x/y/z keys.

  • Color: dict {r,g,b,a} or hex string ("#ff0000").

  • NodePath: string ("../Other/Node").

  • Node-typed export (@export var target: Node2D): node path string, either a scene path ("/Main/Player") or relative to the node ("../Player"); the node's class is checked against the export's type, and the response reports the scene path. null/"" clears.

  • Typed node array (@export var targets: Array[Node2D]): JSON list of node path strings, each resolved and class-checked the same way; errors name the element index.

  • Resource: res:// path string (loads + assigns); null/"" clears. {"__class__": "BoxMesh", ...} creates a built-in resource owned by this property. After scene_save it is serialized in-place as a [sub_resource] inside the .tscn; it is not a reusable .tres. For sharing, first call resource_manage(op="create", params={"type": "BoxMesh", "properties": {...}, "resource_path": "res://meshes/box.tres"}), then pass that res:// path here (or use resource_manage(op="assign")).

  • StringName: plain string. Array/Dictionary: JSON list/object.

  • PackedByteArray: JSON list of whole numbers 0..255, at most 65,536 bytes per value. [] clears. Strings, booleans, fractions and out-of-range values are rejected before mutation. Also supported inside typed containers and resource constructor properties.

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": {
      "path": "<path>",
      "property": "<property>",
      "value": "<value>"
    },
    "name": "node_set_property"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesScene path relative to the edited scene root (e.g. "/Main/Camera3D"), NOT runtime "/root/..." paths.
valueYesNew value. Pass null (or "" for resources) to clear.
propertyYesProperty name (e.g. "fov", "position", "mesh"). Must match Godot's exact identifier — introspect with ``node_get_properties`` if unsure rather than guessing.
scene_fileNoOptional editor-scene guard.
session_idNoOptional Godot session to target. Empty = active session.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv3.1.4
  2. Removedv3.0.7
  3. First observedv2.9.1

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the entire burden and does so thoroughly: it discloses the Editable Children gate, that failures occur before mutation, the exact error class (PROPERTY_NOT_ON_CLASS), validation rejections for PackedByteArray (strings, booleans, fractions, out-of-range, 65,536-byte cap), and that inline resources are serialized as [sub_resource] rather than reusable .tres. That is far more than the name implies and covers safety, failure modes, and side effects.

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 action, then prerequisite, then verification, then a well-structured bullet list of coercions — logical and scannable. It is long, and a few parts duplicate schema text (the 'must match Godot's exact identifier / introspect with node_get_properties' warning appears in both the description and the `property` param), and the Camera3D/Sprite2D/Node3D examples are illustrative but wordy.

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?

An output schema exists, so return values need not be explained, yet the description still notes the response reports the resolved scene path for node-typed exports. Combined with the coercion table, error naming, and serialization caveat, nothing an agent needs to call this 5-parameter mutation tool correctly is missing.

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

Parameters5/5

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

Schema coverage is already 100%, so baseline would be 3, but the description adds substantial meaning the schema cannot express: per-type coercion rules for `value` (Vector dicts, Color hex, NodePath strings, typed node arrays with class checking and element-indexed errors, Resource res:// paths and __class__ constructors, PackedByteArray constraints). It also clarifies clearing semantics (null/"") and node-path formats.

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?

Opens with a specific verb+resource ('Set a property on a node'), which is unmistakable against siblings like node_get_properties, node_create, or resource_manage. It also names node_get_properties and resource_manage as the tools for adjacent jobs, so an agent can route without opening a 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?

Gives a concrete precondition (Editable Children must be enabled for instance-internal nodes, else the call fails before mutation) and a mandatory verification step (call node_get_properties or read godot://node/{path}/properties first). It also routes the shared-resource case to resource_manage. It stops short of stating when not to use this tool at all (e.g. vs node_manage or batch_execute), so it is clear context rather than full when/when-not coverage.

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