Skip to main content
Glama
Beckett — MCP for Godot

Beckett — MCP for Godot

by beckettlab

ui_snapshot

Read-only

Captures running Godot game UI as structured Control data—paths, classes, text, rects, semantic states—so functional checks avoid screenshots and per-control reads.

Instructions

One-call UI snapshot of the RUNNING game: every visible Control as structured data (path, class, text, rect, and the semantic state pixels cannot tell you: disabled, focused, checked, value, selected, editable, tooltip) plus per-control honesty flags. For FUNCTIONAL UI checks this replaces a screenshot plus a read per control; keep screenshot for visual/render bugs. Every field, and the free since_hash re-read: help(tool="ui_snapshot").

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": "ui_snapshot"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNosubtree root to scope the walk (name, relative, or /root/...)
max_nodesNocap on emitted controls (default 150)
occlusionNocompute occluded_by for interactive controls (default true; one hit-test walk per interactive control)
since_hashNohash from a previous call — unchanged UI returns {unchanged:true} instead of the payload
interactive_onlyNoonly buttons/sliders/fields/lists/tabs + focusables (default false = all visible controls)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.14.0
    • changedInput schema / properties / interactive_only / description
      Previous value: -"only buttons/sliders/text fields/lists/tabs + focusables (default false: all visible controls, labels included)"New value: +"only buttons/sliders/fields/lists/tabs + focusables (default false = all visible controls)"
    • changedInput schema / properties / since_hash / description
      Previous value: -"hash from a previous call — unchanged UI returns {unchanged:true} instead of the payload"New value: +"hash from a previous call — unchanged UI returns {unchanged:true} instead of the payload"
  2. Addedv1.12.1

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already cover read-only/non-destructive/closed-world, and the description adds real operational context: the cost of occlusion (one hit-test walk per interactive control), the default cap behavior via max_nodes, and that an unchanged UI returns {unchanged:true} instead of the payload. It also flags that per-control 'honesty flags' exist, which is behavior an agent cannot infer from annotations.

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 core claim and efficient overall, but the middle sentence is a dense parenthetical list that is harder to scan than necessary, and the final pointer to help(tool="ui_snapshot") defers detail rather than eliminating it.

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?

No output schema exists, and the description compensates by enumerating the returned fields (path, class, text, rect, disabled/focused/checked/value/selected/editable/tooltip) and flagging that per-control honesty flags exist. It stops short of defining those flags or the payload envelope, deferring to the help tool, which leaves a small residual gap for a nontrivial return shape.

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 the schema already documents all five parameters including defaults and enum-free semantics; the description mostly reinforces those same points (occlusion cost, since_hash caching). It adds the notion of a 'free' since_hash re-read as a workflow, but that is marginal beyond structured data. Baseline 3 is correct.

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?

States a specific verb and resource (one-call UI snapshot of the running game's visible Controls) and enumerates the payload semantics. It explicitly distinguishes itself from the sibling 'screenshot' tool by scope: functional state vs visual/render bugs.

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?

Gives an explicit alternative and the condition that selects it: 'For FUNCTIONAL UI checks this replaces a screenshot plus a read per control; keep screenshot for visual/render bugs.' It also implies the precondition (a running game) and points to the since_hash re-read path for repeat calls.

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