> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Core preset — the action surface

> Two tools, forty deterministic actions: inspect a document, then edit it with named, verifiable operations — including tracked-changes redlining.

The `core` preset is an **actions-only LLM surface**: instead of many low-level tools, the model gets exactly two —

| Tool | Role |
| - | - |
| `superdoc_inspect` | Read: a deterministic snapshot of the document (blocks, lists, tables, comments, tracked changes, …) |
| `superdoc_perform_action` | Write: one of **40 named actions** with flat, validated arguments and a verifiable receipt |

Every action wraps the underlying [Document API](https://docs.superdoc.dev/document-api/overview.md) operations with product semantics: it resolves targets deterministically, applies the edit, re-inspects the document, and returns a **receipt** with real pre/post evidence — so your agent loop (and your users) can trust what actually happened.

The default preset is still `legacy` (the grouped intent tools documented in the [overview](https://docs.superdoc.dev/ai/agents/llm-tools.md)). The core preset is opt-in: pass `preset: 'core'` everywhere.

## Quick start

> [tab] Node.js
>
> ```typescript theme={null}
> import { createSuperDocClient, createAgentToolkit, type AgentReceipt } from '@superdoc-dev/sdk';
>
> const client = createSuperDocClient();
> await client.connect();
> const doc = await client.open({ doc: './contract.docx' });
>
> // One call — tools, system prompt, and a pre-bound dispatcher that are
> // guaranteed to agree on preset and exclusions.
> const { tools, systemPrompt, dispatch } = await createAgentToolkit({
>   provider: 'openai',
>   preset: 'core',
> });
>
> // ... run your agent loop (see the overview page) ...
> const receipt = (await dispatch(doc, 'superdoc_perform_action', {
>   action: 'replace_text',
>   edits: [{ find: 'thirty (30) days', replace: 'sixty (60) days' }],
>   changeMode: 'tracked',
> })) as AgentReceipt;
>
> console.log(receipt.status, receipt.verificationPassed);
> ```

> [tab] Python
>
> ```python theme={null}
> from superdoc import SuperDocClient, create_agent_toolkit
>
> client = SuperDocClient()
> client.connect()
> doc = client.open({"doc": "./contract.docx"})
>
> # One call — tools, system prompt, and pre-bound dispatchers that are
> # guaranteed to agree on preset and exclusions.
> kit = create_agent_toolkit({"provider": "openai", "preset": "core"})
> tools, system_prompt = kit["tools"], kit["system_prompt"]
>
> receipt = kit["dispatch"](
>     doc,
>     "superdoc_perform_action",
>     {
>         "action": "replace_text",
>         "edits": [{"find": "thirty (30) days", "replace": "sixty (60) days"}],
>         "changeMode": "tracked",
>     },
> )
> print(receipt["status"], receipt.get("verificationPassed"))
> ```

> [!WARNING]
>
> Tools, system prompt, and dispatch must all come from the **same preset** — the legacy dispatcher does not know `superdoc_perform_action` and fails with `Unknown tool`. `createAgentToolkit` guarantees this; if you use the standalone functions (`chooseTools`, `getSystemPrompt`, `dispatchSuperDocTool`) instead, pass the same `preset` (and `excludeActions`) to every call.

## Reading: `superdoc_inspect`

`superdoc_inspect` returns a stable snapshot the model can target edits against. Prefer the **narrowest** inspect that answers the question:

```jsonc theme={null}
// counts only — cheapest possible orientation call
{ "countsOnly": true }

// just the lists and tables
{ "includeDomains": ["lists", "tables"] }

// only headings
{ "includeDomains": ["blocks"], "blockNodeTypes": ["heading"] }
```

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

### Large documents: windowed reads

For long documents, read blocks in contiguous windows instead of one giant snapshot. Ordinals are **absolute**, so windows line up across calls:

```jsonc theme={null}
{ "includeDomains": ["blocks"], "blockOffset": 0,   "blockLimit": 200 }
{ "includeDomains": ["blocks"], "blockOffset": 200, "blockLimit": 200, "omitEmptyBlocks": true, "dropTextPreview": true }
```

`omitEmptyBlocks` and `dropTextPreview` trim the payload for a pure reading pass; `blockTextLimit` caps per-block text length. This keeps a single inspect call from dominating your context window (every tool result lives in conversation history and is re-billed as prompt tokens on every later turn).

> [!NOTE]
>
> All ordinals shown by `superdoc_inspect` (`blockOrdinal`, `paragraphOrdinal`, `headingOrdinal`, `tableOrdinal`, …) are **1-based**, and selectors accept the same 1-based values.

## Editing: `superdoc_perform_action`

One tool, one `action` argument, flat parameters. The dispatcher statically validates arguments against the action's declared schema (unknown keys are rejected with a descriptive error) before anything touches the document.

### Targeting: selectors

Actions that operate on a specific block accept a `selector`:

| Selector | Shape | Use when |
| - | - | - |
| Node id | `{kind:"nodeId", nodeId}` | You have a `nodeId` from `superdoc_inspect` (most precise) |
| Ordinal | `{kind:"ordinal", ordinalKind:"paragraphOrdinal"\|"headingOrdinal"\|"tableOrdinal"\|"listOrdinal"\|"sectionOrdinal"\|"bodyParagraphOrdinal"\|"blockOrdinal", value:N}` | "the 3rd paragraph", "the 2nd table" (1-based) |
| Text search | `{kind:"textSearch", terms:[...], match?:"all"\|"any", occurrence?:N, nodeTypes?:[...]}` | You know the text but not the position |
| Table cell | `{kind:"tableCell", tableOrdinal, rowIndex, columnIndex}` | Cell-scoped edits |
| Relative | `{kind:"relative", position:"after"\|"before", target:selector}` | "the paragraph after the heading X" |

### Placement

Insert-style actions accept a `placement`:

```jsonc theme={null}
{ "at": "document_end" }
{ "at": "document_start" }
{ "at": "after",  "selector": { "kind": "textSearch", "terms": ["Definitions"] } }
{ "at": "before", "selector": { "kind": "nodeId", "nodeId": "p42" } }
```

### Tracked changes: `changeMode`

Most mutating actions accept `changeMode: "tracked"`. In tracked mode the edit is recorded as a **redline suggestion** — a tracked insert/delete/format change the user (or the model) can accept or reject later — instead of being applied directly. This is the backbone of review workflows:

> [tab] Suggest (tracked)
>
> ```jsonc theme={null}
> {
>   "action": "rewrite_block",
>   "selector": { "kind": "ordinal", "ordinalKind": "paragraphOrdinal", "value": 4 },
>   "text": "Either party may terminate this Agreement on sixty (60) days' written notice.",
>   "changeMode": "tracked"
> }
> ```

> [tab] Apply directly
>
> ```jsonc theme={null}
> {
>   "action": "rewrite_block",
>   "selector": { "kind": "ordinal", "ordinalKind": "paragraphOrdinal", "value": 4 },
>   "text": "Either party may terminate this Agreement on sixty (60) days' written notice."
> }
> ```

A "suggest vs. apply directly" toggle in your chat UI maps 1:1 to setting `changeMode` on every mutating call. Review then happens with the same action surface:

* `accept_tracked_changes` / `reject_tracked_changes` — optionally filtered by `author` or `changeType` (`insert` | `delete` | `replacement` | `format`)
* `undo_changes` / `redo_changes` — deterministic history recovery (`untilMarker` restores until a rendered clause marker like `"2.1."` reappears)

A few actions are **always direct** (not tracked) and say so in their reference entry: `move_range`, `split_list`, `set_paragraph_spacing`, `insert_page_break`, `add_hyperlink`, `style_table`. Requesting `changeMode:"tracked"` on `move_range` fails with nothing changed — use `move_text` for tracked text-span moves.

### Receipts

Every action returns a receipt — not just "ok", but evidence:

```jsonc theme={null}
{
  "status": "ok",                    // "ok" | "partial" | "failed"
  "intent": "replace_text",
  "preSnapshot":  { "revision": "41", "counts": { "paragraphs": 58, "trackedChanges": 0 } },
  "postSnapshot": { "revision": "42", "counts": { "paragraphs": 58, "trackedChanges": 2 } },
  "verification": [
    { "check": { "kind": "text-replaced", "find": "thirty (30) days" }, "passed": true }
  ],
  "verificationPassed": true,
  "editsApplied": 2
}
```

What to rely on:

* **`status`** — `partial` means some of the requested work landed (the receipt says which part); `failed` means nothing changed unless the receipt explicitly says otherwise.
* **`verification`** — post-edit checks the action ran against a fresh snapshot (counts deltas, placement adjacency, text presence). `verificationPassed` is the roll-up.
* **`errors[]`** — failures carry a `code`, a human-readable `message` written for the model to act on, and often a structured `recovery` (`{kind: "reinspect" | "retry" | "revert", call?}`) plus a paste-ready `revertHint`.
* **`formattingMatched`** — insert actions that blend new content into its surroundings (e.g. `add_list_items`) report the font/size/style they copied from neighbors, so the model knows not to re-format.
* **List caps** — long per-item lists (`executedOperations`, `selectedTargets`) are capped at 8 entries with a `*Count` field preserving the true total, to keep receipts from bloating your conversation history.

### Action reference

Forty actions, grouped. Arguments marked `?` are optional; most mutating actions also accept `changeMode`.

#### Text & structure

| Action | Arguments | Notes |
| - | - | - |
| `insert_paragraphs` | `texts[]` (or `text`), `placement?`, `headingLevel?` | First item can become a heading (1–6) |
| `insert_heading` | `text`, `level`, `placement?` | |
| `replace_text` | `edits[{find, replace}]`, `selector?`, `caseSensitive?` | Selector scopes all edits to one block |
| `delete_text` | `finds[]`, `selector?`, `caseSensitive?` | Scope with `selector` to delete stray whitespace safely |
| `append_list` | `items[]`, `kind?: ordered\|bullet`, `headingText?`, `placement?` | With `placement`, builds the list at that block instead of document end |
| `create_table` | `rows`, `columns`, `cellTexts?`, `placement?` | Tracked mode makes the whole insertion one tracked change |
| `rewrite_block` | `selector`, `text` | Replaces a block's text; tracked mode produces a redline |
| `fill_placeholders` | `values[]` and/or `fields[{label?, value}]` | Fills template placeholders |
| `move_range` | `fromText`, `toText?`, `afterText` or `beforeText` | Moves a block range or visual "section" identified by text. Auto-extends to the section end when `toText` is omitted. Direct-only: `changeMode:"tracked"` is refused with nothing changed (use `move_text` for tracked moves). Also refuses reversed ranges and ranges containing tables/lists/images — move those with `move_table` or narrow the range |

#### Lists & numbering

| Action | Arguments | Notes |
| - | - | - |
| `convert_list` | `kind`, one of: `listOrdinal?`/`anchorText?`, `fromMarker`+`toMarker`, `fromText`+`toText` | Converts lists, rendered clause ranges ("2.1."–"2.3."), or plain paragraphs to a list **in place** |
| `attach_numbering` | `anchorText` or `nodeId`, `likeMarker` | Numbers a block at the same scheme/level as the sibling rendering `likeMarker` (e.g. `"10."`); tracked mode records the former state |
| `add_list_items` | `anchorText` + `entries[{text, level?}]` | **The** way to add items into an existing list. `level` is relative to the anchor (0 same, positive nests, negative promotes — e.g. `-1` from item "12(e)" creates top-level item 13). Inherits the anchor's look automatically |
| `split_list` | `anchorText`, `restartNumbering?` (default true) | Splits one list into two at an item. Direct edit |

#### History

| Action | Arguments | Notes |
| - | - | - |
| `undo_changes` | `untilMarker?`, `steps?` (1–25) | Steps history back until the marker reappears — deterministic revert |
| `redo_changes` | `steps?` (default 1) | Re-applies edits after an undo overshot. Only valid before any new edit |

#### Moving text

| Action | Arguments | Notes |
| - | - | - |
| `move_text` | `text`, `afterText?` | Direct by default (requires `afterText`). `changeMode:"tracked"` records the move as a redline: tracked delete at the source + tracked insert at the destination — accept keeps the move, reject restores the original order |

#### Comments

| Action | Arguments | Notes |
| - | - | - |
| `comment_paragraphs` | `commentText`, `scope?: all\|body`, `excludeBlockQuotes?` | One comment per paragraph |
| `add_comments` | `commentText`, `selector` or `selectors[]` | Batch many targets into `selectors[]` in ONE call |
| `resolve_comments` | `anchorText?`, `reopen?` | Omit `anchorText` to resolve all open comments |
| `reply_to_comment` | `commentText`, `anchorText` or `commentId` | Adds a **threaded** reply, not a new top-level comment |

#### Tracked-change review

| Action | Arguments | Notes |
| - | - | - |
| `accept_tracked_changes` | `author?`, `changeType?` | e.g. `changeType:"format"` accepts only formatting revisions |
| `reject_tracked_changes` | `author?`, `changeType?` | |

#### Formatting

| Action | Arguments | Notes |
| - | - | - |
| `format_text` | `bold?`/`italic?`/`underline?`/`strike?`, `highlight?`, `color?`, `fontSize?`, `targetText`/`targetTexts[]`/`selector`, `caseSensitive?` | Applies to every occurrence; tracked-safe |
| `apply_style` | `selector`, one of `styleId`, `headingLevel`, `likeText` | `likeText` copies another block's style **and** effective look |
| `format_paragraph` | `selector`, `alignment` | Tracked mode records the former alignment (`w:pPrChange`) |
| `set_paragraph_spacing` | `selector`, `lineSpacing?`, `spaceBefore?`, `spaceAfter?` | Never insert blank paragraphs for spacing. Direct edit |
| `normalize_body_font_size` | `fontSize` | Whole-body font size |
| `set_font_family` | `fontFamily`, `selector?` or `targetText`/`targetTexts[]?` | Omit both to set the whole body typeface |
| `apply_letter_spacing` | `selector`, `letterSpacing` | |

#### Layout, links, media

| Action | Arguments | Notes |
| - | - | - |
| `insert_page_break` | `selector` | Sets `pageBreakBefore` on the block — never pushes content with empty paragraphs. Direct edit |
| `add_hyperlink` | `text`, `url`, `tooltip?` | Turns existing text into a link. Direct edit |
| `insert_toc` | `title?`, `placement?` | Table of contents |

#### Tables

| Action | Arguments | Notes |
| - | - | - |
| `style_table` | `tableOrdinal?`, `accentColor?` | Professional look in one call: accent header, bold labels, banded rows. Direct edit |
| `move_table` | `tableOrdinal?`, `placement` | Moves the whole table with all content in one call |
| `delete_table` | `tableOrdinal?` | Deletes an entire table |
| `insert_table_row` | `tableOrdinal?`, `rowIndex?`, `position?`, `cellTexts?`, `dryRun?` | |
| `insert_table_column` | `tableOrdinal?`, `columnIndex?`, `position?`, `headerText?` | |
| `delete_table_row` | `tableOrdinal?`, `rowIndex` | |
| `delete_table_column` | `tableOrdinal?`, `columnIndex` | |
| `split_table` | `tableOrdinal?`, `rowIndex`, `separatorText?` | |

## Narrowing the surface: `excludeActions`

Hide actions you don't want the model to see. The exclusion narrows **everything coherently**: the `action` enum, the argument schema, the per-action documentation lines in the system prompt, and the dispatch guard (an excluded action is refused even if the model guesses its name).

The safest way to use it is `createAgentToolkit` — one options object, all three surfaces guaranteed to agree:

```typescript theme={null}
const { tools, systemPrompt, dispatch } = await createAgentToolkit({
  provider: 'anthropic',
  preset: 'core',
  excludeActions: ['delete_table', 'fill_placeholders'],
});
```

With the standalone functions, pass the same list everywhere:

> [tab] Node.js
>
> ```typescript theme={null}
> const { tools } = await chooseTools({
>   provider: 'anthropic',
>   preset: 'core',
>   excludeActions: ['delete_table', 'fill_placeholders'],
> });
> const prompt = await getSystemPrompt('core', { excludeActions: ['delete_table', 'fill_placeholders'] });
>
> // Defense in depth: pass the same list at dispatch time.
> await dispatchSuperDocTool(doc, name, args, {
>   preset: 'core',
>   excludeActions: ['delete_table', 'fill_placeholders'],
> });
> ```

> [tab] Python
>
> ```python theme={null}
> tools = choose_tools({
>     "provider": "anthropic",
>     "preset": "core",
>     "excludeActions": ["delete_table", "fill_placeholders"],
> })["tools"]
> prompt = get_system_prompt("core", exclude_actions=["delete_table", "fill_placeholders"])
>
> dispatch_superdoc_tool(doc, name, args, preset="core",
>                        exclude_actions=["delete_table", "fill_placeholders"])
> ```

> [tab] CLI
>
> ```bash theme={null}
> superdoc preset get-tools --preset core --provider anthropic \
>   --excludeActions delete_table,fill_placeholders
> superdoc preset get-system-prompt --preset core \
>   --excludeActions delete_table,fill_placeholders
> ```

Unknown action names in the list throw immediately (typo protection). The legacy preset ignores exclusion options entirely.

## The system prompt

`getSystemPrompt('core')` returns the prompt the action surface was **evaluated with**: document-model vocabulary (visual sections, rendered markers, effective formatting), the full per-action argument documentation, targeting conventions, tracked-changes rules, and receipt-reading discipline (trust the receipt, re-inspect on `partial`, use `revertHint` on failures).

* **Use it as-is** for the best out-of-the-box behavior — the eval suite scores this exact prompt.
* **Extend it** by appending your domain instructions (tone, house style, what to never touch) at the end.
* **Replacing it entirely is not recommended**: the per-action lines teach argument shapes the schema alone can't convey. If you do, keep the action documentation block.

## Creating custom actions

Use `defineAction` to add a named action with built-in `steps` or a native `run` function. `createAgentToolkit` keeps the resulting tool schema, system prompt, and dispatcher aligned. See [Custom actions](https://docs.superdoc.dev/ai/agents/custom-actions.md) for the SDK workflow and the optional coding-agent skill.

## Over MCP

The core preset is also available through the SuperDoc MCP server: start it with `MCP_PRESET=core` and clients get the session lifecycle tools (`superdoc_open` / `superdoc_save` / `superdoc_close`) plus `superdoc_inspect` and `superdoc_perform_action`, registered from the same catalog `chooseTools()` serves — the MCP surface cannot drift from the SDK surface. Server instructions use the core MCP prompt automatically.

## Experimental: `superdoc_execute_code`

The SDK can dispatch a third tool, `superdoc_execute_code` (model-authored JavaScript against a synchronous in-process Document API). It is **work-in-progress and deliberately not advertised**: it is absent from `chooseTools()` results and from the served system prompt, and its behavior may change. It will ship behind an explicit safety flag in a future release. Don't build on it yet.

## Related

* [Overview & agent loops](https://docs.superdoc.dev/ai/agents/llm-tools.md): providers, token budget, error codes, troubleshooting
* [Best practices](https://docs.superdoc.dev/ai/agents/best-practices.md)
* [Document API](https://docs.superdoc.dev/document-api/overview.md): the operations the actions wrap


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.