Deckary MCP tool reference

Deckary exposes six tools for saved Web Builder decks, two shared tools for authoring vocabulary and account skills, and five live document tools that work the same way for explicitly shared PowerPoint presentations, Excel workbooks, and Word documents. Discovery and read tools are non-destructive. Authoring tools validate current artifact truth before applying a change. The connected client's tool schema is authoritative for exact fields and limits.

Tool descriptions are intentionally short because MCP clients truncate long descriptions. The complete authoring vocabulary (node, text, line, chart, table, chart-action, and scene keys) is served by describe_authoring_vocabulary, so the recommended order for any authoring task is read → describe_authoring_vocabulary → author.

Saved Web Builder tools#

The normal sequence is list_decks → read_deck → describe_authoring_vocabulary (before the first authoring call) → optional rendering → author_deck. Reuse the latest revision returned by a successful call.

Consulting visuals#

Consulting visuals such as icebergs, funnels, staircases, issue trees, and strategy houses are written directly in an author_deck program. There is no separate preparation call. A consulting_visual node names a catalog recipe and gives its content in the recipe's own terms, for example {"id": "maturity", "type": "consulting_visual", "placement": {"mode": "absolute", "frame": [72, 120, 816, 360]}, "recipe": "deckary_straight_staircase", "content": {"steps": ["Ad hoc", "Defined", "Managed", "Predictive"]}}. Optional color (accent1 to accent6) and altText complete the node. Call describe_authoring_vocabulary with topic consulting_visuals for when to use one and every recipe's content shape. Live PowerPoint programs for author_live_document accept the same node with frame in place of placement.

Deckary derives the layout from the content, renders any artwork the recipe needs as a reusable deck asset within the same call, and rejects content that does not fit the recipe with an issue at its exact path, such as an iceberg with two drivers instead of three. A successful result may include advisory notes, for example when copy will shrink to fit. read_deck returns an untouched visual in the same recipe and content form, so an agent can revise it by upserting the node.

Shared vocabulary tool#

read_user_skill reads full Markdown for one to three enabled account skills using skillIds from the vocabulary response. It returns skill versions and reports unavailable IDs. It is read-only and available with either permission.

Every vocabulary response also includes your saved preferences, enabled built-in instructions, and a catalog of custom skills. Before planning each task, follow those preferences and read relevant custom skills with read_user_skill. Explicit requests in the conversation override saved preferences. Reuse loaded skills within the task; reload context after changing settings. Settings may take up to 30 seconds to refresh across server workers. These instructions guide the external agent; Deckary cannot guarantee its compliance.

describe_authoring_vocabulary is available with either permission and never changes a document. Call it once before the first author_live_document or author_deck call, and again whenever a validation issue reports an unknown key. live_documents returns the protocol every live host shares: sessions, locators, versions, and settlement. powerpoint_dsl, excel_dsl, and word_dsl return each host's program grammar, and the matching _program_body topics return the complete clause and value vocabulary. chart_actions returns every PowerPoint chart action with its argument schema and applicable chart types, web_deck_scene the WebDeck scene and patch vocabulary for author_deck, and consulting_visuals when to use a consulting visual, how to write the consulting_visual node, and the recipe catalog with each recipe's content shape.

Live document tools#

Each session has a kind (powerpoint, excel, or word). The program's first word must match it: slide {, sheet {, or document {. A locator is a handle from the latest read, such as sl_…, ws_…, or bk_…, optionally narrowed by an A1 window (ws_…!A1:H40, sh_…!A1:D10) or extended to a span (bk_…..bk_…). The live_documents vocabulary topic lists which locators each host accepts for each tool.

The normal sequence is list_live_documents → read_live_document → describe_authoring_vocabulary (before the first write) → optional inspection or rendering → author_live_document. Reuse the latest sessionId, connectionGeneration, and artifact version returned by any successful tool call. Observation calls can recover newer truth. A write is rejected when the expected version is no longer current.

Read and inspection limits#

• read_deck accepts up to ten selected saved-deck slide IDs.
• render_slides and render_live_document accept up to four targets.
• read_live_document and inspect_live_objects accept up to ten locators.
• An Excel read returns at most 20,000 cells; an Excel cell inspection at most 500; an Excel render at most 60 columns by 200 rows.
• Oversized PowerPoint and Word tables are inspected through an A1 cell window such as sh_…!A1:D10.
• visualDetail=atlas is available for exactly one live PowerPoint slide when close-up inspection is necessary.

Limits keep tool responses bounded for an external model. Prefer targeted reads to repeatedly requesting an entire presentation.

Authoring guarantees#

Saved-deck authoring is revision-bound. Live authoring performs a fresh Office capture and compare-and-swap immediately before mutation. Validation failures, preflight rejections, and live version conflicts produce zero mutation; a failed commit is reported as applied: false only when a fresh document fingerprint proves nothing changed.

For author_live_document, treat applied: true as terminal success and settlement_unknown as non-retryable until current document truth has been read. This prevents a duplicate mutation when the result is uncertain.

Scope-dependent tool discovery#

The decks:edit OAuth permission exposes the six saved-deck tools and the shared describe_authoring_vocabulary and read_user_skill tools. The separate live-documents:edit permission enables the five live document tools for PowerPoint, Excel, and Word. A live tool still needs an active add-in sharing session after authorization.

If the expected tools are missing, reconnect and approve the required scope, then follow Troubleshooting.