Tool reference
MCP tools — parameters, scopes, behaviors, and example prompts.
Each MCP tool enforces the scopes listed below (see Setup).
All write tools accept structured input only — they never parse natural language directly. The client (Claude, Codex, etc.) is responsible for translating the user's prompt into the parameters documented here.
list_projects
List presentation projects in your workspace. Paginated; pass the returned cursor to fetch the next page.
- Scope:
project:read - Behavior: read-only, idempotent
Parameters
| Name | Type | Required | Constraints | Default |
|---|---|---|---|---|
cursor | string | no | opaque, returned by a prior call | — |
limit | number | no | 1–100 | 20 |
Returns — { projects, nextCursor, hasMore }. Each project summary includes id, pid, name, theme, page-layout settings, publish state, members (with roles), createdAt / updatedAt, pinnedAt, and firstPageId. nextCursor is opaque (pass it as cursor on the next call) or null when there are no more pages.
Example prompt
"List my Encelade projects and show me the most recent five."
get_project
Get a single project by its public ID (pid).
- Scope:
project:read - Behavior: read-only, idempotent
Parameters
| Name | Type | Required | Constraints |
|---|---|---|---|
pid | string | yes | non-empty |
Returns — Full project record: pid, name, theme, branding, page-layout/grid settings, publish state, the pages array, members (each with a role — the owner is the member with role: "owner"), createdAt / updatedAt, and your pinnedAt for the project (or null).
In ChatGPT and Claude hosts that support MCP Apps, this tool also opens a slide viewer. Select a slide or use the previous/next buttons to navigate. Open in Encelade opens the selected slide for editing. The viewer is read-only and loads slide images on demand; visited slides gain thumbnails. The text response also includes a link to the deck for clients without MCP Apps support.
The viewer requires project:read and project membership (or a tenant admin role). Decks do not need to be published. Image data is delivered only to the UI, without render tokens or public image URLs.
Example prompt
"Show me the details of the deck with pid
abc123, including its pages and collaborators."
get_slide_preview
This read-only tool is visible to the MCP Apps viewer. It accepts a non-empty pid and a UUID pageId, requires project:read, and checks access to that page before reading or rendering its private preview. It returns { pid, pageId, status } as text and the image in UI-only result metadata. The status is ready, or loading when another render is in progress. Rendering failures return a tool error so the viewer can offer a retry.
update_project
Update an existing project's name or theme.
- Scope:
project:write - Behavior: write, idempotent
Parameters
| Name | Type | Required | Constraints |
|---|---|---|---|
pid | string | yes | non-empty |
name | string | no | 1–255 characters |
theme | string | no | valid theme slug |
You must pass at least one of name or theme. Tenant admins and project owners/editors/content editors can update; viewers cannot.
Returns — The updated project record.
Example prompt
"Rename my 'Q3 Report' deck to 'Q3 2026 Quarterly Review' and switch its theme to obsidian."
edit_project
Edit an existing deck from a plain-language instruction, the way the editor's AI chat does: rewrite or translate text, restyle layers, add, reorder or delete pages, change the theme.
- Scope:
project:ai-chat - Behavior: write, destructive (can delete pages), non-idempotent
- Rate limit: 10 calls per minute, shared with
POST /api/public/v1/projects/{pid}/edits
Parameters
| Name | Type | Required | Constraints / default |
|---|---|---|---|
pid | string | yes | non-empty |
instruction | string | yes | 1–4,000 chars: what to change |
pageId | string | no | a page id from get_project; the page an instruction that names no pages applies to |
dryRun | boolean | no | false (default); true reports the changes without saving them |
Tenant admins and project owners/editors can edit; content editors and viewers cannot. Every call uses AI credits, dry runs included.
Returns — { status, message, changes, skipped, changedPageIds, deletedPageIds }. message is the assistant's reply; changes lists each change as { tool, details } and skipped each change it could not make as { tool, reason }. status is one of:
| Status | Meaning |
|---|---|
applied | The changes were saved. |
proposed | dryRun was true; nothing was saved. |
no_changes | The instruction led to no change. |
truncated | The edit hit its output or step limit and nothing was saved. Split the request. |
Page content is not returned: call get_project to read the edited deck.
Errors you can act on — returned as a tool error:
- Out of AI credits — the error text is JSON,
{ code: "CREDITS_EXHAUSTED", message, limit, upgrade_url }, so branch oncode. A credit pack or a bigger plan clears it. - Page not found —
pageIdis not a page of this deck. - The deck changed while the edit ran — someone saved the deck mid-edit, so nothing was saved. Retry.
Example prompt
"In my 'Q3 Review' deck, translate every page into German and delete the appendix."
delete_project
Permanently delete a project. This cannot be undone.
- Scope:
project:delete. An OAuth connection has it only if the client requested it at sign-in; otherwise delete decks in the Encelade app. - Behavior: destructive, non-idempotent
MCP clients annotate this tool as destructive — Claude Desktop and Claude Code will ask for confirmation before invoking it.
Parameters
| Name | Type | Required | Constraints |
|---|---|---|---|
pid | string | yes | non-empty |
Returns — { deleted: true, pid: "<the pid>" } on success.
Example prompt
"Delete the deck named 'Untitled Draft' from my workspace."
generate_project
Generate a deck, one-pager or proposal from a brief. Returns a runId immediately; the run plans and builds the pages in the background.
- Scope:
project:generate - Behavior: write, non-idempotent; with
research: truethe run searches the web - Rate limit: 10 calls per minute, and a cap on runs in progress at once
Parameters
| Name | Type | Required | Constraints / default |
|---|---|---|---|
brief | string | yes | 1–200,000 chars: the request plus any notes, data or research to build from |
artifactType | enum | no | deck (default), one_pager, proposal |
pageCount | "auto" or integer | no | auto (default) or 4 or more; a one-pager is always one page |
locale | string | no | en, de, es or uk; detected from the brief when omitted |
research | boolean | no | false (default); true lets the run search the web |
audience | string | no | ≤ 300 chars |
tone | string | no | ≤ 300 chars |
cta | string | no | ≤ 300 chars, the call to action |
style | enum | no | classic (default) or cinematic; decks only |
onePagerDesign | enum | no | auto (default), editorial, bands, modular; one-pagers only |
theme | string | no | auto (default), a built-in theme id, or tenant-theme:<uuid> from list_themes |
fitToPageCap | boolean | no | false (default); true condenses into your plan's page cap instead of failing |
There are no file uploads or connectors: paste the source text into brief. Links in the brief are read.
Returns — { runId, projectPid, status: "queued" }. Poll with get_generation_run.
Plan limits. When the workspace is out of credits, out of storage or the request is over the plan's limits, the tool error's text is JSON: { code, message, required_plan, limit, upgrade_url }. code is CREDITS_EXHAUSTED, PAGE_LIMIT_EXCEEDED, PRO_REQUIRED, PRESENTATIONS_EXHAUSTED, PROPOSAL_CREATION_REQUIRED or STORAGE_FULL. required_plan is left out when no single plan clears the limit (a credit pack clears CREDITS_EXHAUSTED, deleting files clears STORAGE_FULL), and limit ({ key, value, used }) when the error is not about a count. Branch on code rather than string-matching. Other errors are plain text.
Example prompt
"Create a 10-page presentation about the impact of AI on healthcare. Use a professional tone aimed at hospital executives."
get_generation_run
Check the progress of a run started by generate_project. Poll every 5–15 seconds; a run takes a few minutes.
- Scope:
session:readorproject:generate - Behavior: read-only, idempotent
Parameters
| Name | Type | Required | Constraints |
|---|---|---|---|
runId | string | yes | UUID |
Returns — A one-line status plus the run:
| Field | Notes |
|---|---|
phase | planning, generating, done or failed. Stop polling at done or failed. |
status | The run's stage: queued, intake, researching, planning, writing, composing, done, failed or canceled. |
link | The project URL, available from the start. |
projectPid | The project's public ID, for get_project. |
error | { stage, code } when the run failed, otherwise null. |
startedAt, finishedAt | ISO 8601 timestamps, or null. |
plan | { title, pageCount, pages } once planned, otherwise null. |
Example prompt
"Check on the deck you are generating and give me the link when it's done."
cancel_generation_run
Stop a run started by generate_project. Pages it already wrote stay in the deck; the run ends canceled (phase failed in get_generation_run).
- Scope:
session:writeorproject:generate - Behavior: idempotent; a run that already finished returns an error
Parameters
| Name | Type | Required | Constraints |
|---|---|---|---|
runId | string | yes | UUID |
Returns — { status }, the run's status after the cancel was recorded.
Example prompt
"Stop generating that deck."
list_themes
List the custom themes in your workspace, newest first. Pass a theme's themeId as theme to generate_project to build decks in it.
- Scope:
theme:read - Behavior: read-only, idempotent
Parameters — none.
Returns — { themes }. Each theme has themeId (tenant-theme:<uuid>), name, mode ("light" or "dark"), accent, background, highlightStyle, updatedAt, and studioUrl (where to edit it in Encelade).
Example prompt
"Which Encelade themes do we have? Make a deck about Q3 results in our Acme theme."
create_theme
Create a custom theme from brand colours, fonts and styles — for example when you ask your AI tool to "send our theme to Encelade". Requires the Editor or Admin workspace role.
- Scope:
theme:write - Behavior: write, not idempotent (each call creates a new theme); reaches Brandfetch when a logo is requested
- Rate limit: 5 per minute and 20 per hour, per person
name and colors.accent are required. Anything left out is derived from the colours you give (for example readable text for a dark background) or kept from Encelade's default theme. All colours are hex (#e63946 or #e39).
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
name | string | yes | If the workspace already has a theme with this name, a number is added: Acme (2). |
colors | object | yes | accent (required), accentMuted, background, panel, card, border, text, mutedText. |
chartColors | string[] | no | 1–8 colours; repeated to fill the theme's 8 chart series. |
fonts | object | no | body / heading, each { family, weight? }. Only fonts Encelade offers are applied; others are reported back. |
pageBackground | object | no | { type: "solid", color } or { type: "gradient", colors (2–5), style?: "linear" | "radial", angle? }. |
cards | object | no | fill (same shape as pageBackground), borderColor, borderWidth (0–20), cornerRadius (0–50), shadow. |
titleCard | object | no | Same as cards, without shadow. Gives decks a title card. |
contrast | object | no | Opposite-mode palette for emphasis slides: background, panel, card, border, accent, text, mutedText. Send {} to derive it. |
highlightStyle | string | no | How decks mark key phrases in headlines and tables: accent (default), bold-muted, bold or highlighter. |
logo | object | no | brandDomain (the brand's website, e.g. acme.com), position, widthPercent (3–15). Encelade looks up the logo the brand publishes (via Brandfetch). |
Unknown fields are rejected, so a misspelled field fails rather than being silently ignored.
Returns — { themeId, name, renamed, studioUrl, logo, derived, notApplied }. logo is { domain, kind } when a logo was added, otherwise null; derived lists the colours Encelade filled in; notApplied lists anything it could not use, with a reason.
A logo is optional, so a failed lookup never fails the call: the theme is
created without a logo and notApplied says why (no brand found for the
domain, no logo made for the theme's background, lookup unavailable). Encelade
only uses the version of the logo made for the theme's background, plus the
opposite version for contrast slides, never a version that could disappear
against the slide.
Example prompt
"Send Encelade our theme: accent #E63946, dark navy background #1D3557, Inter for headings, and our logo from acme.com."
update_theme
Change an existing custom theme — for example "make our Acme theme's accent orange". Requires the Editor or Admin workspace role.
- Scope:
theme:write - Behavior: write, destructive (overwrites the stored values); reaches Brandfetch or downloads files when a logo, font or image link is given
- Rate limit: 10 per minute and 60 per hour, per person
The change applies at once to every deck that uses the theme, and there is no undo. Only the fields you pass change; everything else is kept.
Parameters — themeId (required, from list_themes), an optional name, and any of the create_theme fields, all optional:
chartColorsandbackgroundVariantsreplace the whole list;backgroundVariants: []removes every variant.contrastmerges into the stored palette;nullremoves it.titleCard: nullremoves the title card.highlightStyle: nullreturns toaccent.logowithbrandDomain,urlorsvgreplaces the logo, keeping its placement unless you passposition/widthPercent. Alogowith onlyposition/widthPercentmoves or resizes the current logo.logo: nullremoves it.namerenames the theme. If another theme already has that name, the call fails and nothing is changed.
Returns — { themeId, name, studioUrl, changed, derived, decksUsingTheme, logo, customFonts, notApplied }. changed lists the fields that now differ; derived lists the ones that changed as a result of others (for example text colours re-picked for a dark background); decksUsingTheme is how many decks in the workspace use the theme. logo is there only when the call passed a new logo: what was applied, or null if it could not be imported and the theme kept its current one.
A logo, font or image that cannot be imported never fails the call: the theme
keeps its current one and notApplied says why.
Example prompt
"Make our Acme theme dark: background #0B1220 and accent #FF6B35."
delete_theme
Permanently delete a custom theme from the workspace, for everyone in it. Requires the Editor or Admin workspace role.
- Scope:
theme:write - Behavior: write, destructive; there is no undo
- Rate limit: 5 per minute and 20 per hour, per person
Parameters — themeId (required, from list_themes) and confirmDecksUsingTheme (optional).
If any deck uses the theme, the first call deletes nothing. It returns { deleted: false, confirmationRequired: true, themeId, name, decksUsingTheme } so the assistant can tell you how many decks use the theme and ask before deleting. Once you agree, it calls again with confirmDecksUsingTheme set to that count. If the count changed in between, it asks again with the new one. A theme no deck uses is deleted in one call.
Returns — { deleted: true, themeId, name, decksUsingTheme }.
Generated decks keep the look the theme had when they were created. New decks can no longer use the theme.
Example prompt
"Delete the old Acme 2024 theme."