@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.
@@ -5,169 +5,49 @@
5
5
  "tools": [
6
6
  {
7
7
  "toolName": "superdoc_get_content",
8
- "description": "Read document content in various formats",
8
+ "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.",
9
9
  "inputSchema": {
10
10
  "type": "object",
11
11
  "properties": {
12
12
  "action": {
13
13
  "type": "string",
14
14
  "enum": [
15
+ "blocks",
15
16
  "html",
16
17
  "info",
17
18
  "markdown",
18
19
  "text"
19
20
  ],
20
- "description": "The action to perform. One of: html, info, markdown, text."
21
- },
22
- "in": {
23
- "oneOf": [
24
- {
25
- "type": "object",
26
- "properties": {
27
- "kind": {
28
- "const": "story",
29
- "type": "string"
30
- },
31
- "storyType": {
32
- "const": "body",
33
- "type": "string"
34
- }
35
- },
36
- "required": [
37
- "kind",
38
- "storyType"
39
- ]
40
- },
41
- {
42
- "type": "object",
43
- "properties": {
44
- "kind": {
45
- "const": "story",
46
- "type": "string"
47
- },
48
- "storyType": {
49
- "const": "headerFooterSlot",
50
- "type": "string"
51
- },
52
- "section": {
53
- "type": "object",
54
- "properties": {
55
- "kind": {
56
- "const": "section",
57
- "type": "string"
58
- },
59
- "sectionId": {
60
- "type": "string"
61
- }
62
- },
63
- "required": [
64
- "kind",
65
- "sectionId"
66
- ]
67
- },
68
- "headerFooterKind": {
69
- "enum": [
70
- "header",
71
- "footer"
72
- ]
73
- },
74
- "variant": {
75
- "enum": [
76
- "default",
77
- "first",
78
- "even"
79
- ]
80
- },
81
- "resolution": {
82
- "enum": [
83
- "effective",
84
- "explicit"
85
- ]
86
- },
87
- "onWrite": {
88
- "enum": [
89
- "materializeIfInherited",
90
- "editResolvedPart",
91
- "error"
92
- ]
93
- }
94
- },
95
- "required": [
96
- "kind",
97
- "storyType",
98
- "section",
99
- "headerFooterKind",
100
- "variant"
101
- ]
102
- },
103
- {
104
- "type": "object",
105
- "properties": {
106
- "kind": {
107
- "const": "story",
108
- "type": "string"
109
- },
110
- "storyType": {
111
- "const": "headerFooterPart",
112
- "type": "string"
113
- },
114
- "refId": {
115
- "type": "string"
116
- }
117
- },
118
- "required": [
119
- "kind",
120
- "storyType",
121
- "refId"
122
- ]
123
- },
124
- {
125
- "type": "object",
126
- "properties": {
127
- "kind": {
128
- "const": "story",
129
- "type": "string"
130
- },
131
- "storyType": {
132
- "const": "footnote",
133
- "type": "string"
134
- },
135
- "noteId": {
136
- "type": "string"
137
- }
138
- },
139
- "required": [
140
- "kind",
141
- "storyType",
142
- "noteId"
143
- ]
144
- },
145
- {
146
- "type": "object",
147
- "properties": {
148
- "kind": {
149
- "const": "story",
150
- "type": "string"
151
- },
152
- "storyType": {
153
- "const": "endnote",
154
- "type": "string"
155
- },
156
- "noteId": {
157
- "type": "string"
158
- }
159
- },
160
- "required": [
161
- "kind",
162
- "storyType",
163
- "noteId"
164
- ]
165
- }
166
- ]
21
+ "description": "The action to perform. One of: blocks, html, info, markdown, text."
167
22
  },
168
23
  "unflattenLists": {
169
24
  "type": "boolean",
170
- "description": "When true, flattens nested list structures in output. Default: false."
25
+ "description": "When true, flattens nested list structures in output. Default: false. Only for action 'html'. Omit for other actions."
26
+ },
27
+ "offset": {
28
+ "type": "number",
29
+ "description": "Number of blocks to skip. Default: 0. Only for action 'blocks'. Omit for other actions."
30
+ },
31
+ "limit": {
32
+ "type": "number",
33
+ "description": "Maximum blocks to return. Omit for all blocks. Only for action 'blocks'. Omit for other actions."
34
+ },
35
+ "nodeTypes": {
36
+ "type": "array",
37
+ "items": {
38
+ "enum": [
39
+ "paragraph",
40
+ "heading",
41
+ "listItem",
42
+ "table",
43
+ "tableRow",
44
+ "tableCell",
45
+ "tableOfContents",
46
+ "image",
47
+ "sdt"
48
+ ]
49
+ },
50
+ "description": "Filter by block types (e.g. ['paragraph', 'heading']). Omit for all types. Only for action 'blocks'. Omit for other actions."
171
51
  }
172
52
  },
173
53
  "required": [
@@ -192,6 +72,10 @@
192
72
  {
193
73
  "operationId": "doc.info",
194
74
  "intentAction": "info"
75
+ },
76
+ {
77
+ "operationId": "doc.blocks.list",
78
+ "intentAction": "blocks"
195
79
  }
196
80
  ]
197
81
  },
@@ -421,159 +305,13 @@
421
305
  ],
422
306
  "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}."
423
307
  },
424
- "in": {
425
- "oneOf": [
426
- {
427
- "type": "object",
428
- "properties": {
429
- "kind": {
430
- "const": "story",
431
- "type": "string"
432
- },
433
- "storyType": {
434
- "const": "body",
435
- "type": "string"
436
- }
437
- },
438
- "required": [
439
- "kind",
440
- "storyType"
441
- ]
442
- },
443
- {
444
- "type": "object",
445
- "properties": {
446
- "kind": {
447
- "const": "story",
448
- "type": "string"
449
- },
450
- "storyType": {
451
- "const": "headerFooterSlot",
452
- "type": "string"
453
- },
454
- "section": {
455
- "type": "object",
456
- "properties": {
457
- "kind": {
458
- "const": "section",
459
- "type": "string"
460
- },
461
- "sectionId": {
462
- "type": "string"
463
- }
464
- },
465
- "required": [
466
- "kind",
467
- "sectionId"
468
- ]
469
- },
470
- "headerFooterKind": {
471
- "enum": [
472
- "header",
473
- "footer"
474
- ]
475
- },
476
- "variant": {
477
- "enum": [
478
- "default",
479
- "first",
480
- "even"
481
- ]
482
- },
483
- "resolution": {
484
- "enum": [
485
- "effective",
486
- "explicit"
487
- ]
488
- },
489
- "onWrite": {
490
- "enum": [
491
- "materializeIfInherited",
492
- "editResolvedPart",
493
- "error"
494
- ]
495
- }
496
- },
497
- "required": [
498
- "kind",
499
- "storyType",
500
- "section",
501
- "headerFooterKind",
502
- "variant"
503
- ]
504
- },
505
- {
506
- "type": "object",
507
- "properties": {
508
- "kind": {
509
- "const": "story",
510
- "type": "string"
511
- },
512
- "storyType": {
513
- "const": "headerFooterPart",
514
- "type": "string"
515
- },
516
- "refId": {
517
- "type": "string"
518
- }
519
- },
520
- "required": [
521
- "kind",
522
- "storyType",
523
- "refId"
524
- ]
525
- },
526
- {
527
- "type": "object",
528
- "properties": {
529
- "kind": {
530
- "const": "story",
531
- "type": "string"
532
- },
533
- "storyType": {
534
- "const": "footnote",
535
- "type": "string"
536
- },
537
- "noteId": {
538
- "type": "string"
539
- }
540
- },
541
- "required": [
542
- "kind",
543
- "storyType",
544
- "noteId"
545
- ]
546
- },
547
- {
548
- "type": "object",
549
- "properties": {
550
- "kind": {
551
- "const": "story",
552
- "type": "string"
553
- },
554
- "storyType": {
555
- "const": "endnote",
556
- "type": "string"
557
- },
558
- "noteId": {
559
- "type": "string"
560
- }
561
- },
562
- "required": [
563
- "kind",
564
- "storyType",
565
- "noteId"
566
- ]
567
- }
568
- ]
569
- },
570
308
  "value": {
571
309
  "type": "string",
572
- "description": "Text content to insert."
310
+ "description": "Text content to insert. Only for action 'insert'. Omit for other actions."
573
311
  },
574
312
  "type": {
575
313
  "type": "string",
576
- "description": "Content format: 'text' (default), 'markdown', or 'html'.",
314
+ "description": "Content format: 'text' (default), 'markdown', or 'html'. Only for action 'insert'. Omit for other actions.",
577
315
  "enum": [
578
316
  "text",
579
317
  "markdown",
@@ -598,11 +336,11 @@
598
336
  }
599
337
  }
600
338
  ],
601
- "description": "Document fragment to insert (structured content)."
339
+ "description": "Document fragment to insert (structured content). Only for actions 'insert', 'replace'. Omit for other actions."
602
340
  },
603
341
  "placement": {
604
342
  "type": "string",
605
- "description": "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'.",
343
+ "description": "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'. Only for action 'insert'. Omit for other actions.",
606
344
  "enum": [
607
345
  "before",
608
346
  "after",
@@ -620,7 +358,7 @@
620
358
  ]
621
359
  }
622
360
  },
623
- "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables."
361
+ "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables. Only for actions 'insert', 'replace'. Omit for other actions."
624
362
  },
625
363
  "blockId": {
626
364
  "type": "string",
@@ -636,11 +374,11 @@
636
374
  },
637
375
  "offset": {
638
376
  "type": "number",
639
- "description": "Character offset for insertion (alias for --start/--end with same value)."
377
+ "description": "Character offset for insertion (alias for --start/--end with same value). Only for action 'insert'. Omit for other actions."
640
378
  },
641
379
  "text": {
642
380
  "type": "string",
643
- "description": "Replacement text content."
381
+ "description": "Replacement text content. Only for action 'replace'. Omit for other actions."
644
382
  },
645
383
  "behavior": {
646
384
  "type": "string",
@@ -648,7 +386,7 @@
648
386
  "selection",
649
387
  "exact"
650
388
  ],
651
- "description": "Delete behavior: 'selection' (default) or 'exact'."
389
+ "description": "Delete behavior: 'selection' (default) or 'exact'. Only for action 'delete'. Omit for other actions."
652
390
  }
653
391
  },
654
392
  "required": [
@@ -724,7 +462,7 @@
724
462
  },
725
463
  {
726
464
  "toolName": "superdoc_format",
727
- "description": "Change text and paragraph formatting",
465
+ "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.",
728
466
  "inputSchema": {
729
467
  "type": "object",
730
468
  "properties": {
@@ -915,152 +653,6 @@
915
653
  ],
916
654
  "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'."
917
655
  },
918
- "in": {
919
- "oneOf": [
920
- {
921
- "type": "object",
922
- "properties": {
923
- "kind": {
924
- "const": "story",
925
- "type": "string"
926
- },
927
- "storyType": {
928
- "const": "body",
929
- "type": "string"
930
- }
931
- },
932
- "required": [
933
- "kind",
934
- "storyType"
935
- ]
936
- },
937
- {
938
- "type": "object",
939
- "properties": {
940
- "kind": {
941
- "const": "story",
942
- "type": "string"
943
- },
944
- "storyType": {
945
- "const": "headerFooterSlot",
946
- "type": "string"
947
- },
948
- "section": {
949
- "type": "object",
950
- "properties": {
951
- "kind": {
952
- "const": "section",
953
- "type": "string"
954
- },
955
- "sectionId": {
956
- "type": "string"
957
- }
958
- },
959
- "required": [
960
- "kind",
961
- "sectionId"
962
- ]
963
- },
964
- "headerFooterKind": {
965
- "enum": [
966
- "header",
967
- "footer"
968
- ]
969
- },
970
- "variant": {
971
- "enum": [
972
- "default",
973
- "first",
974
- "even"
975
- ]
976
- },
977
- "resolution": {
978
- "enum": [
979
- "effective",
980
- "explicit"
981
- ]
982
- },
983
- "onWrite": {
984
- "enum": [
985
- "materializeIfInherited",
986
- "editResolvedPart",
987
- "error"
988
- ]
989
- }
990
- },
991
- "required": [
992
- "kind",
993
- "storyType",
994
- "section",
995
- "headerFooterKind",
996
- "variant"
997
- ]
998
- },
999
- {
1000
- "type": "object",
1001
- "properties": {
1002
- "kind": {
1003
- "const": "story",
1004
- "type": "string"
1005
- },
1006
- "storyType": {
1007
- "const": "headerFooterPart",
1008
- "type": "string"
1009
- },
1010
- "refId": {
1011
- "type": "string"
1012
- }
1013
- },
1014
- "required": [
1015
- "kind",
1016
- "storyType",
1017
- "refId"
1018
- ]
1019
- },
1020
- {
1021
- "type": "object",
1022
- "properties": {
1023
- "kind": {
1024
- "const": "story",
1025
- "type": "string"
1026
- },
1027
- "storyType": {
1028
- "const": "footnote",
1029
- "type": "string"
1030
- },
1031
- "noteId": {
1032
- "type": "string"
1033
- }
1034
- },
1035
- "required": [
1036
- "kind",
1037
- "storyType",
1038
- "noteId"
1039
- ]
1040
- },
1041
- {
1042
- "type": "object",
1043
- "properties": {
1044
- "kind": {
1045
- "const": "story",
1046
- "type": "string"
1047
- },
1048
- "storyType": {
1049
- "const": "endnote",
1050
- "type": "string"
1051
- },
1052
- "noteId": {
1053
- "type": "string"
1054
- }
1055
- },
1056
- "required": [
1057
- "kind",
1058
- "storyType",
1059
- "noteId"
1060
- ]
1061
- }
1062
- ]
1063
- },
1064
656
  "inline": {
1065
657
  "type": "object",
1066
658
  "properties": {
@@ -1320,27 +912,15 @@
1320
912
  "type": "boolean"
1321
913
  }
1322
914
  },
1323
- "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."
915
+ "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."
1324
916
  },
1325
917
  "ref": {
1326
918
  "type": "string",
1327
- "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."
1328
- },
1329
- "blockId": {
1330
- "type": "string",
1331
- "description": "Block ID of the target paragraph."
1332
- },
1333
- "start": {
1334
- "type": "number",
1335
- "description": "Start offset within the block (character index)."
1336
- },
1337
- "end": {
1338
- "type": "number",
1339
- "description": "End offset within the block (character index)."
919
+ "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."
1340
920
  },
1341
921
  "styleId": {
1342
922
  "type": "string",
1343
- "description": "Required for action 'set_style'."
923
+ "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'."
1344
924
  },
1345
925
  "alignment": {
1346
926
  "type": "string",
@@ -1354,35 +934,35 @@
1354
934
  },
1355
935
  "left": {
1356
936
  "type": "number",
1357
- "description": "Left indentation in twips (1440 = 1 inch)."
937
+ "description": "Left indentation in twips (1440 = 1 inch). Only for action 'set_indentation'. Omit for other actions."
1358
938
  },
1359
939
  "right": {
1360
940
  "type": "number",
1361
- "description": "Right indentation in twips (1440 = 1 inch)."
941
+ "description": "Right indentation in twips (1440 = 1 inch). Only for action 'set_indentation'. Omit for other actions."
1362
942
  },
1363
943
  "firstLine": {
1364
944
  "type": "number",
1365
- "description": "First line indent in twips. Cannot be combined with hanging."
945
+ "description": "First line indent in twips. Cannot be combined with hanging. Only for action 'set_indentation'. Omit for other actions."
1366
946
  },
1367
947
  "hanging": {
1368
948
  "type": "number",
1369
- "description": "Hanging indent in twips. Cannot be combined with firstLine."
949
+ "description": "Hanging indent in twips. Cannot be combined with firstLine. Only for action 'set_indentation'. Omit for other actions."
1370
950
  },
1371
951
  "before": {
1372
952
  "type": "number",
1373
- "description": "Space before paragraph in twips (20 twips = 1pt)."
953
+ "description": "Space before paragraph in twips (20 twips = 1pt). Only for action 'set_spacing'. Omit for other actions."
1374
954
  },
1375
955
  "after": {
1376
956
  "type": "number",
1377
- "description": "Space after paragraph in twips (20 twips = 1pt)."
957
+ "description": "Space after paragraph in twips (20 twips = 1pt). Only for action 'set_spacing'. Omit for other actions."
1378
958
  },
1379
959
  "line": {
1380
960
  "type": "number",
1381
- "description": "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule."
961
+ "description": "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule. Only for action 'set_spacing'. Omit for other actions."
1382
962
  },
1383
963
  "lineRule": {
1384
964
  "type": "string",
1385
- "description": "Line spacing rule. Required when 'line' is set.",
965
+ "description": "Line spacing rule. Required when 'line' is set. Only for action 'set_spacing'. Omit for other actions.",
1386
966
  "enum": [
1387
967
  "auto",
1388
968
  "exact",
@@ -1402,7 +982,8 @@
1402
982
  "enum": [
1403
983
  "preserve",
1404
984
  "matchDirection"
1405
- ]
985
+ ],
986
+ "description": "Only for action 'set_direction'. Omit for other actions."
1406
987
  }
1407
988
  },
1408
989
  "required": [
@@ -1453,194 +1034,48 @@
1453
1034
  "operationId": "doc.format.paragraph.setSpacing",
1454
1035
  "intentAction": "set_spacing",
1455
1036
  "required": [
1456
- "target"
1457
- ]
1458
- },
1459
- {
1460
- "operationId": "doc.format.paragraph.setDirection",
1461
- "intentAction": "set_direction",
1462
- "required": [
1463
- "target",
1464
- "direction"
1465
- ]
1466
- }
1467
- ]
1468
- },
1469
- {
1470
- "toolName": "superdoc_create",
1471
- "description": "Create structural block elements",
1472
- "inputSchema": {
1473
- "type": "object",
1474
- "properties": {
1475
- "action": {
1476
- "type": "string",
1477
- "enum": [
1478
- "heading",
1479
- "paragraph"
1480
- ],
1481
- "description": "The action to perform. One of: heading, paragraph."
1482
- },
1483
- "force": {
1484
- "type": "boolean",
1485
- "description": "Bypass confirmation checks."
1486
- },
1487
- "changeMode": {
1488
- "type": "string",
1489
- "enum": [
1490
- "direct",
1491
- "tracked"
1492
- ],
1493
- "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
1494
- },
1495
- "dryRun": {
1496
- "type": "boolean",
1497
- "description": "Preview the result without applying changes."
1498
- },
1499
- "in": {
1500
- "oneOf": [
1501
- {
1502
- "type": "object",
1503
- "properties": {
1504
- "kind": {
1505
- "const": "story",
1506
- "type": "string"
1507
- },
1508
- "storyType": {
1509
- "const": "body",
1510
- "type": "string"
1511
- }
1512
- },
1513
- "required": [
1514
- "kind",
1515
- "storyType"
1516
- ]
1517
- },
1518
- {
1519
- "type": "object",
1520
- "properties": {
1521
- "kind": {
1522
- "const": "story",
1523
- "type": "string"
1524
- },
1525
- "storyType": {
1526
- "const": "headerFooterSlot",
1527
- "type": "string"
1528
- },
1529
- "section": {
1530
- "type": "object",
1531
- "properties": {
1532
- "kind": {
1533
- "const": "section",
1534
- "type": "string"
1535
- },
1536
- "sectionId": {
1537
- "type": "string"
1538
- }
1539
- },
1540
- "required": [
1541
- "kind",
1542
- "sectionId"
1543
- ]
1544
- },
1545
- "headerFooterKind": {
1546
- "enum": [
1547
- "header",
1548
- "footer"
1549
- ]
1550
- },
1551
- "variant": {
1552
- "enum": [
1553
- "default",
1554
- "first",
1555
- "even"
1556
- ]
1557
- },
1558
- "resolution": {
1559
- "enum": [
1560
- "effective",
1561
- "explicit"
1562
- ]
1563
- },
1564
- "onWrite": {
1565
- "enum": [
1566
- "materializeIfInherited",
1567
- "editResolvedPart",
1568
- "error"
1569
- ]
1570
- }
1571
- },
1572
- "required": [
1573
- "kind",
1574
- "storyType",
1575
- "section",
1576
- "headerFooterKind",
1577
- "variant"
1578
- ]
1579
- },
1580
- {
1581
- "type": "object",
1582
- "properties": {
1583
- "kind": {
1584
- "const": "story",
1585
- "type": "string"
1586
- },
1587
- "storyType": {
1588
- "const": "headerFooterPart",
1589
- "type": "string"
1590
- },
1591
- "refId": {
1592
- "type": "string"
1593
- }
1594
- },
1595
- "required": [
1596
- "kind",
1597
- "storyType",
1598
- "refId"
1599
- ]
1600
- },
1601
- {
1602
- "type": "object",
1603
- "properties": {
1604
- "kind": {
1605
- "const": "story",
1606
- "type": "string"
1607
- },
1608
- "storyType": {
1609
- "const": "footnote",
1610
- "type": "string"
1611
- },
1612
- "noteId": {
1613
- "type": "string"
1614
- }
1615
- },
1616
- "required": [
1617
- "kind",
1618
- "storyType",
1619
- "noteId"
1620
- ]
1621
- },
1622
- {
1623
- "type": "object",
1624
- "properties": {
1625
- "kind": {
1626
- "const": "story",
1627
- "type": "string"
1628
- },
1629
- "storyType": {
1630
- "const": "endnote",
1631
- "type": "string"
1632
- },
1633
- "noteId": {
1634
- "type": "string"
1635
- }
1636
- },
1637
- "required": [
1638
- "kind",
1639
- "storyType",
1640
- "noteId"
1641
- ]
1642
- }
1643
- ]
1037
+ "target"
1038
+ ]
1039
+ },
1040
+ {
1041
+ "operationId": "doc.format.paragraph.setDirection",
1042
+ "intentAction": "set_direction",
1043
+ "required": [
1044
+ "target",
1045
+ "direction"
1046
+ ]
1047
+ }
1048
+ ]
1049
+ },
1050
+ {
1051
+ "toolName": "superdoc_create",
1052
+ "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.",
1053
+ "inputSchema": {
1054
+ "type": "object",
1055
+ "properties": {
1056
+ "action": {
1057
+ "type": "string",
1058
+ "enum": [
1059
+ "heading",
1060
+ "paragraph"
1061
+ ],
1062
+ "description": "The action to perform. One of: heading, paragraph."
1063
+ },
1064
+ "force": {
1065
+ "type": "boolean",
1066
+ "description": "Bypass confirmation checks."
1067
+ },
1068
+ "changeMode": {
1069
+ "type": "string",
1070
+ "enum": [
1071
+ "direct",
1072
+ "tracked"
1073
+ ],
1074
+ "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
1075
+ },
1076
+ "dryRun": {
1077
+ "type": "boolean",
1078
+ "description": "Preview the result without applying changes."
1644
1079
  },
1645
1080
  "at": {
1646
1081
  "oneOf": [
@@ -1759,7 +1194,7 @@
1759
1194
  },
1760
1195
  "text": {
1761
1196
  "type": "string",
1762
- "description": "Paragraph text content."
1197
+ "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."
1763
1198
  },
1764
1199
  "input": {
1765
1200
  "type": "object",
@@ -1857,7 +1292,7 @@
1857
1292
  },
1858
1293
  "text": {
1859
1294
  "type": "string",
1860
- "description": "Text content for the new list item."
1295
+ "description": "Text content for the new list item. Only for action 'insert'. Omit for other actions."
1861
1296
  },
1862
1297
  "input": {
1863
1298
  "type": "object",
@@ -1869,7 +1304,7 @@
1869
1304
  },
1870
1305
  "mode": {
1871
1306
  "type": "string",
1872
- "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'.",
1307
+ "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'.",
1873
1308
  "enum": [
1874
1309
  "empty",
1875
1310
  "fromParagraphs"
@@ -1895,7 +1330,7 @@
1895
1330
  "nodeType",
1896
1331
  "nodeId"
1897
1332
  ],
1898
- "description": "Required when mode is 'empty'. The paragraph to create the list at. Format: {kind:'block', nodeType:'paragraph', nodeId:'<id>'}."
1333
+ "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."
1899
1334
  },
1900
1335
  "kind": {
1901
1336
  "type": "string",
@@ -1911,7 +1346,7 @@
1911
1346
  },
1912
1347
  "preset": {
1913
1348
  "type": "string",
1914
- "description": "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format.",
1349
+ "description": "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format. Only for action 'create'. Omit for other actions.",
1915
1350
  "enum": [
1916
1351
  "decimal",
1917
1352
  "decimalParenthesis",
@@ -1994,7 +1429,8 @@
1994
1429
  "required": [
1995
1430
  "version",
1996
1431
  "levels"
1997
- ]
1432
+ ],
1433
+ "description": "Only for action 'create'. Omit for other actions."
1998
1434
  },
1999
1435
  "sequence": {
2000
1436
  "oneOf": [
@@ -2025,11 +1461,12 @@
2025
1461
  "mode"
2026
1462
  ]
2027
1463
  }
2028
- ]
1464
+ ],
1465
+ "description": "Only for action 'create'. Omit for other actions."
2029
1466
  },
2030
1467
  "continuity": {
2031
1468
  "type": "string",
2032
- "description": "Numbering continuity: 'preserve' keeps numbering; 'none' restarts.",
1469
+ "description": "Numbering continuity: 'preserve' keeps numbering; 'none' restarts. Only for action 'set_type'. Omit for other actions.",
2033
1470
  "enum": [
2034
1471
  "preserve",
2035
1472
  "none"
@@ -2161,23 +1598,11 @@
2161
1598
  "blockId",
2162
1599
  "range"
2163
1600
  ],
2164
- "description": "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}."
1601
+ "description": "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}. Only for actions 'create', 'update'. Omit for other actions."
2165
1602
  },
2166
1603
  "parentId": {
2167
1604
  "type": "string",
2168
- "description": "Parent comment ID for creating a threaded reply."
2169
- },
2170
- "blockId": {
2171
- "type": "string",
2172
- "description": "Block ID of the target paragraph."
2173
- },
2174
- "start": {
2175
- "type": "number",
2176
- "description": "Start offset within the block (character index)."
2177
- },
2178
- "end": {
2179
- "type": "number",
2180
- "description": "End offset within the block (character index)."
1605
+ "description": "Parent comment ID for creating a threaded reply. Only for action 'create'. Omit for other actions."
2181
1606
  },
2182
1607
  "id": {
2183
1608
  "type": "string",
@@ -2185,26 +1610,26 @@
2185
1610
  },
2186
1611
  "status": {
2187
1612
  "type": "string",
2188
- "description": "Set comment status. Use 'resolved' to mark as resolved.",
1613
+ "description": "Set comment status. Use 'resolved' to mark as resolved. Only for action 'update'. Omit for other actions.",
2189
1614
  "enum": [
2190
1615
  "resolved"
2191
1616
  ]
2192
1617
  },
2193
1618
  "isInternal": {
2194
1619
  "type": "boolean",
2195
- "description": "When true, marks the comment as internal (hidden from external collaborators)."
1620
+ "description": "When true, marks the comment as internal (hidden from external collaborators). Only for action 'update'. Omit for other actions."
2196
1621
  },
2197
1622
  "includeResolved": {
2198
1623
  "type": "boolean",
2199
- "description": "When true, includes resolved comments in results. Default: false."
1624
+ "description": "When true, includes resolved comments in results. Default: false. Only for action 'list'. Omit for other actions."
2200
1625
  },
2201
1626
  "limit": {
2202
1627
  "type": "number",
2203
- "description": "Maximum number of comments to return."
1628
+ "description": "Maximum number of comments to return. Only for action 'list'. Omit for other actions."
2204
1629
  },
2205
1630
  "offset": {
2206
1631
  "type": "number",
2207
- "description": "Number of comments to skip for pagination."
1632
+ "description": "Number of comments to skip for pagination. Only for action 'list'. Omit for other actions."
2208
1633
  }
2209
1634
  },
2210
1635
  "required": [
@@ -2261,15 +1686,15 @@
2261
1686
  },
2262
1687
  "limit": {
2263
1688
  "type": "number",
2264
- "description": "Maximum number of tracked changes to return."
1689
+ "description": "Maximum number of tracked changes to return. Only for action 'list'. Omit for other actions."
2265
1690
  },
2266
1691
  "offset": {
2267
1692
  "type": "number",
2268
- "description": "Number of tracked changes to skip for pagination."
1693
+ "description": "Number of tracked changes to skip for pagination. Only for action 'list'. Omit for other actions."
2269
1694
  },
2270
1695
  "type": {
2271
1696
  "type": "string",
2272
- "description": "Filter by change type: 'insert', 'delete', or 'format'.",
1697
+ "description": "Filter by change type: 'insert', 'delete', or 'format'. Only for action 'list'. Omit for other actions.",
2273
1698
  "enum": [
2274
1699
  "insert",
2275
1700
  "delete",
@@ -2278,7 +1703,7 @@
2278
1703
  },
2279
1704
  "force": {
2280
1705
  "type": "boolean",
2281
- "description": "Bypass confirmation checks."
1706
+ "description": "Bypass confirmation checks. Only for action 'decide'. Omit for other actions."
2282
1707
  },
2283
1708
  "changeMode": {
2284
1709
  "type": "string",
@@ -2286,7 +1711,7 @@
2286
1711
  "direct",
2287
1712
  "tracked"
2288
1713
  ],
2289
- "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
1714
+ "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions. Only for action 'decide'. Omit for other actions."
2290
1715
  },
2291
1716
  "decision": {
2292
1717
  "type": "string",
@@ -2353,152 +1778,6 @@
2353
1778
  "inputSchema": {
2354
1779
  "type": "object",
2355
1780
  "properties": {
2356
- "in": {
2357
- "oneOf": [
2358
- {
2359
- "type": "object",
2360
- "properties": {
2361
- "kind": {
2362
- "const": "story",
2363
- "type": "string"
2364
- },
2365
- "storyType": {
2366
- "const": "body",
2367
- "type": "string"
2368
- }
2369
- },
2370
- "required": [
2371
- "kind",
2372
- "storyType"
2373
- ]
2374
- },
2375
- {
2376
- "type": "object",
2377
- "properties": {
2378
- "kind": {
2379
- "const": "story",
2380
- "type": "string"
2381
- },
2382
- "storyType": {
2383
- "const": "headerFooterSlot",
2384
- "type": "string"
2385
- },
2386
- "section": {
2387
- "type": "object",
2388
- "properties": {
2389
- "kind": {
2390
- "const": "section",
2391
- "type": "string"
2392
- },
2393
- "sectionId": {
2394
- "type": "string"
2395
- }
2396
- },
2397
- "required": [
2398
- "kind",
2399
- "sectionId"
2400
- ]
2401
- },
2402
- "headerFooterKind": {
2403
- "enum": [
2404
- "header",
2405
- "footer"
2406
- ]
2407
- },
2408
- "variant": {
2409
- "enum": [
2410
- "default",
2411
- "first",
2412
- "even"
2413
- ]
2414
- },
2415
- "resolution": {
2416
- "enum": [
2417
- "effective",
2418
- "explicit"
2419
- ]
2420
- },
2421
- "onWrite": {
2422
- "enum": [
2423
- "materializeIfInherited",
2424
- "editResolvedPart",
2425
- "error"
2426
- ]
2427
- }
2428
- },
2429
- "required": [
2430
- "kind",
2431
- "storyType",
2432
- "section",
2433
- "headerFooterKind",
2434
- "variant"
2435
- ]
2436
- },
2437
- {
2438
- "type": "object",
2439
- "properties": {
2440
- "kind": {
2441
- "const": "story",
2442
- "type": "string"
2443
- },
2444
- "storyType": {
2445
- "const": "headerFooterPart",
2446
- "type": "string"
2447
- },
2448
- "refId": {
2449
- "type": "string"
2450
- }
2451
- },
2452
- "required": [
2453
- "kind",
2454
- "storyType",
2455
- "refId"
2456
- ]
2457
- },
2458
- {
2459
- "type": "object",
2460
- "properties": {
2461
- "kind": {
2462
- "const": "story",
2463
- "type": "string"
2464
- },
2465
- "storyType": {
2466
- "const": "footnote",
2467
- "type": "string"
2468
- },
2469
- "noteId": {
2470
- "type": "string"
2471
- }
2472
- },
2473
- "required": [
2474
- "kind",
2475
- "storyType",
2476
- "noteId"
2477
- ]
2478
- },
2479
- {
2480
- "type": "object",
2481
- "properties": {
2482
- "kind": {
2483
- "const": "story",
2484
- "type": "string"
2485
- },
2486
- "storyType": {
2487
- "const": "endnote",
2488
- "type": "string"
2489
- },
2490
- "noteId": {
2491
- "type": "string"
2492
- }
2493
- },
2494
- "required": [
2495
- "kind",
2496
- "storyType",
2497
- "noteId"
2498
- ]
2499
- }
2500
- ]
2501
- },
2502
1781
  "select": {
2503
1782
  "oneOf": [
2504
1783
  {
@@ -2672,155 +1951,9 @@
2672
1951
  ],
2673
1952
  "description": "The action to perform. One of: apply, preview."
2674
1953
  },
2675
- "in": {
2676
- "oneOf": [
2677
- {
2678
- "type": "object",
2679
- "properties": {
2680
- "kind": {
2681
- "const": "story",
2682
- "type": "string"
2683
- },
2684
- "storyType": {
2685
- "const": "body",
2686
- "type": "string"
2687
- }
2688
- },
2689
- "required": [
2690
- "kind",
2691
- "storyType"
2692
- ]
2693
- },
2694
- {
2695
- "type": "object",
2696
- "properties": {
2697
- "kind": {
2698
- "const": "story",
2699
- "type": "string"
2700
- },
2701
- "storyType": {
2702
- "const": "headerFooterSlot",
2703
- "type": "string"
2704
- },
2705
- "section": {
2706
- "type": "object",
2707
- "properties": {
2708
- "kind": {
2709
- "const": "section",
2710
- "type": "string"
2711
- },
2712
- "sectionId": {
2713
- "type": "string"
2714
- }
2715
- },
2716
- "required": [
2717
- "kind",
2718
- "sectionId"
2719
- ]
2720
- },
2721
- "headerFooterKind": {
2722
- "enum": [
2723
- "header",
2724
- "footer"
2725
- ]
2726
- },
2727
- "variant": {
2728
- "enum": [
2729
- "default",
2730
- "first",
2731
- "even"
2732
- ]
2733
- },
2734
- "resolution": {
2735
- "enum": [
2736
- "effective",
2737
- "explicit"
2738
- ]
2739
- },
2740
- "onWrite": {
2741
- "enum": [
2742
- "materializeIfInherited",
2743
- "editResolvedPart",
2744
- "error"
2745
- ]
2746
- }
2747
- },
2748
- "required": [
2749
- "kind",
2750
- "storyType",
2751
- "section",
2752
- "headerFooterKind",
2753
- "variant"
2754
- ]
2755
- },
2756
- {
2757
- "type": "object",
2758
- "properties": {
2759
- "kind": {
2760
- "const": "story",
2761
- "type": "string"
2762
- },
2763
- "storyType": {
2764
- "const": "headerFooterPart",
2765
- "type": "string"
2766
- },
2767
- "refId": {
2768
- "type": "string"
2769
- }
2770
- },
2771
- "required": [
2772
- "kind",
2773
- "storyType",
2774
- "refId"
2775
- ]
2776
- },
2777
- {
2778
- "type": "object",
2779
- "properties": {
2780
- "kind": {
2781
- "const": "story",
2782
- "type": "string"
2783
- },
2784
- "storyType": {
2785
- "const": "footnote",
2786
- "type": "string"
2787
- },
2788
- "noteId": {
2789
- "type": "string"
2790
- }
2791
- },
2792
- "required": [
2793
- "kind",
2794
- "storyType",
2795
- "noteId"
2796
- ]
2797
- },
2798
- {
2799
- "type": "object",
2800
- "properties": {
2801
- "kind": {
2802
- "const": "story",
2803
- "type": "string"
2804
- },
2805
- "storyType": {
2806
- "const": "endnote",
2807
- "type": "string"
2808
- },
2809
- "noteId": {
2810
- "type": "string"
2811
- }
2812
- },
2813
- "required": [
2814
- "kind",
2815
- "storyType",
2816
- "noteId"
2817
- ]
2818
- }
2819
- ]
2820
- },
2821
1954
  "expectedRevision": {
2822
1955
  "type": "string",
2823
- "description": "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision."
1956
+ "description": "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision. Only for action 'preview'. Omit for other actions."
2824
1957
  },
2825
1958
  "atomic": {
2826
1959
  "type": "boolean",
@@ -4743,7 +3876,7 @@
4743
3876
  },
4744
3877
  "force": {
4745
3878
  "type": "boolean",
4746
- "description": "Bypass confirmation checks."
3879
+ "description": "Bypass confirmation checks. Only for action 'apply'. Omit for other actions."
4747
3880
  }
4748
3881
  },
4749
3882
  "required": [