@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
  "input_schema": {
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": [
@@ -400,159 +280,13 @@
400
280
  ],
401
281
  "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}."
402
282
  },
403
- "in": {
404
- "oneOf": [
405
- {
406
- "type": "object",
407
- "properties": {
408
- "kind": {
409
- "const": "story",
410
- "type": "string"
411
- },
412
- "storyType": {
413
- "const": "body",
414
- "type": "string"
415
- }
416
- },
417
- "required": [
418
- "kind",
419
- "storyType"
420
- ]
421
- },
422
- {
423
- "type": "object",
424
- "properties": {
425
- "kind": {
426
- "const": "story",
427
- "type": "string"
428
- },
429
- "storyType": {
430
- "const": "headerFooterSlot",
431
- "type": "string"
432
- },
433
- "section": {
434
- "type": "object",
435
- "properties": {
436
- "kind": {
437
- "const": "section",
438
- "type": "string"
439
- },
440
- "sectionId": {
441
- "type": "string"
442
- }
443
- },
444
- "required": [
445
- "kind",
446
- "sectionId"
447
- ]
448
- },
449
- "headerFooterKind": {
450
- "enum": [
451
- "header",
452
- "footer"
453
- ]
454
- },
455
- "variant": {
456
- "enum": [
457
- "default",
458
- "first",
459
- "even"
460
- ]
461
- },
462
- "resolution": {
463
- "enum": [
464
- "effective",
465
- "explicit"
466
- ]
467
- },
468
- "onWrite": {
469
- "enum": [
470
- "materializeIfInherited",
471
- "editResolvedPart",
472
- "error"
473
- ]
474
- }
475
- },
476
- "required": [
477
- "kind",
478
- "storyType",
479
- "section",
480
- "headerFooterKind",
481
- "variant"
482
- ]
483
- },
484
- {
485
- "type": "object",
486
- "properties": {
487
- "kind": {
488
- "const": "story",
489
- "type": "string"
490
- },
491
- "storyType": {
492
- "const": "headerFooterPart",
493
- "type": "string"
494
- },
495
- "refId": {
496
- "type": "string"
497
- }
498
- },
499
- "required": [
500
- "kind",
501
- "storyType",
502
- "refId"
503
- ]
504
- },
505
- {
506
- "type": "object",
507
- "properties": {
508
- "kind": {
509
- "const": "story",
510
- "type": "string"
511
- },
512
- "storyType": {
513
- "const": "footnote",
514
- "type": "string"
515
- },
516
- "noteId": {
517
- "type": "string"
518
- }
519
- },
520
- "required": [
521
- "kind",
522
- "storyType",
523
- "noteId"
524
- ]
525
- },
526
- {
527
- "type": "object",
528
- "properties": {
529
- "kind": {
530
- "const": "story",
531
- "type": "string"
532
- },
533
- "storyType": {
534
- "const": "endnote",
535
- "type": "string"
536
- },
537
- "noteId": {
538
- "type": "string"
539
- }
540
- },
541
- "required": [
542
- "kind",
543
- "storyType",
544
- "noteId"
545
- ]
546
- }
547
- ]
548
- },
549
283
  "value": {
550
284
  "type": "string",
551
- "description": "Text content to insert."
285
+ "description": "Text content to insert. Only for action 'insert'. Omit for other actions."
552
286
  },
553
287
  "type": {
554
288
  "type": "string",
555
- "description": "Content format: 'text' (default), 'markdown', or 'html'.",
289
+ "description": "Content format: 'text' (default), 'markdown', or 'html'. Only for action 'insert'. Omit for other actions.",
556
290
  "enum": [
557
291
  "text",
558
292
  "markdown",
@@ -577,11 +311,11 @@
577
311
  }
578
312
  }
579
313
  ],
580
- "description": "Document fragment to insert (structured content)."
314
+ "description": "Document fragment to insert (structured content). Only for actions 'insert', 'replace'. Omit for other actions."
581
315
  },
582
316
  "placement": {
583
317
  "type": "string",
584
- "description": "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'.",
318
+ "description": "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'. Only for action 'insert'. Omit for other actions.",
585
319
  "enum": [
586
320
  "before",
587
321
  "after",
@@ -599,7 +333,7 @@
599
333
  ]
600
334
  }
601
335
  },
602
- "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables."
336
+ "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables. Only for actions 'insert', 'replace'. Omit for other actions."
603
337
  },
604
338
  "blockId": {
605
339
  "type": "string",
@@ -615,11 +349,11 @@
615
349
  },
616
350
  "offset": {
617
351
  "type": "number",
618
- "description": "Character offset for insertion (alias for --start/--end with same value)."
352
+ "description": "Character offset for insertion (alias for --start/--end with same value). Only for action 'insert'. Omit for other actions."
619
353
  },
620
354
  "text": {
621
355
  "type": "string",
622
- "description": "Replacement text content."
356
+ "description": "Replacement text content. Only for action 'replace'. Omit for other actions."
623
357
  },
624
358
  "behavior": {
625
359
  "type": "string",
@@ -627,7 +361,7 @@
627
361
  "selection",
628
362
  "exact"
629
363
  ],
630
- "description": "Delete behavior: 'selection' (default) or 'exact'."
364
+ "description": "Delete behavior: 'selection' (default) or 'exact'. Only for action 'delete'. Omit for other actions."
631
365
  }
632
366
  },
633
367
  "required": [
@@ -638,7 +372,7 @@
638
372
  },
639
373
  {
640
374
  "name": "superdoc_format",
641
- "description": "Change text and paragraph formatting",
375
+ "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.",
642
376
  "input_schema": {
643
377
  "type": "object",
644
378
  "properties": {
@@ -829,152 +563,6 @@
829
563
  ],
830
564
  "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'."
831
565
  },
832
- "in": {
833
- "oneOf": [
834
- {
835
- "type": "object",
836
- "properties": {
837
- "kind": {
838
- "const": "story",
839
- "type": "string"
840
- },
841
- "storyType": {
842
- "const": "body",
843
- "type": "string"
844
- }
845
- },
846
- "required": [
847
- "kind",
848
- "storyType"
849
- ]
850
- },
851
- {
852
- "type": "object",
853
- "properties": {
854
- "kind": {
855
- "const": "story",
856
- "type": "string"
857
- },
858
- "storyType": {
859
- "const": "headerFooterSlot",
860
- "type": "string"
861
- },
862
- "section": {
863
- "type": "object",
864
- "properties": {
865
- "kind": {
866
- "const": "section",
867
- "type": "string"
868
- },
869
- "sectionId": {
870
- "type": "string"
871
- }
872
- },
873
- "required": [
874
- "kind",
875
- "sectionId"
876
- ]
877
- },
878
- "headerFooterKind": {
879
- "enum": [
880
- "header",
881
- "footer"
882
- ]
883
- },
884
- "variant": {
885
- "enum": [
886
- "default",
887
- "first",
888
- "even"
889
- ]
890
- },
891
- "resolution": {
892
- "enum": [
893
- "effective",
894
- "explicit"
895
- ]
896
- },
897
- "onWrite": {
898
- "enum": [
899
- "materializeIfInherited",
900
- "editResolvedPart",
901
- "error"
902
- ]
903
- }
904
- },
905
- "required": [
906
- "kind",
907
- "storyType",
908
- "section",
909
- "headerFooterKind",
910
- "variant"
911
- ]
912
- },
913
- {
914
- "type": "object",
915
- "properties": {
916
- "kind": {
917
- "const": "story",
918
- "type": "string"
919
- },
920
- "storyType": {
921
- "const": "headerFooterPart",
922
- "type": "string"
923
- },
924
- "refId": {
925
- "type": "string"
926
- }
927
- },
928
- "required": [
929
- "kind",
930
- "storyType",
931
- "refId"
932
- ]
933
- },
934
- {
935
- "type": "object",
936
- "properties": {
937
- "kind": {
938
- "const": "story",
939
- "type": "string"
940
- },
941
- "storyType": {
942
- "const": "footnote",
943
- "type": "string"
944
- },
945
- "noteId": {
946
- "type": "string"
947
- }
948
- },
949
- "required": [
950
- "kind",
951
- "storyType",
952
- "noteId"
953
- ]
954
- },
955
- {
956
- "type": "object",
957
- "properties": {
958
- "kind": {
959
- "const": "story",
960
- "type": "string"
961
- },
962
- "storyType": {
963
- "const": "endnote",
964
- "type": "string"
965
- },
966
- "noteId": {
967
- "type": "string"
968
- }
969
- },
970
- "required": [
971
- "kind",
972
- "storyType",
973
- "noteId"
974
- ]
975
- }
976
- ]
977
- },
978
566
  "inline": {
979
567
  "type": "object",
980
568
  "properties": {
@@ -1234,27 +822,15 @@
1234
822
  "type": "boolean"
1235
823
  }
1236
824
  },
1237
- "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."
825
+ "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."
1238
826
  },
1239
827
  "ref": {
1240
828
  "type": "string",
1241
- "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."
1242
- },
1243
- "blockId": {
1244
- "type": "string",
1245
- "description": "Block ID of the target paragraph."
1246
- },
1247
- "start": {
1248
- "type": "number",
1249
- "description": "Start offset within the block (character index)."
1250
- },
1251
- "end": {
1252
- "type": "number",
1253
- "description": "End offset within the block (character index)."
829
+ "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."
1254
830
  },
1255
831
  "styleId": {
1256
832
  "type": "string",
1257
- "description": "Required for action 'set_style'."
833
+ "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'."
1258
834
  },
1259
835
  "alignment": {
1260
836
  "type": "string",
@@ -1268,35 +844,35 @@
1268
844
  },
1269
845
  "left": {
1270
846
  "type": "number",
1271
- "description": "Left indentation in twips (1440 = 1 inch)."
847
+ "description": "Left indentation in twips (1440 = 1 inch). Only for action 'set_indentation'. Omit for other actions."
1272
848
  },
1273
849
  "right": {
1274
850
  "type": "number",
1275
- "description": "Right indentation in twips (1440 = 1 inch)."
851
+ "description": "Right indentation in twips (1440 = 1 inch). Only for action 'set_indentation'. Omit for other actions."
1276
852
  },
1277
853
  "firstLine": {
1278
854
  "type": "number",
1279
- "description": "First line indent in twips. Cannot be combined with hanging."
855
+ "description": "First line indent in twips. Cannot be combined with hanging. Only for action 'set_indentation'. Omit for other actions."
1280
856
  },
1281
857
  "hanging": {
1282
858
  "type": "number",
1283
- "description": "Hanging indent in twips. Cannot be combined with firstLine."
859
+ "description": "Hanging indent in twips. Cannot be combined with firstLine. Only for action 'set_indentation'. Omit for other actions."
1284
860
  },
1285
861
  "before": {
1286
862
  "type": "number",
1287
- "description": "Space before paragraph in twips (20 twips = 1pt)."
863
+ "description": "Space before paragraph in twips (20 twips = 1pt). Only for action 'set_spacing'. Omit for other actions."
1288
864
  },
1289
865
  "after": {
1290
866
  "type": "number",
1291
- "description": "Space after paragraph in twips (20 twips = 1pt)."
867
+ "description": "Space after paragraph in twips (20 twips = 1pt). Only for action 'set_spacing'. Omit for other actions."
1292
868
  },
1293
869
  "line": {
1294
870
  "type": "number",
1295
- "description": "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule."
871
+ "description": "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule. Only for action 'set_spacing'. Omit for other actions."
1296
872
  },
1297
873
  "lineRule": {
1298
874
  "type": "string",
1299
- "description": "Line spacing rule. Required when 'line' is set.",
875
+ "description": "Line spacing rule. Required when 'line' is set. Only for action 'set_spacing'. Omit for other actions.",
1300
876
  "enum": [
1301
877
  "auto",
1302
878
  "exact",
@@ -1312,194 +888,49 @@
1312
888
  "description": "Required for action 'set_direction'."
1313
889
  },
1314
890
  "alignmentPolicy": {
1315
- "type": "string",
1316
- "enum": [
1317
- "preserve",
1318
- "matchDirection"
1319
- ]
1320
- }
1321
- },
1322
- "required": [
1323
- "action"
1324
- ],
1325
- "additionalProperties": false
1326
- }
1327
- },
1328
- {
1329
- "name": "superdoc_create",
1330
- "description": "Create structural block elements",
1331
- "input_schema": {
1332
- "type": "object",
1333
- "properties": {
1334
- "action": {
1335
- "type": "string",
1336
- "enum": [
1337
- "heading",
1338
- "paragraph"
1339
- ],
1340
- "description": "The action to perform. One of: heading, paragraph."
1341
- },
1342
- "force": {
1343
- "type": "boolean",
1344
- "description": "Bypass confirmation checks."
1345
- },
1346
- "changeMode": {
1347
- "type": "string",
1348
- "enum": [
1349
- "direct",
1350
- "tracked"
1351
- ],
1352
- "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
1353
- },
1354
- "dryRun": {
1355
- "type": "boolean",
1356
- "description": "Preview the result without applying changes."
1357
- },
1358
- "in": {
1359
- "oneOf": [
1360
- {
1361
- "type": "object",
1362
- "properties": {
1363
- "kind": {
1364
- "const": "story",
1365
- "type": "string"
1366
- },
1367
- "storyType": {
1368
- "const": "body",
1369
- "type": "string"
1370
- }
1371
- },
1372
- "required": [
1373
- "kind",
1374
- "storyType"
1375
- ]
1376
- },
1377
- {
1378
- "type": "object",
1379
- "properties": {
1380
- "kind": {
1381
- "const": "story",
1382
- "type": "string"
1383
- },
1384
- "storyType": {
1385
- "const": "headerFooterSlot",
1386
- "type": "string"
1387
- },
1388
- "section": {
1389
- "type": "object",
1390
- "properties": {
1391
- "kind": {
1392
- "const": "section",
1393
- "type": "string"
1394
- },
1395
- "sectionId": {
1396
- "type": "string"
1397
- }
1398
- },
1399
- "required": [
1400
- "kind",
1401
- "sectionId"
1402
- ]
1403
- },
1404
- "headerFooterKind": {
1405
- "enum": [
1406
- "header",
1407
- "footer"
1408
- ]
1409
- },
1410
- "variant": {
1411
- "enum": [
1412
- "default",
1413
- "first",
1414
- "even"
1415
- ]
1416
- },
1417
- "resolution": {
1418
- "enum": [
1419
- "effective",
1420
- "explicit"
1421
- ]
1422
- },
1423
- "onWrite": {
1424
- "enum": [
1425
- "materializeIfInherited",
1426
- "editResolvedPart",
1427
- "error"
1428
- ]
1429
- }
1430
- },
1431
- "required": [
1432
- "kind",
1433
- "storyType",
1434
- "section",
1435
- "headerFooterKind",
1436
- "variant"
1437
- ]
1438
- },
1439
- {
1440
- "type": "object",
1441
- "properties": {
1442
- "kind": {
1443
- "const": "story",
1444
- "type": "string"
1445
- },
1446
- "storyType": {
1447
- "const": "headerFooterPart",
1448
- "type": "string"
1449
- },
1450
- "refId": {
1451
- "type": "string"
1452
- }
1453
- },
1454
- "required": [
1455
- "kind",
1456
- "storyType",
1457
- "refId"
1458
- ]
1459
- },
1460
- {
1461
- "type": "object",
1462
- "properties": {
1463
- "kind": {
1464
- "const": "story",
1465
- "type": "string"
1466
- },
1467
- "storyType": {
1468
- "const": "footnote",
1469
- "type": "string"
1470
- },
1471
- "noteId": {
1472
- "type": "string"
1473
- }
1474
- },
1475
- "required": [
1476
- "kind",
1477
- "storyType",
1478
- "noteId"
1479
- ]
1480
- },
1481
- {
1482
- "type": "object",
1483
- "properties": {
1484
- "kind": {
1485
- "const": "story",
1486
- "type": "string"
1487
- },
1488
- "storyType": {
1489
- "const": "endnote",
1490
- "type": "string"
1491
- },
1492
- "noteId": {
1493
- "type": "string"
1494
- }
1495
- },
1496
- "required": [
1497
- "kind",
1498
- "storyType",
1499
- "noteId"
1500
- ]
1501
- }
1502
- ]
891
+ "type": "string",
892
+ "enum": [
893
+ "preserve",
894
+ "matchDirection"
895
+ ],
896
+ "description": "Only for action 'set_direction'. Omit for other actions."
897
+ }
898
+ },
899
+ "required": [
900
+ "action"
901
+ ],
902
+ "additionalProperties": false
903
+ }
904
+ },
905
+ {
906
+ "name": "superdoc_create",
907
+ "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.",
908
+ "input_schema": {
909
+ "type": "object",
910
+ "properties": {
911
+ "action": {
912
+ "type": "string",
913
+ "enum": [
914
+ "heading",
915
+ "paragraph"
916
+ ],
917
+ "description": "The action to perform. One of: heading, paragraph."
918
+ },
919
+ "force": {
920
+ "type": "boolean",
921
+ "description": "Bypass confirmation checks."
922
+ },
923
+ "changeMode": {
924
+ "type": "string",
925
+ "enum": [
926
+ "direct",
927
+ "tracked"
928
+ ],
929
+ "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
930
+ },
931
+ "dryRun": {
932
+ "type": "boolean",
933
+ "description": "Preview the result without applying changes."
1503
934
  },
1504
935
  "at": {
1505
936
  "oneOf": [
@@ -1618,7 +1049,7 @@
1618
1049
  },
1619
1050
  "text": {
1620
1051
  "type": "string",
1621
- "description": "Paragraph text content."
1052
+ "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."
1622
1053
  },
1623
1054
  "input": {
1624
1055
  "type": "object",
@@ -1702,7 +1133,7 @@
1702
1133
  },
1703
1134
  "text": {
1704
1135
  "type": "string",
1705
- "description": "Text content for the new list item."
1136
+ "description": "Text content for the new list item. Only for action 'insert'. Omit for other actions."
1706
1137
  },
1707
1138
  "input": {
1708
1139
  "type": "object",
@@ -1714,7 +1145,7 @@
1714
1145
  },
1715
1146
  "mode": {
1716
1147
  "type": "string",
1717
- "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'.",
1148
+ "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'.",
1718
1149
  "enum": [
1719
1150
  "empty",
1720
1151
  "fromParagraphs"
@@ -1740,7 +1171,7 @@
1740
1171
  "nodeType",
1741
1172
  "nodeId"
1742
1173
  ],
1743
- "description": "Required when mode is 'empty'. The paragraph to create the list at. Format: {kind:'block', nodeType:'paragraph', nodeId:'<id>'}."
1174
+ "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."
1744
1175
  },
1745
1176
  "kind": {
1746
1177
  "type": "string",
@@ -1756,7 +1187,7 @@
1756
1187
  },
1757
1188
  "preset": {
1758
1189
  "type": "string",
1759
- "description": "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format.",
1190
+ "description": "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format. Only for action 'create'. Omit for other actions.",
1760
1191
  "enum": [
1761
1192
  "decimal",
1762
1193
  "decimalParenthesis",
@@ -1839,7 +1270,8 @@
1839
1270
  "required": [
1840
1271
  "version",
1841
1272
  "levels"
1842
- ]
1273
+ ],
1274
+ "description": "Only for action 'create'. Omit for other actions."
1843
1275
  },
1844
1276
  "sequence": {
1845
1277
  "oneOf": [
@@ -1870,11 +1302,12 @@
1870
1302
  "mode"
1871
1303
  ]
1872
1304
  }
1873
- ]
1305
+ ],
1306
+ "description": "Only for action 'create'. Omit for other actions."
1874
1307
  },
1875
1308
  "continuity": {
1876
1309
  "type": "string",
1877
- "description": "Numbering continuity: 'preserve' keeps numbering; 'none' restarts.",
1310
+ "description": "Numbering continuity: 'preserve' keeps numbering; 'none' restarts. Only for action 'set_type'. Omit for other actions.",
1878
1311
  "enum": [
1879
1312
  "preserve",
1880
1313
  "none"
@@ -1951,23 +1384,11 @@
1951
1384
  "blockId",
1952
1385
  "range"
1953
1386
  ],
1954
- "description": "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}."
1387
+ "description": "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}. Only for actions 'create', 'update'. Omit for other actions."
1955
1388
  },
1956
1389
  "parentId": {
1957
1390
  "type": "string",
1958
- "description": "Parent comment ID for creating a threaded reply."
1959
- },
1960
- "blockId": {
1961
- "type": "string",
1962
- "description": "Block ID of the target paragraph."
1963
- },
1964
- "start": {
1965
- "type": "number",
1966
- "description": "Start offset within the block (character index)."
1967
- },
1968
- "end": {
1969
- "type": "number",
1970
- "description": "End offset within the block (character index)."
1391
+ "description": "Parent comment ID for creating a threaded reply. Only for action 'create'. Omit for other actions."
1971
1392
  },
1972
1393
  "id": {
1973
1394
  "type": "string",
@@ -1975,26 +1396,26 @@
1975
1396
  },
1976
1397
  "status": {
1977
1398
  "type": "string",
1978
- "description": "Set comment status. Use 'resolved' to mark as resolved.",
1399
+ "description": "Set comment status. Use 'resolved' to mark as resolved. Only for action 'update'. Omit for other actions.",
1979
1400
  "enum": [
1980
1401
  "resolved"
1981
1402
  ]
1982
1403
  },
1983
1404
  "isInternal": {
1984
1405
  "type": "boolean",
1985
- "description": "When true, marks the comment as internal (hidden from external collaborators)."
1406
+ "description": "When true, marks the comment as internal (hidden from external collaborators). Only for action 'update'. Omit for other actions."
1986
1407
  },
1987
1408
  "includeResolved": {
1988
1409
  "type": "boolean",
1989
- "description": "When true, includes resolved comments in results. Default: false."
1410
+ "description": "When true, includes resolved comments in results. Default: false. Only for action 'list'. Omit for other actions."
1990
1411
  },
1991
1412
  "limit": {
1992
1413
  "type": "number",
1993
- "description": "Maximum number of comments to return."
1414
+ "description": "Maximum number of comments to return. Only for action 'list'. Omit for other actions."
1994
1415
  },
1995
1416
  "offset": {
1996
1417
  "type": "number",
1997
- "description": "Number of comments to skip for pagination."
1418
+ "description": "Number of comments to skip for pagination. Only for action 'list'. Omit for other actions."
1998
1419
  }
1999
1420
  },
2000
1421
  "required": [
@@ -2019,15 +1440,15 @@
2019
1440
  },
2020
1441
  "limit": {
2021
1442
  "type": "number",
2022
- "description": "Maximum number of tracked changes to return."
1443
+ "description": "Maximum number of tracked changes to return. Only for action 'list'. Omit for other actions."
2023
1444
  },
2024
1445
  "offset": {
2025
1446
  "type": "number",
2026
- "description": "Number of tracked changes to skip for pagination."
1447
+ "description": "Number of tracked changes to skip for pagination. Only for action 'list'. Omit for other actions."
2027
1448
  },
2028
1449
  "type": {
2029
1450
  "type": "string",
2030
- "description": "Filter by change type: 'insert', 'delete', or 'format'.",
1451
+ "description": "Filter by change type: 'insert', 'delete', or 'format'. Only for action 'list'. Omit for other actions.",
2031
1452
  "enum": [
2032
1453
  "insert",
2033
1454
  "delete",
@@ -2036,7 +1457,7 @@
2036
1457
  },
2037
1458
  "force": {
2038
1459
  "type": "boolean",
2039
- "description": "Bypass confirmation checks."
1460
+ "description": "Bypass confirmation checks. Only for action 'decide'. Omit for other actions."
2040
1461
  },
2041
1462
  "changeMode": {
2042
1463
  "type": "string",
@@ -2044,7 +1465,7 @@
2044
1465
  "direct",
2045
1466
  "tracked"
2046
1467
  ],
2047
- "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
1468
+ "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions. Only for action 'decide'. Omit for other actions."
2048
1469
  },
2049
1470
  "decision": {
2050
1471
  "type": "string",
@@ -2096,152 +1517,6 @@
2096
1517
  "input_schema": {
2097
1518
  "type": "object",
2098
1519
  "properties": {
2099
- "in": {
2100
- "oneOf": [
2101
- {
2102
- "type": "object",
2103
- "properties": {
2104
- "kind": {
2105
- "const": "story",
2106
- "type": "string"
2107
- },
2108
- "storyType": {
2109
- "const": "body",
2110
- "type": "string"
2111
- }
2112
- },
2113
- "required": [
2114
- "kind",
2115
- "storyType"
2116
- ]
2117
- },
2118
- {
2119
- "type": "object",
2120
- "properties": {
2121
- "kind": {
2122
- "const": "story",
2123
- "type": "string"
2124
- },
2125
- "storyType": {
2126
- "const": "headerFooterSlot",
2127
- "type": "string"
2128
- },
2129
- "section": {
2130
- "type": "object",
2131
- "properties": {
2132
- "kind": {
2133
- "const": "section",
2134
- "type": "string"
2135
- },
2136
- "sectionId": {
2137
- "type": "string"
2138
- }
2139
- },
2140
- "required": [
2141
- "kind",
2142
- "sectionId"
2143
- ]
2144
- },
2145
- "headerFooterKind": {
2146
- "enum": [
2147
- "header",
2148
- "footer"
2149
- ]
2150
- },
2151
- "variant": {
2152
- "enum": [
2153
- "default",
2154
- "first",
2155
- "even"
2156
- ]
2157
- },
2158
- "resolution": {
2159
- "enum": [
2160
- "effective",
2161
- "explicit"
2162
- ]
2163
- },
2164
- "onWrite": {
2165
- "enum": [
2166
- "materializeIfInherited",
2167
- "editResolvedPart",
2168
- "error"
2169
- ]
2170
- }
2171
- },
2172
- "required": [
2173
- "kind",
2174
- "storyType",
2175
- "section",
2176
- "headerFooterKind",
2177
- "variant"
2178
- ]
2179
- },
2180
- {
2181
- "type": "object",
2182
- "properties": {
2183
- "kind": {
2184
- "const": "story",
2185
- "type": "string"
2186
- },
2187
- "storyType": {
2188
- "const": "headerFooterPart",
2189
- "type": "string"
2190
- },
2191
- "refId": {
2192
- "type": "string"
2193
- }
2194
- },
2195
- "required": [
2196
- "kind",
2197
- "storyType",
2198
- "refId"
2199
- ]
2200
- },
2201
- {
2202
- "type": "object",
2203
- "properties": {
2204
- "kind": {
2205
- "const": "story",
2206
- "type": "string"
2207
- },
2208
- "storyType": {
2209
- "const": "footnote",
2210
- "type": "string"
2211
- },
2212
- "noteId": {
2213
- "type": "string"
2214
- }
2215
- },
2216
- "required": [
2217
- "kind",
2218
- "storyType",
2219
- "noteId"
2220
- ]
2221
- },
2222
- {
2223
- "type": "object",
2224
- "properties": {
2225
- "kind": {
2226
- "const": "story",
2227
- "type": "string"
2228
- },
2229
- "storyType": {
2230
- "const": "endnote",
2231
- "type": "string"
2232
- },
2233
- "noteId": {
2234
- "type": "string"
2235
- }
2236
- },
2237
- "required": [
2238
- "kind",
2239
- "storyType",
2240
- "noteId"
2241
- ]
2242
- }
2243
- ]
2244
- },
2245
1520
  "select": {
2246
1521
  "oneOf": [
2247
1522
  {
@@ -2405,155 +1680,9 @@
2405
1680
  ],
2406
1681
  "description": "The action to perform. One of: apply, preview."
2407
1682
  },
2408
- "in": {
2409
- "oneOf": [
2410
- {
2411
- "type": "object",
2412
- "properties": {
2413
- "kind": {
2414
- "const": "story",
2415
- "type": "string"
2416
- },
2417
- "storyType": {
2418
- "const": "body",
2419
- "type": "string"
2420
- }
2421
- },
2422
- "required": [
2423
- "kind",
2424
- "storyType"
2425
- ]
2426
- },
2427
- {
2428
- "type": "object",
2429
- "properties": {
2430
- "kind": {
2431
- "const": "story",
2432
- "type": "string"
2433
- },
2434
- "storyType": {
2435
- "const": "headerFooterSlot",
2436
- "type": "string"
2437
- },
2438
- "section": {
2439
- "type": "object",
2440
- "properties": {
2441
- "kind": {
2442
- "const": "section",
2443
- "type": "string"
2444
- },
2445
- "sectionId": {
2446
- "type": "string"
2447
- }
2448
- },
2449
- "required": [
2450
- "kind",
2451
- "sectionId"
2452
- ]
2453
- },
2454
- "headerFooterKind": {
2455
- "enum": [
2456
- "header",
2457
- "footer"
2458
- ]
2459
- },
2460
- "variant": {
2461
- "enum": [
2462
- "default",
2463
- "first",
2464
- "even"
2465
- ]
2466
- },
2467
- "resolution": {
2468
- "enum": [
2469
- "effective",
2470
- "explicit"
2471
- ]
2472
- },
2473
- "onWrite": {
2474
- "enum": [
2475
- "materializeIfInherited",
2476
- "editResolvedPart",
2477
- "error"
2478
- ]
2479
- }
2480
- },
2481
- "required": [
2482
- "kind",
2483
- "storyType",
2484
- "section",
2485
- "headerFooterKind",
2486
- "variant"
2487
- ]
2488
- },
2489
- {
2490
- "type": "object",
2491
- "properties": {
2492
- "kind": {
2493
- "const": "story",
2494
- "type": "string"
2495
- },
2496
- "storyType": {
2497
- "const": "headerFooterPart",
2498
- "type": "string"
2499
- },
2500
- "refId": {
2501
- "type": "string"
2502
- }
2503
- },
2504
- "required": [
2505
- "kind",
2506
- "storyType",
2507
- "refId"
2508
- ]
2509
- },
2510
- {
2511
- "type": "object",
2512
- "properties": {
2513
- "kind": {
2514
- "const": "story",
2515
- "type": "string"
2516
- },
2517
- "storyType": {
2518
- "const": "footnote",
2519
- "type": "string"
2520
- },
2521
- "noteId": {
2522
- "type": "string"
2523
- }
2524
- },
2525
- "required": [
2526
- "kind",
2527
- "storyType",
2528
- "noteId"
2529
- ]
2530
- },
2531
- {
2532
- "type": "object",
2533
- "properties": {
2534
- "kind": {
2535
- "const": "story",
2536
- "type": "string"
2537
- },
2538
- "storyType": {
2539
- "const": "endnote",
2540
- "type": "string"
2541
- },
2542
- "noteId": {
2543
- "type": "string"
2544
- }
2545
- },
2546
- "required": [
2547
- "kind",
2548
- "storyType",
2549
- "noteId"
2550
- ]
2551
- }
2552
- ]
2553
- },
2554
1683
  "expectedRevision": {
2555
1684
  "type": "string",
2556
- "description": "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision."
1685
+ "description": "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision. Only for action 'preview'. Omit for other actions."
2557
1686
  },
2558
1687
  "atomic": {
2559
1688
  "type": "boolean",
@@ -4476,7 +3605,7 @@
4476
3605
  },
4477
3606
  "force": {
4478
3607
  "type": "boolean",
4479
- "description": "Bypass confirmation checks."
3608
+ "description": "Bypass confirmation checks. Only for action 'apply'. Omit for other actions."
4480
3609
  }
4481
3610
  },
4482
3611
  "required": [