gogcli-mcp-sheets 2.23.2 → 2.24.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
-    "version": "2.23.2"
+    "version": "2.24.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli (Sheets)",
       "source": "./",
       "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
-      "version": "2.23.2",
+      "version": "2.24.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp-sheets",
   "displayName": "gogcli (Sheets)",
-  "version": "2.23.2",
+  "version": "2.24.0",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -3,7 +3,7 @@
 > [!WARNING]
 > **AI-developed project.** This codebase was built and is actively maintained by [Claude Code](https://www.anthropic.com/claude). Review all code and tool permissions before use.
 
-Extended Google Sheets [MCP](https://modelcontextprotocol.io) server via [gogcli](https://github.com/openclaw/gogcli). Includes auth tools plus 22 additional dedicated Sheets tools for tab management, formatting, named ranges, and more.
+Extended Google Sheets [MCP](https://modelcontextprotocol.io) server via [gogcli](https://github.com/openclaw/gogcli). Includes auth tools plus 55 additional dedicated Sheets tools for tab management, formatting, named ranges, Connected Sheets, and more.
 
 ## Requirements
 
@@ -44,9 +44,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 claude mcp add gogcli-sheets -- gogcli-mcp-sheets
 ```
 
-## Extra Sheets Tools (22)
+## Extra Sheets Tools (55)
 
-Plus 5 auth tools and 8 base Sheets tools (get, update, append, clear, metadata, create, find-replace, run).
+Plus 8 auth tools and 8 base Sheets tools (get, update, append, clear, metadata, create, find-replace, run) — 71 in all.
 
 | Tool | Description |
 |------|-------------|
@@ -72,8 +72,39 @@ Plus 5 auth tools and 8 base Sheets tools (get, update, append, clear, metadata,
 | `gog_sheets_notes` | Read cell notes |
 | `gog_sheets_update_note` | Add or update cell notes |
 | `gog_sheets_links` | List hyperlinks in a range |
-| `gog_sheets_set_links` | Set =HYPERLINK() cells in one call (batch) |
+| `gog_sheets_links_set` | Set =HYPERLINK() cells in one call (batch) |
 | `gog_sheets_snapshot` | Back up a whole spreadsheet before a risky edit |
+| `gog_sheets_datasource_list` | List Connected Sheets data sources (BigQuery / Looker) with sheet + execution status |
+| `gog_sheets_datasource_describe` | Full data-source spec, including its query, status and refresh schedules |
+| `gog_sheets_datasource_table_list` | List anchored data-source tables (extracts) and their A1 anchors |
+| `gog_sheets_datasource_table_describe` | Describe the extract anchored at an A1 cell |
+| `gog_sheets_datasource_table_read` | Read a bounded number of rows out of an extract |
+| `gog_sheets_list_tabs` | List tabs in a spreadsheet (sheetId, title, index, gridProperties) |
+| `gog_sheets_copy_paste` | Copy a range's values/formulas/format to another range (tiles to fill down/across). |
+| `gog_sheets_validation_get` | Read data-validation rules (dropdowns, checkboxes, conditions) on a range. |
+| `gog_sheets_validation_set` | Set a data-validation rule on a range: dropdowns, checkboxes, number/date conditions, or custom formulas. |
+| `gog_sheets_validation_clear` | Remove all data-validation rules from a range. |
+| `gog_sheets_delete_dimension` | Delete a row or column span, table-aware: intersecting tables are shrunk and their remaining data preserved. |
+| `gog_sheets_batch_update` | Update values in multiple ranges atomically with one Sheets API request. |
+| `gog_sheets_reorder_tab` | Move a tab to a specific 0-based position. |
+| `gog_sheets_chart_list` | List embedded charts in a spreadsheet. |
+| `gog_sheets_chart_get` | Get a chart's full definition (spec + position) by chart ID. |
+| `gog_sheets_chart_create` | Create an embedded chart from a JSON ChartSpec. |
+| `gog_sheets_chart_update` | Replace a chart's spec by chart ID. |
+| `gog_sheets_chart_delete` | Delete a chart by chart ID. |
+| `gog_sheets_table_list` | List Google Sheets tables in a spreadsheet. |
+| `gog_sheets_table_get` | Get a Google Sheets table by table ID. |
+| `gog_sheets_table_create` | Create a Google Sheets table over a range with typed columns. |
+| `gog_sheets_table_append` | Append data rows to a table. |
+| `gog_sheets_table_clear` | Clear all data rows from a table. |
+| `gog_sheets_table_delete` | Delete a Google Sheets table. By default preserves the table's cell values and formulas (emulates "Convert to range"); set keep_data=false to also wipe the data. |
+| `gog_sheets_banding_list` | List alternating-color banded ranges. |
+| `gog_sheets_banding_set` | Apply alternating colors to a range. |
+| `gog_sheets_banding_clear` | Remove alternating-color banding by ID or for a whole sheet. |
+| `gog_sheets_filter_set` | Set a basic filter on a range; replacing an existing filter requires replace=true. |
+| `gog_sheets_conditional_format_list` | List conditional formatting rules. |
+| `gog_sheets_conditional_format_add` | Add a conditional formatting rule to a range (boolean or gradient). |
+| `gog_sheets_conditional_format_clear` | Remove conditional formatting rules from a sheet. |
 
 ## License
 

package/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user asks to read, write, format, or manage Google She
 
 # gogcli-mcp-sheets
 
-Extended Google Sheets MCP server via [gogcli](https://github.com/openclaw/gogcli) — 35 tools: auth + 8 base Sheets + 22 extra dedicated Sheets tools.
+Extended Google Sheets MCP server via [gogcli](https://github.com/openclaw/gogcli) — 71 tools: 8 auth + 8 base Sheets + 55 extra dedicated Sheets tools.
 
 - **Source:** [github.com/chrischall/gogcli-mcp](https://github.com/chrischall/gogcli-mcp)
 
@@ -51,12 +51,43 @@ Extended Google Sheets MCP server via [gogcli](https://github.com/openclaw/gogcl
 | `gog_sheets_notes` | Read cell notes |
 | `gog_sheets_update_note` | Add or update cell notes |
 | `gog_sheets_links` | List hyperlinks in a range |
-| `gog_sheets_set_links` | Set =HYPERLINK() cells in one call (batch) |
+| `gog_sheets_links_set` | Set =HYPERLINK() cells in one call (batch) |
 | `gog_sheets_snapshot` | Back up a whole spreadsheet before a risky edit |
+| `gog_sheets_datasource_list` | List Connected Sheets data sources (BigQuery / Looker) with sheet + execution status |
+| `gog_sheets_datasource_describe` | Full data-source spec, including its query, status and refresh schedules |
+| `gog_sheets_datasource_table_list` | List anchored data-source tables (extracts) and their A1 anchors |
+| `gog_sheets_datasource_table_describe` | Describe the extract anchored at an A1 cell |
+| `gog_sheets_datasource_table_read` | Read a bounded number of rows out of an extract |
 | `gog_sheets_named_ranges_list` | List named ranges |
 | `gog_sheets_named_ranges_get` | Get a named range |
 | `gog_sheets_named_ranges_add` | Create a named range |
 | `gog_sheets_named_ranges_update` | Update a named range |
 | `gog_sheets_named_ranges_delete` | Delete a named range |
+| `gog_sheets_list_tabs` | List tabs in a spreadsheet (sheetId, title, index, gridProperties) |
+| `gog_sheets_copy_paste` | Copy a range's values/formulas/format to another range (tiles to fill down/across). |
+| `gog_sheets_validation_get` | Read data-validation rules (dropdowns, checkboxes, conditions) on a range. |
+| `gog_sheets_validation_set` | Set a data-validation rule on a range: dropdowns, checkboxes, number/date conditions, or custom formulas. |
+| `gog_sheets_validation_clear` | Remove all data-validation rules from a range. |
+| `gog_sheets_delete_dimension` | Delete a row or column span, table-aware: intersecting tables are shrunk and their remaining data preserved. |
+| `gog_sheets_batch_update` | Update values in multiple ranges atomically with one Sheets API request. |
+| `gog_sheets_reorder_tab` | Move a tab to a specific 0-based position. |
+| `gog_sheets_chart_list` | List embedded charts in a spreadsheet. |
+| `gog_sheets_chart_get` | Get a chart's full definition (spec + position) by chart ID. |
+| `gog_sheets_chart_create` | Create an embedded chart from a JSON ChartSpec. |
+| `gog_sheets_chart_update` | Replace a chart's spec by chart ID. |
+| `gog_sheets_chart_delete` | Delete a chart by chart ID. |
+| `gog_sheets_table_list` | List Google Sheets tables in a spreadsheet. |
+| `gog_sheets_table_get` | Get a Google Sheets table by table ID. |
+| `gog_sheets_table_create` | Create a Google Sheets table over a range with typed columns. |
+| `gog_sheets_table_append` | Append data rows to a table. |
+| `gog_sheets_table_clear` | Clear all data rows from a table. |
+| `gog_sheets_table_delete` | Delete a Google Sheets table. By default preserves the table's cell values and formulas (emulates "Convert to range"); set keep_data=false to also wipe the data. |
+| `gog_sheets_banding_list` | List alternating-color banded ranges. |
+| `gog_sheets_banding_set` | Apply alternating colors to a range. |
+| `gog_sheets_banding_clear` | Remove alternating-color banding by ID or for a whole sheet. |
+| `gog_sheets_filter_set` | Set a basic filter on a range; replacing an existing filter requires replace=true. |
+| `gog_sheets_conditional_format_list` | List conditional formatting rules. |
+| `gog_sheets_conditional_format_add` | Add a conditional formatting rule to a range (boolean or gradient). |
+| `gog_sheets_conditional_format_clear` | Remove conditional formatting rules from a sheet. |
 
-Plus 5 auth tools and 8 base Sheets tools.
+Plus 8 auth tools and 8 base Sheets tools.

package/dist/index.js

@@ -31731,6 +31731,7 @@ function formatAuthHealth(raw, now) {
 // ../gogcli-mcp/src/tools/auth.ts
 function registerAuthToolsWith(server, defaultServices) {
   const servicesDescribe = `Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "${defaultServices}". Prefer the narrowest set you need \u2014 requesting a service whose Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request with invalid_scope.`;
+  const extraScopesDescribe = "Additional raw OAuth scope URIs to request, comma-separated, on top of the ones `services` implies. Use for scopes no service covers \u2014 e.g. https://www.googleapis.com/auth/bigquery.readonly, required before gog_sheets_datasource_* can read BigQuery-backed Connected Sheets. Leave unset otherwise: an extra scope whose API is not enabled on the OAuth client project makes Google reject the WHOLE authorization with invalid_scope.";
   server.registerTool("gog_auth_list", {
     description: "List the Google accounts stored in gogcli, with their scopes. This reads local configuration only \u2014 it does not contact Google and does NOT tell you whether an account still works: a signed-out account whose refresh token expired or was revoked is listed here exactly like a healthy one, scopes and all. Use gog_auth_health to check whether an account can actually authenticate.",
     annotations: { readOnlyHint: true },
@@ -31780,11 +31781,14 @@ function registerAuthToolsWith(server, defaultServices) {
     annotations: { destructiveHint: true },
     inputSchema: {
       email: external_exports.string().describe("Google account email to authorize"),
-      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe)
+      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: external_exports.string().optional().describe(extraScopesDescribe)
     }
-  }, async ({ email: email3, services = defaultServices }) => {
+  }, async ({ email: email3, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(["auth", "add", email3, "--services", services], {
+      const args = ["auth", "add", email3, "--services", services];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`, "--force-consent");
+      return rawTextResult(await run(args, {
         interactive: true,
         timeout: 3e5
       }));
@@ -31796,14 +31800,14 @@ function registerAuthToolsWith(server, defaultServices) {
     description: "Begin REMOTE/headless Google authorization (step 1 of 2). Returns a sign-in URL to open in any browser \u2014 no local server or terminal on the gogcli host is needed, so this works over the hosted connector where the interactive gog_auth_add cannot. Hand the URL to the user; after they sign in, the browser is redirected to a localhost URL that fails to load \u2014 that is expected. They copy that full redirected URL (from the address bar) and you pass it to gog_auth_add_complete. The link is valid for 10 minutes. If you pass a custom `services` here, pass the SAME value to gog_auth_add_complete or the second step will not match this one.",
     inputSchema: {
       email: external_exports.string().describe("Google account email to authorize"),
-      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe)
+      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: external_exports.string().optional().describe(`${extraScopesDescribe} Pass the SAME value to gog_auth_add_complete.`)
     }
-  }, async ({ email: email3, services = defaultServices }) => {
+  }, async ({ email: email3, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(
-        ["auth", "add", email3, "--remote", "--step", "1", "--services", services, "--force-consent"],
-        { redactMode: "tokens" }
-      ));
+      const args = ["auth", "add", email3, "--remote", "--step", "1", "--services", services, "--force-consent"];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
+      return rawTextResult(await run(args, { redactMode: "tokens" }));
     } catch (err) {
       return errorResult(errorText(err));
     }
@@ -31818,25 +31822,28 @@ function registerAuthToolsWith(server, defaultServices) {
       ),
       services: external_exports.string().optional().default(defaultServices).describe(
         `Services authorized \u2014 MUST match the value passed to gog_auth_add_url. Default: "${defaultServices}".`
+      ),
+      extraScopes: external_exports.string().optional().describe(
+        "Extra OAuth scope URIs \u2014 MUST match the value passed to gog_auth_add_url, for the same reason `services` must: the two steps have to describe the same grant."
       )
     }
-  }, async ({ email: email3, redirectUrl, services = defaultServices }) => {
+  }, async ({ email: email3, redirectUrl, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(
-        [
-          "auth",
-          "add",
-          email3,
-          "--remote",
-          "--step",
-          "2",
-          "--auth-url",
-          redirectUrl,
-          "--services",
-          services,
-          "--force-consent"
-        ]
-      ));
+      const args = [
+        "auth",
+        "add",
+        email3,
+        "--remote",
+        "--step",
+        "2",
+        "--auth-url",
+        redirectUrl,
+        "--services",
+        services,
+        "--force-consent"
+      ];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
+      return rawTextResult(await run(args));
     } catch (err) {
       return errorResult(errorText(err));
     }
@@ -32020,7 +32027,7 @@ function registerSheetsTools(server) {
 }
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.23.2" : "0.0.0";
+var VERSION = true ? "2.24.0" : "0.0.0";
 
 // ../gogcli-mcp/src/auth-log.ts
 var FAILURES = /* @__PURE__ */ new Set([
@@ -33393,6 +33400,68 @@ ${errorText(err)}`
     if (parent) args.push(`--parent=${parent}`);
     return runOrDiagnose(args, { account });
   });
+  const bigQueryScopeNote = " BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission error here means the token is missing that scope, NOT that the spreadsheet has no data sources \u2014 re-authorize with gog_auth_add_url/gog_auth_add_complete (or gog_auth_add), keeping the account's EXISTING services selection and passing extraScopes=https://www.googleapis.com/auth/bigquery.readonly with forceConsent. Looker sources reuse the account's existing Looker link and need nothing extra.";
+  server.registerTool("gog_sheets_datasource_list", {
+    description: "List the Connected Sheets data sources in a spreadsheet (BigQuery or Looker), each joined with its DATA_SOURCE sheet and current execution status. This is the discovery call \u2014 start here to get the dataSourceId the describe tool wants. Deliberately does not print custom SQL; use gog_sheets_datasource_describe for that." + bigQueryScopeNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, account }) => {
+    return runOrDiagnose(["sheets", "datasource", "list", spreadsheetId], { account });
+  });
+  server.registerTool("gog_sheets_datasource_describe", {
+    description: "Describe one Connected Sheets data source in full: the complete API DataSource spec (including the BigQuery raw query, which gog_sheets_datasource_list withholds), its sheet properties, its DataExecutionStatus and any refresh schedules. Refreshes are asynchronous and this tool cannot start one \u2014 poll it until state is SUCCEEDED or FAILED, and read the status error text when it is FAILED." + bigQueryScopeNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      dataSourceId: external_exports.string().describe("Data source ID, as reported by gog_sheets_datasource_list"),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, dataSourceId, account }) => {
+    return runOrDiagnose(["sheets", "datasource", "describe", spreadsheetId, dataSourceId], { account });
+  });
+  server.registerTool("gog_sheets_datasource_table_list", {
+    description: `List the data-source tables \u2014 "extracts" in the Sheets editor \u2014 anchored in a spreadsheet. A data-source table has NO id of its own in the Sheets API: its definition lives on its top-left cell, so every extract is identified by a sheet-qualified A1 anchor (e.g. "Extracts!B3"). That anchor is what the describe and read tools take. Filter with dataSourceId to see only one source's extracts.` + bigQueryScopeNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      dataSourceId: external_exports.string().optional().describe("Only list tables belonging to this data source ID"),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, dataSourceId, account }) => {
+    const args = ["sheets", "datasource", "table", "list", spreadsheetId];
+    if (dataSourceId) args.push(`--data-source-id=${dataSourceId}`);
+    return runOrDiagnose(args, { account });
+  });
+  server.registerTool("gog_sheets_datasource_table_describe", {
+    description: "Describe the data-source table (extract) anchored at an A1 cell: its source, configured columns, sort/filter spec and row limit. Read this before gog_sheets_datasource_table_read when you need to know what the columns MEAN \u2014 the read returns values, not the extract's definition." + bigQueryScopeNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      anchor: external_exports.string().describe(`Sheet-qualified A1 anchor of the extract's top-left cell, e.g. "Extracts!B3". Get it from gog_sheets_datasource_table_list \u2014 an extract has no other identifier.`),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, anchor, account }) => {
+    return runOrDiagnose(["sheets", "datasource", "table", "describe", spreadsheetId, anchor], { account });
+  });
+  server.registerTool("gog_sheets_datasource_table_read", {
+    description: 'Read the values out of the data-source table (extract) anchored at an A1 cell. Bounded on purpose: at most maxRows data rows (gog default 1000) plus the header row, which is returned separately. The JSON reports "truncated": true when the configured extract can hold more rows than were returned \u2014 treat that exactly like a truncated search, i.e. do not conclude a value is absent from it; raise maxRows or narrow the extract instead. Use render=UNFORMATTED_VALUE for arithmetic (FORMATTED_VALUE returns display strings) or render=FORMULA to see the cell formulas.' + bigQueryScopeNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      anchor: external_exports.string().describe(`Sheet-qualified A1 anchor of the extract's top-left cell, e.g. "Extracts!B3" (from gog_sheets_datasource_table_list)`),
+      maxRows: external_exports.number().int().positive().optional().describe("Maximum data rows to read (gog default: 1000). The header row is returned separately and does not count against this."),
+      render: external_exports.enum(["FORMATTED_VALUE", "UNFORMATTED_VALUE", "FORMULA"]).optional().describe("How cell values are rendered (gog default: FORMATTED_VALUE)"),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, anchor, maxRows, render, account }) => {
+    const args = ["sheets", "datasource", "table", "read", spreadsheetId, anchor];
+    if (maxRows !== void 0) args.push(`--max-rows=${maxRows}`);
+    if (render) args.push(`--render=${render}`);
+    return runOrDiagnose(args, { account });
+  });
 }
 
 // src/index.ts

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-sheets",
   "display_name": "gogcli (Sheets)",
-  "version": "2.23.2",
+  "version": "2.24.0",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",
@@ -319,6 +319,26 @@
     {
       "name": "gog_sheets_conditional_format_clear",
       "description": "Remove conditional formatting rules from a sheet."
+    },
+    {
+      "name": "gog_sheets_datasource_list",
+      "description": "List Connected Sheets data sources (BigQuery/Looker) with their sheet and execution status"
+    },
+    {
+      "name": "gog_sheets_datasource_describe",
+      "description": "Describe one Connected Sheets data source in full, including its query, status and refresh schedules"
+    },
+    {
+      "name": "gog_sheets_datasource_table_list",
+      "description": "List anchored data-source tables (extracts) and the A1 anchors that identify them"
+    },
+    {
+      "name": "gog_sheets_datasource_table_describe",
+      "description": "Describe the data-source table (extract) anchored at an A1 cell"
+    },
+    {
+      "name": "gog_sheets_datasource_table_read",
+      "description": "Read a bounded number of rows out of a data-source table (extract)"
     }
   ],
   "compatibility": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-sheets",
-  "version": "2.23.2",
+  "version": "2.24.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-sheets",
   "description": "Extended Google Sheets MCP server via gogcli — all base tools plus full Sheets support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp-sheets"
   },
-  "version": "2.23.2",
+  "version": "2.24.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp-sheets",
-      "version": "2.23.2",
+      "version": "2.24.0",
       "transport": {
         "type": "stdio"
       },

package/src/tools/sheets-extra.ts

@@ -1006,4 +1006,109 @@ export function registerExtraSheetsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+  // Connected Sheets (gog >= 0.37.0, openclaw/gogcli#938). Read-only by
+  // construction — gog exposes no create/update/refresh/delete here, so none of
+  // these can change a data source or trigger a query.
+  //
+  // The scope is the thing to know before calling any of them: Google requires
+  // https://www.googleapis.com/auth/bigquery.readonly whenever a Sheets
+  // response CONTAINS BigQuery Connected Sheets data, and ordinary `sheets`
+  // authorization deliberately does not ask for it. So an account that reads
+  // every other part of this spreadsheet still gets a permission error here,
+  // and re-authorizing is the only fix. gog's error names the scope and the
+  // exact command; the note below is so the model does not first conclude the
+  // spreadsheet has no data sources.
+  const bigQueryScopeNote =
+    ' BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request ' +
+    'https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission ' +
+    'error here means the token is missing that scope, NOT that the spreadsheet has no data sources — re-authorize with ' +
+    'gog_auth_add_url/gog_auth_add_complete (or gog_auth_add), keeping the account\'s EXISTING services selection and ' +
+    'passing extraScopes=https://www.googleapis.com/auth/bigquery.readonly with forceConsent. Looker sources reuse the ' +
+    'account\'s existing Looker link and need nothing extra.';
+
+  server.registerTool('gog_sheets_datasource_list', {
+    description:
+      'List the Connected Sheets data sources in a spreadsheet (BigQuery or Looker), each joined with its DATA_SOURCE sheet ' +
+      'and current execution status. This is the discovery call — start here to get the dataSourceId the describe tool wants. ' +
+      'Deliberately does not print custom SQL; use gog_sheets_datasource_describe for that.' + bigQueryScopeNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, account }) => {
+    return runOrDiagnose(['sheets', 'datasource', 'list', spreadsheetId], { account });
+  });
+
+  server.registerTool('gog_sheets_datasource_describe', {
+    description:
+      'Describe one Connected Sheets data source in full: the complete API DataSource spec (including the BigQuery raw query, ' +
+      'which gog_sheets_datasource_list withholds), its sheet properties, its DataExecutionStatus and any refresh schedules. ' +
+      'Refreshes are asynchronous and this tool cannot start one — poll it until state is SUCCEEDED or FAILED, and read the ' +
+      'status error text when it is FAILED.' + bigQueryScopeNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      dataSourceId: z.string().describe('Data source ID, as reported by gog_sheets_datasource_list'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, dataSourceId, account }) => {
+    return runOrDiagnose(['sheets', 'datasource', 'describe', spreadsheetId, dataSourceId], { account });
+  });
+
+  server.registerTool('gog_sheets_datasource_table_list', {
+    description:
+      'List the data-source tables — "extracts" in the Sheets editor — anchored in a spreadsheet. A data-source table has NO ' +
+      'id of its own in the Sheets API: its definition lives on its top-left cell, so every extract is identified by a ' +
+      'sheet-qualified A1 anchor (e.g. "Extracts!B3"). That anchor is what the describe and read tools take. Filter with ' +
+      'dataSourceId to see only one source\'s extracts.' + bigQueryScopeNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      dataSourceId: z.string().optional().describe('Only list tables belonging to this data source ID'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, dataSourceId, account }) => {
+    const args = ['sheets', 'datasource', 'table', 'list', spreadsheetId];
+    if (dataSourceId) args.push(`--data-source-id=${dataSourceId}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_sheets_datasource_table_describe', {
+    description:
+      'Describe the data-source table (extract) anchored at an A1 cell: its source, configured columns, sort/filter spec and ' +
+      'row limit. Read this before gog_sheets_datasource_table_read when you need to know what the columns MEAN — the read ' +
+      'returns values, not the extract\'s definition.' + bigQueryScopeNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      anchor: z.string().describe('Sheet-qualified A1 anchor of the extract\'s top-left cell, e.g. "Extracts!B3". Get it from gog_sheets_datasource_table_list — an extract has no other identifier.'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, anchor, account }) => {
+    return runOrDiagnose(['sheets', 'datasource', 'table', 'describe', spreadsheetId, anchor], { account });
+  });
+
+  server.registerTool('gog_sheets_datasource_table_read', {
+    description:
+      'Read the values out of the data-source table (extract) anchored at an A1 cell. Bounded on purpose: at most maxRows data ' +
+      'rows (gog default 1000) plus the header row, which is returned separately. The JSON reports "truncated": true when the ' +
+      'configured extract can hold more rows than were returned — treat that exactly like a truncated search, i.e. do not ' +
+      'conclude a value is absent from it; raise maxRows or narrow the extract instead. Use render=UNFORMATTED_VALUE for ' +
+      'arithmetic (FORMATTED_VALUE returns display strings) or render=FORMULA to see the cell formulas.' + bigQueryScopeNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      anchor: z.string().describe('Sheet-qualified A1 anchor of the extract\'s top-left cell, e.g. "Extracts!B3" (from gog_sheets_datasource_table_list)'),
+      maxRows: z.number().int().positive().optional().describe('Maximum data rows to read (gog default: 1000). The header row is returned separately and does not count against this.'),
+      render: z.enum(['FORMATTED_VALUE', 'UNFORMATTED_VALUE', 'FORMULA']).optional().describe('How cell values are rendered (gog default: FORMATTED_VALUE)'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, anchor, maxRows, render, account }) => {
+    const args = ['sheets', 'datasource', 'table', 'read', spreadsheetId, anchor];
+    if (maxRows !== undefined) args.push(`--max-rows=${maxRows}`);
+    if (render) args.push(`--render=${render}`);
+    return runOrDiagnose(args, { account });
+  });
+
 }

package/tests/tools/sheets-extra.test.ts

@@ -1512,3 +1512,102 @@ describe('non-text result passthrough', () => {
     expect(result.content[0].text).toMatch(/warning/i);
   });
 });
+
+// Connected Sheets (gog >= 0.37.0, openclaw/gogcli#938). Read-only discovery
+// and bounded extract reads. An extract has no id of its own in the Sheets API,
+// so the anchor is a POSITIONAL argument, not a flag — getting that wrong makes
+// gog reject the call, which is why the arg order is pinned here.
+describe('gog_sheets_datasource_list', () => {
+  it('calls runOrDiagnose with the spreadsheet id', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_list', { spreadsheetId: 'sid' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'datasource', 'list', 'sid'], { account: undefined });
+  });
+
+  it('forwards account', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_list', { spreadsheetId: 'sid', account: 'me@x.com' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'datasource', 'list', 'sid'], { account: 'me@x.com' });
+  });
+});
+
+describe('gog_sheets_datasource_describe', () => {
+  it('passes the data source id positionally after the spreadsheet id', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_describe', { spreadsheetId: 'sid', dataSourceId: 'ds1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'describe', 'sid', 'ds1'],
+      { account: undefined },
+    );
+  });
+});
+
+describe('gog_sheets_datasource_table_list', () => {
+  it('omits --data-source-id when no filter is given', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_table_list', { spreadsheetId: 'sid' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'table', 'list', 'sid'],
+      { account: undefined },
+    );
+  });
+
+  it('filters by data source id when given', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_table_list', { spreadsheetId: 'sid', dataSourceId: 'ds1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'table', 'list', 'sid', '--data-source-id=ds1'],
+      { account: undefined },
+    );
+  });
+});
+
+describe('gog_sheets_datasource_table_describe', () => {
+  it('passes the A1 anchor positionally', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_table_describe', { spreadsheetId: 'sid', anchor: 'Extracts!B3' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'table', 'describe', 'sid', 'Extracts!B3'],
+      { account: undefined },
+    );
+  });
+});
+
+describe('gog_sheets_datasource_table_read', () => {
+  it('reads with gog defaults when no bounds are given', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_table_read', { spreadsheetId: 'sid', anchor: 'Extracts!B3' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'table', 'read', 'sid', 'Extracts!B3'],
+      { account: undefined },
+    );
+  });
+
+  it('passes --max-rows and --render', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_table_read', {
+      spreadsheetId: 'sid', anchor: 'Extracts!B3', maxRows: 250, render: 'UNFORMATTED_VALUE',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'table', 'read', 'sid', 'Extracts!B3', '--max-rows=250', '--render=UNFORMATTED_VALUE'],
+      { account: undefined },
+    );
+  });
+
+  it('rejects a render mode gog does not accept', async () => {
+    const harness = await setupHandlers();
+    const result = await harness.callTool('gog_sheets_datasource_table_read', {
+      spreadsheetId: 'sid', anchor: 'Extracts!B3', render: 'RAW',
+    });
+    expect(result.isError).toBe(true);
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+});