@superdoc-dev/sdk 1.0.0-next.74 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,169 +3,49 @@
3
3
  "tools": [
4
4
  {
5
5
  "name": "superdoc_get_content",
6
- "description": "Read document content in various formats",
6
+ "description": "Read document content. Use action \"info\" for structure and styles, \"blocks\" for all block IDs and types, \"text\" or \"markdown\" for content. Call info or blocks before editing.",
7
7
  "parameters": {
8
8
  "type": "object",
9
9
  "properties": {
10
10
  "action": {
11
11
  "type": "string",
12
12
  "enum": [
13
+ "blocks",
13
14
  "html",
14
15
  "info",
15
16
  "markdown",
16
17
  "text"
17
18
  ],
18
- "description": "The action to perform. One of: html, info, markdown, text."
19
- },
20
- "in": {
21
- "oneOf": [
22
- {
23
- "type": "object",
24
- "properties": {
25
- "kind": {
26
- "const": "story",
27
- "type": "string"
28
- },
29
- "storyType": {
30
- "const": "body",
31
- "type": "string"
32
- }
33
- },
34
- "required": [
35
- "kind",
36
- "storyType"
37
- ]
38
- },
39
- {
40
- "type": "object",
41
- "properties": {
42
- "kind": {
43
- "const": "story",
44
- "type": "string"
45
- },
46
- "storyType": {
47
- "const": "headerFooterSlot",
48
- "type": "string"
49
- },
50
- "section": {
51
- "type": "object",
52
- "properties": {
53
- "kind": {
54
- "const": "section",
55
- "type": "string"
56
- },
57
- "sectionId": {
58
- "type": "string"
59
- }
60
- },
61
- "required": [
62
- "kind",
63
- "sectionId"
64
- ]
65
- },
66
- "headerFooterKind": {
67
- "enum": [
68
- "header",
69
- "footer"
70
- ]
71
- },
72
- "variant": {
73
- "enum": [
74
- "default",
75
- "first",
76
- "even"
77
- ]
78
- },
79
- "resolution": {
80
- "enum": [
81
- "effective",
82
- "explicit"
83
- ]
84
- },
85
- "onWrite": {
86
- "enum": [
87
- "materializeIfInherited",
88
- "editResolvedPart",
89
- "error"
90
- ]
91
- }
92
- },
93
- "required": [
94
- "kind",
95
- "storyType",
96
- "section",
97
- "headerFooterKind",
98
- "variant"
99
- ]
100
- },
101
- {
102
- "type": "object",
103
- "properties": {
104
- "kind": {
105
- "const": "story",
106
- "type": "string"
107
- },
108
- "storyType": {
109
- "const": "headerFooterPart",
110
- "type": "string"
111
- },
112
- "refId": {
113
- "type": "string"
114
- }
115
- },
116
- "required": [
117
- "kind",
118
- "storyType",
119
- "refId"
120
- ]
121
- },
122
- {
123
- "type": "object",
124
- "properties": {
125
- "kind": {
126
- "const": "story",
127
- "type": "string"
128
- },
129
- "storyType": {
130
- "const": "footnote",
131
- "type": "string"
132
- },
133
- "noteId": {
134
- "type": "string"
135
- }
136
- },
137
- "required": [
138
- "kind",
139
- "storyType",
140
- "noteId"
141
- ]
142
- },
143
- {
144
- "type": "object",
145
- "properties": {
146
- "kind": {
147
- "const": "story",
148
- "type": "string"
149
- },
150
- "storyType": {
151
- "const": "endnote",
152
- "type": "string"
153
- },
154
- "noteId": {
155
- "type": "string"
156
- }
157
- },
158
- "required": [
159
- "kind",
160
- "storyType",
161
- "noteId"
162
- ]
163
- }
164
- ]
19
+ "description": "The action to perform. One of: blocks, html, info, markdown, text."
165
20
  },
166
21
  "unflattenLists": {
167
22
  "type": "boolean",
168
- "description": "When true, flattens nested list structures in output. Default: false."
23
+ "description": "When true, flattens nested list structures in output. Default: false. Only for action 'html'. Omit for other actions."
24
+ },
25
+ "offset": {
26
+ "type": "number",
27
+ "description": "Number of blocks to skip. Default: 0. Only for action 'blocks'. Omit for other actions."
28
+ },
29
+ "limit": {
30
+ "type": "number",
31
+ "description": "Maximum blocks to return. Omit for all blocks. Only for action 'blocks'. Omit for other actions."
32
+ },
33
+ "nodeTypes": {
34
+ "type": "array",
35
+ "items": {
36
+ "enum": [
37
+ "paragraph",
38
+ "heading",
39
+ "listItem",
40
+ "table",
41
+ "tableRow",
42
+ "tableCell",
43
+ "tableOfContents",
44
+ "image",
45
+ "sdt"
46
+ ]
47
+ },
48
+ "description": "Filter by block types (e.g. ['paragraph', 'heading']). Omit for all types. Only for action 'blocks'. Omit for other actions."
169
49
  }
170
50
  },
171
51
  "required": [
@@ -175,12 +55,13 @@
175
55
  },
176
56
  "metadata": {
177
57
  "mutates": false,
178
- "operationCount": 4,
58
+ "operationCount": 5,
179
59
  "operations": [
180
60
  "doc.getText",
181
61
  "doc.getMarkdown",
182
62
  "doc.getHtml",
183
- "doc.info"
63
+ "doc.info",
64
+ "doc.blocks.list"
184
65
  ]
185
66
  }
186
67
  },
@@ -410,159 +291,13 @@
410
291
  ],
411
292
  "description": "Target address object. Use 'ref' instead if you have a search handle. Format: {kind:'text', blockId, range:{start,end}} or {kind:'block', nodeType, nodeId}."
412
293
  },
413
- "in": {
414
- "oneOf": [
415
- {
416
- "type": "object",
417
- "properties": {
418
- "kind": {
419
- "const": "story",
420
- "type": "string"
421
- },
422
- "storyType": {
423
- "const": "body",
424
- "type": "string"
425
- }
426
- },
427
- "required": [
428
- "kind",
429
- "storyType"
430
- ]
431
- },
432
- {
433
- "type": "object",
434
- "properties": {
435
- "kind": {
436
- "const": "story",
437
- "type": "string"
438
- },
439
- "storyType": {
440
- "const": "headerFooterSlot",
441
- "type": "string"
442
- },
443
- "section": {
444
- "type": "object",
445
- "properties": {
446
- "kind": {
447
- "const": "section",
448
- "type": "string"
449
- },
450
- "sectionId": {
451
- "type": "string"
452
- }
453
- },
454
- "required": [
455
- "kind",
456
- "sectionId"
457
- ]
458
- },
459
- "headerFooterKind": {
460
- "enum": [
461
- "header",
462
- "footer"
463
- ]
464
- },
465
- "variant": {
466
- "enum": [
467
- "default",
468
- "first",
469
- "even"
470
- ]
471
- },
472
- "resolution": {
473
- "enum": [
474
- "effective",
475
- "explicit"
476
- ]
477
- },
478
- "onWrite": {
479
- "enum": [
480
- "materializeIfInherited",
481
- "editResolvedPart",
482
- "error"
483
- ]
484
- }
485
- },
486
- "required": [
487
- "kind",
488
- "storyType",
489
- "section",
490
- "headerFooterKind",
491
- "variant"
492
- ]
493
- },
494
- {
495
- "type": "object",
496
- "properties": {
497
- "kind": {
498
- "const": "story",
499
- "type": "string"
500
- },
501
- "storyType": {
502
- "const": "headerFooterPart",
503
- "type": "string"
504
- },
505
- "refId": {
506
- "type": "string"
507
- }
508
- },
509
- "required": [
510
- "kind",
511
- "storyType",
512
- "refId"
513
- ]
514
- },
515
- {
516
- "type": "object",
517
- "properties": {
518
- "kind": {
519
- "const": "story",
520
- "type": "string"
521
- },
522
- "storyType": {
523
- "const": "footnote",
524
- "type": "string"
525
- },
526
- "noteId": {
527
- "type": "string"
528
- }
529
- },
530
- "required": [
531
- "kind",
532
- "storyType",
533
- "noteId"
534
- ]
535
- },
536
- {
537
- "type": "object",
538
- "properties": {
539
- "kind": {
540
- "const": "story",
541
- "type": "string"
542
- },
543
- "storyType": {
544
- "const": "endnote",
545
- "type": "string"
546
- },
547
- "noteId": {
548
- "type": "string"
549
- }
550
- },
551
- "required": [
552
- "kind",
553
- "storyType",
554
- "noteId"
555
- ]
556
- }
557
- ]
558
- },
559
294
  "value": {
560
295
  "type": "string",
561
- "description": "Text content to insert."
296
+ "description": "Text content to insert. Only for action 'insert'. Omit for other actions."
562
297
  },
563
298
  "type": {
564
299
  "type": "string",
565
- "description": "Content format: 'text' (default), 'markdown', or 'html'.",
300
+ "description": "Content format: 'text' (default), 'markdown', or 'html'. Only for action 'insert'. Omit for other actions.",
566
301
  "enum": [
567
302
  "text",
568
303
  "markdown",
@@ -587,11 +322,11 @@
587
322
  }
588
323
  }
589
324
  ],
590
- "description": "Document fragment to insert (structured content)."
325
+ "description": "Document fragment to insert (structured content). Only for actions 'insert', 'replace'. Omit for other actions."
591
326
  },
592
327
  "placement": {
593
328
  "type": "string",
594
- "description": "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'.",
329
+ "description": "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'. Only for action 'insert'. Omit for other actions.",
595
330
  "enum": [
596
331
  "before",
597
332
  "after",
@@ -609,7 +344,7 @@
609
344
  ]
610
345
  }
611
346
  },
612
- "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables."
347
+ "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables. Only for actions 'insert', 'replace'. Omit for other actions."
613
348
  },
614
349
  "blockId": {
615
350
  "type": "string",
@@ -625,11 +360,11 @@
625
360
  },
626
361
  "offset": {
627
362
  "type": "number",
628
- "description": "Character offset for insertion (alias for --start/--end with same value)."
363
+ "description": "Character offset for insertion (alias for --start/--end with same value). Only for action 'insert'. Omit for other actions."
629
364
  },
630
365
  "text": {
631
366
  "type": "string",
632
- "description": "Replacement text content."
367
+ "description": "Replacement text content. Only for action 'replace'. Omit for other actions."
633
368
  },
634
369
  "behavior": {
635
370
  "type": "string",
@@ -637,7 +372,7 @@
637
372
  "selection",
638
373
  "exact"
639
374
  ],
640
- "description": "Delete behavior: 'selection' (default) or 'exact'."
375
+ "description": "Delete behavior: 'selection' (default) or 'exact'. Only for action 'delete'. Omit for other actions."
641
376
  }
642
377
  },
643
378
  "required": [
@@ -659,7 +394,7 @@
659
394
  },
660
395
  {
661
396
  "name": "superdoc_format",
662
- "description": "Change text and paragraph formatting",
397
+ "description": "Change text and paragraph formatting. Use action \"inline\" with a search ref for bold/italic/etc. Use action \"set_style\" with a styleId from superdoc_get_content info to apply a named paragraph style.",
663
398
  "parameters": {
664
399
  "type": "object",
665
400
  "properties": {
@@ -850,152 +585,6 @@
850
585
  ],
851
586
  "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle. Required for actions 'set_style', 'set_alignment', 'set_indentation', 'set_spacing', 'set_direction'."
852
587
  },
853
- "in": {
854
- "oneOf": [
855
- {
856
- "type": "object",
857
- "properties": {
858
- "kind": {
859
- "const": "story",
860
- "type": "string"
861
- },
862
- "storyType": {
863
- "const": "body",
864
- "type": "string"
865
- }
866
- },
867
- "required": [
868
- "kind",
869
- "storyType"
870
- ]
871
- },
872
- {
873
- "type": "object",
874
- "properties": {
875
- "kind": {
876
- "const": "story",
877
- "type": "string"
878
- },
879
- "storyType": {
880
- "const": "headerFooterSlot",
881
- "type": "string"
882
- },
883
- "section": {
884
- "type": "object",
885
- "properties": {
886
- "kind": {
887
- "const": "section",
888
- "type": "string"
889
- },
890
- "sectionId": {
891
- "type": "string"
892
- }
893
- },
894
- "required": [
895
- "kind",
896
- "sectionId"
897
- ]
898
- },
899
- "headerFooterKind": {
900
- "enum": [
901
- "header",
902
- "footer"
903
- ]
904
- },
905
- "variant": {
906
- "enum": [
907
- "default",
908
- "first",
909
- "even"
910
- ]
911
- },
912
- "resolution": {
913
- "enum": [
914
- "effective",
915
- "explicit"
916
- ]
917
- },
918
- "onWrite": {
919
- "enum": [
920
- "materializeIfInherited",
921
- "editResolvedPart",
922
- "error"
923
- ]
924
- }
925
- },
926
- "required": [
927
- "kind",
928
- "storyType",
929
- "section",
930
- "headerFooterKind",
931
- "variant"
932
- ]
933
- },
934
- {
935
- "type": "object",
936
- "properties": {
937
- "kind": {
938
- "const": "story",
939
- "type": "string"
940
- },
941
- "storyType": {
942
- "const": "headerFooterPart",
943
- "type": "string"
944
- },
945
- "refId": {
946
- "type": "string"
947
- }
948
- },
949
- "required": [
950
- "kind",
951
- "storyType",
952
- "refId"
953
- ]
954
- },
955
- {
956
- "type": "object",
957
- "properties": {
958
- "kind": {
959
- "const": "story",
960
- "type": "string"
961
- },
962
- "storyType": {
963
- "const": "footnote",
964
- "type": "string"
965
- },
966
- "noteId": {
967
- "type": "string"
968
- }
969
- },
970
- "required": [
971
- "kind",
972
- "storyType",
973
- "noteId"
974
- ]
975
- },
976
- {
977
- "type": "object",
978
- "properties": {
979
- "kind": {
980
- "const": "story",
981
- "type": "string"
982
- },
983
- "storyType": {
984
- "const": "endnote",
985
- "type": "string"
986
- },
987
- "noteId": {
988
- "type": "string"
989
- }
990
- },
991
- "required": [
992
- "kind",
993
- "storyType",
994
- "noteId"
995
- ]
996
- }
997
- ]
998
- },
999
588
  "inline": {
1000
589
  "type": "object",
1001
590
  "properties": {
@@ -1255,27 +844,15 @@
1255
844
  "type": "boolean"
1256
845
  }
1257
846
  },
1258
- "description": "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold."
847
+ "description": "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold. Only for action 'inline'. Omit for other actions."
1259
848
  },
1260
849
  "ref": {
1261
850
  "type": "string",
1262
- "description": "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting."
1263
- },
1264
- "blockId": {
1265
- "type": "string",
1266
- "description": "Block ID of the target paragraph."
1267
- },
1268
- "start": {
1269
- "type": "number",
1270
- "description": "Start offset within the block (character index)."
1271
- },
1272
- "end": {
1273
- "type": "number",
1274
- "description": "End offset within the block (character index)."
851
+ "description": "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting. Only for action 'inline'. Omit for other actions."
1275
852
  },
1276
853
  "styleId": {
1277
854
  "type": "string",
1278
- "description": "Required for action 'set_style'."
855
+ "description": "Named paragraph style ID (e.g. 'Normal', 'Heading1', 'BodyText'). Use superdoc_search to find a nearby paragraph, then inspect its style to determine the correct styleId. Required for action 'set_style'."
1279
856
  },
1280
857
  "alignment": {
1281
858
  "type": "string",
@@ -1289,35 +866,35 @@
1289
866
  },
1290
867
  "left": {
1291
868
  "type": "number",
1292
- "description": "Left indentation in twips (1440 = 1 inch)."
869
+ "description": "Left indentation in twips (1440 = 1 inch). Only for action 'set_indentation'. Omit for other actions."
1293
870
  },
1294
871
  "right": {
1295
872
  "type": "number",
1296
- "description": "Right indentation in twips (1440 = 1 inch)."
873
+ "description": "Right indentation in twips (1440 = 1 inch). Only for action 'set_indentation'. Omit for other actions."
1297
874
  },
1298
875
  "firstLine": {
1299
876
  "type": "number",
1300
- "description": "First line indent in twips. Cannot be combined with hanging."
877
+ "description": "First line indent in twips. Cannot be combined with hanging. Only for action 'set_indentation'. Omit for other actions."
1301
878
  },
1302
879
  "hanging": {
1303
880
  "type": "number",
1304
- "description": "Hanging indent in twips. Cannot be combined with firstLine."
881
+ "description": "Hanging indent in twips. Cannot be combined with firstLine. Only for action 'set_indentation'. Omit for other actions."
1305
882
  },
1306
883
  "before": {
1307
884
  "type": "number",
1308
- "description": "Space before paragraph in twips (20 twips = 1pt)."
885
+ "description": "Space before paragraph in twips (20 twips = 1pt). Only for action 'set_spacing'. Omit for other actions."
1309
886
  },
1310
887
  "after": {
1311
888
  "type": "number",
1312
- "description": "Space after paragraph in twips (20 twips = 1pt)."
889
+ "description": "Space after paragraph in twips (20 twips = 1pt). Only for action 'set_spacing'. Omit for other actions."
1313
890
  },
1314
891
  "line": {
1315
892
  "type": "number",
1316
- "description": "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule."
893
+ "description": "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule. Only for action 'set_spacing'. Omit for other actions."
1317
894
  },
1318
895
  "lineRule": {
1319
896
  "type": "string",
1320
- "description": "Line spacing rule. Required when 'line' is set.",
897
+ "description": "Line spacing rule. Required when 'line' is set. Only for action 'set_spacing'. Omit for other actions.",
1321
898
  "enum": [
1322
899
  "auto",
1323
900
  "exact",
@@ -1337,7 +914,8 @@
1337
914
  "enum": [
1338
915
  "preserve",
1339
916
  "matchDirection"
1340
- ]
917
+ ],
918
+ "description": "Only for action 'set_direction'. Omit for other actions."
1341
919
  }
1342
920
  },
1343
921
  "required": [
@@ -1345,194 +923,48 @@
1345
923
  ],
1346
924
  "additionalProperties": false
1347
925
  },
1348
- "metadata": {
1349
- "mutates": true,
1350
- "operationCount": 6,
1351
- "operations": [
1352
- "doc.format.apply",
1353
- "doc.styles.paragraph.setStyle",
1354
- "doc.format.paragraph.setAlignment",
1355
- "doc.format.paragraph.setIndentation",
1356
- "doc.format.paragraph.setSpacing",
1357
- "doc.format.paragraph.setDirection"
1358
- ]
1359
- }
1360
- },
1361
- {
1362
- "name": "superdoc_create",
1363
- "description": "Create structural block elements",
1364
- "parameters": {
1365
- "type": "object",
1366
- "properties": {
1367
- "action": {
1368
- "type": "string",
1369
- "enum": [
1370
- "heading",
1371
- "paragraph"
1372
- ],
1373
- "description": "The action to perform. One of: heading, paragraph."
1374
- },
1375
- "force": {
1376
- "type": "boolean",
1377
- "description": "Bypass confirmation checks."
1378
- },
1379
- "changeMode": {
1380
- "type": "string",
1381
- "enum": [
1382
- "direct",
1383
- "tracked"
1384
- ],
1385
- "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
1386
- },
1387
- "dryRun": {
1388
- "type": "boolean",
1389
- "description": "Preview the result without applying changes."
1390
- },
1391
- "in": {
1392
- "oneOf": [
1393
- {
1394
- "type": "object",
1395
- "properties": {
1396
- "kind": {
1397
- "const": "story",
1398
- "type": "string"
1399
- },
1400
- "storyType": {
1401
- "const": "body",
1402
- "type": "string"
1403
- }
1404
- },
1405
- "required": [
1406
- "kind",
1407
- "storyType"
1408
- ]
1409
- },
1410
- {
1411
- "type": "object",
1412
- "properties": {
1413
- "kind": {
1414
- "const": "story",
1415
- "type": "string"
1416
- },
1417
- "storyType": {
1418
- "const": "headerFooterSlot",
1419
- "type": "string"
1420
- },
1421
- "section": {
1422
- "type": "object",
1423
- "properties": {
1424
- "kind": {
1425
- "const": "section",
1426
- "type": "string"
1427
- },
1428
- "sectionId": {
1429
- "type": "string"
1430
- }
1431
- },
1432
- "required": [
1433
- "kind",
1434
- "sectionId"
1435
- ]
1436
- },
1437
- "headerFooterKind": {
1438
- "enum": [
1439
- "header",
1440
- "footer"
1441
- ]
1442
- },
1443
- "variant": {
1444
- "enum": [
1445
- "default",
1446
- "first",
1447
- "even"
1448
- ]
1449
- },
1450
- "resolution": {
1451
- "enum": [
1452
- "effective",
1453
- "explicit"
1454
- ]
1455
- },
1456
- "onWrite": {
1457
- "enum": [
1458
- "materializeIfInherited",
1459
- "editResolvedPart",
1460
- "error"
1461
- ]
1462
- }
1463
- },
1464
- "required": [
1465
- "kind",
1466
- "storyType",
1467
- "section",
1468
- "headerFooterKind",
1469
- "variant"
1470
- ]
1471
- },
1472
- {
1473
- "type": "object",
1474
- "properties": {
1475
- "kind": {
1476
- "const": "story",
1477
- "type": "string"
1478
- },
1479
- "storyType": {
1480
- "const": "headerFooterPart",
1481
- "type": "string"
1482
- },
1483
- "refId": {
1484
- "type": "string"
1485
- }
1486
- },
1487
- "required": [
1488
- "kind",
1489
- "storyType",
1490
- "refId"
1491
- ]
1492
- },
1493
- {
1494
- "type": "object",
1495
- "properties": {
1496
- "kind": {
1497
- "const": "story",
1498
- "type": "string"
1499
- },
1500
- "storyType": {
1501
- "const": "footnote",
1502
- "type": "string"
1503
- },
1504
- "noteId": {
1505
- "type": "string"
1506
- }
1507
- },
1508
- "required": [
1509
- "kind",
1510
- "storyType",
1511
- "noteId"
1512
- ]
1513
- },
1514
- {
1515
- "type": "object",
1516
- "properties": {
1517
- "kind": {
1518
- "const": "story",
1519
- "type": "string"
1520
- },
1521
- "storyType": {
1522
- "const": "endnote",
1523
- "type": "string"
1524
- },
1525
- "noteId": {
1526
- "type": "string"
1527
- }
1528
- },
1529
- "required": [
1530
- "kind",
1531
- "storyType",
1532
- "noteId"
1533
- ]
1534
- }
1535
- ]
926
+ "metadata": {
927
+ "mutates": true,
928
+ "operationCount": 6,
929
+ "operations": [
930
+ "doc.format.apply",
931
+ "doc.styles.paragraph.setStyle",
932
+ "doc.format.paragraph.setAlignment",
933
+ "doc.format.paragraph.setIndentation",
934
+ "doc.format.paragraph.setSpacing",
935
+ "doc.format.paragraph.setDirection"
936
+ ]
937
+ }
938
+ },
939
+ {
940
+ "name": "superdoc_create",
941
+ "description": "Create one paragraph or heading per call. After creating, search for it and apply formatting (fontFamily, fontSize) from neighboring blocks. For multiple paragraphs, use superdoc_mutations with text.insert steps instead of calling create repeatedly.",
942
+ "parameters": {
943
+ "type": "object",
944
+ "properties": {
945
+ "action": {
946
+ "type": "string",
947
+ "enum": [
948
+ "heading",
949
+ "paragraph"
950
+ ],
951
+ "description": "The action to perform. One of: heading, paragraph."
952
+ },
953
+ "force": {
954
+ "type": "boolean",
955
+ "description": "Bypass confirmation checks."
956
+ },
957
+ "changeMode": {
958
+ "type": "string",
959
+ "enum": [
960
+ "direct",
961
+ "tracked"
962
+ ],
963
+ "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
964
+ },
965
+ "dryRun": {
966
+ "type": "boolean",
967
+ "description": "Preview the result without applying changes."
1536
968
  },
1537
969
  "at": {
1538
970
  "oneOf": [
@@ -1651,7 +1083,7 @@
1651
1083
  },
1652
1084
  "text": {
1653
1085
  "type": "string",
1654
- "description": "Paragraph text content."
1086
+ "description": "Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item — do NOT use newlines to put multiple items in one paragraph."
1655
1087
  },
1656
1088
  "input": {
1657
1089
  "type": "object",
@@ -1743,7 +1175,7 @@
1743
1175
  },
1744
1176
  "text": {
1745
1177
  "type": "string",
1746
- "description": "Text content for the new list item."
1178
+ "description": "Text content for the new list item. Only for action 'insert'. Omit for other actions."
1747
1179
  },
1748
1180
  "input": {
1749
1181
  "type": "object",
@@ -1755,7 +1187,7 @@
1755
1187
  },
1756
1188
  "mode": {
1757
1189
  "type": "string",
1758
- "description": "Required. Creation mode: 'empty' creates a new empty list at the paragraph specified by 'at'; 'fromParagraphs' converts existing paragraph(s) specified by 'target' into list items. Required for action 'create'.",
1190
+ "description": "Required. 'fromParagraphs' converts existing paragraphs into list items — each paragraph becomes one item, so create one paragraph per item first. 'empty' creates a new empty list at 'at'. Required for action 'create'.",
1759
1191
  "enum": [
1760
1192
  "empty",
1761
1193
  "fromParagraphs"
@@ -1781,7 +1213,7 @@
1781
1213
  "nodeType",
1782
1214
  "nodeId"
1783
1215
  ],
1784
- "description": "Required when mode is 'empty'. The paragraph to create the list at. Format: {kind:'block', nodeType:'paragraph', nodeId:'<id>'}."
1216
+ "description": "Required when mode is 'empty'. The paragraph to create the list at. Format: {kind:'block', nodeType:'paragraph', nodeId:'<id>'}. Only for action 'create'. Omit for other actions."
1785
1217
  },
1786
1218
  "kind": {
1787
1219
  "type": "string",
@@ -1797,7 +1229,7 @@
1797
1229
  },
1798
1230
  "preset": {
1799
1231
  "type": "string",
1800
- "description": "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format.",
1232
+ "description": "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format. Only for action 'create'. Omit for other actions.",
1801
1233
  "enum": [
1802
1234
  "decimal",
1803
1235
  "decimalParenthesis",
@@ -1880,7 +1312,8 @@
1880
1312
  "required": [
1881
1313
  "version",
1882
1314
  "levels"
1883
- ]
1315
+ ],
1316
+ "description": "Only for action 'create'. Omit for other actions."
1884
1317
  },
1885
1318
  "sequence": {
1886
1319
  "oneOf": [
@@ -1911,11 +1344,12 @@
1911
1344
  "mode"
1912
1345
  ]
1913
1346
  }
1914
- ]
1347
+ ],
1348
+ "description": "Only for action 'create'. Omit for other actions."
1915
1349
  },
1916
1350
  "continuity": {
1917
1351
  "type": "string",
1918
- "description": "Numbering continuity: 'preserve' keeps numbering; 'none' restarts.",
1352
+ "description": "Numbering continuity: 'preserve' keeps numbering; 'none' restarts. Only for action 'set_type'. Omit for other actions.",
1919
1353
  "enum": [
1920
1354
  "preserve",
1921
1355
  "none"
@@ -2005,23 +1439,11 @@
2005
1439
  "blockId",
2006
1440
  "range"
2007
1441
  ],
2008
- "description": "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}."
1442
+ "description": "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}. Only for actions 'create', 'update'. Omit for other actions."
2009
1443
  },
2010
1444
  "parentId": {
2011
1445
  "type": "string",
2012
- "description": "Parent comment ID for creating a threaded reply."
2013
- },
2014
- "blockId": {
2015
- "type": "string",
2016
- "description": "Block ID of the target paragraph."
2017
- },
2018
- "start": {
2019
- "type": "number",
2020
- "description": "Start offset within the block (character index)."
2021
- },
2022
- "end": {
2023
- "type": "number",
2024
- "description": "End offset within the block (character index)."
1446
+ "description": "Parent comment ID for creating a threaded reply. Only for action 'create'. Omit for other actions."
2025
1447
  },
2026
1448
  "id": {
2027
1449
  "type": "string",
@@ -2029,26 +1451,26 @@
2029
1451
  },
2030
1452
  "status": {
2031
1453
  "type": "string",
2032
- "description": "Set comment status. Use 'resolved' to mark as resolved.",
1454
+ "description": "Set comment status. Use 'resolved' to mark as resolved. Only for action 'update'. Omit for other actions.",
2033
1455
  "enum": [
2034
1456
  "resolved"
2035
1457
  ]
2036
1458
  },
2037
1459
  "isInternal": {
2038
1460
  "type": "boolean",
2039
- "description": "When true, marks the comment as internal (hidden from external collaborators)."
1461
+ "description": "When true, marks the comment as internal (hidden from external collaborators). Only for action 'update'. Omit for other actions."
2040
1462
  },
2041
1463
  "includeResolved": {
2042
1464
  "type": "boolean",
2043
- "description": "When true, includes resolved comments in results. Default: false."
1465
+ "description": "When true, includes resolved comments in results. Default: false. Only for action 'list'. Omit for other actions."
2044
1466
  },
2045
1467
  "limit": {
2046
1468
  "type": "number",
2047
- "description": "Maximum number of comments to return."
1469
+ "description": "Maximum number of comments to return. Only for action 'list'. Omit for other actions."
2048
1470
  },
2049
1471
  "offset": {
2050
1472
  "type": "number",
2051
- "description": "Number of comments to skip for pagination."
1473
+ "description": "Number of comments to skip for pagination. Only for action 'list'. Omit for other actions."
2052
1474
  }
2053
1475
  },
2054
1476
  "required": [
@@ -2084,15 +1506,15 @@
2084
1506
  },
2085
1507
  "limit": {
2086
1508
  "type": "number",
2087
- "description": "Maximum number of tracked changes to return."
1509
+ "description": "Maximum number of tracked changes to return. Only for action 'list'. Omit for other actions."
2088
1510
  },
2089
1511
  "offset": {
2090
1512
  "type": "number",
2091
- "description": "Number of tracked changes to skip for pagination."
1513
+ "description": "Number of tracked changes to skip for pagination. Only for action 'list'. Omit for other actions."
2092
1514
  },
2093
1515
  "type": {
2094
1516
  "type": "string",
2095
- "description": "Filter by change type: 'insert', 'delete', or 'format'.",
1517
+ "description": "Filter by change type: 'insert', 'delete', or 'format'. Only for action 'list'. Omit for other actions.",
2096
1518
  "enum": [
2097
1519
  "insert",
2098
1520
  "delete",
@@ -2101,7 +1523,7 @@
2101
1523
  },
2102
1524
  "force": {
2103
1525
  "type": "boolean",
2104
- "description": "Bypass confirmation checks."
1526
+ "description": "Bypass confirmation checks. Only for action 'decide'. Omit for other actions."
2105
1527
  },
2106
1528
  "changeMode": {
2107
1529
  "type": "string",
@@ -2109,7 +1531,7 @@
2109
1531
  "direct",
2110
1532
  "tracked"
2111
1533
  ],
2112
- "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
1534
+ "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions. Only for action 'decide'. Omit for other actions."
2113
1535
  },
2114
1536
  "decision": {
2115
1537
  "type": "string",
@@ -2169,152 +1591,6 @@
2169
1591
  "parameters": {
2170
1592
  "type": "object",
2171
1593
  "properties": {
2172
- "in": {
2173
- "oneOf": [
2174
- {
2175
- "type": "object",
2176
- "properties": {
2177
- "kind": {
2178
- "const": "story",
2179
- "type": "string"
2180
- },
2181
- "storyType": {
2182
- "const": "body",
2183
- "type": "string"
2184
- }
2185
- },
2186
- "required": [
2187
- "kind",
2188
- "storyType"
2189
- ]
2190
- },
2191
- {
2192
- "type": "object",
2193
- "properties": {
2194
- "kind": {
2195
- "const": "story",
2196
- "type": "string"
2197
- },
2198
- "storyType": {
2199
- "const": "headerFooterSlot",
2200
- "type": "string"
2201
- },
2202
- "section": {
2203
- "type": "object",
2204
- "properties": {
2205
- "kind": {
2206
- "const": "section",
2207
- "type": "string"
2208
- },
2209
- "sectionId": {
2210
- "type": "string"
2211
- }
2212
- },
2213
- "required": [
2214
- "kind",
2215
- "sectionId"
2216
- ]
2217
- },
2218
- "headerFooterKind": {
2219
- "enum": [
2220
- "header",
2221
- "footer"
2222
- ]
2223
- },
2224
- "variant": {
2225
- "enum": [
2226
- "default",
2227
- "first",
2228
- "even"
2229
- ]
2230
- },
2231
- "resolution": {
2232
- "enum": [
2233
- "effective",
2234
- "explicit"
2235
- ]
2236
- },
2237
- "onWrite": {
2238
- "enum": [
2239
- "materializeIfInherited",
2240
- "editResolvedPart",
2241
- "error"
2242
- ]
2243
- }
2244
- },
2245
- "required": [
2246
- "kind",
2247
- "storyType",
2248
- "section",
2249
- "headerFooterKind",
2250
- "variant"
2251
- ]
2252
- },
2253
- {
2254
- "type": "object",
2255
- "properties": {
2256
- "kind": {
2257
- "const": "story",
2258
- "type": "string"
2259
- },
2260
- "storyType": {
2261
- "const": "headerFooterPart",
2262
- "type": "string"
2263
- },
2264
- "refId": {
2265
- "type": "string"
2266
- }
2267
- },
2268
- "required": [
2269
- "kind",
2270
- "storyType",
2271
- "refId"
2272
- ]
2273
- },
2274
- {
2275
- "type": "object",
2276
- "properties": {
2277
- "kind": {
2278
- "const": "story",
2279
- "type": "string"
2280
- },
2281
- "storyType": {
2282
- "const": "footnote",
2283
- "type": "string"
2284
- },
2285
- "noteId": {
2286
- "type": "string"
2287
- }
2288
- },
2289
- "required": [
2290
- "kind",
2291
- "storyType",
2292
- "noteId"
2293
- ]
2294
- },
2295
- {
2296
- "type": "object",
2297
- "properties": {
2298
- "kind": {
2299
- "const": "story",
2300
- "type": "string"
2301
- },
2302
- "storyType": {
2303
- "const": "endnote",
2304
- "type": "string"
2305
- },
2306
- "noteId": {
2307
- "type": "string"
2308
- }
2309
- },
2310
- "required": [
2311
- "kind",
2312
- "storyType",
2313
- "noteId"
2314
- ]
2315
- }
2316
- ]
2317
- },
2318
1594
  "select": {
2319
1595
  "oneOf": [
2320
1596
  {
@@ -2485,155 +1761,9 @@
2485
1761
  ],
2486
1762
  "description": "The action to perform. One of: apply, preview."
2487
1763
  },
2488
- "in": {
2489
- "oneOf": [
2490
- {
2491
- "type": "object",
2492
- "properties": {
2493
- "kind": {
2494
- "const": "story",
2495
- "type": "string"
2496
- },
2497
- "storyType": {
2498
- "const": "body",
2499
- "type": "string"
2500
- }
2501
- },
2502
- "required": [
2503
- "kind",
2504
- "storyType"
2505
- ]
2506
- },
2507
- {
2508
- "type": "object",
2509
- "properties": {
2510
- "kind": {
2511
- "const": "story",
2512
- "type": "string"
2513
- },
2514
- "storyType": {
2515
- "const": "headerFooterSlot",
2516
- "type": "string"
2517
- },
2518
- "section": {
2519
- "type": "object",
2520
- "properties": {
2521
- "kind": {
2522
- "const": "section",
2523
- "type": "string"
2524
- },
2525
- "sectionId": {
2526
- "type": "string"
2527
- }
2528
- },
2529
- "required": [
2530
- "kind",
2531
- "sectionId"
2532
- ]
2533
- },
2534
- "headerFooterKind": {
2535
- "enum": [
2536
- "header",
2537
- "footer"
2538
- ]
2539
- },
2540
- "variant": {
2541
- "enum": [
2542
- "default",
2543
- "first",
2544
- "even"
2545
- ]
2546
- },
2547
- "resolution": {
2548
- "enum": [
2549
- "effective",
2550
- "explicit"
2551
- ]
2552
- },
2553
- "onWrite": {
2554
- "enum": [
2555
- "materializeIfInherited",
2556
- "editResolvedPart",
2557
- "error"
2558
- ]
2559
- }
2560
- },
2561
- "required": [
2562
- "kind",
2563
- "storyType",
2564
- "section",
2565
- "headerFooterKind",
2566
- "variant"
2567
- ]
2568
- },
2569
- {
2570
- "type": "object",
2571
- "properties": {
2572
- "kind": {
2573
- "const": "story",
2574
- "type": "string"
2575
- },
2576
- "storyType": {
2577
- "const": "headerFooterPart",
2578
- "type": "string"
2579
- },
2580
- "refId": {
2581
- "type": "string"
2582
- }
2583
- },
2584
- "required": [
2585
- "kind",
2586
- "storyType",
2587
- "refId"
2588
- ]
2589
- },
2590
- {
2591
- "type": "object",
2592
- "properties": {
2593
- "kind": {
2594
- "const": "story",
2595
- "type": "string"
2596
- },
2597
- "storyType": {
2598
- "const": "footnote",
2599
- "type": "string"
2600
- },
2601
- "noteId": {
2602
- "type": "string"
2603
- }
2604
- },
2605
- "required": [
2606
- "kind",
2607
- "storyType",
2608
- "noteId"
2609
- ]
2610
- },
2611
- {
2612
- "type": "object",
2613
- "properties": {
2614
- "kind": {
2615
- "const": "story",
2616
- "type": "string"
2617
- },
2618
- "storyType": {
2619
- "const": "endnote",
2620
- "type": "string"
2621
- },
2622
- "noteId": {
2623
- "type": "string"
2624
- }
2625
- },
2626
- "required": [
2627
- "kind",
2628
- "storyType",
2629
- "noteId"
2630
- ]
2631
- }
2632
- ]
2633
- },
2634
1764
  "expectedRevision": {
2635
1765
  "type": "string",
2636
- "description": "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision."
1766
+ "description": "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision. Only for action 'preview'. Omit for other actions."
2637
1767
  },
2638
1768
  "atomic": {
2639
1769
  "type": "boolean",
@@ -4556,7 +3686,7 @@
4556
3686
  },
4557
3687
  "force": {
4558
3688
  "type": "boolean",
4559
- "description": "Bypass confirmation checks."
3689
+ "description": "Bypass confirmation checks. Only for action 'apply'. Omit for other actions."
4560
3690
  }
4561
3691
  },
4562
3692
  "required": [