LLM Tools

Give LLMs structured access to document operations with provider-ready tool definitions and dispatch

The SuperDoc SDK ships tool definitions that plug directly into OpenAI, Anthropic, Vercel AI, or any custom LLM integration. Pick tools, send them with your prompt, dispatch the model’s tool calls — the SDK handles schema formatting, argument validation, and execution.

LLM tools are in alpha. Tool names and schemas may change between releases.

Quick start

Install the SDK, create a client, and wire up an agentic loop.

Node.js

npm install @superdoc-dev/sdk openai

import { createSuperDocClient, chooseTools, dispatchSuperDocTool } from '@superdoc-dev/sdk';
import OpenAI from 'openai';

const client = createSuperDocClient();
await client.connect();
await client.doc.open({ doc: './contract.docx' });

const { tools } = await chooseTools({ provider: 'openai' });
const openai = new OpenAI();

const messages = [
  { role: 'system', content: 'You edit documents using the provided tools.' },
  { role: 'user', content: 'Find the termination clause and rewrite it to allow 30-day notice.' },
];

// Agentic loop
while (true) {
  const response = await openai.chat.completions.create({
    model: 'gpt-5.2',
    messages,
    tools,
  });

  const message = response.choices[0].message;
  messages.push(message);

  if (!message.tool_calls?.length) break;

  for (const call of message.tool_calls) {
    const result = await dispatchSuperDocTool(
      client, call.function.name, JSON.parse(call.function.arguments),
    );
    messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(result) });
  }
}

await client.doc.save({ inPlace: true });
await client.dispose();

Python

pip install superdoc-sdk openai

from superdoc import SuperDocClient, choose_tools, dispatch_superdoc_tool
import openai, json

client = SuperDocClient()
client.connect()
client.doc.open(doc="./contract.docx")

result = choose_tools(provider="openai")
tools = result["tools"]

messages = [
    {"role": "system", "content": "You edit documents using the provided tools."},
    {"role": "user", "content": "Find the termination clause and rewrite it to allow 30-day notice."},
]

while True:
    response = openai.chat.completions.create(
        model="gpt-5.2", messages=messages, tools=tools
    )
    message = response.choices[0].message
    messages.append(message)

    if not message.tool_calls:
        break

    for call in message.tool_calls:
        result = dispatch_superdoc_tool(
            client, call.function.name, json.loads(call.function.arguments)
        )
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

client.doc.save(in_place=True)
client.dispose()

Tool selection

chooseTools() returns provider-formatted tool definitions ready to pass to your LLM.

Node.js

import { chooseTools } from '@superdoc-dev/sdk';

const { tools, meta } = await chooseTools({
  provider: 'openai',   // 'openai' | 'anthropic' | 'vercel' | 'generic'
});

Python

from superdoc import choose_tools

result = choose_tools(
    provider="openai",
)
tools = result["tools"]

The current SDK returns the full grouped intent tool set for the selected provider. Group filtering and meta-discovery are not part of the shipped public API here.

Current tool set

The generated catalog currently contains 9 grouped intent tools:

Tool	Actions	What it does
superdoc_get_content	text, markdown, html, info	Read document content in different formats
superdoc_search	match	Find text or nodes and return handles or addresses for later edits
superdoc_edit	insert, replace, delete, undo, redo	Perform text edits and history actions
superdoc_format	inline, set_style, set_alignment, set_indentation, set_spacing	Apply inline or paragraph formatting
superdoc_create	paragraph, heading	Create structural block elements
superdoc_list	insert, create, detach, indent, outdent, set_level, set_type	Create and manipulate lists
superdoc_comment	create, update, delete, get, list	Manage comment threads
superdoc_track_changes	list, decide	Review and resolve tracked changes
superdoc_mutations	preview, apply	Execute multi-step atomic edits as a batch

Multi-action tools use an action argument to select the underlying operation. Single-action tools like superdoc_search do not require action.

Dispatching tool calls

dispatchSuperDocTool() resolves a tool name to the correct SDK method, validates arguments, and executes the call.

Node.js

import { dispatchSuperDocTool } from '@superdoc-dev/sdk';

const result = await dispatchSuperDocTool(client, toolName, args);

Python (sync)

from superdoc import dispatch_superdoc_tool

result = dispatch_superdoc_tool(client, tool_name, args)

Python (async)

from superdoc import dispatch_superdoc_tool_async

result = await dispatch_superdoc_tool_async(client, tool_name, args)

The dispatcher validates required parameters, enforces mutual exclusivity constraints, and throws descriptive errors if arguments are invalid — so the LLM gets actionable feedback.

Providers

Each provider gets tool definitions in its native format.

OpenAI

const { tools } = await chooseTools({ provider: 'openai' });
// [{ type: 'function', function: { name, description, parameters } }]

Anthropic

const { tools } = await chooseTools({ provider: 'anthropic' });
// [{ name, description, input_schema }]

Vercel AI

const { tools } = await chooseTools({ provider: 'vercel' });
// [{ type: 'function', function: { name, description, parameters } }]

Generic

const { tools } = await chooseTools({ provider: 'generic' });
// [{ name, description, parameters, returns, metadata }]

Best practices

Start with the full grouped set

The current catalog is intentionally small. In most integrations you should load the full grouped set once and let the model choose among the 9 tools.

Minimize tool calls

A typical edit should take 3-5 tool calls: read, search, mutate, done. Instruct the LLM to plan all edits before calling tools, and to batch multiple changes only when atomic execution is genuinely helpful.

Read first, then search before editing

Use superdoc_get_content to understand the document, then superdoc_search to obtain stable handles or addresses. Pass those targets into superdoc_edit, superdoc_format, superdoc_create, superdoc_list, or superdoc_comment.

Prefer focused tools; use superdoc_mutations as an escape hatch

Use the focused intent tools for straightforward edits. Reach for superdoc_mutations when you need preview/apply semantics, atomic multi-step edits, or a batched workflow that would otherwise require several target refreshes.

Feed errors back to the model

dispatchSuperDocTool surfaces structured errors from the underlying SDK and Document API. Pass these back as tool results — most models self-correct on the next turn.

Add tool call examples for repeatable actions

If your workflow involves the same kind of edit across many documents (e.g., always rewriting a specific clause, always adding a comment to a section), include a concrete tool call example in your system prompt. Models that see a working example of the exact tool invocation produce correct calls more reliably than models that only see the schema.

Include a system prompt

Tell the model what it can do and how to approach edits. You can load the bundled prompt with getSystemPrompt(), or start with something like this:

You edit `.docx` files using SuperDoc intent tools. Be efficient and minimize tool calls.

## Workflow

1. **Read** — Use `superdoc_get_content` to understand the document.
2. **Search** — Use `superdoc_search` to find stable handles or block addresses.
3. **Edit** — Use the focused tool that matches the job:
   - `superdoc_edit` for insert, replace, delete, undo, redo
   - `superdoc_format` for inline or paragraph formatting
   - `superdoc_create` for paragraphs and headings
   - `superdoc_comment` for comment threads
   - `superdoc_track_changes` for review decisions
4. **Batch only when useful** — Use `superdoc_mutations` for preview/apply or atomic multi-step edits.

Keep it to 3-5 tool calls total when possible.

## Rules

- Search before mutating so targets come from fresh results.
- Use focused intent tools for normal edits.
- Use `superdoc_mutations` when you need an atomic batch or preview/apply flow.
- Set `changeMode: "tracked"` when edits need human review.
- Feed tool errors back to the model so it can recover.

Utility functions

Function	Description
chooseTools(input)	Load grouped tool definitions for a provider
dispatchSuperDocTool(client, name, args)	Execute a tool call against a connected client
listTools(provider)	List all tool definitions for a provider
getToolCatalog()	Load the full tool catalog with metadata
getSystemPrompt()	Read the bundled system prompt for intent tools

Related

• MCP Server — connect AI agents via the Model Context Protocol
• Skills — reusable prompt templates for LLM document editing
• SDKs — typed Node.js and Python wrappers
• Document API — the operation set behind the tools
• AI Agents — headless mode for server-side AI workflows