Skip to main content
Glama
Beckett — MCP for Godot

Beckett — MCP for Godot

by beckettlab

screenshot

Read-only

Capture images of the running Godot game or editor view for the agent to inspect, with optional crops, scaling, format control, and numbered UI annotations.

Instructions

Capture an image the agent can see. target=game (default) captures the RUNNING game; target=editor the editor's 2D or 3D view (PNG only). A bare call caps the long edge at max_dim=1280: pass scale, region, max_dim=0, format or save_to to opt out. annotate=ui draws numbered Set-of-Mark boxes and returns the legend. For pure functional state ui_snapshot is cheaper. Token dials, game pixels, delivery: help(tool="screenshot").

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

Input Schema

NameRequiredDescriptionDefault
scaleNo0.05..1.0 downscale before encode (default 1.0)
formatNopng (default) | jpeg | webp (game target)
regionNo[x,y,w,h] pixel crop
targetNogame | editor
deliverNoinline (default) | link (a capture:// resource_link, no base64) | both
max_dimNolong-edge cap in px (default 1280 on a bare call; 0 = no cap)
qualityNojpeg/webp quality 0.1..1.0 (default 0.8)
save_toNoalso write the frame here (res://, user:// or absolute): a diff baseline
annotateNoui = numbered marks on interactive controls + their legend (game target)
viewportNoSubViewport (or its container) path: its own game pixels, not the window
max_marksNocap on annotate marks (default 40)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.17.0
    • changedInput schema / properties / annotate / description
      Previous value: -"'ui' = draw numbered marks on interactive controls + return the legend (game target)"New value: +"ui = numbered marks on interactive controls + their legend (game target)"
    • changedInput schema / properties / max_dim / description
      Previous value: -"cap the long edge in px (default 1280 on a call with no other framing argument; 0 = no cap)"New value: +"long-edge cap in px (default 1280 on a bare call; 0 = no cap)"
    • changedInput schema / properties / save_to / description
      Previous value: -"also write the frame to this path (res://, user:// or absolute); mints a diff baseline"New value: +"also write the frame here (res://, user:// or absolute): a diff baseline"
    • changedInput schema / properties / scale / description
      Previous value: -"0.05..1.0 downscale before encode (game target; default 1.0)"New value: +"0.05..1.0 downscale before encode (default 1.0)"
    • addedInput schema / properties / viewport
      Added value: +{
      +  "description": "SubViewport (or its container) path: its own game pixels, not the window",
      +  "type": "string"
      +}
  2. Changed3 schema fields changedv1.14.0
    • addedInput schema / properties / deliver
      Added value: +{
      +  "description": "inline (default) | link (a capture:// resource_link, no base64) | both",
      +  "type": "string"
      +}
    • addedInput schema / properties / max_dim
      Added value: +{
      +  "description": "cap the long edge in px (default 1280 on a call with no other framing argument; 0 = no cap)",
      +  "type": "integer"
      +}
    • changedInput schema / properties / save_to / description
      Previous value: -"also write the frame to this path (res://, user:// or absolute) so later captures can be diffed against it — the agent still gets the image inline"New value: +"also write the frame to this path (res://, user:// or absolute); mints a diff baseline"
  3. Addedv1.12.1
  4. Removedv1.10.0
  5. First observedv1.0.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already establish read-only/non-destructive, and the description adds constraints annotations cannot express: the bare-call 1280px long-edge cap and exactly which parameters defeat it, editor target being PNG-only, annotate being game-target-only with a mark cap, and save_to doubling as a diff baseline. Nothing contradicts readOnlyHint=true or destructiveHint=false.

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 one-liner purpose, then defaults, then opt-outs, then the alternative, then a pointer to help — a sensible information hierarchy with no filler sentences. The telegraphic, colon-heavy phrasing ("Token dials, game pixels, delivery: help(...)") is dense to the point of being terse for an unfamiliar reader, which costs a point.

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 an 11-parameter, zero-required, no-output-schema tool, the description covers the default path, the opt-out path, target-specific limits, the sibling alternative, and where deeper documentation lives. The response shape (image inline, capture:// link, or legend on annotate) is inferable from the schema's own deliver/annotate descriptions, so no critical gap remains.

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; the description earns above that by disclosing cross-parameter behavior the schema cannot: the implicit default max_dim=1280 only on a bare call, and format being game-target-only. It stops short of 5 because it doesn't clarify interactions like region plus scale ordering or viewport vs. target precedence, leaving genuinely ambiguous combinations undocumented.

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?

"Capture an image the agent can see" pairs a specific verb with a concrete artifact, then immediately disambiguates the two targets (running game vs. editor 2D/3D view). An agent can distinguish this from render_probe, ui_snapshot, or game_logs without opening any schema.

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?

Explicit default behavior ("target=game (default)"), an explicit opt-out path ("pass scale, region, max_dim=0, format or save_to opt out"), and a named cheaper alternative with its selecting condition ("For pure functional state ui_snapshot is cheaper"). It also routes deep-detail seekers to help(tool="screenshot") rather than bloating the description.

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