grr

Overview Schema Source Related Servers Discussions Admin

sheets.spreadsheets.getByDataFilter

Retrieve a spreadsheet by ID and use data filters to return only intersecting ranges or selected grid data.

Instructions

Returns the spreadsheet at the given ID. The caller must specify the spreadsheet ID. For more information, see Read, write, and search metadata. This method differs from GetSpreadsheet in that it allows selecting which subsets of spreadsheet data to return by specifying a dataFilters parameter. Multiple DataFilters can be specified. Specifying one or more data filters returns the portions of the spreadsheet that intersect ranges matched by any of the filters. By default, data within grids is not returned. You can include gri [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 GetSpreadsheetByDataFilterRequest object accepting commentsViewMode, dataFilters, excludeTablesInBandedRanges, includeGridData; pass it via params or whole via body_file Siblings over the same resource: batchUpdate, 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 GetSpreadsheetByDataFilterRequest object.
`request_body`	No	Request body of type GetSpreadsheetByDataFilterRequest: pass it via `params` (merged into the built body) or whole via `body_file`.
`spreadsheetId`	Yes	[URL path segment] The spreadsheet to request.

Output Schema

Name	Required	Description	Default
`sheets`	No
`comments`	No
`properties`	No
`dataSources`	No
`namedRanges`	No
`spreadsheetId`	No
`spreadsheetUrl`	No
`commentsViewMode`	No
`developerMetadata`	No
`dataSourceSchedules`	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 GetSpreadsheetByDataFilterRequest object."

addedInput schema / properties / request_body

Added value: +{
+  "description": "Request body of type GetSpreadsheetByDataFilterRequest: pass it via `params` (merged into the built body) or whole via `body_file`.",
+  "properties": {
+    "commentsViewMode": {
+      "enum": [
+        "COMMENTS_VIEW_MODE_UNSPECIFIED",
+        "COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS",
+        "COMMENTS_VIEW_MODE_OMITTED",
+        "COMMENTS_VIEW_MODE_INCLUDED"
+      ],
+      "type": "string"
+    },
+    "dataFilters": {
+      "items": {
+        "properties": {
+          "a1Range": {
+            "type": "string"
+          },
+          "developerMetadataLookup": {
+            "properties": {
+              "locationMatchingStrategy": {
+                "enum": [
+                  "DEVELOPER_METADATA_LOCATION_MATCHING_STRATEGY_UNSPECIFIED",
+                  "EXACT_LOCATION",
+                  "INTERSECTING_LOCATION"
+                ],
+                "type": "string"
+              },
+              "locationType": {
+                "enum": [
+                  "DEVELOPER_METADATA_LOCATION_TYPE_UNSPECIFIED",
+                  "ROW",
+                  "COLUMN",
+                  "SHEET",
+                  "SPREADSHEET"
+                ],
+                "type": "string"
+              },
+              "metadataId": {
+                "type": "integer"
+              },
+              "metadataKey": {
+                "type": "string"
+              },
+              "metadataLocation": {
+                "properties": {
+                  "dimensionRange": {
+                    "type": "object"
+                  },
+                  "locationType": {
+                    "enum": [
+                      "DEVELOPER_METADATA_LOCATION_TYPE_UNSPECIFIED",
+                      "ROW",
+                      "COLUMN",
+                      "SHEET",
+                      "SPREADSHEET"
+                    ],
+                    "type": "string"
+                  },
+                  "sheetId": {
+                    "type": "integer"
+                  },
+                  "spreadsheet": {
+                    "type": "boolean"
+                  }
+                },
+                "type": "object"
+              },
+              "metadataValue": {
+                "type": "string"
+              },
+              "visibility": {
+                "enum": [
+                  "DEVELOPER_METADATA_VISIBILITY_UNSPECIFIED",
+                  "DOCUMENT",
+                  "PROJECT"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "gridRange": {
+            "properties": {
+              "endColumnIndex": {
+                "type": "integer"
+              },
+              "endRowIndex": {
+                "type": "integer"
+              },
+              "sheetId": {
+                "type": "integer"
+              },
+              "startColumnIndex": {
+                "type": "integer"
+              },
+              "startRowIndex": {
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "excludeTablesInBandedRanges": {
+      "type": "boolean"
+    },
+    "includeGridData": {
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}

Changed2 schema fields changedOct 26, 2026

changedInput schema / properties / spreadsheetId / description

Previous value: -"The spreadsheet to request."New value: +"[URL path segment] The spreadsheet to request."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "comments": {
+      "items": {
+        "properties": {
+          "anchorId": {
+            "type": "string"
+          },
+          "commentId": {
+            "type": "string"
+          },
+          "headPost": {
+            "properties": {
+              "assigneeEmail": {
+                "type": "string"
+              },
+              "author": {
+                "properties": {
+                  "anonymous": {
+                    "type": "boolean"
+                  },
+                  "displayName": {
+                    "type": "string"
+                  },
+                  "me": {
+                    "type": "boolean"
+                  },
+                  "user": {
+                    "type": "string"
+                  }
+                },
+                "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"
+              },
+              "fromCopiedSpreadsheet": {
+                "type": "boolean"
+              },
+              "fromImportedSpreadsheet": {
+                "type": "boolean"
+              },
+              "postId": {
+                "type": "string"
+              },
+              "updateTime": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "plainTextQuote": {
+            "type": "string"
+          },
+          "replies": {
+            "items": {
+              "properties": {
+                "assigneeEmail": {
+                  "type": "string"
+                },
+                "author": {
+                  "properties": {
+                    "anonymous": {
+                      "type": "boolean"
+                    },
+                    "displayName": {
+                      "type": "string"
+                    },
+                    "me": {
+                      "type": "boolean"
+                    },
+                    "user": {
+                      "type": "string"
+                    }
+                  },
+                  "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"
+                },
+                "fromCopiedSpreadsheet": {
+                  "type": "boolean"
+                },
+                "fromImportedSpreadsheet": {
+                  "type": "boolean"
+                },
+                "postId": {
+                  "type": "string"
+                },
+                "updateTime": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "status": {
+            "enum": [
+              "STATUS_UNSPECIFIED",
+              "OPEN",
+              "RESOLVED"
+            ],
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "commentsViewMode": {
+      "enum": [
+        "COMMENTS_VIEW_MODE_UNSPECIFIED",
+        "COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS",
+        "COMMENTS_VIEW_MODE_OMITTED",
+        "COMMENTS_VIEW_MODE_INCLUDED"
+      ],
+      "type": "string"
+    },
+    "dataSourceSchedules": {
+      "items": {
+        "properties": {
+          "dailySchedule": {
+            "properties": {
+              "startTime": {
+                "properties": {
+                  "hours": {
+                    "type": "integer"
+                  },
+                  "minutes": {
+                    "type": "integer"
+                  },
+                  "nanos": {
+                    "type": "integer"
+                  },
+                  "seconds": {
+                    "type": "integer"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "monthlySchedule": {
+            "properties": {
+              "daysOfMonth": {
+                "items": {
+                  "type": "integer"
+                },
+                "type": "array"
+              },
+              "startTime": {
+                "properties": {
+                  "hours": {
+                    "type": "integer"
+                  },
+                  "minutes": {
+                    "type": "integer"
+                  },
+                  "nanos": {
+                    "type": "integer"
+                  },
+                  "seconds": {
+                    "type": "integer"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "nextRun": {
+            "properties": {
+              "endTime": {
+                "type": "string"
+              },
+              "startTime": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "refreshScope": {
+            "enum": [
+              "DATA_SOURCE_REFRESH_SCOPE_UNSPECIFIED",
+              "ALL_DATA_SOURCES"
+            ],
+            "type": "string"
+          },
+          "weeklySchedule": {
+            "properties": {
+              "daysOfWeek": {
+                "items": {
+                  "enum": [
+                    "DAY_OF_WEEK_UNSPECIFIED",
+                    "MONDAY",
+                    "TUESDAY",
+                    "WEDNESDAY",
+                    "THURSDAY",
+                    "FRIDAY",
+                    "SATURDAY",
+                    "SUNDAY"
+                  ],
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "startTime": {
+                "properties": {
+                  "hours": {
+                    "type": "integer"
+                  },
+                  "minutes": {
+                    "type": "integer"
+                  },
+                  "nanos": {
+                    "type": "integer"
+                  },
+                  "seconds": {
+                    "type": "integer"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "dataSources": {
+      "items": {
+        "properties": {
+          "calculatedColumns": {
+            "items": {
+              "properties": {
+                "formula": {
+                  "type": "string"
+                },
+                "reference": {
+                  "properties": {
+                    "name": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "dataSourceId": {
+            "type": "string"
+          },
+          "sheetId": {
+            "type": "integer"
+          },
+          "spec": {
+            "properties": {
+              "bigQuery": {
+                "properties": {
+                  "projectId": {
+                    "type": "string"
+                  },
+                  "querySpec": {
+                    "type": "object"
+                  },
+                  "tableSpec": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              },
+              "looker": {
+                "properties": {
+                  "explore": {
+                    "type": "string"
+                  },
+                  "instanceUri": {
+                    "type": "string"
+                  },
+                  "model": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "parameters": {
+                "items": {
+                  "properties": {
+                    "name": {
+                      "type": "string"
+                    },
+                    "namedRangeId": {
+                      "type": "string"
+                    },
+                    "range": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "developerMetadata": {
+      "items": {
+        "properties": {
+          "location": {
+            "properties": {
+              "dimensionRange": {
+                "properties": {
+                  "dimension": {
+                    "enum": [
+                      "DIMENSION_UNSPECIFIED",
+                      "ROWS",
+                      "COLUMNS"
+                    ],
+                    "type": "string"
+                  },
+                  "endIndex": {
+                    "type": "integer"
+                  },
+                  "sheetId": {
+                    "type": "integer"
+                  },
+                  "startIndex": {
+                    "type": "integer"
+                  }
+                },
+                "type": "object"
+              },
+              "locationType": {
+                "enum": [
+                  "DEVELOPER_METADATA_LOCATION_TYPE_UNSPECIFIED",
+                  "ROW",
+                  "COLUMN",
+                  "SHEET",
+                  "SPREADSHEET"
+                ],
+                "type": "string"
+              },
+              "sheetId": {
+                "type": "integer"
+              },
+              "spreadsheet": {
+                "type": "boolean"
+              }
+            },
+            "type": "object"
+          },
+          "metadataId": {
+            "type": "integer"
+          },
+          "metadataKey": {
+            "type": "string"
+          },
+          "metadataValue": {
+            "type": "string"
+          },
+          "visibility": {
+            "enum": [
+              "DEVELOPER_METADATA_VISIBILITY_UNSPECIFIED",
+              "DOCUMENT",
+              "PROJECT"
+            ],
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "namedRanges": {
+      "items": {
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "namedRangeId": {
+            "type": "string"
+          },
+          "range": {
+            "properties": {
+              "endColumnIndex": {
+                "type": "integer"
+              },
+              "endRowIndex": {
+                "type": "integer"
+              },
+              "sheetId": {
+                "type": "integer"
+              },
+              "startColumnIndex": {
+                "type": "integer"
+              },
+              "startRowIndex": {
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "properties": {
+      "properties": {
+        "autoRecalc": {
+          "enum": [
+            "RECALCULATION_INTERVAL_UNSPECIFIED",
+            "ON_CHANGE",
+            "MINUTE",
+            "HOUR"
+          ],
+          "type": "string"
+        },
+        "defaultFormat": {
+          "properties": {
+            "backgroundColor": {
+              "properties": {
+                "alpha": {
+                  "type": "number"
+                },
+                "blue": {
+                  "type": "number"
+                },
+                "green": {
+                  "type": "number"
+                },
+                "red": {
+                  "type": "number"
+                }
+              },
+              "type": "object"
+            },
+            "backgroundColorStyle": {
+              "properties": {
+                "rgbColor": {
+                  "type": "object"
+                },
+                "themeColor": {
+                  "enum": [
+                    "THEME_COLOR_TYPE_UNSPECIFIED",
+                    "TEXT",
+                    "BACKGROUND",
+                    "ACCENT1",
+                    "ACCENT2",
+                    "ACCENT3",
+                    "ACCENT4",
+                    "ACCENT5",
+                    "ACCENT6",
+                    "LINK"
+                  ],
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "borders": {
+              "properties": {
+                "bottom": {
+                  "type": "object"
+                },
+                "left": {
+                  "type": "object"
+                },
+                "right": {
+                  "type": "object"
+                },
+                "top": {
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "horizontalAlignment": {
+              "enum": [
+                "HORIZONTAL_ALIGN_UNSPECIFIED",
+                "LEFT",
+                "CENTER",
+                "RIGHT"
+              ],
+              "type": "string"
+            },
+            "hyperlinkDisplayType": {
+              "enum": [
+                "HYPERLINK_DISPLAY_TYPE_UNSPECIFIED",
+                "LINKED",
+                "PLAIN_TEXT"
+              ],
+              "type": "string"
+            },
+            "numberFormat": {
+              "properties": {
+                "pattern": {
+                  "type": "string"
+                },
+                "type": {
+                  "enum": [
+                    "NUMBER_FORMAT_TYPE_UNSPECIFIED",
+                    "TEXT",
+                    "NUMBER",
+                    "PERCENT",
+                    "CURRENCY",
+                    "DATE",
+                    "TIME",
+                    "DATE_TIME",
+                    "SCIENTIFIC"
+                  ],
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "padding": {
+              "properties": {
+                "bottom": {
+                  "type": "integer"
+                },
+                "left": {
+                  "type": "integer"
+                },
+                "right": {
+                  "type": "integer"
+                },
+                "top": {
+                  "type": "integer"
+                }
+              },
+              "type": "object"
+            },
+            "textDirection": {
+              "enum": [
+                "TEXT_DIRECTION_UNSPECIFIED",
+                "LEFT_TO_RIGHT",
+                "RIGHT_TO_LEFT"
+              ],
+              "type": "string"
+            },
+            "textFormat": {
+              "properties": {
+                "bold": {
+                  "type": "boolean"
+                },
+                "fontFamily": {
+                  "type": "string"
+                },
+                "fontSize": {
+                  "type": "integer"
+                },
+                "foregroundColor": {
+                  "type": "object"
+                },
+                "foregroundColorStyle": {
+                  "type": "object"
+                },
+                "italic": {
+                  "type": "boolean"
+                },
+                "link": {
+                  "type": "object"
+                },
+                "strikethrough": {
+                  "type": "boolean"
+                },
+                "underline": {
+                  "type": "boolean"
+                }
+              },
+              "type": "object"
+            },
+            "textRotation": {
+              "properties": {
+                "angle": {
+                  "type": "integer"
+                },
+                "vertical": {
+                  "type": "boolean"
+                }
+              },
+              "type": "object"
+            },
+            "verticalAlignment": {
+              "enum": [
+                "VERTICAL_ALIGN_UNSPECIFIED",
+                "TOP",
+                "MIDDLE",
+                "BOTTOM"
+              ],
+              "type": "string"
+            },
+            "wrapStrategy": {
+              "enum": [
+                "WRAP_STRATEGY_UNSPECIFIED",
+                "OVERFLOW_CELL",
+                "LEGACY_WRAP",
+                "CLIP",
+                "WRAP"
+              ],
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "importFunctionsExternalUrlAccessAllowed": {
+          "type": "boolean"
+        },
+        "iterativeCalculationSettings": {
+          "properties": {
+            "convergenceThreshold": {
+              "type": "number"
+            },
+            "maxIterations": {
+              "type": "integer"
+            }
+          },
+          "type": "object"
+        },
+        "locale": {
+          "type": "string"
+        },
+        "spreadsheetTheme": {
+          "properties": {
+            "primaryFontFamily": {
+              "type": "string"
+            },
+            "themeColors": {
+              "items": {
+                "properties": {
+                  "color": {
+                    "type": "object"
+                  },
+                  "colorType": {
+                    "enum": [
+                      "THEME_COLOR_TYPE_UNSPECIFIED",
+                      "TEXT",
+                      "BACKGROUND",
+                      "ACCENT1",
+                      "ACCENT2",
+                      "ACCENT3",
+                      "ACCENT4",
+                      "ACCENT5",
+                      "ACCENT6",
+                      "LINK"
+                    ],
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "type": "object"
+        },
+        "timeZone": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "sheets": {
+      "items": {
+        "properties": {
+          "bandedRanges": {
+            "items": {
+              "properties": {
+                "bandedRangeId": {
+                  "type": "integer"
+                },
+                "bandedRangeReference": {
+                  "type": "string"
+                },
+                "columnProperties": {
+                  "properties": {
+                    "firstBandColor": {
+                      "type": "object"
+                    },
+                    "firstBandColorStyle": {
+                      "type": "object"
+                    },
+                    "footerColor": {
+                      "type": "object"
+                    },
+                    "footerColorStyle": {
+                      "type": "object"
+                    },
+                    "headerColor": {
+                      "type": "object"
+                    },
+                    "headerColorStyle": {
+                      "type": "object"
+                    },
+                    "secondBandColor": {
+                      "type": "object"
+                    },
+                    "secondBandColorStyle": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                },
+                "range": {
+                  "properties": {
+                    "endColumnIndex": {
+                      "type": "integer"
+                    },
+                    "endRowIndex": {
+                      "type": "integer"
+                    },
+                    "sheetId": {
+                      "type": "integer"
+                    },
+                    "startColumnIndex": {
+                      "type": "integer"
+                    },
+                    "startRowIndex": {
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                },
+                "rowProperties": {
+                  "properties": {
+                    "firstBandColor": {
+                      "type": "object"
+                    },
+                    "firstBandColorStyle": {
+                      "type": "object"
+                    },
+                    "footerColor": {
+                      "type": "object"
+                    },
+                    "footerColorStyle": {
+                      "type": "object"
+                    },
+                    "headerColor": {
+                      "type": "object"
+                    },
+                    "headerColorStyle": {
+                      "type": "object"
+                    },
+                    "secondBandColor": {
+                      "type": "object"
+                    },
+                    "secondBandColorStyle": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "basicFilter": {
+            "properties": {
+              "criteria": {
+                "type": "object"
+              },
+              "filterSpecs": {
+                "items": {
+                  "properties": {
+                    "columnIndex": {
+                      "type": "integer"
+                    },
+                    "dataSourceColumnReference": {
+                      "type": "object"
+                    },
+                    "filterCriteria": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "range": {
+                "properties": {
+                  "endColumnIndex": {
+                    "type": "integer"
+                  },
+                  "endRowIndex": {
+                    "type": "integer"
+                  },
+                  "sheetId": {
+                    "type": "integer"
+                  },
+                  "startColumnIndex": {
+                    "type": "integer"
+                  },
+                  "startRowIndex": {
+                    "type": "integer"
+                  }
+                },
+                "type": "object"
+              },
+              "sortSpecs": {
+                "items": {
+                  "properties": {
+                    "backgroundColor": {
+                      "type": "object"
+                    },
+                    "backgroundColorStyle": {
+                      "type": "object"
+                    },
+                    "dataSourceColumnReference": {
+                      "type": "object"
+                    },
+                    "dimensionIndex": {
+                      "type": "integer"
+                    },
+                    "foregroundColor": {
+                      "type": "object"
+                    },
+                    "foregroundColorStyle": {
+                      "type": "object"
+                    },
+                    "sortOrder": {
+                      "enum": [
+                        "SORT_ORDER_UNSPECIFIED",
+                        "ASCENDING",
+                        "DESCENDING"
+                      ],
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "tableId": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "charts": {
+            "items": {
+              "properties": {
+                "border": {
+                  "properties": {
+                    "color": {
+                      "type": "object"
+                    },
+                    "colorStyle": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                },
+                "chartId": {
+                  "type": "integer"
+                },
+                "position": {
+                  "properties": {
+                    "newSheet": {
+                      "type": "boolean"
+                    },
+                    "overlayPosition": {
+                      "type": "object"
+                    },
+                    "sheetId": {
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                },
+                "spec": {
+                  "properties": {
+                    "altText": {
+                      "type": "string"
+                    },
+                    "backgroundColor": {
+                      "type": "object"
+                    },
+                    "backgroundColorStyle": {
+                      "type": "object"
+                    },
+                    "basicChart": {
+                      "type": "object"
+                    },
+                    "bubbleChart": {
+                      "type": "object"
+                    },
+                    "candlestickChart": {
+                      "type": "object"
+                    },
+                    "dataSourceChartProperties": {
+                      "type": "object"
+                    },
+                    "filterSpecs": {
+                      "items": {
+                        "type": "object"
+                      },
+                      "type": "array"
+                    },
+                    "fontName": {
+                      "type": "string"
+                    },
+                    "hiddenDimensionStrategy": {
+                      "enum": [
+                        "CHART_HIDDEN_DIMENSION_STRATEGY_UNSPECIFIED",
+                        "SKIP_HIDDEN_ROWS_AND_COLUMNS",
+                        "SKIP_HIDDEN_ROWS",
+                        "SKIP_HIDDEN_COLUMNS",
+                        "SHOW_ALL"
+                      ],
+                      "type": "string"
+                    },
+                    "histogramChart": {
+                      "type": "object"
+                    },
+                    "maximized": {
+                      "type": "boolean"
+                    },
+                    "orgChart": {
+                      "type": "object"
+                    },
+                    "pieChart": {
+                      "type": "object"
+                    },
+                    "scorecardChart": {
+                      "type": "object"
+                    },
+                    "sortSpecs": {
+                      "items": {
+                        "type": "object"
+                      },
+                      "type": "array"
+                    },
+                    "subtitle": {
+                      "type": "string"
+                    },
+                    "subtitleTextFormat": {
+                      "type": "object"
+                    },
+                    "subtitleTextPosition": {
+                      "type": "object"
+                    },
+                    "title": {
+                      "type": "string"
+                    },
+                    "titleTextFormat": {
+                      "type": "object"
+                    },
+                    "titleTextPosition": {
+                      "type": "object"
+                    },
+                    "treemapChart": {
+                      "type": "object"
+                    },
+                    "waterfallChart": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "columnGroups": {
+            "items": {
+              "properties": {
+                "collapsed": {
+                  "type": "boolean"
+                },
+                "depth": {
+                  "type": "integer"
+                },
+                "range": {
+                  "properties": {
+                    "dimension": {
+                      "enum": [
+                        "DIMENSION_UNSPECIFIED",
+                        "ROWS",
+                        "COLUMNS"
+                      ],
+                      "type": "string"
+                    },
+                    "endIndex": {
+                      "type": "integer"
+                    },
+                    "sheetId": {
+                      "type": "integer"
+                    },
+                    "startIndex": {
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "commentAnchors": {
+            "items": {
+              "properties": {
+                "anchorId": {
+                  "type": "string"
+                },
+                "range": {
+                  "properties": {
+                    "endColumnIndex": {
+                      "type": "integer"
+                    },
+                    "endRowIndex": {
+                      "type": "integer"
+                    },
+                    "sheetId": {
+                      "type": "integer"
+                    },
+                    "startColumnIndex": {
+                      "type": "integer"
+                    },
+                    "startRowIndex": {
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "conditionalFormats": {
+            "items": {
+              "properties": {
+                "booleanRule": {
+                  "properties": {
+                    "condition": {
+                      "type": "object"
+                    },
+                    "format": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                },
+                "gradientRule": {
+                  "properties": {
+                    "maxpoint": {
+                      "type": "object"
+                    },
+                    "midpoint": {
+                      "type": "object"
+                    },
+                    "minpoint": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                },
+                "ranges": {
+                  "items": {
+                    "properties": {
+                      "endColumnIndex": {
+                        "type": "integer"
+                      },
+                      "endRowIndex": {
+                        "type": "integer"
+                      },
+                      "sheetId": {
+                        "type": "integer"
+                      },
+                      "startColumnIndex": {
+                        "type": "integer"
+                      },
+                      "startRowIndex": {
+                        "type": "integer"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "data": {
+            "items": {
+              "properties": {
+                "columnMetadata": {
+                  "items": {
+                    "properties": {
+                      "dataSourceColumnReference": {
+                        "type": "object"
+                      },
+                      "developerMetadata": {
+                        "items": {
+                          "type": "object"
+                        },
+                        "type": "array"
+                      },
+                      "hiddenByFilter": {
+                        "type": "boolean"
+                      },
+                      "hiddenByUser": {
+                        "type": "boolean"
+                      },
+                      "pixelSize": {
+                        "type": "integer"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "rowData": {
+                  "items": {
+                    "properties": {
+                      "values": {
+                        "items": {
+                          "type": "object"
+                        },
+                        "type": "array"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "rowMetadata": {
+                  "items": {
+                    "properties": {
+                      "dataSourceColumnReference": {
+                        "type": "object"
+                      },
+                      "developerMetadata": {
+                        "items": {
+                          "type": "object"
+                        },
+                        "type": "array"
+                      },
+                      "hiddenByFilter": {
+                        "type": "boolean"
+                      },
+                      "hiddenByUser": {
+                        "type": "boolean"
+                      },
+                      "pixelSize": {
+                        "type": "integer"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "startColumn": {
+                  "type": "integer"
+                },
+                "startRow": {
+                  "type": "integer"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "developerMetadata": {
+            "items": {
+              "properties": {
+                "location": {
+                  "properties": {
+                    "dimensionRange": {
+                      "type": "object"
+                    },
+                    "locationType": {
+                      "enum": [
+                        "DEVELOPER_METADATA_LOCATION_TYPE_UNSPECIFIED",
+                        "ROW",
+                        "COLUMN",
+                        "SHEET",
+                        "SPREADSHEET"
+                      ],
+                      "type": "string"
+                    },
+                    "sheetId": {
+                      "type": "integer"
+                    },
+                    "spreadsheet": {
+                      "type": "boolean"
+                    }
+                  },
+                  "type": "object"
+                },
+                "metadataId": {
+                  "type": "integer"
+                },
+                "metadataKey": {
+                  "type": "string"
+                },
+                "metadataValue": {
+                  "type": "string"
+                },
+                "visibility": {
+                  "enum": [
+                    "DEVELOPER_METADATA_VISIBILITY_UNSPECIFIED",
+                    "DOCUMENT",
+                    "PROJECT"
+                  ],
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "filterViews": {
+            "items": {
+              "properties": {
+                "criteria": {
+                  "type": "object"
+                },
+                "filterSpecs": {
+                  "items": {
+                    "properties": {
+                      "columnIndex": {
+                        "type": "integer"
+                      },
+                      "dataSourceColumnReference": {
+                        "type": "object"
+                      },
+                      "filterCriteria": {
+                        "type": "object"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "filterViewId": {
+                  "type": "integer"
+                },
+                "namedRangeId": {
+                  "type": "string"
+                },
+                "range": {
+                  "properties": {
+                    "endColumnIndex": {
+                      "type": "integer"
+                    },
+                    "endRowIndex": {
+                      "type": "integer"
+                    },
+                    "sheetId": {
+                      "type": "integer"
+                    },
+                    "startColumnIndex": {
+                      "type": "integer"
+                    },
+                    "startRowIndex": {
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                },
+                "sortSpecs": {
+                  "items": {
+                    "properties": {
+                      "backgroundColor": {
+                        "type": "object"
+                      },
+                      "backgroundColorStyle": {
+                        "type": "object"
+                      },
+                      "dataSourceColumnReference": {
+                        "type": "object"
+                      },
+                      "dimensionIndex": {
+                        "type": "integer"
+                      },
+                      "foregroundColor": {
+                        "type": "object"
+                      },
+                      "foregroundColorStyle": {
+                        "type": "object"
+                      },
+                      "sortOrder": {
+                        "enum": [
+                          "SORT_ORDER_UNSPECIFIED",
+                          "ASCENDING",
+                          "DESCENDING"
+                        ],
+                        "type": "string"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "tableId": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "merges": {
+            "items": {
+              "properties": {
+                "endColumnIndex": {
+                  "type": "integer"
+                },
+                "endRowIndex": {
+                  "type": "integer"
+                },
+                "sheetId": {
+                  "type": "integer"
+                },
+                "startColumnIndex": {
+                  "type": "integer"
+                },
+                "startRowIndex": {
+                  "type": "integer"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "properties": {
+            "properties": {
+              "dataSourceSheetProperties": {
+                "properties": {
+                  "columns": {
+                    "items": {
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  "dataExecutionStatus": {
+                    "type": "object"
+                  },
+                  "dataSourceId": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "gridProperties": {
+                "properties": {
+                  "columnCount": {
+                    "type": "integer"
+                  },
+                  "columnGroupControlAfter": {
+                    "type": "boolean"
+                  },
+                  "frozenColumnCount": {
+                    "type": "integer"
+                  },
+                  "frozenRowCount": {
+                    "type": "integer"
+                  },
+                  "hideGridlines": {
+                    "type": "boolean"
+                  },
+                  "rowCount": {
+                    "type": "integer"
+                  },
+                  "rowGroupControlAfter": {
+                    "type": "boolean"
+                  }
+                },
+                "type": "object"
+              },
+              "hidden": {
+                "type": "boolean"
+              },
+              "index": {
+                "type": "integer"
+              },
+              "rightToLeft": {
+                "type": "boolean"
+              },
+              "sheetId": {
+                "type": "integer"
+              },
+              "sheetType": {
+                "enum": [
+                  "SHEET_TYPE_UNSPECIFIED",
+                  "GRID",
+                  "OBJECT",
+                  "DATA_SOURCE"
+                ],
+                "type": "string"
+              },
+              "tabColor": {
+                "properties": {
+                  "alpha": {
+                    "type": "number"
+                  },
+                  "blue": {
+                    "type": "number"
+                  },
+                  "green": {
+                    "type": "number"
+                  },
+                  "red": {
+                    "type": "number"
+                  }
+                },
+                "type": "object"
+              },
+              "tabColorStyle": {
+                "properties": {
+                  "rgbColor": {
+                    "type": "object"
+                  },
+                  "themeColor": {
+                    "enum": [
+                      "THEME_COLOR_TYPE_UNSPECIFIED",
+                      "TEXT",
+                      "BACKGROUND",
+                      "ACCENT1",
+                      "ACCENT2",
+                      "ACCENT3",
+                      "ACCENT4",
+                      "ACCENT5",
+                      "ACCENT6",
+                      "LINK"
+                    ],
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "title": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "protectedRanges": {
+            "items": {
+              "properties": {
+                "description": {
+                  "type": "string"
+                },
+                "editors": {
+                  "properties": {
+                    "domainUsersCanEdit": {
+                      "type": "boolean"
+                    },
+                    "groups": {
+                      "items": {
+                        "type": "string"
+                      },
+                      "type": "array"
+                    },
+                    "users": {
+                      "items": {
+                        "type": "string"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "type": "object"
+                },
+                "namedRangeId": {
+                  "type": "string"
+                },
+                "protectedRangeId": {
+                  "type": "integer"
+                },
+                "range": {
+                  "properties": {
+                    "endColumnIndex": {
+                      "type": "integer"
+                    },
+                    "endRowIndex": {
+                      "type": "integer"
+                    },
+                    "sheetId": {
+                      "type": "integer"
+                    },
+                    "startColumnIndex": {
+                      "type": "integer"
+                    },
+                    "startRowIndex": {
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                },
+                "requestingUserCanEdit": {
+                  "type": "boolean"
+                },
+                "tableId": {
+                  "type": "string"
+                },
+                "unprotectedRanges": {
+                  "items": {
+                    "properties": {
+                      "endColumnIndex": {
+                        "type": "integer"
+                      },
+                      "endRowIndex": {
+                        "type": "integer"
+                      },
+                      "sheetId": {
+                        "type": "integer"
+                      },
+                      "startColumnIndex": {
+                        "type": "integer"
+                      },
+                      "startRowIndex": {
+                        "type": "integer"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "warningOnly": {
+                  "type": "boolean"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "rowGroups": {
+            "items": {
+              "properties": {
+                "collapsed": {
+                  "type": "boolean"
+                },
+                "depth": {
+                  "type": "integer"
+                },
+                "range": {
+                  "properties": {
+                    "dimension": {
+                      "enum": [
+                        "DIMENSION_UNSPECIFIED",
+                        "ROWS",
+                        "COLUMNS"
+                      ],
+                      "type": "string"
+                    },
+                    "endIndex": {
+                      "type": "integer"
+                    },
+                    "sheetId": {
+                      "type": "integer"
+                    },
+                    "startIndex": {
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "slicers": {
+            "items": {
+              "properties": {
+                "position": {
+                  "properties": {
+                    "newSheet": {
+                      "type": "boolean"
+                    },
+                    "overlayPosition": {
+                      "type": "object"
+                    },
+                    "sheetId": {
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                },
+                "slicerId": {
+                  "type": "integer"
+                },
+                "spec": {
+                  "properties": {
+                    "applyToPivotTables": {
+                      "type": "boolean"
+                    },
+                    "backgroundColor": {
+                      "type": "object"
+                    },
+                    "backgroundColorStyle": {
+                      "type": "object"
+                    },
+                    "columnIndex": {
+                      "type": "integer"
+                    },
+                    "dataRange": {
+                      "type": "object"
+                    },
+                    "filterCriteria": {
+                      "type": "object"
+                    },
+                    "horizontalAlignment": {
+                      "enum": [
+                        "HORIZONTAL_ALIGN_UNSPECIFIED",
+                        "LEFT",
+                        "CENTER",
+                        "RIGHT"
+                      ],
+                      "type": "string"
+                    },
+                    "textFormat": {
+                      "type": "object"
+                    },
+                    "title": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "tables": {
+            "items": {
+              "properties": {
+                "columnProperties": {
+                  "items": {
+                    "properties": {
+                      "columnIndex": {
+                        "type": "integer"
+                      },
+                      "columnName": {
+                        "type": "string"
+                      },
+                      "columnType": {
+                        "enum": [
+                          "COLUMN_TYPE_UNSPECIFIED",
+                          "DOUBLE",
+                          "CURRENCY",
+                          "PERCENT",
+                          "DATE",
+                          "TIME",
+                          "DATE_TIME",
+                          "TEXT",
+                          "BOOLEAN",
+                          "DROPDOWN",
+                          "FILES_CHIP",
+                          "PEOPLE_CHIP",
+                          "FINANCE_CHIP",
+                          "PLACE_CHIP",
+                          "RATINGS_CHIP"
+                        ],
+                        "type": "string"
+                      },
+                      "dataValidationRule": {
+                        "type": "object"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "range": {
+                  "properties": {
+                    "endColumnIndex": {
+                      "type": "integer"
+                    },
+                    "endRowIndex": {
+                      "type": "integer"
+                    },
+                    "sheetId": {
+                      "type": "integer"
+                    },
+                    "startColumnIndex": {
+                      "type": "integer"
+                    },
+                    "startRowIndex": {
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                },
+                "rowsProperties": {
+                  "properties": {
+                    "firstBandColorStyle": {
+                      "type": "object"
+                    },
+                    "footerColorStyle": {
+                      "type": "object"
+                    },
+                    "headerColorStyle": {
+                      "type": "object"
+                    },
+                    "secondBandColorStyle": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                },
+                "tableId": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "spreadsheetId": {
+      "type": "string"
+    },
+    "spreadsheetUrl": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedOct 26, 2026

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does disclose important traits: it is issued as HTTP POST, is refused under --readonly safety profiles, and returns the API response resource as JSON. It omits auth/permission requirements and ends on a truncated clause ('You can include gri'), which weakens the otherwise solid disclosure.

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?

Front-loaded and mostly efficient, but the text is a concatenation of API docs, a documentation link, and harness boilerplate, and it contains a visibly truncated sentence ('You can include gri') that wastes space without conveying meaning.

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?

An output schema exists so return values need not be explained, and the bidirectional filter semantics plus the POST/readonly caveat cover what an agent needs to invoke it correctly. The truncated default-grid-data sentence leaves a documented behavior incomplete.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: multiple DataFilters are allowed and the result is the union of portions intersecting any matched range, and it clarifies that the request body fields (commentsViewMode, dataFilters, excludeTablesInBandedRanges, includeGridData) can be passed via `params` or `body_file`.

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

Purpose5/5

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

States a specific verb and resource ('Returns the spreadsheet at the given ID') and explicitly contrasts itself with the sibling sheets.spreadsheets.get by naming the dataFilters selection capability as the differentiator. An agent can pick between the two without opening either schema.

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

Usage Guidelines4/5

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

It names the alternative (GetSpreadsheet) and the condition that selects this one (selecting subsets of data via dataFilters), plus the default that grid data is not returned unless requested. It stops short of explicit when-not-to-use guidance, but the routing signal is clear.

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

Deploy Server