Skip to main content
Glama

set_node_properties

Idempotent

Update node properties in a Godot scene with type-checked values and save changes in one call.

Instructions

Set node properties in a scene in one Godot process. Always-array: one update for a one-off edit. Each value is checked against the property's declared type, never stored as a zero (Property Values in docs/tools.md). A Dictionary or Array value replaces the stored one whole; send every key. Saves once. Returns: results[], one per update in input order, each with success, error or skipped; warnings leads when a value is set but not saved. Errors while a runtime session is live.

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>",
      "updates": "<updates>"
    },
    "name": "set_node_properties"
  }
}

Input Schema

NameRequiredDescriptionDefault
updatesYesProperty updates to apply
scenePathYesScene file path relative to the project
projectPathYesPath to the Godot project directory
abortOnErrorNoStop processing on first error (default: false)

Output Schema

NameRequiredDescriptionDefault
resultsYes
warningsNoPresent when an update succeeded on the loaded scene but the scene file does not store it (a script variable declared without @export), naming the update index, or when the save dropped content no update asked to change.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv4.0.1
    • changedInput schema / properties / updates / items / properties / property / description
      Previous value: -"GDScript property name in snake_case (e.g. \"position\", \"modulate\", \"collision_layer\")"New value: +"GDScript property name in snake_case (e.g. \"position\", \"modulate\", \"collision_layer\"), or \"metadata/<name>\", or a slash key the node declares (e.g. \"theme_override_colors/font_color\")"
    • changedInput schema / properties / updates / items / properties / value / description
      Previous value: -"New property value. Vector2/Vector3/Color auto-convert from {\"x\",\"y\"} / {\"x\",\"y\",\"z\"} / {\"r\",\"g\",\"b\",\"a\"} objects; primitives pass through. Packed*Array and script-declared Array[T] properties take a plain array and the element conversions apply per element (e.g. [{\"x\":10,\"y\":20}, ...] for Polygon2D.polygon); an element that cannot represent the element type errors with its index instead of silently storing zeros."New value: +"New property value. Vector2/Vector3/Color auto-convert from {\"x\",\"y\"} / {\"x\",\"y\",\"z\"} / {\"r\",\"g\",\"b\",\"a\"} objects; primitives pass through. Packed*Array and script-declared Array[T] properties take a plain array and the element conversions apply per element (e.g. [{\"x\":10,\"y\":20}, ...] for Polygon2D.polygon); a script-declared Dictionary[K, V] takes a plain object (keys are strings, converted to K); an element that cannot represent the element type errors with its index or key instead of silently storing zeros. Object-typed properties (e.g. CollisionShape2D.shape) take a res:// path, a {type: ClassName, ...props} dict that builds a Resource inline, or null to clear; slash-suffixed keys like shader_parameter/<uniform> go inside that dict, not on the node."
    • addedOutput schema / properties / results / items / properties / resolvedNodePath
      Added value: +{
      +  "description": "Where nodePath led, in root/... form. Present when the node was found; differs from nodePath for a %Name path.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / results / items / properties / skipped
      Added value: +{
      +  "description": "True when abortOnError stopped processing before this update.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / warnings
      Added value: +{
      +  "description": "Present when an update succeeded on the loaded scene but the scene file does not store it (a script variable declared without @export), naming the update index, or when the save dropped content no update asked to change.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / required
      Added value: +[
      +  "results"
      +]
  2. Changed1 schema field changedv3.8.0
    • changedInput schema / properties / updates / items / properties / value / description
      Previous value: -"New property value"New value: +"New property value. Vector2/Vector3/Color auto-convert from {\"x\",\"y\"} / {\"x\",\"y\",\"z\"} / {\"r\",\"g\",\"b\",\"a\"} objects; primitives pass through. Packed*Array and script-declared Array[T] properties take a plain array and the element conversions apply per element (e.g. [{\"x\":10,\"y\":20}, ...] for Polygon2D.polygon); an element that cannot represent the element type errors with its index instead of silently storing zeros."
  3. Addedv3.1.1

TDQS

A4/5.0
Behavior5/5

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

Beyond the lone idempotentHint annotation, the description discloses that values are type-checked and never silently stored as zeros, that Dictionary/Array values replace the stored value wholesale ("send every key"), that the scene is saved once, and that runtime sessions cause errors. It also describes the return payload (results[] in input order with success/error/skipped, plus warnings) even though an output schema exists. None of this contradicts idempotentHint.

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?

Roughly 110 words, front-loaded with the core action and then the calling pattern, with every sentence carrying information. A few clauses are terse to the point of being cryptic ("warnings leads when a value is set but not saved") and the type-conversion detail largely duplicates the schema.

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

Completeness4/5

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

For a 4-parameter mutation tool with full schema coverage and an output schema, this covers the essentials: validation behavior, persistence, error conditions, and result ordering. Minor gaps remain around abortOnError's effect and whether the target scene must already exist on disk.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: the array-form requirement for `updates`, the replace-whole semantics for Dictionary/Array values, and the fact that failures are reported per element rather than silently coerced. `abortOnError` is left entirely to the schema, which keeps it from a 5.

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?

"Set node properties in a scene in one Godot process" gives a specific verb (set), resource (node properties), and scope (a scene file, single process invocation), which naturally separates it from set_resource_properties and set_project_setting. It stops short of explicitly naming any sibling or stating what this tool is not, so it stays at a clear-but-undifferentiated 4.

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?

"Always-array: one update for a one-off edit" clarifies the calling pattern even for a single edit, and "Errors while a runtime session is live" is a real precondition worth knowing. However, there is no explicit statement of when to choose this over set_resource_properties or batch_scene_operations, and no mention of preconditions such as the scene existing or being saved.

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