grr

Overview Schema Source Related Servers Discussions Admin

docs.documents.batchUpdate

Apply multiple edits to a Google Docs document in one atomic batch; if any update is invalid, the whole request fails and no changes are applied.

Instructions

Applies one or more updates to the document. Each request is validated before being applied. If any request is not valid, then the entire request will fail and nothing will be applied. Some requests have replies to give you some information about how they are applied. Other requests do not need to return information; these each return an empty reply. The order of replies matches that of the requests. For example, suppose you call batchUpdate with four updates, and only the third one returns information. The response would have two empty replies, the reply to the third request, and another empt [HTTP POST] — creates or triggers a change; refused under --readonly safety profiles. Returns the API's response resource as JSON — request body is a JSON BatchUpdateDocumentRequest object accepting requests, writeControl; pass it via params or whole via body_file Siblings over the same resource: create, get.

Input Schema

Name	Required	Description
`query`	No	Extra KEY=VALUE query pairs for endpoints whose parameters Discovery does not describe.
`params`	No	Parameter map merged into the request; typed parameters win.
`dry_run`	No	Return the request that would be sent, without sending it.
`body_file`	No	Read the request body from this file ('-' for stdin) instead of building one from the parameters. The body is a JSON BatchUpdateDocumentRequest object.
`documentId`	Yes	[URL path segment] The ID of the document to update.
`request_body`	No	Request body of type BatchUpdateDocumentRequest: pass it via `params` (merged into the built body) or whole via `body_file`.

Output Schema

Name	Required	Description	Default
`replies`	No
`documentId`	No
`writeControl`	No
`commentUpdateState`	No
`suggestionResponses`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 26, 2026

changedInput schema / properties / body_file / description

Previous value: -"Read the request body from this file ('-' for stdin) instead of building one from the parameters."New value: +"Read the request body from this file ('-' for stdin) instead of building one from the parameters. The body is a JSON BatchUpdateDocumentRequest object."

addedInput schema / properties / request_body

Added value: +{
+  "description": "Request body of type BatchUpdateDocumentRequest: pass it via `params` (merged into the built body) or whole via `body_file`.",
+  "properties": {
+    "requests": {
+      "items": {
+        "properties": {
+          "acceptSuggestion": {
+            "properties": {
+              "suggestionId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "addCommentReply": {
+            "properties": {
+              "commentId": {
+                "type": "string"
+              },
+              "post": {
+                "properties": {
+                  "assigneeEmail": {
+                    "type": "string"
+                  },
+                  "author": {
+                    "type": "object"
+                  },
+                  "commentAction": {
+                    "enum": [
+                      "COMMENT_ACTION_TYPE_UNSPECIFIED",
+                      "NO_COMMENT_ACTION_CHANGE",
+                      "RESOLVE",
+                      "REOPEN"
+                    ],
+                    "type": "string"
+                  },
+                  "content": {
+                    "type": "string"
+                  },
+                  "contentHtml": {
+                    "type": "string"
+                  },
+                  "createTime": {
+                    "type": "string"
+                  },
+                  "deleted": {
+                    "type": "boolean"
+                  },
+                  "fromCopiedDocument": {
+                    "type": "boolean"
+                  },
+                  "fromDocumentComparison": {
+                    "type": "boolean"
+                  },
+                  "fromImportedDocument": {
+                    "type": "boolean"
+                  },
+                  "postId": {
+                    "type": "string"
+                  },
+                  "suggestionAction": {
+                    "enum": [
+                      "SUGGESTION_ACTION_TYPE_UNSPECIFIED",
+                      "NO_SUGGESTION_ACTION_CHANGE",
+                      "ACCEPT",
+                      "REJECT"
+                    ],
+                    "type": "string"
+                  },
+                  "updateTime": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "suggestionId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "addDocumentTab": {
+            "properties": {
+              "tabProperties": {
+                "properties": {
+                  "iconEmoji": {
+                    "type": "string"
+                  },
+                  "index": {
+                    "type": "integer"
+                  },
+                  "nestingLevel": {
+                    "type": "integer"
+                  },
+                  "parentTabId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "createDropdownDefinition": {
+            "properties": {
+              "dropdownDefinition": {
+                "properties": {
+                  "dropdownDefinitionId": {
+                    "type": "string"
+                  },
+                  "dropdownDefinitionProperties": {
+                    "type": "object"
+                  },
+                  "suggestedDeletionId": {
+                    "type": "string"
+                  },
+                  "suggestedDropdownDefinitionPropertiesChanges": {
+                    "type": "object"
+                  },
+                  "suggestedInsertionId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "tabId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "createFooter": {
+            "properties": {
+              "sectionBreakLocation": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "type": {
+                "enum": [
+                  "HEADER_FOOTER_TYPE_UNSPECIFIED",
+                  "DEFAULT"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "createFootnote": {
+            "properties": {
+              "endOfSegmentLocation": {
+                "properties": {
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "location": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "createHeader": {
+            "properties": {
+              "sectionBreakLocation": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "type": {
+                "enum": [
+                  "HEADER_FOOTER_TYPE_UNSPECIFIED",
+                  "DEFAULT"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "createNamedRange": {
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "range": {
+                "properties": {
+                  "endIndex": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "startIndex": {
+                    "type": "integer"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "createParagraphBullets": {
+            "properties": {
+              "bulletPreset": {
+                "enum": [
+                  "BULLET_GLYPH_PRESET_UNSPECIFIED",
+                  "BULLET_DISC_CIRCLE_SQUARE",
+                  "BULLET_DIAMONDX_ARROW3D_SQUARE",
+                  "BULLET_CHECKBOX",
+                  "BULLET_ARROW_DIAMOND_DISC",
+                  "BULLET_STAR_CIRCLE_SQUARE",
+                  "BULLET_ARROW3D_CIRCLE_SQUARE",
+                  "BULLET_LEFTTRIANGLE_DIAMOND_DISC",
+                  "BULLET_DIAMONDX_HOLLOWDIAMOND_SQUARE",
+                  "BULLET_DIAMOND_CIRCLE_SQUARE",
+                  "NUMBERED_DECIMAL_ALPHA_ROMAN",
+                  "NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS",
+                  "NUMBERED_DECIMAL_NESTED",
+                  "NUMBERED_UPPERALPHA_ALPHA_ROMAN",
+                  "NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL",
+                  "NUMBERED_ZERODECIMAL_ALPHA_ROMAN"
+                ],
+                "type": "string"
+              },
+              "range": {
+                "properties": {
+                  "endIndex": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "startIndex": {
+                    "type": "integer"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "deleteComment": {
+            "properties": {
+              "commentId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "deleteCommentReply": {
+            "properties": {
+              "commentId": {
+                "type": "string"
+              },
+              "postId": {
+                "type": "string"
+              },
+              "suggestionId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "deleteContentRange": {
+            "properties": {
+              "range": {
+                "properties": {
+                  "endIndex": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "startIndex": {
+                    "type": "integer"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "deleteDropdownDefinition": {
+            "properties": {
+              "dropdownDefinitionId": {
+                "type": "string"
+              },
+              "tabId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "deleteFooter": {
+            "properties": {
+              "footerId": {
+                "type": "string"
+              },
+              "tabId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "deleteHeader": {
+            "properties": {
+              "headerId": {
+                "type": "string"
+              },
+              "tabId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "deleteNamedRange": {
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "namedRangeId": {
+                "type": "string"
+              },
+              "tabsCriteria": {
+                "properties": {
+                  "tabIds": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "deleteParagraphBullets": {
+            "properties": {
+              "range": {
+                "properties": {
+                  "endIndex": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "startIndex": {
+                    "type": "integer"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "deletePositionedObject": {
+            "properties": {
+              "objectId": {
+                "type": "string"
+              },
+              "tabId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "deleteSuggestion": {
+            "properties": {
+              "suggestionId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "deleteTab": {
+            "properties": {
+              "tabId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "deleteTableColumn": {
+            "properties": {
+              "tableCellLocation": {
+                "properties": {
+                  "columnIndex": {
+                    "type": "integer"
+                  },
+                  "rowIndex": {
+                    "type": "integer"
+                  },
+                  "tableStartLocation": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "deleteTableRow": {
+            "properties": {
+              "tableCellLocation": {
+                "properties": {
+                  "columnIndex": {
+                    "type": "integer"
+                  },
+                  "rowIndex": {
+                    "type": "integer"
+                  },
+                  "tableStartLocation": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "insertComment": {
+            "properties": {
+              "assigneeEmailAddress": {
+                "type": "string"
+              },
+              "content": {
+                "type": "string"
+              },
+              "range": {
+                "properties": {
+                  "endIndex": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "startIndex": {
+                    "type": "integer"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "insertDate": {
+            "properties": {
+              "dateElementProperties": {
+                "properties": {
+                  "dateFormat": {
+                    "enum": [
+                      "DATE_FORMAT_UNSPECIFIED",
+                      "DATE_FORMAT_CUSTOM",
+                      "DATE_FORMAT_MONTH_DAY_ABBREVIATED",
+                      "DATE_FORMAT_MONTH_DAY_FULL",
+                      "DATE_FORMAT_MONTH_DAY_YEAR_ABBREVIATED",
+                      "DATE_FORMAT_ISO8601"
+                    ],
+                    "type": "string"
+                  },
+                  "displayText": {
+                    "type": "string"
+                  },
+                  "locale": {
+                    "type": "string"
+                  },
+                  "timeFormat": {
+                    "enum": [
+                      "TIME_FORMAT_UNSPECIFIED",
+                      "TIME_FORMAT_DISABLED",
+                      "TIME_FORMAT_HOUR_MINUTE",
+                      "TIME_FORMAT_HOUR_MINUTE_TIMEZONE"
+                    ],
+                    "type": "string"
+                  },
+                  "timeZoneId": {
+                    "type": "string"
+                  },
+                  "timestamp": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "endOfSegmentLocation": {
+                "properties": {
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "location": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "insertDropdown": {
+            "properties": {
+              "dropdownDefinitionId": {
+                "type": "string"
+              },
+              "endOfSegmentLocation": {
+                "properties": {
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "location": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "selectedOptionId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "insertInlineImage": {
+            "properties": {
+              "endOfSegmentLocation": {
+                "properties": {
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "location": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "objectSize": {
+                "properties": {
+                  "height": {
+                    "type": "object"
+                  },
+                  "width": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              },
+              "uri": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "insertPageBreak": {
+            "properties": {
+              "endOfSegmentLocation": {
+                "properties": {
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "location": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "insertPerson": {
+            "properties": {
+              "endOfSegmentLocation": {
+                "properties": {
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "location": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "personProperties": {
+                "properties": {
+                  "email": {
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "insertRichLink": {
+            "properties": {
+              "endOfSegmentLocation": {
+                "properties": {
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "location": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "richLinkProperties": {
+                "properties": {
+                  "mimeType": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string"
+                  },
+                  "uri": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "insertSectionBreak": {
+            "properties": {
+              "endOfSegmentLocation": {
+                "properties": {
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "location": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "sectionType": {
+                "enum": [
+                  "SECTION_TYPE_UNSPECIFIED",
+                  "CONTINUOUS",
+                  "NEXT_PAGE"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "insertTable": {
+            "properties": {
+              "columns": {
+                "type": "integer"
+              },
+              "endOfSegmentLocation": {
+                "properties": {
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "location": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "rows": {
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "insertTableColumn": {
+            "properties": {
+              "insertRight": {
+                "type": "boolean"
+              },
+              "tableCellLocation": {
+                "properties": {
+                  "columnIndex": {
+                    "type": "integer"
+                  },
+                  "rowIndex": {
+                    "type": "integer"
+                  },
+                  "tableStartLocation": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "insertTableRow": {
+            "properties": {
+              "insertBelow": {
+                "type": "boolean"
+              },
+              "tableCellLocation": {
+                "properties": {
+                  "columnIndex": {
+                    "type": "integer"
+                  },
+                  "rowIndex": {
+                    "type": "integer"
+                  },
+                  "tableStartLocation": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "insertText": {
+            "properties": {
+              "endOfSegmentLocation": {
+                "properties": {
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "location": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "text": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "mergeTableCells": {
+            "properties": {
+              "tableRange": {
+                "properties": {
+                  "columnSpan": {
+                    "type": "integer"
+                  },
+                  "rowSpan": {
+                    "type": "integer"
+                  },
+                  "tableCellLocation": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "pinTableHeaderRows": {
+            "properties": {
+              "pinnedHeaderRowsCount": {
+                "type": "integer"
+              },
+              "tableStartLocation": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "rejectSuggestion": {
+            "properties": {
+              "suggestionId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "replaceAllText": {
+            "properties": {
+              "containsText": {
+                "properties": {
+                  "matchCase": {
+                    "type": "boolean"
+                  },
+                  "searchByRegex": {
+                    "type": "boolean"
+                  },
+                  "text": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "replaceText": {
+                "type": "string"
+              },
+              "tabsCriteria": {
+                "properties": {
+                  "tabIds": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "replaceImage": {
+            "properties": {
+              "imageObjectId": {
+                "type": "string"
+              },
+              "imageReplaceMethod": {
+                "enum": [
+                  "IMAGE_REPLACE_METHOD_UNSPECIFIED",
+                  "CENTER_CROP"
+                ],
+                "type": "string"
+              },
+              "tabId": {
+                "type": "string"
+              },
+              "uri": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "replaceNamedRangeContent": {
+            "properties": {
+              "namedRangeId": {
+                "type": "string"
+              },
+              "namedRangeName": {
+                "type": "string"
+              },
+              "tabsCriteria": {
+                "properties": {
+                  "tabIds": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  }
+                },
+                "type": "object"
+              },
+              "text": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "unmergeTableCells": {
+            "properties": {
+              "tableRange": {
+                "properties": {
+                  "columnSpan": {
+                    "type": "integer"
+                  },
+                  "rowSpan": {
+                    "type": "integer"
+                  },
+                  "tableCellLocation": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "updateCommentPost": {
+            "properties": {
+              "commentId": {
+                "type": "string"
+              },
+              "content": {
+                "type": "string"
+              },
+              "postId": {
+                "type": "string"
+              },
+              "suggestionId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "updateDocumentStyle": {
+            "properties": {
+              "documentStyle": {
+                "properties": {
+                  "background": {
+                    "type": "object"
+                  },
+                  "defaultFooterId": {
+                    "type": "string"
+                  },
+                  "defaultHeaderId": {
+                    "type": "string"
+                  },
+                  "documentFormat": {
+                    "type": "object"
+                  },
+                  "evenPageFooterId": {
+                    "type": "string"
+                  },
+                  "evenPageHeaderId": {
+                    "type": "string"
+                  },
+                  "firstPageFooterId": {
+                    "type": "string"
+                  },
+                  "firstPageHeaderId": {
+                    "type": "string"
+                  },
+                  "flipPageOrientation": {
+                    "type": "boolean"
+                  },
+                  "marginBottom": {
+                    "type": "object"
+                  },
+                  "marginFooter": {
+                    "type": "object"
+                  },
+                  "marginHeader": {
+                    "type": "object"
+                  },
+                  "marginLeft": {
+                    "type": "object"
+                  },
+                  "marginRight": {
+                    "type": "object"
+                  },
+                  "marginTop": {
+                    "type": "object"
+                  },
+                  "pageNumberStart": {
+                    "type": "integer"
+                  },
+                  "pageSize": {
+                    "type": "object"
+                  },
+                  "useCustomHeaderFooterMargins": {
+                    "type": "boolean"
+                  },
+                  "useEvenPageHeaderFooter": {
+                    "type": "boolean"
+                  },
+                  "useFirstPageHeaderFooter": {
+                    "type": "boolean"
+                  }
+                },
+                "type": "object"
+              },
+              "fields": {
+                "type": "string"
+              },
+              "tabId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "updateDocumentTabProperties": {
+            "properties": {
+              "fields": {
+                "type": "string"
+              },
+              "tabProperties": {
+                "properties": {
+                  "iconEmoji": {
+                    "type": "string"
+                  },
+                  "index": {
+                    "type": "integer"
+                  },
+                  "nestingLevel": {
+                    "type": "integer"
+                  },
+                  "parentTabId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "updateDropdownDefinitionProperties": {
+            "properties": {
+              "dropdownDefinitionId": {
+                "type": "string"
+              },
+              "dropdownDefinitionProperties": {
+                "properties": {
+                  "options": {
+                    "items": {
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  "title": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "fields": {
+                "type": "string"
+              },
+              "selectedOptionIdReplacements": {
+                "type": "object"
+              },
+              "tabId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "updateDropdownProperties": {
+            "properties": {
+              "dropdownId": {
+                "type": "string"
+              },
+              "dropdownProperties": {
+                "properties": {
+                  "displayValue": {
+                    "type": "string"
+                  },
+                  "dropdownDefinitionId": {
+                    "type": "string"
+                  },
+                  "selectedOptionId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "fields": {
+                "type": "string"
+              },
+              "tabId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "updateNamedStyle": {
+            "properties": {
+              "fields": {
+                "type": "string"
+              },
+              "namedStyle": {
+                "properties": {
+                  "namedStyleType": {
+                    "enum": [
+                      "NAMED_STYLE_TYPE_UNSPECIFIED",
+                      "NORMAL_TEXT",
+                      "TITLE",
+                      "SUBTITLE",
+                      "HEADING_1",
+                      "HEADING_2",
+                      "HEADING_3",
+                      "HEADING_4",
+                      "HEADING_5",
+                      "HEADING_6"
+                    ],
+                    "type": "string"
+                  },
+                  "paragraphStyle": {
+                    "type": "object"
+                  },
+                  "textStyle": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              },
+              "tabId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "updateParagraphStyle": {
+            "properties": {
+              "fields": {
+                "type": "string"
+              },
+              "paragraphStyle": {
+                "properties": {
+                  "alignment": {
+                    "enum": [
+                      "ALIGNMENT_UNSPECIFIED",
+                      "START",
+                      "CENTER",
+                      "END",
+                      "JUSTIFIED"
+                    ],
+                    "type": "string"
+                  },
+                  "avoidWidowAndOrphan": {
+                    "type": "boolean"
+                  },
+                  "borderBetween": {
+                    "type": "object"
+                  },
+                  "borderBottom": {
+                    "type": "object"
+                  },
+                  "borderLeft": {
+                    "type": "object"
+                  },
+                  "borderRight": {
+                    "type": "object"
+                  },
+                  "borderTop": {
+                    "type": "object"
+                  },
+                  "direction": {
+                    "enum": [
+                      "CONTENT_DIRECTION_UNSPECIFIED",
+                      "LEFT_TO_RIGHT",
+                      "RIGHT_TO_LEFT"
+                    ],
+                    "type": "string"
+                  },
+                  "headingId": {
+                    "type": "string"
+                  },
+                  "indentEnd": {
+                    "type": "object"
+                  },
+                  "indentFirstLine": {
+                    "type": "object"
+                  },
+                  "indentStart": {
+                    "type": "object"
+                  },
+                  "keepLinesTogether": {
+                    "type": "boolean"
+                  },
+                  "keepWithNext": {
+                    "type": "boolean"
+                  },
+                  "lineSpacing": {
+                    "type": "number"
+                  },
+                  "namedStyleType": {
+                    "enum": [
+                      "NAMED_STYLE_TYPE_UNSPECIFIED",
+                      "NORMAL_TEXT",
+                      "TITLE",
+                      "SUBTITLE",
+                      "HEADING_1",
+                      "HEADING_2",
+                      "HEADING_3",
+                      "HEADING_4",
+                      "HEADING_5",
+                      "HEADING_6"
+                    ],
+                    "type": "string"
+                  },
+                  "pageBreakBefore": {
+                    "type": "boolean"
+                  },
+                  "shading": {
+                    "type": "object"
+                  },
+                  "spaceAbove": {
+                    "type": "object"
+                  },
+                  "spaceBelow": {
+                    "type": "object"
+                  },
+                  "spacingMode": {
+                    "enum": [
+                      "SPACING_MODE_UNSPECIFIED",
+                      "NEVER_COLLAPSE",
+                      "COLLAPSE_LISTS"
+                    ],
+                    "type": "string"
+                  },
+                  "tabStops": {
+                    "items": {
+                      "type": "object"
+                    },
+                    "type": "array"
+                  }
+                },
+                "type": "object"
+              },
+              "range": {
+                "properties": {
+                  "endIndex": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "startIndex": {
+                    "type": "integer"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "updateSectionStyle": {
+            "properties": {
+              "fields": {
+                "type": "string"
+              },
+              "range": {
+                "properties": {
+                  "endIndex": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "startIndex": {
+                    "type": "integer"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "sectionStyle": {
+                "properties": {
+                  "columnProperties": {
+                    "items": {
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  "columnSeparatorStyle": {
+                    "enum": [
+                      "COLUMN_SEPARATOR_STYLE_UNSPECIFIED",
+                      "NONE",
+                      "BETWEEN_EACH_COLUMN"
+                    ],
+                    "type": "string"
+                  },
+                  "contentDirection": {
+                    "enum": [
+                      "CONTENT_DIRECTION_UNSPECIFIED",
+                      "LEFT_TO_RIGHT",
+                      "RIGHT_TO_LEFT"
+                    ],
+                    "type": "string"
+                  },
+                  "defaultFooterId": {
+                    "type": "string"
+                  },
+                  "defaultHeaderId": {
+                    "type": "string"
+                  },
+                  "evenPageFooterId": {
+                    "type": "string"
+                  },
+                  "evenPageHeaderId": {
+                    "type": "string"
+                  },
+                  "firstPageFooterId": {
+                    "type": "string"
+                  },
+                  "firstPageHeaderId": {
+                    "type": "string"
+                  },
+                  "flipPageOrientation": {
+                    "type": "boolean"
+                  },
+                  "marginBottom": {
+                    "type": "object"
+                  },
+                  "marginFooter": {
+                    "type": "object"
+                  },
+                  "marginHeader": {
+                    "type": "object"
+                  },
+                  "marginLeft": {
+                    "type": "object"
+                  },
+                  "marginRight": {
+                    "type": "object"
+                  },
+                  "marginTop": {
+                    "type": "object"
+                  },
+                  "pageNumberStart": {
+                    "type": "integer"
+                  },
+                  "sectionType": {
+                    "enum": [
+                      "SECTION_TYPE_UNSPECIFIED",
+                      "CONTINUOUS",
+                      "NEXT_PAGE"
+                    ],
+                    "type": "string"
+                  },
+                  "useFirstPageHeaderFooter": {
+                    "type": "boolean"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "updateTableCellStyle": {
+            "properties": {
+              "fields": {
+                "type": "string"
+              },
+              "tableCellStyle": {
+                "properties": {
+                  "backgroundColor": {
+                    "type": "object"
+                  },
+                  "borderBottom": {
+                    "type": "object"
+                  },
+                  "borderLeft": {
+                    "type": "object"
+                  },
+                  "borderRight": {
+                    "type": "object"
+                  },
+                  "borderTop": {
+                    "type": "object"
+                  },
+                  "columnSpan": {
+                    "type": "integer"
+                  },
+                  "contentAlignment": {
+                    "enum": [
+                      "CONTENT_ALIGNMENT_UNSPECIFIED",
+                      "CONTENT_ALIGNMENT_UNSUPPORTED",
+                      "TOP",
+                      "MIDDLE",
+                      "BOTTOM"
+                    ],
+                    "type": "string"
+                  },
+                  "paddingBottom": {
+                    "type": "object"
+                  },
+                  "paddingLeft": {
+                    "type": "object"
+                  },
+                  "paddingRight": {
+                    "type": "object"
+                  },
+                  "paddingTop": {
+                    "type": "object"
+                  },
+                  "rowSpan": {
+                    "type": "integer"
+                  }
+                },
+                "type": "object"
+              },
+              "tableRange": {
+                "properties": {
+                  "columnSpan": {
+                    "type": "integer"
+                  },
+                  "rowSpan": {
+                    "type": "integer"
+                  },
+                  "tableCellLocation": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              },
+              "tableStartLocation": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "updateTableColumnProperties": {
+            "properties": {
+              "columnIndices": {
+                "items": {
+                  "type": "integer"
+                },
+                "type": "array"
+              },
+              "fields": {
+                "type": "string"
+              },
+              "tableColumnProperties": {
+                "properties": {
+                  "width": {
+                    "type": "object"
+                  },
+                  "widthType": {
+                    "enum": [
+                      "WIDTH_TYPE_UNSPECIFIED",
+                      "EVENLY_DISTRIBUTED",
+                      "FIXED_WIDTH"
+                    ],
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "tableStartLocation": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "updateTableRowStyle": {
+            "properties": {
+              "fields": {
+                "type": "string"
+              },
+              "rowIndices": {
+                "items": {
+                  "type": "integer"
+                },
+                "type": "array"
+              },
+              "tableRowStyle": {
+                "properties": {
+                  "minRowHeight": {
+                    "type": "object"
+                  },
+                  "preventOverflow": {
+                    "type": "boolean"
+                  },
+                  "tableHeader": {
+                    "type": "boolean"
+                  }
+                },
+                "type": "object"
+              },
+              "tableStartLocation": {
+                "properties": {
+                  "index": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "updateTextStyle": {
+            "properties": {
+              "fields": {
+                "type": "string"
+              },
+              "range": {
+                "properties": {
+                  "endIndex": {
+                    "type": "integer"
+                  },
+                  "segmentId": {
+                    "type": "string"
+                  },
+                  "startIndex": {
+                    "type": "integer"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "textStyle": {
+                "properties": {
+                  "backgroundColor": {
+                    "type": "object"
+                  },
+                  "baselineOffset": {
+                    "enum": [
+                      "BASELINE_OFFSET_UNSPECIFIED",
+                      "NONE",
+                      "SUPERSCRIPT",
+                      "SUBSCRIPT"
+                    ],
+                    "type": "string"
+                  },
+                  "bold": {
+                    "type": "boolean"
+                  },
+                  "fontSize": {
+                    "type": "object"
+                  },
+                  "foregroundColor": {
+                    "type": "object"
+                  },
+                  "italic": {
+                    "type": "boolean"
+                  },
+                  "link": {
+                    "type": "object"
+                  },
+                  "smallCaps": {
+                    "type": "boolean"
+                  },
+                  "strikethrough": {
+                    "type": "boolean"
+                  },
+                  "underline": {
+                    "type": "boolean"
+                  },
+                  "weightedFontFamily": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "writeControl": {
+      "properties": {
+        "requiredRevisionId": {
+          "type": "string"
+        },
+        "targetRevisionId": {
+          "type": "string"
+        },
+        "writeMode": {
+          "enum": [
+            "WRITE_MODE_UNSPECIFIED",
+            "EDIT",
+            "SUGGEST"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

Changed2 schema fields changedOct 26, 2026

changedInput schema / properties / documentId / description

Previous value: -"The ID of the document to update."New value: +"[URL path segment] The ID of the document to update."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "commentUpdateState": {
+      "enum": [
+        "COMMENT_UPDATE_STATE_UNSPECIFIED",
+        "NO_UPDATES_REQUESTED",
+        "ALL_SAVED",
+        "ALL_FAILED_UNKNOWN_REASON"
+      ],
+      "type": "string"
+    },
+    "documentId": {
+      "type": "string"
+    },
+    "replies": {
+      "items": {
+        "properties": {
+          "addCommentReply": {
+            "properties": {
+              "post": {
+                "properties": {
+                  "assigneeEmail": {
+                    "type": "string"
+                  },
+                  "author": {
+                    "type": "object"
+                  },
+                  "commentAction": {
+                    "enum": [
+                      "COMMENT_ACTION_TYPE_UNSPECIFIED",
+                      "NO_COMMENT_ACTION_CHANGE",
+                      "RESOLVE",
+                      "REOPEN"
+                    ],
+                    "type": "string"
+                  },
+                  "content": {
+                    "type": "string"
+                  },
+                  "contentHtml": {
+                    "type": "string"
+                  },
+                  "createTime": {
+                    "type": "string"
+                  },
+                  "deleted": {
+                    "type": "boolean"
+                  },
+                  "fromCopiedDocument": {
+                    "type": "boolean"
+                  },
+                  "fromDocumentComparison": {
+                    "type": "boolean"
+                  },
+                  "fromImportedDocument": {
+                    "type": "boolean"
+                  },
+                  "postId": {
+                    "type": "string"
+                  },
+                  "suggestionAction": {
+                    "enum": [
+                      "SUGGESTION_ACTION_TYPE_UNSPECIFIED",
+                      "NO_SUGGESTION_ACTION_CHANGE",
+                      "ACCEPT",
+                      "REJECT"
+                    ],
+                    "type": "string"
+                  },
+                  "updateTime": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "addDocumentTab": {
+            "properties": {
+              "tabProperties": {
+                "properties": {
+                  "iconEmoji": {
+                    "type": "string"
+                  },
+                  "index": {
+                    "type": "integer"
+                  },
+                  "nestingLevel": {
+                    "type": "integer"
+                  },
+                  "parentTabId": {
+                    "type": "string"
+                  },
+                  "tabId": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "createDropdownDefinition": {
+            "properties": {
+              "dropdownDefinition": {
+                "properties": {
+                  "dropdownDefinitionId": {
+                    "type": "string"
+                  },
+                  "dropdownDefinitionProperties": {
+                    "type": "object"
+                  },
+                  "suggestedDeletionId": {
+                    "type": "string"
+                  },
+                  "suggestedDropdownDefinitionPropertiesChanges": {
+                    "type": "object"
+                  },
+                  "suggestedInsertionId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "createFooter": {
+            "properties": {
+              "footerId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "createFootnote": {
+            "properties": {
+              "footnoteId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "createHeader": {
+            "properties": {
+              "headerId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "createNamedRange": {
+            "properties": {
+              "namedRangeId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "insertComment": {
+            "properties": {
+              "commentThread": {
+                "properties": {
+                  "anchorId": {
+                    "type": "string"
+                  },
+                  "commentId": {
+                    "type": "string"
+                  },
+                  "headPost": {
+                    "type": "object"
+                  },
+                  "plainTextQuote": {
+                    "type": "string"
+                  },
+                  "replies": {
+                    "items": {
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  "status": {
+                    "enum": [
+                      "STATUS_UNSPECIFIED",
+                      "OPEN",
+                      "RESOLVED"
+                    ],
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "insertDropdown": {
+            "properties": {
+              "dropdown": {
+                "properties": {
+                  "dropdownId": {
+                    "type": "string"
+                  },
+                  "dropdownProperties": {
+                    "type": "object"
+                  },
+                  "suggestedDeletionIds": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "suggestedDropdownPropertiesChanges": {
+                    "type": "object"
+                  },
+                  "suggestedInsertionIds": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "suggestedTextStyleChanges": {
+                    "type": "object"
+                  },
+                  "textStyle": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "insertInlineImage": {
+            "properties": {
+              "objectId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "insertInlineSheetsChart": {
+            "properties": {
+              "objectId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "replaceAllText": {
+            "properties": {
+              "occurrencesChanged": {
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "suggestionResponses": {
+      "items": {
+        "properties": {
+          "acceptedSuggestionIds": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "createdSuggestionIds": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "deletedSuggestionIds": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "rejectedSuggestionIds": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "updatedSummarySuggestionIds": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "writeControl": {
+      "properties": {
+        "requiredRevisionId": {
+          "type": "string"
+        },
+        "targetRevisionId": {
+          "type": "string"
+        },
+        "writeMode": {
+          "enum": [
+            "WRITE_MODE_UNSPECIFIED",
+            "EDIT",
+            "SUGGEST"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

First observedOct 26, 2026

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral burden and does so well: it discloses all-or-nothing validation, reply ordering, HTTP POST mutation semantics, and refusal under read-only safety profiles. It does not cover auth requirements or quotas, but it gives the agent the key behavioral traits for invoking this mutation safely.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and atomicity, which is good, but it spends several sentences explaining reply ordering in detail even though an output schema exists. It also contains a visibly truncated phrase ('another empt') followed by appended harness metadata, which makes the overall structure feel less polished.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex batch mutation tool with a large nested request schema and an output schema, the description covers the essential context: atomic validation, request body shape, response behavior, and mutation safety. The schema supplies the detailed request types and parameter semantics, so the description is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the parameters thoroughly. The description adds that the request body accepts requests and writeControl and can be supplied via params or body_file, but this largely repeats what the schema descriptions state. Baseline 3 is appropriate because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it applies one or more updates to a document. It also names the sibling operations on the same resource (create, get), though it does not explicitly contrast batchUpdate with them. The purpose is clear enough for an agent to identify it as the document-mutation operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'Applies one or more updates to the document' and by the sibling list, but there is no explicit guidance about when to choose batchUpdate versus create/get or other update mechanisms. The atomic-failure behavior is useful context but is not usage guidance. It is minimum viable rather than explicit when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server