Skip to main content
Glama

get_ui_elements

Read-only

Lists running scene Controls with rect, type, and text so you can find names and paths before simulating clicks. Filter by class, scope to a root, and skip hidden or clipped elements.

Instructions

List the running scene Controls with rect, type and text. Call before simulate_input click_element to find names and paths. Needs a runtime session. visibleOnly (default true) drops hidden Controls and ones clipped out of view. filter narrows by class; root limits the list to one Control and its descendants. Returns: projectPath, elements[] with path/type/rect/visible/onScreen (visibleRect if clipped), optional text/disabled/tooltip. Errors on a non-Control filter or an unknown root.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_ui_elements"
  }
}

Input Schema

NameRequiredDescriptionDefault
rootNoList only this Control and its descendants. Same lookup as simulate_input click_element: absolute path, relative path or node name (BFS matched). Visibility and clipping by ancestors above it still apply. An unknown name, or a node that is not a Control, is an error.
filterNoFilter by native Control class name (e.g. "Button", "Label", "LineEdit"); subclasses match. A class Control inherits from (CanvasItem, Node) lists every Control. Any other name, including a script class_name, is an error.
visibleOnlyNoOnly return Controls that are visible in the tree and have area on screen, not clipped away by a ScrollContainer, a clip_contents ancestor or the viewport (default: true). Set false to include the rest.

Output Schema

NameRequiredDescriptionDefault
tipYes
elementsYes
warningsNo
projectPathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv4.0.1
    • changedInput schema / properties / filter / description
      Previous value: -"Filter by Control node type (e.g. \"Button\", \"Label\", \"LineEdit\")"New value: +"Filter by native Control class name (e.g. \"Button\", \"Label\", \"LineEdit\"); subclasses match. A class Control inherits from (CanvasItem, Node) lists every Control. Any other name, including a script class_name, is an error."
    • addedInput schema / properties / root
      Added value: +{
      +  "description": "List only this Control and its descendants. Same lookup as simulate_input click_element: absolute path, relative path or node name (BFS matched). Visibility and clipping by ancestors above it still apply. An unknown name, or a node that is not a Control, is an error.",
      +  "type": "string"
      +}
    • changedInput schema / properties / visibleOnly / description
      Previous value: -"Only return nodes where Control.visible is true (default: true). Set false to include hidden elements."New value: +"Only return Controls that are visible in the tree and have area on screen, not clipped away by a ScrollContainer, a clip_contents ancestor or the viewport (default: true). Set false to include the rest."
    • addedOutput schema / properties / elements / items / properties / onScreen
      Added value: +{
      +  "description": "Whether any of the rect is reachable on screen after every clipping ancestor and the viewport. A Control with no area counts when its point is inside.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / elements / items / properties / rect / properties / height / type
      Previous value: -"number"New value: +[
      +  "number",
      +  "null"
      +]
    • changedOutput schema / properties / elements / items / properties / rect / properties / width / type
      Previous value: -"number"New value: +[
      +  "number",
      +  "null"
      +]
    • changedOutput schema / properties / elements / items / properties / rect / properties / x / type
      Previous value: -"number"New value: +[
      +  "number",
      +  "null"
      +]
    • changedOutput schema / properties / elements / items / properties / rect / properties / y / type
      Previous value: -"number"New value: +[
      +  "number",
      +  "null"
      +]
    • addedOutput schema / properties / elements / items / properties / visibleRect
      Added value: +{
      +  "description": "The part of rect that is on screen, present only when onScreen is true and the rect is clipped.",
      +  "properties": {
      +    "height": {
      +      "type": "number"
      +    },
      +    "width": {
      +      "type": "number"
      +    },
      +    "x": {
      +      "type": "number"
      +    },
      +    "y": {
      +      "type": "number"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / projectPath
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / required
      Added value: +[
      +  "projectPath",
      +  "elements",
      +  "tip"
      +]
  2. Addedv3.1.1
  3. Removedv3.0.0
  4. Addedv1.0.0

TDQS

A4.6/5.0
Behavior5/5

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

readOnlyHint already covers the safety profile, and the description goes further: it declares the runtime-session requirement, the hiding/clipping semantics of visibleOnly, and the two error conditions (non-Control filter, unknown root). That is real behavioral context beyond the annotation.

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?

Every sentence carries information and the primary action plus the follow-up call are front-loaded. The style is terse to the point of being telegraphic ("Errors on a non-Control filter or an unknown root"), which costs a little readability but no substance.

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 three-parameter read tool with a full output schema, the description covers purpose, ordering, preconditions, parameter caveats, and failure modes. 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% and the parameter descriptions already spell out defaults, class-name matching, and error cases, so the description's one-line recap of visibleOnly/filter/root is largely redundant. Baseline 3 applies 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.

Purpose5/5

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

Opens with a specific verb and resource ("List the running scene Controls") and immediately states what each element carries (rect, type, text). It also distinguishes itself from the sibling it feeds (simulate_input click_element) rather than from a lookalike lister, which is enough for an agent to route correctly.

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

Usage Guidelines5/5

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

"Call before simulate_input click_element to find names and paths" gives an explicit ordering rule and names the consumer tool, and "Needs a runtime session" states the precondition. There is no when-not clause, but the usage condition is concrete and actionable.

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