Skip to main content
Glama

get_scene_tree

Read-only

Retrieve a scene's node hierarchy as a nested tree, scoped by depth or parent path. Use it to map nodes, node paths, and attached scripts before editing them.

Instructions

Get a scene's node hierarchy as a nested tree. maxDepth: 1 lists only direct children; the default -1 is the whole tree. parentPath scopes to one subtree. Returns: the root node { name, type, path, script, children[] }, every child the same shape; path is a root/... node path the node tools accept, script a res:// path or an empty string. A node cut by maxDepth has children null and a childCount, and warnings leads. Errors if the scene or parentPath is not found.

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

Input Schema

NameRequiredDescriptionDefault
maxDepthNoMaximum recursion depth. -1 for unlimited (default: -1). 1 returns only direct children.
scenePathYesScene file path relative to the project
parentPathNoScope to a subtree starting at this node path (e.g. "root/Player")
projectPathYesPath to the Godot project directory

Output Schema

NameRequiredDescriptionDefault
nameYes
pathYesNode path from the scene root in the "root/..." form the node tools accept.
typeYes
scriptYesres:// path of the attached script, or "".
childrenYesChild nodes, each in this same shape. Null when maxDepth stopped the listing at a node that has children; childCount says how many.
warningsNoRoot node only. Present when maxDepth cut the tree.
childCountNoOnly when children is null: how many children were not listed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv4.0.1
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "childCount": {
      +      "description": "Only when children is null: how many children were not listed.",
      +      "type": "number"
      +    },
      +    "children": {
      +      "description": "Child nodes, each in this same shape. Null when maxDepth stopped the listing at a node that has children; childCount says how many.",
      +      "items": {
      +        "type": "object"
      +      },
      +      "type": [
      +        "array",
      +        "null"
      +      ]
      +    },
      +    "name": {
      +      "type": "string"
      +    },
      +    "path": {
      +      "description": "Node path from the scene root in the \"root/...\" form the node tools accept.",
      +      "type": "string"
      +    },
      +    "script": {
      +      "description": "res:// path of the attached script, or \"\".",
      +      "type": "string"
      +    },
      +    "type": {
      +      "type": "string"
      +    },
      +    "warnings": {
      +      "description": "Root node only. Present when maxDepth cut the tree.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "name",
      +    "type",
      +    "path",
      +    "script",
      +    "children"
      +  ],
      +  "type": "object"
      +}
  2. Addedv3.1.1
  3. Removedv3.0.0
  4. Addedv1.0.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations only declare readOnlyHint=true, so the description carries the behavioral load and does so well: it discloses the truncation marker ('children null and a childCount'), that warnings leads the response, and that it errors when the scene or parentPath is missing. These are non-obvious behaviors an agent could not infer from the annotations. Return-shape detail is partly redundant with the existing output schema, which keeps it from being a 5.

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?

The purpose is front-loaded in one sentence, followed by parameter semantics, return shape, truncation edge case, and error behavior in a tight sequence. Every sentence carries information; there is no filler.

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 read-only tree-fetch with an output schema, this covers what an agent needs: defaults, subtree scoping, the exact node shape, how truncated nodes look, the meaning of path and script for follow-up node tools, and error conditions. Nothing material 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 description coverage is 100%, so the schema already documents maxDepth values, scenePath, parentPath examples, and projectPath, and the description largely restates the maxDepth and parentPath semantics. It adds a little by framing parentPath as scoping the tree rather than just starting a path. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

The opening sentence gives a specific verb and resource: 'Get a scene's node hierarchy as a nested tree.' That distinguishes it from siblings like get_scene_dependencies or get_node_properties by the shape of the result. It stops short of naming an alternative tool to route away from, so it is clear but not explicitly differentiated.

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?

It explains the meaningful usage decisions: maxDepth of 1 for direct children, default -1 for the whole tree, and parentPath to scope a subtree. That is real guidance about how to narrow a call. It does not say when a different tool would be better, and there are no explicit exclusions.

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