Screenshot Tools for AI Agents

These tools capture images for the agent to look at: the 3D view from any camera, editor previews, a single card, or a panel. They change nothing. See Take screenshots with an agent for how to choose one.

Tools in this family#

5 tools. The tool reference lists every family. An MCP client shows each tool as mcp__diceytable__<name>.

→ D / → H: the call escalates with certain arguments (see the tool). +: the call takes the class of the tool or action it dispatches to. bridge: answered by the bridge, on any surface, with no tab.

capture_surfaces#

List capture surfaces — List the screenshot surfaces registered in the tab (viewport, model and material previews, deck cards, image editors, panels).

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Lists the screenshot surfaces the tab has registered right now. The list includes the 3-D viewport and the DOM panel surface. In the editor you also get the model, prefab and material previews. Deck cards, deck sheets and the card layout preview are surfaces too. So are textures, the two image editors, the board-from-image tracer and screenshots-gallery items. Each row says whether the surface is mounted and which instance it shows, such as an asset path or a deck id. It also says how faithful its pixels are.

When to use it. Before screenshot_surface, to learn which surfaces and instances exist; before screenshot_panel with mode: "exact", to see whether exact capture is allowed (exactCapture).

Class. R. It shares the screenshot rate limit (2 per second, bursts of 4).

Gotchas.

• A surface appears only while its tab or panel is open: open the Model tab to get model-preview, a Prefab tab to get prefab-preview (its 3D view, in the camera position the user left it).
• fidelity.level is native (the canvas's own pixels), file (the stored image re-encoded), rasterised (a DOM rendering, with known gaps) or exact.

Example#

A request and the structured result it returns.

{
  "request": {},
  "response": {
    "surfaces": [
      {
        "id": "viewport",
        "label": "Main viewport",
        "mounted": true,
        "kind": "scene",
        "fidelity": {
          "level": "native",
          "gaps": []
        }
      },
      {
        "id": "model-preview",
        "instance": "models/cargo-crate.glb",
        "label": "Model tab preview",
        "mounted": true,
        "kind": "canvas",
        "fidelity": {
          "level": "native",
          "gaps": []
        }
      },
      {
        "id": "panel",
        "label": "DOM panel or dialog",
        "mounted": true,
        "kind": "dom",
        "exactCapture": false,
        "fidelity": {
          "level": "rasterised",
          "gaps": []
        }
      }
    ]
  }
}

screenshot_viewport#

Screenshot viewport — Capture the editor, preview or table 3D viewport as a size-budgeted image: current view or an agent camera (top, front, side, iso, fit to entities, explicit pose), with overlays hidden on request.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Takes a picture of the 3-D viewport in the editor, preview or table, within a byte budget. It comes back as MCP image content with a short summary. The summary gives the size, bytes and format, the camera pose used, and the overlay categories it hid. It also says whether the budget made the image smaller. By default you see the user's current view. camera can place a separate agent camera instead: top, front, side, iso, fit-selection, {fitEntities: [...]} or an explicit {position, target, fov} in feet.

When to use it. To see what you built or what happened at the table. hide: "chrome" removes gizmos, outlines, seat labels and other overlays while keeping game content; settle: true waits for assets and bodies first. Prefer describe_panel for UI and table_snapshot for facts: images are expensive.

Class. R, plus files:local when you pass saveTo. Rate-limited to 2 per second (bursts of 4), shared with every capture tool and describe_panel.

Gotchas.

• Budget. The default is a 1280 px long edge and 600,000 bytes of WebP; maxBytes goes up to 5,000,000, but over DiceyTable's server relay every capture is held to 400,000 bytes. When a budget cannot be met at the requested quality the image is re-encoded smaller, and clamped: true says so. png is lossless and large; ask for it only for pixel checks.
• Live room, host. A host's tab holds the identity of every face-down card, so in a live room the host may capture only its own view (camera: "current"); any other camera is refused with role-denied. Players and spectators may use any camera: their tab never held the hidden faces.
• Peerless preview. The agent camera may go anywhere above the table surface; a pose whose eye is below the play surface is refused with role-denied, because it could look up at the faces of cards lying face down. The editor has no such limit (you are authoring your own project).
• Editor. The Edit Mode viewport is captured the same way, in every editor (game, room, table, asset), so you can check lighting or placement without opening a preview. It shows the draft as the viewport renders it, including unsaved edits. Edit Mode switched on inside a live room is still that live room: the host rule above applies.
• The agent camera has no post-processing (bloom, ambient occlusion, depth of field); fidelity.gaps says no-post-fx. tier: "ultra" renders through the photo pipeline instead: slow (seconds) and faithful. In a live room ultra asks the user first.
• The tab must be visible: a background tab renders no frames and the capture fails. A preview opened by playtest_start must be brought to the front.
• With the current camera, the user may notice one frame without overlays when hide is used.
• Refused during an immersive VR session.
• A room pack's decor does not render in the preview; a capture there adds a warning.
• saveTo also writes the image, inside the bridge's allowed folders; its extension must match format. It creates a new file and never overwrites one (an existing path is refused with exists).
• The image may show mod-authored text and art, so the result is marked untrusted.

Example#

A top-down view of the preview with overlays hidden. The image itself arrives as MCP image content next to this summary:

{
  "request": {
    "camera": "top",
    "hide": "chrome",
    "width": 1280,
    "settle": true,
    "tab": "tab_Zr7bN2cW5yHe"
  },
  "response": {
    "surface": "viewport",
    "width": 1280,
    "height": 720,
    "bytes": 214336,
    "format": "webp",
    "camera": {
      "position": {
        "x": 0,
        "y": 9.4,
        "z": 0
      },
      "target": {
        "x": 0,
        "y": 2.5,
        "z": 0
      },
      "fov": 46
    },
    "hiddenCategories": [
      "selection-outlines",
      "transform-gizmos",
      "editor-helpers",
      "seat-areas",
      "seat-labels",
      "hand-zones",
      "snap-points",
      "zones",
      "vector-lines",
      "debug-overlays",
      "drag-ghosts",
      "presence-avatars",
      "tooltips"
    ],
    "clamped": false,
    "durationMs": 184,
    "fidelity": {
      "level": "native",
      "gaps": [
        "no-post-fx"
      ]
    }
  }
}

screenshot_surface#

Screenshot surface — Capture a registered editor surface as a size-budgeted image: model or material preview, deck card or sheet, card layout, texture, miniPaint, quick editor, board trace or a screenshots-gallery item.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Takes a picture of a registered editor surface and returns it as a budgeted image. It works on every surface but the viewport. That can be the Model tab's preview or the Material tab's sphere. It can be a deck card or sheet, the card layout preview, or a texture. It can also be miniPaint, the quick editor, the board-from-image tracer, or an item in the screenshots gallery.

When to use it. To check art and assets without the scene around them: a converted model, a material, a card layout. For one card of a deck at any size, screenshot_card needs no open tab.

Class. R, plus files:local for saveTo.

Gotchas.

• The surface must be mounted: open its tab first. When several instances are mounted (two Model tabs), pass instance from capture_surfaces; otherwise the call is invalid-arguments with the instances listed.
• camera presets apply to the 3-D previews (model, material); other surfaces ignore them.
• The same byte budgets as screenshot_viewport, including the 400 KB relay cap.

Example#

A request and the structured result it returns.

{
  "request": {
    "surface": "model-preview",
    "instance": "models/cargo-crate.glb",
    "camera": "iso",
    "width": 768,
    "height": 768
  },
  "response": {
    "surface": "model-preview",
    "instance": "models/cargo-crate.glb",
    "width": 768,
    "height": 768,
    "bytes": 58210,
    "format": "webp",
    "hiddenCategories": [],
    "clamped": false,
    "durationMs": 96,
    "fidelity": {
      "level": "native",
      "gaps": []
    }
  }
}

screenshot_card#

Screenshot card — Render one card of a deck in the editor (face or back) as a size-budgeted image.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Draws one card of a deck, face or back, and returns it as a budgeted image. It uses the same drawing code as the deck preview and the sheet builder. The image is clipped to the card's rounded outline. It can be any size up to 2576 px. No tab needs to be open.

When to use it. To check card art after deck_create, deck_set_cards or a layout change, and to read a card's content visually.

Class. R, plus files:local for saveTo.

Gotchas.

• index is zero-based; beyond the deck's size is out-of-range with the valid range.
• Without width/height the card's authored cell size is used, capped at a 1280 px long edge.
• Faces are drawn with the deck's rotation rules; backs are drawn upright.
• This renders authoring data in the editor. It is not a way to look at hidden cards at a table: table tools only ever see your seat's view.

Example#

A request and the structured result it returns.

{
  "request": {
    "deckId": "deck_goods",
    "index": 0,
    "side": "face",
    "height": 700,
    "format": "png"
  },
  "response": {
    "surface": "deck-card",
    "width": 500,
    "height": 700,
    "bytes": 402118,
    "format": "png",
    "hiddenCategories": [],
    "clamped": false,
    "durationMs": 41,
    "fidelity": {
      "level": "native",
      "gaps": []
    }
  }
}

screenshot_panel#

Screenshot panel — Capture a DOM panel or dialog in the editor, table or lobby tab: approximate (rasterised, default) or exact (tab capture on Chromium desktop, needing one user click per session). Try describe_panel first.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Takes a picture of a DOM panel or dialog in the editor, table or lobby tab. mode: "approximate" is the default. It draws the panel's DOM into an image. mode: "exact" uses the browser's own tab capture on Chromium desktop, cropped to the panel. It needs one click from the user per session.

When to use it. Rarely. describe_panel returns the same panel's fields, values and actions as text, which is cheaper and exact. Use a screenshot when layout or appearance is the question.

Class. R, plus files:local for saveTo.

Gotchas.

• Approximate mode cannot show cross-origin images without CORS, iframes (the mod sandbox, miniPaint), closed shadow roots or some CSS; fidelity.gaps lists what was missing.
• Exact mode must be allowed in the connect dialog or Settings ▸ AI agents (exact-capture-disabled otherwise). The first exact capture of a session waits up to 60 seconds for the user to click "Allow tab capture" and pick this tab; the browser shows its "sharing this tab" bar while it lasts. The track is proven to be a capture of this tab before any frame is read (not-self-capture otherwise) and stops after 5 minutes without an exact capture.
• If the user declines, the prompt stays quiet for 10 minutes unless you pass ask: true. Firefox, Safari and mobile cannot prove self-capture and answer exact-capture-unsupported. With fallback: true either case returns an approximate capture instead of an error.
• The panel must be on screen; open it first with panel_open.

Example#

An approximate capture of the Publish dialog, saved to disk as well:

{
  "request": {
    "panel": "dialog.publish",
    "saveTo": "screenshots/publish-dialog.webp"
  },
  "response": {
    "surface": "panel",
    "panel": "dialog.publish",
    "width": 1280,
    "height": 904,
    "bytes": 167422,
    "format": "webp",
    "hiddenCategories": [],
    "clamped": false,
    "durationMs": 612,
    "fidelity": {
      "level": "rasterised",
      "gaps": []
    },
    "savedTo": "C:\\Users\\sam\\games\\harbour-merchants\\screenshots\\publish-dialog.webp"
  }
}