Skip to main content
Glama

validate

Check GDScript syntax or Godot scene integrity in headless Godot before attaching or running scripts; catches script, scene, structure, and signal errors.

Instructions

Validate GDScript syntax or scene integrity in headless Godot. Use before attach_script or run_script. Give exactly one of scriptPath, source or scenePath, or a targets array (one process); an unknown key is an error. checks needs scenePath and instantiates the scene, running each attached script's _init(). Returns: { warnings?, valid, errors } for one target, { warnings?, results: [{ target, valid, errors }] } for targets; an invalid result always has an error.

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

Input Schema

NameRequiredDescriptionDefault
checksNo[single, requires scenePath] Structural and signal-verification checks to run against the scene. Types: "structure" (validate node tree against a schema) and "signals" (verify signal connections and handler methods, optional nodePath scope). Merged into the errors array with a "check" discriminator. Not accepted alongside targets: put checks on the target they belong to.
sourceNo[single] Inline GDScript source code to validate. Written to a temporary file and validated against the project.
targetsNo[batch] Array of targets to validate in a single Godot process. Each item is an object with exactly one of scriptPath, source or scenePath, or a bare path string (.gd = scriptPath, .tscn or .scn = scenePath). Cannot be combined with the top-level scriptPath, source, scenePath or checks.
scenePathNo[single] Path to a .tscn scene file relative to the project to validate (e.g. "scenes/main.tscn")
scriptPathNo[single] Path to a .gd file relative to the project to validate (e.g. "scripts/player.gd"). A file that does not load as a GDScript is reported invalid with a "Not validated" error, since nothing checks it.
projectPathYesPath to the Godot project directory

Output Schema

NameRequiredDescriptionDefault
validNoSingle target only.
errorsNoSingle target only.
resultsNotargets only: one entry per target, in input order.
warningsNoEngine diagnostics that matched no validated file (an autoload, a script attached inside a scene), as "<file>:<line>: <message>", capped with a "+N more" tail. They do not change valid.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv4.0.1
    • changedInput schema / properties / checks / description
      Previous value: -"[single, requires scenePath] Structural and signal-verification checks to run against the scene. Types: \"structure\" (validate node tree against a schema) and \"signals\" (verify signal connections and handler methods, optional nodePath scope). Merged into the errors array with a \"check\" discriminator."New value: +"[single, requires scenePath] Structural and signal-verification checks to run against the scene. Types: \"structure\" (validate node tree against a schema) and \"signals\" (verify signal connections and handler methods, optional nodePath scope). Merged into the errors array with a \"check\" discriminator. Not accepted alongside targets: put checks on the target they belong to."
    • changedInput schema / properties / scriptPath / description
      Previous value: -"[single] Path to a .gd file relative to the project to validate (e.g. \"scripts/player.gd\")"New value: +"[single] Path to a .gd file relative to the project to validate (e.g. \"scripts/player.gd\"). A file that does not load as a GDScript is reported invalid with a \"Not validated\" error, since nothing checks it."
    • changedInput schema / properties / targets / description
      Previous value: -"[batch] Array of targets to validate in a single Godot process. Each item must have exactly one of: scriptPath, source, or scenePath."New value: +"[batch] Array of targets to validate in a single Godot process. Each item is an object with exactly one of scriptPath, source or scenePath, or a bare path string (.gd = scriptPath, .tscn or .scn = scenePath). Cannot be combined with the top-level scriptPath, source, scenePath or checks."
    • addedInput schema / properties / targets / items / anyOf
      Added value: +[
      +  {
      +    "description": "A path ending in .gd, .tscn or .scn",
      +    "type": "string"
      +  },
      +  {
      +    "properties": {
      +      "checks": {
      +        "description": "[requires scenePath] Structural / signal checks for this target, run in the same Godot process as the rest of the batch. Same shape as the top-level checks array.",
      +        "items": {
      +          "properties": {
      +            "nodePath": {
      +              "description": "[signals] Optional node path to scope the check to a subtree (e.g. \"root/HUD\")",
      +              "type": "string"
      +            },
      +            "schema": {
      +              "description": "[structure] Recursive node schema: { type?: string, children?: Schema[], hasProperty?: string }. Checks the root node and subtree.",
      +              "type": "object"
      +            },
      +            "type": {
      +              "description": "The kind of check to run",
      +              "enum": [
      +                "structure",
      +                "signals"
      +              ],
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "type"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "scenePath": {
      +        "description": "Path to a .tscn scene file relative to the project",
      +        "type": "string"
      +      },
      +      "scriptPath": {
      +        "description": "Path to a .gd file relative to the project",
      +        "type": "string"
      +      },
      +      "source": {
      +        "description": "Inline GDScript source code",
      +        "type": "string"
      +      }
      +    },
      +    "type": "object"
      +  }
      +]
    • removedInput schema / properties / targets / items / properties
      Removed value: -{
      -  "checks": {
      -    "description": "[requires scenePath] Structural / signal checks for this target, run in the same Godot process as the rest of the batch. Same shape as the top-level checks array.",
      -    "items": {
      -      "properties": {
      -        "nodePath": {
      -          "description": "[signals] Optional node path to scope the check to a subtree (e.g. \"root/HUD\")",
      -          "type": "string"
      -        },
      -        "schema": {
      -          "description": "[structure] Recursive node schema: { type?: string, children?: Schema[], hasProperty?: string }. Checks the root node and subtree.",
      -          "type": "object"
      -        },
      -        "type": {
      -          "description": "The kind of check to run",
      -          "enum": [
      -            "structure",
      -            "signals"
      -          ],
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "type"
      -      ],
      -      "type": "object"
      -    },
      -    "type": "array"
      -  },
      -  "scenePath": {
      -    "description": "Path to a .tscn scene file relative to the project",
      -    "type": "string"
      -  },
      -  "scriptPath": {
      -    "description": "Path to a .gd file relative to the project",
      -    "type": "string"
      -  },
      -  "source": {
      -    "description": "Inline GDScript source code",
      -    "type": "string"
      -  }
      -}
    • removedInput schema / properties / targets / items / type
      Removed value: -"object"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "errors": {
      +      "description": "Single target only.",
      +      "items": {
      +        "properties": {
      +          "check": {
      +            "description": "checks[] findings: \"structure\" or \"signals\".",
      +            "type": "string"
      +          },
      +          "line": {
      +            "description": "Parse errors only, when Godot reported a line.",
      +            "type": "number"
      +          },
      +          "message": {
      +            "type": "string"
      +          },
      +          "method": {
      +            "type": "string"
      +          },
      +          "node": {
      +            "type": "string"
      +          },
      +          "path": {
      +            "description": "Structure findings about one node.",
      +            "type": "string"
      +          },
      +          "problem": {
      +            "description": "Signals findings: the problem code.",
      +            "type": "string"
      +          },
      +          "severity": {
      +            "description": "\"warning\" on a finding that does not make the target invalid (an orphaned_handler that may be connected in code).",
      +            "type": "string"
      +          },
      +          "signal": {
      +            "type": "string"
      +          },
      +          "target": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "message"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "results": {
      +      "description": "targets only: one entry per target, in input order.",
      +      "items": {
      +        "properties": {
      +          "errors": {
      +            "items": {
      +              "properties": {
      +                "check": {
      +                  "description": "checks[] findings: \"structure\" or \"signals\".",
      +                  "type": "string"
      +                },
      +                "line": {
      +                  "description": "Parse errors only, when Godot reported a line.",
      +                  "type": "number"
      +                },
      +                "message": {
      +                  "type": "string"
      +                },
      +                "method": {
      +                  "type": "string"
      +                },
      +                "node": {
      +                  "type": "string"
      +                },
      +                "path": {
      +                  "description": "Structure findings about one node.",
      +                  "type": "string"
      +                },
      +                "problem": {
      +                  "description": "Signals findings: the problem code.",
      +                  "type": "string"
      +                },
      +                "severity": {
      +                  "description": "\"warning\" on a finding that does not make the target invalid (an orphaned_handler that may be connected in code).",
      +                  "type": "string"
      +                },
      +                "signal": {
      +                  "type": "string"
      +                },
      +                "target": {
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "message"
      +              ],
      +              "type": "object"
      +            },
      +            "type": "array"
      +          },
      +          "target": {
      +            "type": "string"
      +          },
      +          "valid": {
      +            "type": "boolean"
      +          }
      +        },
      +        "required": [
      +          "target",
      +          "valid",
      +          "errors"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "valid": {
      +      "description": "Single target only.",
      +      "type": "boolean"
      +    },
      +    "warnings": {
      +      "description": "Engine diagnostics that matched no validated file (an autoload, a script attached inside a scene), as \"<file>:<line>: <message>\", capped with a \"+N more\" tail. They do not change valid.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Changed3 schema fields changedv3.8.0
    • addedInput schema / properties / checks
      Added value: +{
      +  "description": "[single, requires scenePath] Structural and signal-verification checks to run against the scene. Types: \"structure\" (validate node tree against a schema) and \"signals\" (verify signal connections and handler methods, optional nodePath scope). Merged into the errors array with a \"check\" discriminator.",
      +  "items": {
      +    "properties": {
      +      "nodePath": {
      +        "description": "[signals] Optional node path to scope the check to a subtree (e.g. \"root/HUD\")",
      +        "type": "string"
      +      },
      +      "schema": {
      +        "description": "[structure] Recursive node schema: { type?: string, children?: Schema[], hasProperty?: string }. Checks the root node and subtree.",
      +        "type": "object"
      +      },
      +      "type": {
      +        "description": "The kind of check to run",
      +        "enum": [
      +          "structure",
      +          "signals"
      +        ],
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "type"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / targets / items / properties / checks
      Added value: +{
      +  "description": "[requires scenePath] Structural / signal checks for this target, run in the same Godot process as the rest of the batch. Same shape as the top-level checks array.",
      +  "items": {
      +    "properties": {
      +      "nodePath": {
      +        "description": "[signals] Optional node path to scope the check to a subtree (e.g. \"root/HUD\")",
      +        "type": "string"
      +      },
      +      "schema": {
      +        "description": "[structure] Recursive node schema: { type?: string, children?: Schema[], hasProperty?: string }. Checks the root node and subtree.",
      +        "type": "object"
      +      },
      +      "type": {
      +        "description": "The kind of check to run",
      +        "enum": [
      +          "structure",
      +          "signals"
      +        ],
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "type"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedInput schema / properties / targets / items / properties / scenePath / description
      Previous value: -"Path to a .tscn file relative to the project"New value: +"Path to a .tscn scene file relative to the project"
  3. Addedv3.1.1
  4. Removedv3.0.0
  5. Addedv1.0.0

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the strict mutual-exclusivity contract ('exactly one of ... or a targets array'), that unknown keys are errors, and that checks instantiates the scene and runs each attached script's _init() — a real side effect the schema does not mention. It omits whether the tool mutates project files or how long a batch run may take, so it falls just short of fully transparent.

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 purpose and the ordering rule, then constraints, then return shape — a sensible information hierarchy with little waste. The middle sentence packing the mutual-exclusion rule and error behavior is dense and reads as a run-on, costing a point on crispness.

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 six-parameter, multi-mode (single/batch) tool with a nested checks concept, the description covers mode selection, exclusivity rules, the scenePath prerequisite for checks, side effects, and both return shapes. Combined with the existing output schema and 100% parameter coverage, nothing an agent needs in order 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.

Parameters3/5

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

Schema coverage is 100%, so per-parameter meaning is already fully documented, including the mutual-exclusion notes in the targets and checks descriptions. The description condenses those rules into a single 'exactly one of' sentence and adds the unknown-key-rejection rule, which is genuine but marginal added meaning over the schema; 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 set: 'Validate GDScript syntax or scene integrity in headless Godot', which clearly frames the tool as a syntax/integrity checker. It is distinguishable from attach_script and run_script by naming them as downstream consumers, but it never contrasts with the sibling check_project, which is the obvious near-neighbor, so it stops short of full sibling differentiation.

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?

'Use before attach_script or run_script' gives a concrete invocation point and implicit ordering rule, which is clear usage context. There are no explicit when-not-to-use conditions and no mention of check_project or the other validation-ish siblings, so it is strong but not exhaustive routing guidance.

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