Core preset — the action surface

​

Quick start

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);

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"))

​

Reading: superdoc_inspect

// counts only — cheapest possible orientation call
{ "countsOnly": true }

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

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

​

Large documents: windowed reads

{ "includeDomains": ["blocks"], "blockOffset": 0,   "blockLimit": 200 }
{ "includeDomains": ["blocks"], "blockOffset": 200, "blockLimit": 200, "omitEmptyBlocks": true, "dropTextPreview": true }

​

Editing: superdoc_perform_action

​

Targeting: selectors

​

Placement

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

​

Tracked changes: changeMode

{
  "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"
}

{
  "action": "rewrite_block",
  "selector": { "kind": "ordinal", "ordinalKind": "paragraphOrdinal", "value": 4 },
  "text": "Either party may terminate this Agreement on sixty (60) days' written notice."
}

• 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)

​

Receipts

{
  "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
}

• 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

​

Text & structure

​

Lists & numbering

​

History

​

Moving text

​

Comments

​

Tracked-change review

​

Formatting

​

Layout, links, media

​

Tables

​

Narrowing the surface: excludeActions

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

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'],
});

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"])

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

​

The system prompt

• 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

​

Over MCP

​

Experimental: superdoc_execute_code

​

Related

• Overview & agent loops: providers, token budget, error codes, troubleshooting
• Best practices
• Document API: the operations the actions wrap