Page, Panel and Field Tools for AI Agents

These tools work on every kind of DiceyTable tab. They read where the tab is, open and describe panels, and read, set or press any registered field or button the same way your own click would. The field catalogue lists every id.

Tools in this family#

11 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.

page_info#

Page info — Describe the current DiceyTable tab: URL, surface, project and subject, room, role, editor lease, unsaved state, site version and catalogue hash.

Input

Output (structured content)

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

Tells you about the tab a call lands on. You get its URL and surface, and the open project with its subject (game, room or table). You also get the room id and your table role. It says whether this editor tab holds the project lease, and whether there are unsaved changes. Last come the site's version and the tool-catalogue hash.

When to use it. Before acting in a tab you did not just open, after page_navigate, and whenever a call answers wrong-surface or tool-unavailable. It is the cheapest way to learn what the tab can do.

Class. R. It is available on every surface, including settings.

Gotchas.

• lease: "read-only" means another tab of the same user holds the editor lease. Every write tool refuses with read-only-lease there, exactly as the human's controls are read-only.
• On preview and table tabs, unsaved is always false; unsaved state is an editor concept.
• role is offline on a peerless preview or solo table, otherwise host, player or spectator.
• Compare catalogueHash with your bridge's: a mismatch means the site and bridge were built from different tool catalogues, and page_call_tool may be needed for new tools.
• untrustedTitle is the document title and can name a mod; untrustedRoomName is a live room's display name, chosen by its owner.
• In a live room (role host, player or spectator), a same-tab page_navigate leaves the room and so asks the user first.

Example#

An editor tab holding the lease, with unsaved edits:

{
  "request": {},
  "response": {
    "url": "https://diceytable.com/editor/game/9b1d6f2a-3c4e-4a7b-8f10-5e2d7c9a1b36",
    "surface": "editor",
    "untrustedTitle": "Harbour Merchants — DiceyTable Editor",
    "projectId": "9b1d6f2a-3c4e-4a7b-8f10-5e2d7c9a1b36",
    "subject": "game",
    "lease": "owner",
    "unsaved": true,
    "siteVersion": "4f2c9d1",
    "catalogueHash": "c41f0e7a2b9d"
  }
}

page_navigate#

Navigate — Open a DiceyTable page in this tab or a new one: the editor for a project, a preview, a live table room, a lobby, or the open-tables list. Leaving unsaved editor changes is destructive and needs confirm: true. Leaving a live table room in this tab (host, player or spectator) asks the user to confirm in the DiceyTable tab; newTab never leaves anything. A new tab is opened without a user click, so the browser's pop-up blocker can stop it: the result says joined: false with a note when no tab joined. For a preview prefer playtest_start.

Input

Output (structured content)

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

Opens a DiceyTable page, in this tab or a new one. It can open the editor for a project, in a given mode if you like. It can open a play-test preview of a project. It can also open a live table room, a /play lobby, or the list of open tables. It uses the same URLs the app's own links build, for example /editor/game/<projectId>, /table?preview=<projectId>, /table?room=<roomId> and /play/lobby/<roomId>.

When to use it. To move between surfaces: from the editor to a lobby, or to open a room you were invited to. To open a project inside the editor you are already in, project_open is gentler (it refuses rather than discards). To play-test, prefer playtest_start, which saves first and pairs the new preview tab for you.

Class. W, escalating to D when this tab has unsaved editor changes and newTab is false: leaving would discard them, so the call needs confirm: true, and the first D call of the session makes a "Before AI agent changes" restore point. It escalates to H when this tab is in a live table room (as host, player or spectator) and newTab is false: leaving the room asks the user in the DiceyTable tab (the dialog names the room), and on Allow the tab leaves through the same path as its own Leave game button before the page changes. confirm: true does not skip that question. With newTab: true nothing is left or discarded and it stays W.

Gotchas.

• A same-tab navigation returns before the page unloads; the tab then reconnects by itself with the same tab id. Wait a moment and call page_info before the next call to that tab.
• A new tab opened this way joins your session by itself, with no pairing dialog: the tab you called registers a single-use hand-off (60 seconds) for your session only, and the new tab inherits the user's consent choices from it. The call waits up to 15 seconds for the new tab to join and then returns joined: true and its tabId (select it with session_select_tab).
• A new tab is opened without a user click, so the browser's pop-up blocker can stop it, and the tab you called cannot see whether it did. When nothing joined, the result says joined: false with a note naming the likely cause: usually the pop-up blocker (the user has to allow pop-ups for DiceyTable), otherwise a slow load or a tab where the user is signed out. A tab that did open can still join for about a minute, so check session_list_tabs again before giving up. For a preview use playtest_start: it reports a blocked pop-up as an error and leaves an Open Preview link in the editor for the user to click.
• discardedChanges: true reports that a D navigation dropped unsaved edits.

Example#

Opening a lobby in a new tab, which leaves the editor's unsaved work alone (so it stays W):

{
  "request": {
    "to": {
      "page": "lobby",
      "roomId": "3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75"
    },
    "newTab": true
  },
  "response": {
    "url": "/play/lobby/3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75",
    "tabId": "tab_Zr7bN2cW5yHe",
    "joined": true,
    "discardedChanges": false
  }
}

panel_list#

List panels — List every registered panel in the editor, preview or table tab, open or closed, with what opening it requires (a selected entity, an item tab, a settings section).

Input

Output (structured content)

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

Lists every registered panel on this surface, open or closed. For each one you get its id, its label and whether it is open. available says whether this page can open it. requiresTarget says what it needs first, such as an entity. A one-line hint says how a human opens it. Panel ids are the same ids the field catalogue is grouped by.

When to use it. To discover UI you cannot see: which panels exist in the Edit Mode shell or the table's settings, and which of them hold the fields you want. Then describe_panel for its fields and actions, or panel_open to mount it.

Class. R. Available in the editor, preview and table tabs; a lobby tab has no panel list (use describe_panel with a lobby.* panel id instead).

Gotchas.

• A preview tab lists the table panels too, because it renders the same table app.
• available: false means this page has not registered how to open that panel right now, so panel_open would answer not-mounted.

Example#

Only open panels, in an editor tab with entity obj_12 selected:

{
  "request": {
    "includeClosed": false
  },
  "response": {
    "panels": [
      {
        "id": "editor.hierarchy",
        "label": "Hierarchy",
        "surface": "editor",
        "open": true,
        "available": true,
        "openHint": "Always mounted in Edit Mode (left panel)."
      },
      {
        "id": "inspector.entity",
        "label": "ENTITY",
        "surface": "editor",
        "open": true,
        "available": true,
        "openHint": "Select the entity in the Hierarchy; the ENTITY section expands.",
        "requiresTarget": "entity"
      },
      {
        "id": "inspector.rigidbody",
        "label": "RIGIDBODY",
        "surface": "editor",
        "open": true,
        "available": true,
        "openHint": "Select the entity; the RIGIDBODY component section.",
        "requiresTarget": "entity"
      }
    ]
  }
}

panel_open#

Open panel — Open a registered panel in the editor, preview or table tab (selecting its target first when it needs one) so its fields mount.

Input

Output (structured content)

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

Opens a registered panel the way a human would. It selects the panel's target entity, switches the item tab, or opens the Settings section. Then the panel's fields mount, so fields_set can reach them.

When to use it. Before setting several fields on one panel, or before screenshot_panel. For a one-off field change, fields_set with autoOpen: true opens the panel for you.

Class. W, needing only the read scope: it changes what is on screen, not the project.

Gotchas.

• A panel with a target kind needs target (for example {"kind": "entity", "id": "obj_12"}), and the kind must match the panel's; otherwise invalid-arguments.
• The call waits up to 1.5 seconds for the panel to report open and then returns open as it stands. open: false is not an error: check the target, or call describe_panel to see what is mounted.
• An unknown id is not-found; a panel of another surface is wrong-surface; one the page cannot open now is not-mounted with the panel's open hint.

Example#

A request and the structured result it returns.

{
  "request": {
    "panel": "inspector.rigidbody",
    "target": {
      "kind": "entity",
      "id": "obj_12"
    }
  },
  "response": {
    "panel": "inspector.rigidbody",
    "open": true
  }
}

panel_close#

Close panel — Close a registered panel in the editor, preview or table tab.

Input

Output (structured content)

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

Closes a registered panel, such as a dialog, an item tab or a settings section. It uses the panel's own close path.

When to use it. To tidy up after panel_open or before a screenshot_viewport that the panel would cover. It is never needed for correctness.

Class. W, needing only the read scope.

Gotchas.

• A panel that is part of the page layout registers no close, and answers invalid.
• A panel that is not on this page is not-mounted.

Example#

A request and the structured result it returns.

{
  "request": {
    "panel": "dialog.preferences"
  },
  "response": {
    "panel": "dialog.preferences",
    "open": false
  }
}

fields_list#

List fields — List form fields in the editor, table or lobby tab, filtered by panel, target, id prefix or kind, optionally with values; includes fields of closed panels unless mountedOnly. Lengths are in feet.

Input

Output (structured content)

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

Lists form fields. A field is the generic handle on any control in the Edit Mode shell, the table's settings or the lobby. Each row has an instance id you can pass to fields_get and fields_set. It also has the definition id it came from, a label, its kind, its panel, its class and, for lengths, its unit. Fields on screen come first, in page order. Then, unless you pass mountedOnly, come the definitions this surface has that are not mounted. That shows you what opening a panel would add.

When to use it. To find the id of a control you want to change: filter by panel, idPrefix or kind, add includeValues to read values in the same call. For the full list of ids offline, read the field catalogue. For one panel as a whole, describe_panel is tidier.

Class. R.

Gotchas.

• An instance id is <field>@<kind>:<id> when the field belongs to a target: the Inspector's mass of entity obj_12 is inspector.rigidbody.mass@entity:obj_12. A not-mounted row carries the bare definition id and a requiresTarget kind instead.
• Values are only read for mounted fields, and only with includeValues: true.
• Lengths are in feet (unit: "ft"), whatever display unit the user chose in File ▸ Preferences.
• Controls inside a hidden subtree are skipped unless includeHidden: true.
• Values can carry mod-authored text, so every value comes back as untrustedValue. The label of a field derived from mod content (script variables, plugin settings, lobby setup options) comes back as untrustedLabel instead of label.

Example#

The rigidbody fields of one entity, with values:

{
  "request": {
    "panel": "inspector.rigidbody",
    "target": {
      "kind": "entity",
      "id": "obj_12"
    },
    "includeValues": true,
    "mountedOnly": true,
    "limit": 3
  },
  "response": {
    "fields": [
      {
        "id": "inspector.rigidbody.enabled@entity:obj_12",
        "definitionId": "inspector.rigidbody.enabled",
        "label": "Enabled",
        "kind": "boolean",
        "panel": "inspector.rigidbody",
        "cls": "W",
        "mounted": true,
        "untrustedValue": true,
        "target": {
          "kind": "entity",
          "id": "obj_12"
        }
      },
      {
        "id": "inspector.rigidbody.type@entity:obj_12",
        "definitionId": "inspector.rigidbody.type",
        "label": "Type",
        "kind": "select",
        "panel": "inspector.rigidbody",
        "cls": "W",
        "mounted": true,
        "untrustedValue": "dynamic",
        "target": {
          "kind": "entity",
          "id": "obj_12"
        }
      },
      {
        "id": "inspector.rigidbody.mass@entity:obj_12",
        "definitionId": "inspector.rigidbody.mass",
        "label": "Mass",
        "kind": "number",
        "panel": "inspector.rigidbody",
        "cls": "W",
        "mounted": true,
        "untrustedValue": 0.02,
        "target": {
          "kind": "entity",
          "id": "obj_12"
        }
      }
    ],
    "total": 8,
    "nextCursor": "3"
  }
}

fields_get#

Get fields — Read field values in the editor, table or lobby tab together with live constraints: min, max, step, options, enabled, visible and unit.

Input

Output (structured content)

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

Reads fields by instance id. Each control comes with its live limits. You get the current min, max and step, and the options a select offers right now. You also learn whether the field is enabled and visible, and its unit.

When to use it. Before a fields_set whose value depends on the current one, or to learn a range that the live control narrows (a slider whose maximum depends on another setting). For many fields of one panel, describe_panel gives values and constraints in one call.

Class. R.

Gotchas.

• A field that exists but is not on screen returns error: "not mounted; open panel \"<panel>\"" instead of a value; open it with panel_open. An unknown id returns error: "not found".
• Lengths come back in feet with unit: "ft"; colours from colour pickers are [r, g, b] in 0..1.
• Values and options can carry mod-authored text, so they come back as untrustedValue and untrustedOptions.

Example#

One mounted field with its live constraints, and one whose panel is closed:

{
  "request": {
    "ids": [
      "inspector.rigidbody.friction@entity:obj_12",
      "item.texture.sampling.filtering@asset:textures/felt.png"
    ]
  },
  "response": {
    "fields": [
      {
        "id": "inspector.rigidbody.friction@entity:obj_12",
        "untrustedValue": 0.5,
        "min": 0,
        "max": 1,
        "step": 0.01,
        "enabled": true,
        "visible": true
      },
      {
        "id": "item.texture.sampling.filtering@asset:textures/felt.png",
        "error": "not mounted; open panel \"item.texture.sampling\""
      }
    ]
  }
}

fields_set#

Set fields — Set form fields in the editor, table or lobby tab through each control's own change handler, in a batch. Values are validated and never clamped; lengths are feet unless a unit is given. autoOpen opens each field's panel first.

Input

Output (structured content)

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

Sets a batch of fields through each control's own change handler, the same code a human edit runs. The tool checks the value, the handler runs and React commits. Then the tool reads the control back. Nothing is written behind the control's back.

When to use it. For any setting that has a control but no semantic tool: a rigidbody's friction, a texture's sampling mode, a lobby's room name. Prefer the semantic tools where they exist (entity_update, material_set, manifest_set); they validate against the document schema and skip the navigation.

Class. W. The write scope depends on the surface: editor:write in the editor, table:play on a table, preview or lobby tab.

Gotchas.

• D and H fields are refused, with status disabled and the tool to use instead. fields_set has no confirm argument and cannot raise the in-tab dialog, so a field such as the lobby's visibility must go through lobby_settings_set.
• Values are never clamped. An out-of-range number is refused with out-of-range and the allowed range. That is deliberate: a silently clamped value is how controls end up holding a number nobody chose.
• Lengths are in feet. Pass unit (mm, cm, m, in, ft or yd) to give a length in another unit; unit on a non-length field is invalid.
• A field the user is typing in is refused with focused-by-user: the human wins. Retry after they leave it.
• Setting a value equal to the current one calls nothing and reports status: "applied", applied: false, equal: true. appliedCount counts these no-ops too.
• autoOpen: true opens each not-mounted field's panel (grouped by panel and target) and waits up to 3 seconds for the fields to mount. Without it, a closed panel's field is not-mounted.
• atomic: true validates every value first and applies nothing if any fails; during the apply it stops at the first failure and reports what was already applied. The batch lands inside one undo checkpoint window, so one undo usually reverts it.
• In an editor tab without the project lease every entry is read-only-lease.
• Check equal in each result: false after an apply means the control normalised the value (rounded, snapped) and untrustedReadback holds what it kept.

Example#

Two fields at once: one applied, one refused with its range (never clamped):

{
  "request": {
    "values": [
      {
        "id": "inspector.rigidbody.friction@entity:obj_12",
        "value": 0.8
      },
      {
        "id": "inspector.rigidbody.restitution@entity:obj_12",
        "value": 1.4
      }
    ]
  },
  "response": {
    "results": [
      {
        "id": "inspector.rigidbody.friction@entity:obj_12",
        "status": "applied",
        "untrustedReadback": 0.8,
        "equal": true,
        "applied": true
      },
      {
        "id": "inspector.rigidbody.restitution@entity:obj_12",
        "status": "out-of-range",
        "error": "Restitution must be within [0, 1]; got 1.4. Values are never clamped.",
        "applied": false
      }
    ],
    "appliedCount": 1
  }
}

actions_list#

List actions — List registered buttons and menu commands in the editor, table or lobby tab with their action class (W, D or H).

Input

Output (structured content)

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

Lists the buttons and menu commands the tab has registered. Each one shows its own class: W (can be undone), D (destructive) or H (asks the user). Commands on screen come first, with enabled. Then come the commands this surface defines that are not on screen, unless you pass mountedOnly.

When to use it. To find a command no semantic tool covers: a menu item, a panel button such as "Reset fit" or the lobby's Save. The editor's menu bar registers every item as menu.<menu>.<item> (for example menu.file.save) while the menu is open; miniPaint's commands are minipaint.menu.<command>.

Class. R.

Gotchas.

• Menu and miniPaint actions exist only while their menu or dialog is mounted, so they never appear as not-mounted rows. Open the menu first.
• A menu or miniPaint row built from a name (a project, a pack) has no label of ours, so its on-screen text comes back as untrustedLabel instead of label.
• The class shown is the one actions_invoke will enforce.
• A mounted action on a target is listed by its instance id (<actionId>@<kind>:<id>), with the bare actionId and the target beside it. actions_invoke accepts that id as it is.

Example#

The actions of the collision section, one of them mounted:

{
  "request": {
    "panel": "inspector.collision",
    "target": {
      "kind": "entity",
      "id": "obj_12"
    }
  },
  "response": {
    "actions": [
      {
        "id": "inspector.collision.edit-box@entity:obj_12",
        "actionId": "inspector.collision.edit-box",
        "label": "Edit Collision Box",
        "panel": "inspector.collision",
        "cls": "W",
        "mounted": true,
        "enabled": true,
        "target": {
          "kind": "entity",
          "id": "obj_12"
        }
      },
      {
        "id": "inspector.collision.reset-fit@entity:obj_12",
        "actionId": "inspector.collision.reset-fit",
        "label": "Reset to fit",
        "panel": "inspector.collision",
        "cls": "W",
        "mounted": true,
        "enabled": true,
        "target": {
          "kind": "entity",
          "id": "obj_12"
        }
      }
    ],
    "total": 2
  }
}

actions_invoke#

Invoke action — Invoke a registered button or menu command in the editor, table or lobby tab. The action's own class applies: D needs confirm: true and H asks the user in the tab.

Input

Output (structured content)

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

Presses a registered button or menu command, just as a human click would. The command's latest click handler runs inside the agent's action context. If the handler is async, the tool waits for it, so a failure comes back to you.

When to use it. For a command listed by actions_list that has no semantic tool. When a semantic tool exists (saving is project_save, deleting is entity_delete), use it: it reports a structured result instead of the handler's.

Class. W is only the floor: the call takes the action's own class. A D action needs confirm: true; an H action raises the in-tab confirmation before the handler runs, and confirm does not skip it. An action the tab does not know answers not-found; a menu action that is not on screen answers not-mounted.

Gotchas.

• id takes either form: the id exactly as actions_list returns it for an action on a target (inspector.collision.reset-fit@entity:obj_12), or the bare action id together with target. Passing both is fine when they agree; an id and a target that name different things are refused with invalid-arguments.
• A button lives on the panel that shows it. not-mounted means that panel is closed: open it with panel_open first (Add Light is on room.lights, the Lights folder).
• The write scope depends on the surface, as for fields_set.
• A disabled button is refused with disabled, the same as for the human.
• In an editor tab without the project lease, anything above R is read-only-lease.
• result is whatever the handler returned, made JSON-safe; most return nothing.
• table.save-load.restore-autosave (Restore Autosave) is a load like any other. During a live ranked match it raises a consent prompt for every other human participant, which only humans can answer, and if they agree the match ends unranked before the autosave is restored. invoked: true means the request was made, not that the table changed: read table_snapshot or match_get afterwards.

Example#

Pressing a W button; a D action would also need confirm: true:

{
  "request": {
    "id": "inspector.collision.reset-fit",
    "target": {
      "kind": "entity",
      "id": "obj_12"
    }
  },
  "response": {
    "id": "inspector.collision.reset-fit",
    "invoked": true,
    "cls": "W"
  }
}

describe_panel#

Describe panel — Describe a panel in the editor, table or lobby tab as text: its fields with values and its actions. Cheaper than a screenshot.

Input

Output (structured content)

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

Describes a panel as text. It lists every field on screen with its value, range, options and whether it is enabled. It also lists the panel's fields that are not mounted, so you know what opening the panel would show. Last come the panel's actions, each with its class.

When to use it. Instead of a screenshot whenever the question is "what does this panel say or allow": it is cheaper, exact, and gives you the ids for fields_set and actions_invoke. Works on lobby panels too.

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

Gotchas.

• open reports whether the panel is currently open; a closed panel still lists its static fields (without values) and its actions.
• Derived field families (component, material and room-light properties) and per-instance ones (plugin settings, script variables) are listed only when mounted.
• Field rows are shaped like fields_list's: values in untrustedValue and untrustedOptions, and mod-derived labels in untrustedLabel. Action rows are shaped like actions_list's.

Example#

A request and the structured result it returns.

{
  "request": {
    "panel": "lobby.owner",
    "target": {
      "kind": "lobby",
      "id": "3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75"
    }
  },
  "response": {
    "panel": "lobby.owner",
    "label": "Lobby owner settings",
    "open": true,
    "fields": [
      {
        "id": "lobby.owner.max-players@lobby:3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75",
        "definitionId": "lobby.owner.max-players",
        "label": "Player seats",
        "kind": "integer",
        "panel": "lobby.owner",
        "cls": "W",
        "mounted": true,
        "untrustedValue": 4,
        "min": 1,
        "max": 10,
        "enabled": true
      },
      {
        "id": "lobby.owner.visibility@lobby:3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75",
        "definitionId": "lobby.owner.visibility",
        "label": "Who can see this lobby",
        "kind": "select",
        "panel": "lobby.owner",
        "cls": "H",
        "mounted": true,
        "untrustedValue": "public",
        "untrustedOptions": [
          {
            "value": "public",
            "label": "Public"
          },
          {
            "value": "friends",
            "label": "Friends"
          },
          {
            "value": "private",
            "label": "Private"
          }
        ],
        "enabled": true
      }
    ],
    "actions": [
      {
        "id": "lobby.owner.save@lobby:3e8a1c5d-7b2f-4d90-a6e4-0c9b8f1d2a75",
        "actionId": "lobby.owner.save",
        "label": "Save",
        "panel": "lobby.owner",
        "cls": "W",
        "mounted": true,
        "enabled": false
      }
    ]
  }
}