Project and Publishing Tools for AI Agents

These tools manage the editor project as a whole. They open and save it, and make restore points and versions. They undo and redo, run checks, sync with GitHub and publish. Some steps always wait for your click in the tab: deleting a project, going back to a version, and publishing.

Tools in this family#

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

project_list#

List projects — List the user's editor projects (game, room and table mods) in the editor tab.

Input

Output (structured content)

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

Lists the signed-in user's editor projects: game, room and table mods. You see them as the project picker shows them. Each one has its id, name, subject and last update, and says whether it has been published.

When to use it. To find the id for project_open, or to check whether a project with a given name already exists before project_create. Filter with subject.

Class. R, editor tab only.

Gotchas.

• Only this account's projects are listed. A user with two accounts sees a different list in each; an "empty" list is often the other login.
• untrustedName is the author's text (it can be anything, including an imported mod's name).

Example#

A request and the structured result it returns.

{
  "request": {
    "subject": "game",
    "limit": 2
  },
  "response": {
    "projects": [
      {
        "id": "9b1d6f2a-3c4e-4a7b-8f10-5e2d7c9a1b36",
        "untrustedName": "Harbour Merchants",
        "subject": "game",
        "updatedAt": "2026-09-29T13:58:12.000Z",
        "published": false
      },
      {
        "id": "c2a7e419-0f3b-4e6d-9d21-8b5f7a3c0e94",
        "untrustedName": "Backgammon Night",
        "subject": "game",
        "updatedAt": "2026-09-21T19:02:44.000Z",
        "published": true
      }
    ],
    "total": 5,
    "nextCursor": "2"
  }
}

project_open#

Open project — Open an editor project in the editor tab through the project picker.

Input

Output (structured content)

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

Opens an editor project in this tab, through the project picker's own path. It reports the project's subject. It also says whether this tab holds the editor lease.

When to use it. To switch the editor tab to another project. Passing mode also moves the editor into that subject's editor (game, room or table) when the project is of that subject.

Class. W with editor:write. It never discards work.

Gotchas.

• If this tab has unsaved changes the call refuses with confirm-required instead of discarding them. Call project_save first, or use page_navigate with confirm: true if the user wants the changes thrown away.
• lease: "read-only" means another tab of this user holds the project; you can read it, and every write tool will answer read-only-lease.
• An unknown id is not-found; list ids with project_list.

Example#

A request and the structured result it returns.

{
  "request": {
    "projectId": "c2a7e419-0f3b-4e6d-9d21-8b5f7a3c0e94"
  },
  "response": {
    "projectId": "c2a7e419-0f3b-4e6d-9d21-8b5f7a3c0e94",
    "subject": "game",
    "lease": "owner"
  }
}

project_create#

Create project — Create a new game, room or table project in the editor tab through the create flow, and open it. Every mod gets its own PUBLIC GitHub repository at creation (there are no local-only mods), so the user's GitHub account must be connected in the tab; if it is not, the call fails and the user must connect it (or create a free GitHub account) first. Counts toward the user's creation limit (Free 3 per 24 h / 12 per 30 days, Player 9 / 36, Game Master unlimited); at the limit the server refuses with mod-creation-limit and the error says when the next slot opens.

Input

Output (structured content)

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

Makes a new game, room or table project through the editor's create flow, together with its own public GitHub repository. It opens the project and returns its id.

When to use it. At the start of building something new. Choose subject carefully: a game holds entities, seats, scripts and decks; a room is decor and lighting that games can use; a table is the table model and its seat ring.

Class. W with editor:write.

Gotchas.

• Creating counts toward the user's limit, the same limit the editor's create dialog shows: Free accounts may create 3 games in any 24 hours and 12 in any 30 days, Player members 9 and 36, Game Masters any number. Deleting a project does not give its creation back. At the limit the create fails with the server's mod-creation-limit message, which says which limit was hit; do not retry, tell the user.
• There are no project templates: every project starts from the create flow's defaults for its subject.
• GitHub must be connected in the tab. There are no local-only projects: every mod is created with a repository, named by repo or, when that is omitted, a slug of name. If GitHub is not connected the call fails; connecting it is the human's OAuth grant, so tell the user to connect it in the tab (or create a free account at github.com/signup first). A name that already exists on their account is refused by GitHub; pass a different repo.
• The project belongs to the signed-in user. It is not published until a human publishes it, but its files are checkpointed to the repository's wip branch as it is edited.
• If creation fails, the error points to diagnostics_get, where the editor's own message lands.

Example#

A request and the structured result it returns.

{
  "request": {
    "subject": "game",
    "name": "Harbour Merchants",
    "repo": "harbour-merchants"
  },
  "response": {
    "projectId": "9b1d6f2a-3c4e-4a7b-8f10-5e2d7c9a1b36",
    "subject": "game"
  }
}

project_save#

Save project — Save the editor project's draft, flushing every open item tab first.

Input

Output (structured content)

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

Saves the editor project's draft, the same as File ▸ Save. First it flushes every open item tab (model, texture, deck, script…). That way their pending edits are part of the save.

When to use it. After a batch of edits, before playtest_start (which saves anyway), before project_open or navigating away, and before publish_preview so the preview reflects your work.

Class. W with editor:write. Requires the project lease.

Gotchas.

• flushedTabs lists the item tabs that had unsaved edits and were flushed.
• saved: false means the save did not happen (the editor keeps its own error in diagnostics); savedAt is only set on success.
• Saving is not publishing. Nothing reaches GitHub until a human publishes.

Example#

A save that flushed the open deck tab first:

{
  "request": {},
  "response": {
    "saved": true,
    "savedAt": "2026-09-29T14:02:31.000Z",
    "flushedTabs": [
      "cards/harbour.deck.json"
    ]
  }
}

project_status#

Project status — Report the editor project's state: dirty, lease, work-in-progress and GitHub link.

Input

Output (structured content)

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

Reports the state of the editor project. You get its id and subject, and whether the draft has unsaved changes. You also see who holds the lease and when it was last saved. Last comes the GitHub repo and ref it is linked to.

When to use it. Before and after saving or publishing, and to confirm a publish landed (the human clicks Publish; this tool shows the new state).

Class. R, editor tab only.

Gotchas.

• dirty is the editor's own unsaved-changes flag; project_save clears it.
• github is absent until the project has been linked to a repository.

Example#

A request and the structured result it returns.

{
  "request": {},
  "response": {
    "projectId": "c2a7e419-0f3b-4e6d-9d21-8b5f7a3c0e94",
    "subject": "game",
    "dirty": true,
    "lease": "owner",
    "lastSavedAt": "2026-09-21T19:02:44.000Z",
    "github": {
      "repo": "sam-plays/backgammon-night",
      "ref": "main"
    }
  }
}

project_checkpoint#

Create restore point — Create a named restore point of the editor project's draft.

Input

Output (structured content)

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

Creates a named restore point of the draft. Restore points appear in project_versions and can be brought back with project_restore_version.

When to use it. Before a large or risky batch (a scripted rebuild of the scene, a mass delete), so the user can go back. The first destructive (D) call of every agent session already makes one called "Before AI agent changes <time>", so you do not need one for a single delete.

Class. W with editor:write. Requires the project lease.

Gotchas.

• The draft must save for the restore point to exist; a failure is reported as internal with the reason in diagnostics.
• Without label the restore point is named "Checkpoint <date time>".

Example#

A request and the structured result it returns.

{
  "request": {
    "label": "Before rebuilding the market board"
  },
  "response": {
    "checkpointId": "rp_1759154551000",
    "createdAt": "2026-09-29T14:02:31.000Z"
  }
}

project_versions#

List versions — List the editor project's restore points and saved versions.

Input

Output (structured content)

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

Lists the project's restore points and saved versions, newest first, with their ids, labels, times and kinds.

When to use it. To find the id for project_restore_version, or to confirm that project_checkpoint or a D call's automatic restore point exists.

Class. R.

Gotchas.

• A version's label was typed by whoever made it (or is a synced commit message), so it comes back as untrustedLabel.

Example#

A request and the structured result it returns.

{
  "request": {
    "limit": 2
  },
  "response": {
    "versions": [
      {
        "id": "rp_1759154551000",
        "untrustedLabel": "Before rebuilding the market board",
        "createdAt": "2026-09-29T14:02:31.000Z",
        "kind": "restore-point"
      },
      {
        "id": "rp_1759153920000",
        "untrustedLabel": "Before AI agent changes 2026-09-29 13:52",
        "createdAt": "2026-09-29T13:52:00.000Z",
        "kind": "restore-point"
      }
    ],
    "total": 7,
    "nextCursor": "2"
  }
}

project_restore_version#

Restore version — Requires the user's confirmation in the DiceyTable tab. Restore an editor project version, overwriting the current draft.

Input

Output (structured content)

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

Brings back a saved version of the project. It overwrites the current draft with that version.

When to use it. When the user asks to go back to an earlier state, or to undo a batch that undo cannot reach (after a reload, or beyond the history limit).

Class. H: the user must click Allow in the DiceyTable tab's confirmation dialog, which names the version. There is no argument or scope that skips it; an unanswered dialog is denied after 120 seconds (human-timeout).

Gotchas.

• The version id must come from project_versions; an unknown id is not-found.
• Unsaved edits made since the version are lost; checkpoint first if they matter.

Example#

Only after the user clicked Allow in the tab:

{
  "request": {
    "versionId": "rp_1759153920000"
  },
  "response": {
    "restored": true,
    "versionId": "rp_1759153920000"
  }
}

project_validate#

Validate project — Validate the editor project on demand: manifest and scene schemas, editor problems, the script safety scanner over each scene script's last compiled body, asset resolution and credits. Scripts are compiled only when the Script editor saves them (script_write does), so the scripts check reports the latest compile results rather than recompiling. Returns fresh diagnostics.

Input

Output (structured content)

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

Runs the project's checks now and returns fresh diagnostics. It checks the manifest and the scene against their schemas. It returns the editor's Problems list and runs the script safety scanner over the scene scripts. Asset and credit problems come back too, with the latest script compile results. The tab's diagnostics hub gets the same entries.

When to use it. After a batch of edits and before playtest_start or publish_preview. It is the fastest way to learn that a manifest edit broke the schema or that a script uses a blocked global. Pass checks to run a subset.

Class. R.

Gotchas.

• scripts does not compile anything: it reports the latest diagnostics from the Script editor's compiler, which runs when a script is saved. To get compile results for new source, save it with script_write, which returns them directly.
• scanner scans the scene scripts in setup.json. The mod's own entry script is scanned by publish_preview and by script_write when you save it.
• manifest also reports what the manifest alone cannot show about a game's bots: a bot whose handler no scene script registers (bot-handler-missing, a warning here and a refusal at publish), a handler registered only in a script's uncompiled source (bot-handler-stale-compile: save that script), and an .onnx file no AI model declares (ai-model-undeclared, an error). It does not re-read the model files; ai_models_list does that.
• assets and credits report what the editor's Problems list knows about the draft and publish; they do not re-fetch files.
• Entry text quotes mod code and file names; it is marked untrusted.

Example#

A scene script that mentions a blocked global in a comment:

{
  "request": {
    "checks": [
      "manifest",
      "scanner"
    ]
  },
  "response": {
    "ok": false,
    "errorCount": 1,
    "warningCount": 0,
    "entries": [
      {
        "id": "d_41",
        "seq": 188,
        "at": 1759154560000,
        "severity": "error",
        "source": "scanner",
        "code": "dom-access",
        "message": "Scripts cannot access DOM/window globals. Matched \"window\" on line 1. This scan is a whole-word text match with no lexer, so the name is banned inside strings and comments too — rename or reword it.",
        "file": "setup.json",
        "count": 1,
        "firstAt": 1759154560000,
        "lastAt": 1759154560000,
        "untrusted": true
      }
    ]
  }
}

project_delete#

Delete project — Requires the user's confirmation in the DiceyTable tab. Delete an editor project through the delete-project flow.

Input

Output (structured content)

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

Deletes an editor project through the delete-project flow. It removes the project's draft and its local files.

When to use it. Only when the user asks for a project to be deleted.

Class. H: the dialog names the project and says what is removed. Nothing you pass skips it.

Gotchas.

• The project's GitHub repository is not deleted; only DiceyTable's draft and the browser's copy are.
• A denied or failed delete answers human-denied and changes nothing.

Example#

Only after the user confirmed in the tab:

{
  "request": {
    "projectId": "e5d0b8c1-6a2f-4b37-9c84-1f7e3a9d2b60"
  },
  "response": {
    "deleted": true
  }
}

publish_preview#

Preview publish — Preview a publish of the editor project: changed files, version, precheck, scanner and credit results, and the AI-attested credits that block publish until a human reviews them.

Input

Output (structured content)

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

Shows what a publish would do, without doing it. You see the manifest version and the files that would change on GitHub: added, modified or deleted. You get the server's publish precheck. You also get the same checks and script safety scan that the preview and the registration scanner run. It lists files with no credit, and the AI-attested credits that still need a human review. blocked and blockers sum it up in plain sentences. They name everything that would keep the Publish button disabled.

When to use it. Before publish_request, to fix what you can (scanner errors, schema errors) and to tell the user what only they can do (review AI-attested credits, connect GitHub, add a cover image).

Class. R. It saves the draft first (as Publish's first phase does) so the preview matches what would ship.

Gotchas.

• Unreviewed AI-attested credits always block. No agent can review them: the review panel's controls are human-only, and the server refuses the publish anyway (ai-credits-unreviewed).
• Uncredited files do not block a publish on their own; they are listed so you can credit them.
• A file between 45 and 50 MB saves but cannot be published; it shows up as an issue here.
• Issues quote file names and code, so the result is marked untrusted.
• The result also carries releaseBranch and, when known, releaseVersion from the precheck.

Example#

One unreviewed AI-attested credit blocks the publish:

{
  "request": {},
  "response": {
    "version": "0.4.0",
    "files": [
      {
        "path": "diceytable.mod.json",
        "change": "modified",
        "bytes": 2210
      },
      {
        "path": "models/cargo-crate.glb",
        "change": "added",
        "bytes": 912004
      }
    ],
    "blocked": true,
    "blockers": [
      "1 credit an AI agent attested needs a person's review (Manifest ▸ Credits, or the Publish dialog). Publish is refused until it is signed."
    ],
    "uncreditedPaths": [],
    "unreviewedAiRecordIds": [
      "cr_9f3a"
    ],
    "issues": [],
    "releaseBranch": "main"
  }
}

publish_request#

Request publish — Requires the user's confirmation in the DiceyTable tab. Open the editor's Publish dialog prefilled; the user reviews every AI-attested credit and clicks Publish. Needs the publish:request scope.

Input

Output (structured content)

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

Opens the editor's Publish dialog with the version and commit message filled in. It never publishes. The user checks the file list there. They review and sign every AI-attested credit, then click Publish themselves.

When to use it. When the work is ready and publish_preview shows nothing you can still fix. Tell the user what they will be asked to review.

Class. H, and it needs the publish:request scope, which is off by default on new keys. The in-tab dialog explains that allowing it only opens the Publish dialog; if the user declines, nothing opens.

Gotchas.

• dialogOpened: true, published: false is the normal answer: the push happens later, if and when the human clicks Publish. Call project_status or publish_preview afterwards to see whether it happened.
• The result lists unreviewedAiRecordIds and a note: while any are unreviewed, Publish stays disabled in the dialog.
• In an editor tab without the project lease it is refused with read-only-lease.

Example#

After the user allowed it in the tab. Nothing is pushed until they click Publish:

{
  "request": {
    "version": "0.4.0",
    "message": "Add cargo crates and the tide track"
  },
  "response": {
    "dialogOpened": true,
    "published": false,
    "unreviewedAiRecordIds": [
      "cr_9f3a"
    ],
    "note": "The Publish dialog is open. Publish stays disabled until the user reviews the AI-attested credits there; nothing has been pushed."
  }
}

sync_status#

GitHub sync status — Report the editor project's GitHub sync state and any conflicts.

Input

Output (structured content)

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

Reports the project's GitHub sync state, the same as the status bar's sync light. It says whether the local draft is ahead of or behind GitHub. It also lists any conflicts. Each one has its path, and says if it is a plain file conflict or a manifest merge item.

When to use it. After a human edited the repository on GitHub, or when publish_preview reports a conflict.

Class. R.

Gotchas.

• Conflict paths are file names from the repository and are marked untrusted.
• Manifest conflicts (kind: "manifest") are resolved item by item in the manifest merge panel, by the user; they cannot be resolved with sync_resolve.

Example#

A request and the structured result it returns.

{
  "request": {},
  "response": {
    "state": "conflict",
    "ahead": 2,
    "behind": 1,
    "conflicts": [
      {
        "path": "rules/quick-start.md",
        "kind": "file"
      },
      {
        "path": "diceytable.mod.json",
        "kind": "manifest"
      }
    ]
  }
}

sync_resolve#

Resolve sync conflicts — Resolve GitHub sync conflicts in the editor project per file. Keeping local or merging is W; any resolution that discards a side asks the user in the tab.

Input

Output (structured content)

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

Settles GitHub sync conflicts one file at a time, through the sync dialog's own path. The dialog records each choice. keep: "local" keeps the draft's copy, and GitHub keeps its history. keep: "remote" swaps the local copy for GitHub's.

When to use it. To clear file conflicts that sync_status lists, when you know which side is right.

Class. W, escalating to H when any resolution is remote: taking GitHub's version overwrites the local, unpublished copy, so the user confirms in the tab, and the dialog lists the files. local stays W.

Gotchas.

• keep: "merge" is refused: only the manifest is merged, and only in its own panel.
• Every path must have an open file conflict; otherwise not-found (or invalid-arguments for a manifest item).
• A file that failed to resolve is reported in failed with the reason, and also lands in diagnostics.

Example#

Keeping the local copy is W; taking GitHub's (remote) would ask the user:

{
  "request": {
    "resolutions": [
      {
        "path": "rules/quick-start.md",
        "keep": "local"
      }
    ]
  },
  "response": {
    "resolved": [
      "rules/quick-start.md"
    ]
  }
}

undo#

Undo — Undo the last editor changes in the editor tab's history.

Input

Output (structured content)

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

Undoes editor changes, just like Edit ▸ Undo. It steps back through the Edit Mode shell's history.

When to use it. To back out your own last change, or a batch of them. Scene edits, room and table-pack edits and manifest edits are all history steps.

Class. W with editor:write. Requires the project lease.

Gotchas.

• The history groups edits that land within about half a second of each other into one step, so a quick batch of tool calls often undoes as one.
• applied is how many steps were actually undone, which can be fewer than steps when the history runs out; check canUndo.
• The history belongs to the tab, not to you: undo also reverts changes the human made. Use it for your own recent work.
• For older states use project_versions and project_restore_version.

Example#

A request and the structured result it returns.

{
  "request": {
    "steps": 2
  },
  "response": {
    "applied": 2,
    "canUndo": true,
    "canRedo": true
  }
}

redo#

Redo — Redo editor changes in the editor tab's history.

Input

Output (structured content)

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

Redoes editor changes that undo stepped back, as Edit ▸ Redo does.

When to use it. Right after an undo you did not mean.

Class. W with editor:write. Requires the project lease.

Gotchas.

• Any new edit after an undo clears the redo history, as in every editor.
• applied can be fewer than steps; check canRedo.

Example#

A request and the structured result it returns.

{
  "request": {},
  "response": {
    "applied": 1,
    "canUndo": true,
    "canRedo": true
  }
}