Core action reference

The core preset advertises two tools. superdoc_inspect reads a deterministic snapshot. superdoc_perform_action runs one named action with flat arguments and returns a receipt. This page documents both from the action registry in @superdoc/sdk, and the same definitions are served over MCP under MCP_PRESET=core.

The registry changes across SDK releases without changing the preset id. Pin the SDK version when your integration depends on a specific action set, and read the advertised schema after upgrading:

import { getToolCatalog } from '@superdoc/sdk';

const catalog = await getToolCatalog('core');
const performAction = catalog.tools.find((tool) => tool.toolName === 'superdoc_perform_action');
console.log(performAction?.inputSchema);

superdoc_inspect

Every argument is optional. Prefer the narrowest call that answers the question, because the result lives in conversation history for the rest of the run.

Domains: blocks, lists, tables, comments, trackedChanges, sections, headerFooters, styles, contentControls, fields, hyperlinks, bookmarks, permissionRanges, images.

Every ordinal in a snapshot is 1-based, and selectors accept the same values. Use findText to locate a heading or phrase in a long document instead of paging through windows.

Selectors

Actions that operate on a block take a selector. Batch actions take selectors[].

ordinalKind is one of blockOrdinal, paragraphOrdinal, bodyParagraphOrdinal, headingOrdinal, listOrdinal, tableOrdinal, or sectionOrdinal. match on a text search is all or any, and nodeTypes narrows to paragraph, heading, or listItem.

Placement

Actions that insert content take a placement:

{ "at": "document_end" }
{ "at": "document_start" }
{ "at": "after", "selector": { "kind": "textSearch", "terms": ["Definitions"] } }
{ "at": "before", "selector": { "kind": "nodeId", "nodeId": "p42" } }

changeMode

Actions that accept changeMode record the edit as a tracked change when it is "tracked" and edit directly otherwise. The tool schema advertises the argument once for the whole tool, so the table below is the only place that says which actions honor it. Passing it to an action marked No looks compliant and produces a direct edit. move_range accepts the argument and then fails without mutating, because a block-range deletion cannot be tracked.

The safety guide explains why a loop that promises reviewable output must enforce this allowlist in code.

Actions

Arguments marked ? are optional. Styled text arguments (texts, cellTexts, entries) accept either a plain string or an object with runs and marks so new content can match its neighbors in the same call.

Text and structure

Lists and numbering

History

Moving text

Comments

Tracked-change review

Exclude both when a person must make the final decision. Safety shows the exclusion.

Formatting

Layout, links, and table of contents

Tables

tableOrdinal is 1-based. Omit it only when the document contains exactly one table; with several tables the action cannot resolve a target and fails. rowIndex and columnIndex are 0-based, unlike every ordinal, so rowIndex: 0 is the first row. The tableCell selector uses the same 0-based row and column indices.

Receipts

Every dispatched action returns a receipt. Reads return a snapshot instead, and argument validation throws before a receipt exists. Build an agent explains how a loop should branch on the three cases.

Actions add their own evidence, such as editsApplied and editsSkipped on replace_text, formattingMatched on inserts that copy neighboring formatting, and addedItems on add_list_items.

Verification checks include revision-changed, block-count-delta, comment-count-delta, tracked-change-count-delta, block-text-contains, table-shape, and list-item-count. The standard revision-changed check fails when a mutation turns out to be a no-op, so verificationPassed: false does not by itself say whether anything changed. Read the snapshots.

Add your own

createAgentToolkit accepts customActions, which extend this registry with named verbs of your own that dispatch through the same tool. Their receipts report succeeded rather than ok. See Custom actions.

Not advertised

The dispatcher also routes superdoc_execute_code, agent_apply, agent_verify, and agent_operation. They are for SDK callers, they are absent from the tool list and the system prompt, and a model-facing loop should refuse them. Build an agent shows the check.