Skip to main content
Glama

sheets.spreadsheets.values.batchGet

Retrieves values from one or more spreadsheet ranges by ID and range notation, returning the requested cell data as JSON for batch reads.

Instructions

Returns one or more ranges of values from a spreadsheet. The caller must specify the spreadsheet ID and one or more ranges [HTTP GET]. Returns the requested resource as JSON — request bodies are built from the typed parameters (typed flags win over the params map), or read whole from body_file Siblings over the same resource: append, batchClear, batchClearByDataFilter, batchGetByDataFilter, batchUpdate, batchUpdateByDataFilter, clear, get, update.

Input Schema

NameRequiredDescriptionDefault
queryNoExtra KEY=VALUE query pairs for endpoints whose parameters Discovery does not describe.
paramsNoParameter map merged into the request; typed parameters win.
rangesNo
dry_runNoReturn the request that would be sent, without sending it.
body_fileNoRead the request body from this file ('-' for stdin) instead of building one from the parameters.
spreadsheetIdYes[URL path segment] The ID of the spreadsheet to retrieve data from.
majorDimensionNo[query parameter] The major dimension that results should use. For example, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`, then requesting `ranges=["A1:B2"],majorDimension=RO Values: `DIMENSION_UNSPECIFIED` = The default value, do not use.; `ROWS` = Operates on the rows of a sheet.; `COLUMNS` = Operates on the columns of a sheet..
valueRenderOptionNo[query parameter] How values should be represented in the output. The default render option is ValueRenderOption.FORMATTED_VALUE. Values: `FORMATTED_VALUE` = Values will be calculated & formatted in the response according to the cell's formatting. Formatting is based on the spreadsheet's locale, not the requesting user's locale. For example, if `A1` is `1.23` and `A2` is `=A1` and formatted as currency, then `A2` would return `"$1.23"`.; `UNFORMATTED_VALUE` = Values will be calculated, but not formatted in the reply. For example, if `A1` is `1.23` and `A2` is `=A1` and formatted as currency, then `A2` would return the number `1.23`.; `FORMULA` = Values will not be calculated. The reply will include the formulas. For example, if `A1` is `1.23` and `A2` is `=A1` and formatted as currency, then A2 would return `"=A1"`. Sheets treats date and time values as decimal values. This lets you perform arithmetic on them in formulas. For more information on interpreting date and time values, see [About date & time values](https://developers.google.com/workspace/sheets/api/guides/formats#about_date_time_values)..
dateTimeRenderOptionNo[query parameter] How dates, times, and durations should be represented in the output. This is ignored if value_render_option is FORMATTED_VALUE. The default dateTime render opti Values: `SERIAL_NUMBER` = Instructs date, time, datetime, and duration fields to be output as doubles in "serial number" format, as popularized by Lotus 1-2-3. The whole number portion of the value (left of the decimal) counts the days since December 30th 1899. The fractional portion (right of the decimal) counts the time as a fraction of the day. For example, January 1st 1900 at noon would be 2.5, 2 because it's 2 days after December 30th 1899, and .5 because noon is half a day. February 1st 1900 at 3pm would be 33.625. This correctly treats the year 1900 as not a leap year.; `FORMATTED_STRING` = Instructs date, time, datetime, and duration fields to be output as strings in their given number format (which depends on the spreadsheet locale)..

Output Schema

NameRequiredDescriptionDefault
valueRangesNo
spreadsheetIdNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • changedInput schema / properties / dateTimeRenderOption / description
      Previous value: -"How dates, times, and durations should be represented in the output. This is ignored if value_render_option is FORMATTED_VALUE. The default dateTime render opti"New value: +"[query parameter] How dates, times, and durations should be represented in the output. This is ignored if value_render_option is FORMATTED_VALUE. The default dateTime render opti Values: `SERIAL_NUMBER` = Instructs date, time, datetime, and duration fields to be output as doubles in \"serial number\" format, as popularized by Lotus 1-2-3. The whole number portion of the value (left of the decimal) counts the days since December 30th 1899. The fractional portion (right of the decimal) counts the time as a fraction of the day. For example, January 1st 1900 at noon would be 2.5, 2 because it's 2 days after December 30th 1899, and .5 because noon is half a day. February 1st 1900 at 3pm would be 33.625. This correctly treats the year 1900 as not a leap year.; `FORMATTED_STRING` = Instructs date, time, datetime, and duration fields to be output as strings in their given number format (which depends on the spreadsheet locale).."
    • changedInput schema / properties / majorDimension / description
      Previous value: -"The major dimension that results should use. For example, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`, then requesting `ranges=[\"A1:B2\"],majorDimension=RO"New value: +"[query parameter] The major dimension that results should use. For example, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`, then requesting `ranges=[\"A1:B2\"],majorDimension=RO Values: `DIMENSION_UNSPECIFIED` = The default value, do not use.; `ROWS` = Operates on the rows of a sheet.; `COLUMNS` = Operates on the columns of a sheet.."
    • changedInput schema / properties / ranges / items / description
      Previous value: -"The [A1 notation or R1C1 notation](https://developers.google.com/workspace/sheets/api/guides/concepts#cell) of the range to retrieve values from."New value: +"[query parameter] The [A1 notation or R1C1 notation](https://developers.google.com/workspace/sheets/api/guides/concepts#cell) of the range to retrieve values from."
    • changedInput schema / properties / spreadsheetId / description
      Previous value: -"The ID of the spreadsheet to retrieve data from."New value: +"[URL path segment] The ID of the spreadsheet to retrieve data from."
    • changedInput schema / properties / valueRenderOption / description
      Previous value: -"How values should be represented in the output. The default render option is ValueRenderOption.FORMATTED_VALUE."New value: +"[query parameter] How values should be represented in the output. The default render option is ValueRenderOption.FORMATTED_VALUE. Values: `FORMATTED_VALUE` = Values will be calculated & formatted in the response according to the cell's formatting. Formatting is based on the spreadsheet's locale, not the requesting user's locale. For example, if `A1` is `1.23` and `A2` is `=A1` and formatted as currency, then `A2` would return `\"$1.23\"`.; `UNFORMATTED_VALUE` = Values will be calculated, but not formatted in the reply. For example, if `A1` is `1.23` and `A2` is `=A1` and formatted as currency, then `A2` would return the number `1.23`.; `FORMULA` = Values will not be calculated. The reply will include the formulas. For example, if `A1` is `1.23` and `A2` is `=A1` and formatted as currency, then A2 would return `\"=A1\"`. Sheets treats date and time values as decimal values. This lets you perform arithmetic on them in formulas. For more information on interpreting date and time values, see [About date & time values](https://developers.google.com/workspace/sheets/api/guides/formats#about_date_time_values).."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "spreadsheetId": {
      +      "type": "string"
      +    },
      +    "valueRanges": {
      +      "items": {
      +        "properties": {
      +          "majorDimension": {
      +            "enum": [
      +              "DIMENSION_UNSPECIFIED",
      +              "ROWS",
      +              "COLUMNS"
      +            ],
      +            "type": "string"
      +          },
      +          "range": {
      +            "type": "string"
      +          },
      +          "values": {
      +            "items": {
      +              "items": {
      +                "type": "any"
      +              },
      +              "type": "array"
      +            },
      +            "type": "array"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
  2. First observed

TDQS

B3.3/5.0
Behavior3/5

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

With no annotations, the description carries the burden alone; '[HTTP GET]' does signal read-only semantics, and it usefully explains the request-building precedence (typed flags > `params` map > `body_file`). It says nothing about auth scopes, permission requirements, or what happens on partial/invalid ranges. An output schema exists, so return-shape disclosure is not required.

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 first two sentences are front-loaded and efficient, but the third is a run-on wrapper-boilerplate sentence, and the trailing sibling enumeration of ten names adds bulk without routing guidance. Some of that text does not earn its place.

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 read wrapper with a rich schema (89% coverage) and an output schema, the description covers the essentials: what it returns, the required inputs, and the request-construction mechanics of this generic wrapper. Only the missing when-not guidance keeps it from a 5.

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 89%, so the baseline is 3, and the description adds real value by explaining how `params`, typed flags, and `body_file` interact and which wins. It also restates the ranges requirement. The enum parameters (majorDimension, valueRenderOption, dateTimeRenderOption) get no extra narrative, but the schema documents them thoroughly.

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?

States a specific verb and resource: 'Returns one or more ranges of values from a spreadsheet', and the plural 'ranges' distinguishes it from single-range get. It names the sibling family at the end, but leaves the agent to infer which sibling is the real alternative for a single-range read.

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

Usage Guidelines2/5

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

The description never says when to use this tool instead of `get` or `batchGetByDataFilter` — it only dumps the sibling names as a list. The only usage constraint given is the requirement to specify a spreadsheet ID and at least one range, which is already a schema fact.

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

Deploy Server

Other Tools