## Tools {#tools}

Tools come in groups. Your assistant may see every tool; one your grant does not cover is refused with `agent-capability-required` when called. A tool answer has `ok`, and a refusal carries an `error` with a `code` and a `message`, usually with a `fix` that names the next step. Sign-in and access refusals are different: the server answers with an HTTP error whose `error` is the code (for example `agent-token-required`), with no `ok`.

| Group | Read | Write |
| --- | --- | --- |
| Context | `workspace_context`, `agent_grants_list`, `profile_get` | `agent_grants_revoke` |
| Projects | `project_list`, `project_get` | `project_create`, `file_create`, `project_rename`, `project_duplicate`, `project_fork`, `project_archive`, `project_unarchive`, `project_trash`, `project_restore` |
| Documents | `document_get`, `document_validate` | `document_apply`, `document_arrange`, `scene_add`, `choice_add`, `node_configure`, `document_paste_nodes`, `document_replace`, and one `document_*` tool per edit |
| Schema | `schema_nodes`, `schema_node` |  |
| Media | `media_list`, `media_describe`, `media_measure`, `media_compare`, `cast_list`, `cast_get` | `media_upload_url`, `media_complete`, `media_import_url`, `media_review` (a clip audit spends budget), `cast_save`, `cast_place` |
| Generate | `generate_models`, `generate_quote` | `generate_run`, `generate_finish`, `generate_status`, `take_pick` |
| Preview | `preview_url`, `playthrough_simulate` | `watch_through_start`, `watch_through_get` (reading an open watch-through also moves it on) |
| Publish | `publish_copy_get`, `publish_status` | `publish_copy_set`, `publish_copy_generate`, `publish_images_set`, `publish_logo_generate`, `publish_request`, `publish_rollback`, `publish_check`, `publish_fork_settings` |
| History | `document_revisions`, `document_revision_get`, `document_diff` | `document_checkpoint_set`, `document_restore` |
| Advice | `analytics_paths`, `benchmarks_get`, `performance_series`, `usage_report`, `credits_history`, `templates_list`, `templates_get` |  |
| Series | `series_bible_get`, `series_bible_validate`, `rights_note_check`, `series_manifest_get` | `series_bible_save`, `series_bible_request_approval`, `series_bible_sync_approval`, `series_manifest_save` |
| Saved templates |  | `templates_save`, `templates_update`, `templates_delete`, `templates_restore`, `templates_insert` |
| Template links | `workflow_template_lookup`, `workflow_template_get` | `workflow_template_share`, `workflow_template_save`, `workflow_template_remove` |

Read tools change nothing, but some still need a permission: `generate_quote` needs a generate budget, and every publish tool needs publish.
NEUKO operator tools (`journal_add`, `journal_list`, `ledger_read`, `ledger_record`, `ledger_report`, `panel_watch`, `panel_verdict`, `whats_new_pending`, `whats_new_attach`, and the series bible approval tools) refuse other connections. `media_review` needs only media: read but is not read-only: a clip audit spends from the generate budget (see [generate and spending](/docs/mcp/tools#generate)).

`usage_report` answers what the Creator console shows for a date range: jobs, failures and estimated USD per model, your project and publication counts, and playback totals. It needs viewer analytics and templates on, for every project, because it adds up all your projects. Choice and drop-off counts per story are in `analytics_paths`. `credits_history` lists what your credits were spent on, newest first: charges, returns and holds for runs still in progress. It never lists purchases, grants or refunds, and it needs the same access as the usage report. `profile_get` reads your public username and avatar; only you can change them, on Home. These three tools roll out by account: until they reach yours, a call answers `feature-disabled` and changes nothing.

`media_compare` also rolls out by account, with the same answer until it reaches yours.

`document_restore` shows its result on an open Canvas and in Earlier versions, with the connection label, time, revision and run. Those facts stay after reload. See [restore an earlier version](/docs/mcp/build#restore).

When Home is open, the project list shows your assistant's project changes within a few seconds, without a reload. A project it creates, copies, restores or unarchives appears, one it renames shows the new name, and one it archives or trashes leaves the list. The card names your connection, for example "Renamed by Claude just now", and a File it added shows as "“Episode 2” added by Claude". Trash shows which connection moved a project there. A Rename you are typing stays as you typed it, and the dialog tells you the new name. This rolls out by account.

`document_replace` swaps a whole File for a document you give it, as Import JSON does in the editor. It adds a new version on top of the current one. The old version stays in Earlier versions, and `document_restore` brings it back. See [replace a whole File](/docs/mcp/build#replace).

`publish_rollback` and `agent_grants_revoke` are hard to undo. `project_trash` moves a project to Trash, and `project_restore` brings it back until it is deleted. Trash can delete a project 30 days after it was moved there. Your assistant should confirm with you before calling any of these three.

`project_archive` hides a project from your active list and deletes nothing; `project_unarchive` brings it back. A series in an archived or trashed project stops playing in the Bitebox app until the project is active again, and its public pages stay up. So when a project has a series in the app, your assistant cannot archive, unarchive, trash or restore it. It asks you to do that in the editor. A series you revoked does not play in the app, so it does not block these actions.

No tool deletes a project permanently or takes down a publication. Your assistant asks you to delete a project from Trash in the editor, and a NEUKO operator handles a takedown.

The examples below show tool arguments. Values in angle brackets are placeholders: your assistant fills them from earlier answers.

### Start with workspace_context {#workspace-context}

```
workspace_context {}
workspace_context { "projectId": "<projectId>" }
```

It returns what the grant allows, your credits, the node types this workspace offers, the publish format, the current project if you name one, and what this server cannot do. Read node types and their ports from here and from `schema_nodes`; do not guess them.

### Read, then write {#read-and-write}

Read tools change nothing. Write tools save a new revision.

```
project_list {}
document_get { "projectId": "<projectId>" }
```

`document_get` returns the head `revisionId`. Pass it as `expectedRevisionId` on the next write, and build related edits as one `document_apply` batch. A batch is one revision and one undo step. If any command is refused, nothing is written, and the answer names which command and why. Add `"dryRun": true` to check a batch without saving.

```
document_apply {
  "projectId": "<projectId>",
  "expectedRevisionId": "<revisionId>",
  "commands": [
    { "type": "connect",
      "connection": {
        "source": { "nodeId": "<fromNode>", "endpointId": "<outputId>" },
        "target": { "nodeId": "<toNode>", "endpointId": "<inputId>" } } }
  ]
}
```

Every write answers a new `revisionId`; use it for the next one.

### Run an editing node on the server {#run-an-editing-node}

The editing cards — rotate & flip, invert, trim, crop, resize, color correction, and composite — bake on the server with `node_run`. Wire the card's source first (the connect in the batch above), then run it. A still answers at once and writes `props.src` and `props.outputKey` on the node, the same fields the open editor's bake writes, as one new revision. A clip (a Trim on a video, any card on a video, or a Composite with a clip on Base or Overlay) answers a `runId` instead; poll `node_run_status` until it reports `done`, then read the node again. Color correction with a wired Reference image matches the colors on the server too. A clip takes one table from its middle frame, so every frame gets the same change. For Composite, wire Base (endpoint `base`), and optionally Overlay (`overlay`) and an AI Mask Region (`region`). With a clip, the result runs Base's length (the Overlay's when Base is a picture); set `overlayStartMs` and `overlayEndMs` for when the Overlay shows, and `overlayAudio` to `mix` to keep the Overlay's sound. What stays transparent in a clip becomes the Background colour, black when none is set.

```
node_run        { "projectId": "<projectId>", "nodeId": "<editNodeId>" }
node_run_status { "projectId": "<projectId>", "runId": "<runId>" }
```

Settings that change nothing (a card left at zero rotation, a trim of the whole clip) answer the source file unchanged and write nothing. Editing bakes cost no credits.

### Saved templates {#templates}

Saved templates are the nodes in the Saved panel in Canvas. They belong to you, not to one project, so a template saved from one project can go into any other. Writing them needs documents: write; changing, removing or restoring one also needs a connection with Every project. Reading them (`templates_list`, `templates_get`) needs analytics: read, and so do `templates_update` and `templates_insert`, which read the template first.

```
templates_save { "projectId": "<projectId>", "nodeIds": ["<nodeId>", "<nodeId>"], "name": "Two-way choice" }
templates_insert { "templateId": "<templateId>", "projectId": "<otherProjectId>" }
```

`templates_insert` places a copy with new node ids, as dropping the template on the canvas does, in one revision. The copy keeps each node's content, its exits and options in their saved order with their labels, and the wires between template nodes. A link to a node outside the template is not placed. It answers `nodeIdMap` so your assistant can connect the new nodes to the rest of the story. `templates_delete` removes a template from the Saved panel; `templates_restore` brings it back.

### Template links {#template-links}

A template link gives another creator their own copy of a whole project. They are not available to every account yet; where they are off, every template link tool answers not found. Sharing, saving and removing need documents: write; reading a link or looking one up needs documents: read.

```
workflow_template_share { "projectId": "<projectId>", "title": "Onboarding drip" }
workflow_template_save { "linkId": "<linkId or share URL>" }
```

A project has one live link: sharing it again answers the same link with `existing: true`. `workflow_template_save` copies the linked project as it is now into a new project in your connection's scope, so your assistant can build in it next. `workflow_template_remove` stops the link; copies already saved stay. Your assistant should confirm with you before sharing or removing a link.

### Generate and spending {#generate}

Pick a model from `generate_models`, quote it, then run it.

```
generate_quote { "projectId": "<projectId>", "definitionId": "<model>", "prompt": "<prompt>" }
generate_run   { "projectId": "<projectId>",
                 "runs": [ { "definitionId": "<model>", "prompt": "<prompt>", "nodeId": "<node>" } ] }
```

- A quote spends nothing. `withinBudget: true` means the quote fits today's budget. It does not promise the run will succeed.
- `generate_run` spends credits. It takes up to four runs at once. Check progress with `generate_status`.
- `generate_finish` re-renders a draft take (Seedance 2.5, Seedance 2.5 Reference or Flux 3 with Draft on) at full quality. A Seedance draft can be finished for 14 days. It quotes first; `quoteOnly: true` stops at the quote.
- Text tiles run by `nodeId` too: Generate Text takes its wired Prompt (and optional system prompt and media), Witness and Adjudicator take their wired stills and keep their default prompts unless the node overrides them. A finished text run appends to the node and `generate_status` returns the text. A Generate Text node with no wired prompt is refused with `prompt-missing` before anything is spent. A Generate Text node runs the model saved in `/props/model`, at that model's price, or the default when none is saved. A saved model that is not in the Generate Text menu is refused with `unknown-model` before anything is spent.
- While a run on a node is going, the node carries a run marker, so the editor shows it as running. When the run fails or is canceled, `generate_status` removes the marker before it tells your assistant the run ended, so this removal never changes the File after that answer. When the marker cannot be removed yet, `generate_status` answers `status: "finishing"`: poll again. Until your assistant polls the run or the File is next saved, `document_get` can still show the marker of a run that has ended. The editor stops showing it as soon as the File is opened.
- A node that a run has filled plays without a Prompt node. Its saved media (or a saved prompt on the node) counts as its Prompt, so the File is ready to play once the story is wired. To run the node again, wire a Prompt into it.
- A generate node keeps every take in order, and the newest take plays. `take_pick` plays another take, the same as the arrows on the node: `{ "projectId": "<projectId>", "nodeId": "<node>", "take": 2 }`. Take 1 is the oldest. It spends nothing.
- `media_review` checks a clip's size and format for free. A clip audit (`audit: true`, or expected lines, on-screen text or cast) costs a fixed amount from the same daily budget.
- A run over the day's budget is refused before anything runs or is charged. See [budget refused](/docs/mcp/troubleshooting#budget-refused).
- Some tiles take no prompt. `generate_models` marks them `promptRequired: false`. Depth Map reads a wired picture: place an Image node with a hosted `src`, wire it into the tile's `image` input, then quote and run the tile by `nodeId`. A Depth Map with no picture wired is refused before anything is spent. Remove Background works the same way and returns the subject on transparent pixels. Remove Video Background takes a wired clip in its `video` input and returns an MP4 of the subject on one solid colour; a run with no clip wired is refused before anything is spent. To put the subject on something else, run Composite on the result.
- `generate_models` lists only models with a price. A model without one is refused with `model-not-quotable`.
- Try On dresses the person in one picture in the garment from a second picture. Pass the person as `imageUrl` and the garment as the one entry of `imageUrls`. A Prompt is optional. The result keeps the person picture's aspect ratio at about 0.6 megapixels. It runs only in a series project whose bible lists `try-on` and whose rights note `rights_note_check` answers complete. A complete note names no real person, so use a synthetic or cast character. Any other run is refused with `rights-note-required` before the quote, and nothing is charged.

Ask your assistant to quote first and tell you the cost before it runs anything large.

### Reuse a cast across projects {#cast}

A cast library is a project that holds your characters. Each character has numbered versions. A version has one reference still (a single image of the character) for each view, such as front or side. It can also have a voice, model presets and a LoRA, which is a small add-on model trained on one character's look. A saved version does not change.

```
cast_save  { "projectId": "<cast project>", "castId": "dorothy-gale", "expectedVersion": 0,
               "displayName": "Dorothy Gale", "references": [ { "view": "front", "src": "<still from media_list>" } ] }
cast_place { "projectId": "<series project>", "castProjectId": "<cast project>",
               "castId": "dorothy-gale", "version": 1 }
```

- Upload the stills to the cast project first. `cast_save` accepts only images from that project's `media_list`.
- `cast_place` adds the stills of that version to a File in another project as Image nodes. It returns their ids as `castNodeIds`. Connect the Image nodes to the reference inputs of a video model. Then pass the same ids to `media_review` to check that each clip matches the cast. A cast member you name who is not in the clip fails the check. If the review answers `incomplete`, run it again before you retake the clip.
- Your assistant can use a cast library only when its token's scope includes the cast project.
- `cast_save` also needs the history permission, because it numbers versions from the File's history.

### A series bible needs your approval {#series-bible}

```
series_bible_save             { "projectId": "<series project>", "bible": { … }, "expectedVersion": 0, "rightsNote": { … } }
series_bible_request_approval { "projectId": "<series project>", "sha256": "<draft sha256>", "reviewUrl": "https://…" }
series_bible_sync_approval    { "projectId": "<series project>", "issue": "NEU-1234" }
series_bible_get              { "projectId": "<series project>" }
```

- Your assistant saves a series bible as a draft only. It cannot approve one.
- `series_bible_request_approval` writes an approval ticket in Linear. The ticket shows the bible version and its hash, the rights note hash, any premium models with their reasons and the budget. Then it shows the whole bible and rights note as the server holds them. That is what you approve. The review page link is only for your comments.
- You approve in Linear: add the label **Bible approved** to the ticket. A comment is never an approval.
- `series_bible_sync_approval` has the server read the ticket. It approves only your label, added after the ticket last changed, for the exact hashes of the current draft. Your assistant never sends the verdict.
- Premium models in a draft never run. They run only after you approve the bible that lists them.
- The approval tools work only for NEUKO's own Content Factory, on a NEUKO operator's connection; other connections get `agent-forbidden`. Until assistants have their own Linear identity, the server reports the checks but approves nothing.

### Publish needs your confirmation {#publish}

```
publish_check   { "projectId": "<projectId>" }
publish_request { "projectId": "<projectId>" }
publish_status  { "projectId": "<projectId>" }
```

Run `publish_check` on the File first. The card keeps Publish off until the version it publishes has a passing check. A rollback to a version that was public before is not checked again. `publish_request` does not make anything public. You see a pending-publish card in the open Canvas; one click publishes. The one exception is a NEUKO team account with direct publish. Its assistant publishes after a passing check, without a click. The consent screen does not offer this. Until you click, `publish_status` reports `pending`, and afterwards `published` with the link. A request you do not confirm expires.

The card names the agent by the name its connection registered, which you saw when you connected it, or says "An agent". It lists each File the request publishes. **Watch** opens the story's play page, as viewers see it, playing the exact version the request publishes, even if you saved the File again since. The page keeps your published page's title and copy when the story has a release. **Open** opens that File on the Canvas in a new tab, at its latest save. The card makes a new link each time you press Watch. A preview link lasts 15 minutes; an expired one says so and tells you how to get a new one. An agent with history access gets the same link with `preview_url` and a `revisionId`. If previews on the play page are not on yet, Watch and `preview_url` open the reference player instead.

On a content factory drop (several episode Files on a project the factory records in its run ledger), your click on that card is also your review verdict. Publish is a pass. Not now asks one thing first: send back for fixes, or cancel this drop, with the top problem and an optional note. The server saves your verdict from your own click; the agent reads it with `ledger_read` and can never write it for you.

Two publish helpers have daily rate limits, separate from credits. `publish_copy_generate` draws on your daily writer quota. `publish_logo_generate` allows three logo draws a day per project and twelve a day across your projects, failed draws included.

---
Source commit: 9ccaa86d41d7 · Build date: 2026-11-17T03:27:39.423Z
