You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -132,49 +130,31 @@ Install the SDK, create a client, and wire up an agentic loop.
132
130
133
131
result = choose_tools(
134
132
provider="openai",
135
-
mode="essential",
136
-
groups=["comments"],
137
133
)
138
134
tools = result["tools"]
139
135
```
140
136
</Tab>
141
137
</Tabs>
142
138
143
-
### Essential mode (default)
139
+
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.
144
140
145
-
Returns 5 essential tools plus `discover_tools` — a meta-tool that lets the LLM load more groups on demand. This keeps the initial context small while giving the model access to the full toolkit when needed.
141
+
## Current tool set
146
142
147
-
The 5 essential tools:
143
+
The generated catalog currently contains 9 grouped intent tools:
148
144
149
-
| Tool | What it does |
150
-
| --- | --- |
151
-
|`get_document_text`| Returns the full plain-text content of the document |
152
-
|`query_match`| Searches by node type, text pattern, or both — returns matches with addresses |
153
-
|`apply_mutations`| Batch edit: rewrite, insert, delete text and apply formatting in one call |
154
-
|`get_node_by_id`| Get details about a specific node by its address |
155
-
|`undo`| Undo the last operation |
156
-
157
-
If you pass `groups`, those groups are loaded **in addition** to the essential set:
158
-
159
-
```typescript
160
-
// Essential tools + all comment tools
161
-
const { tools } =awaitchooseTools({
162
-
provider: 'openai',
163
-
groups: ['comments'],
164
-
});
165
-
```
166
-
167
-
### All mode
168
-
169
-
Returns every tool from the requested groups (or all groups if `groups` is omitted). The `core` group is always included.
170
-
171
-
```typescript
172
-
const { tools } =awaitchooseTools({
173
-
provider: 'openai',
174
-
mode: 'all',
175
-
groups: ['core', 'format', 'comments'],
176
-
});
177
-
```
145
+
| Tool | Actions | What it does |
146
+
| --- | --- | --- |
147
+
|`superdoc_get_content`|`text`, `markdown`, `html`, `info`| Read document content in different formats |
148
+
|`superdoc_search`|`match`| Find text or nodes and return handles or addresses for later edits |
149
+
|`superdoc_edit`|`insert`, `replace`, `delete`, `undo`, `redo`| Perform text edits and history actions |
The dispatcher validates required parameters, enforces mutual exclusivity constraints, and throws descriptive errors if arguments are invalid — so the LLM gets actionable feedback.
208
188
209
-
## Tool groups
210
-
211
-
Tools are organized into 11 groups. In essential mode, the LLM can load any group dynamically via `discover_tools`.
|`lists`| Bullet and numbered lists, indentation, list type conversion |
221
-
|`comments`| Create, edit, delete, resolve, and list comment threads |
222
-
|`trackChanges`| List, inspect, accept, and reject tracked changes |
223
-
|`toc`| Table of contents — create, configure, refresh |
224
-
|`history`| Undo and redo |
225
-
|`session`| Open, save, close, and manage document sessions |
226
-
227
-
## The discover_tools pattern
228
-
229
-
When the LLM needs tools beyond the essential set, it calls `discover_tools` with the groups it wants. Since `discover_tools` is a meta-tool (not a document operation), intercept it before `dispatchSuperDocTool` and handle it client-side via `chooseTools`:
230
-
231
-
```typescript
232
-
import { chooseTools } from'@superdoc-dev/sdk';
233
-
234
-
for (const call ofmessage.tool_calls) {
235
-
let result;
236
-
const args =JSON.parse(call.function.arguments);
237
-
238
-
if (call.function.name==='discover_tools') {
239
-
// Meta-tool — resolve client-side, then merge new tools
Each provider gets tool definitions in its native format.
@@ -284,79 +219,69 @@ Each provider gets tool definitions in its native format.
284
219
285
220
## Best practices
286
221
287
-
### Start with essential mode
222
+
### Start with the full grouped set
288
223
289
-
Load only the 5 essential tools plus `discover_tools`. This keeps the context window small and gives the model room to reason. Let it call `discover_tools` when it needs more — don't front-load every group.
224
+
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.
290
225
291
226
### Minimize tool calls
292
227
293
-
A typical edit should take 3–5 tool calls: query, mutate, done. Instruct the LLM to plan all edits before calling tools, and to batch multiple changes into a single `apply_mutations` call when possible.
228
+
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.
294
229
295
-
### Use `apply_mutations` for text edits
230
+
### Read first, then search before editing
296
231
297
-
`apply_mutations` can rewrite, insert, delete, and format text in one call. It supports multiple steps, so the LLM can edit several paragraphs at once. Use it for any operation on existing text.
232
+
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`.
233
+
234
+
### Prefer focused tools; use `superdoc_mutations` as an escape hatch
235
+
236
+
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.
298
237
299
238
### Feed errors back to the model
300
239
301
-
`dispatchSuperDocTool`throws descriptive errors with codes like `MATCH_NOT_FOUND` or `INVALID_ARGUMENT`. Pass these back as tool results — most models self-correct on the next turn.
240
+
`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.
302
241
303
242
### Add tool call examples for repeatable actions
304
243
305
244
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.
306
245
307
246
### Include a system prompt
308
247
309
-
Tell the model what it can do and how to approach edits. Here's an example:
248
+
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:
310
249
311
250
````markdown
312
-
You edit `.docx` files using SuperDoc tools. Be efficient — minimize tool calls.
251
+
You edit `.docx` files using SuperDoc intent tools. Be efficient and minimize tool calls.
313
252
314
253
## Workflow
315
254
316
-
1.**Query** — Call `query_match` to find text you want to edit.
317
-
Use `require: "any"` to match broadly.
318
-
2.**Plan** — Decide what changes to make. Think through all
319
-
edits before making tool calls.
320
-
3.**Mutate** — Call `apply_mutations` to rewrite, insert, delete,
321
-
or format text.
322
-
323
-
Keep it to 3–5 tool calls total.
324
-
325
-
## Tools
326
-
327
-
You start with 5 essential tools plus `discover_tools`.
328
-
Call `discover_tools` to load additional categories when needed:
255
+
1.**Read** — Use `superdoc_get_content` to understand the document.
256
+
2.**Search** — Use `superdoc_search` to find stable handles or block addresses.
257
+
3.**Edit** — Use the focused tool that matches the job:
258
+
-`superdoc_edit` for insert, replace, delete, undo, redo
259
+
-`superdoc_format` for inline or paragraph formatting
260
+
-`superdoc_create` for paragraphs and headings
261
+
-`superdoc_comment` for comment threads
262
+
-`superdoc_track_changes` for review decisions
263
+
4.**Batch only when useful** — Use `superdoc_mutations` for preview/apply or atomic multi-step edits.
329
264
330
-
| Category | What it covers |
331
-
|----------|----------------|
332
-
| core | Read nodes, get text, query, mutations |
333
-
| format | Text formatting, alignment, spacing, borders |
0 commit comments