gogcli-mcp 2.23.1 → 2.24.0

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "2.23.1",
+  "version": "2.24.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",
@@ -102,7 +102,7 @@
     },
     {
       "name": "gog_gmail_search",
-      "description": "Search Gmail threads by query"
+      "description": "Search Gmail threads using Gmail query syntax; newest-first, and flags a truncated result set"
     },
     {
       "name": "gog_gmail_get",
@@ -118,7 +118,7 @@
     },
     {
       "name": "gog_calendar_events",
-      "description": "List calendar events with optional filters"
+      "description": "List calendar events; paginated (gog returns only 10 by default) and flags a truncated range"
     },
     {
       "name": "gog_calendar_get",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "2.23.1",
+  "version": "2.24.0",
   "mcpName": "io.github.chrischall/gogcli-mcp",
   "description": "MCP server wrapping gogcli for Google service access",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

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

package/src/gmail-results.ts

@@ -0,0 +1,239 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { rawTextResult } from '@chrischall/mcp-utils';
+import { run } from './runner.js';
+import { annotateTruncation, hasMorePages } from './pagination.js';
+import type { MatchCount } from './pagination.js';
+
+// Post-processing for Gmail search output, on the seam between gog's JSON and
+// the model client. Two guarantees live here, both of which exist because a
+// client read a search response and confidently reported that a message did not
+// exist when it did:
+//
+//   1. A capped result set SAYS SO, in prose. gog reports a nextPageToken and
+//      nothing else; a token is easy to skim past, and skipping it turns a
+//      partial answer into a false negative.
+//   2. Results are newest-first by internalDate. Gmail's own thread ordering
+//      keys on the thread, so a message that arrived today can rank below
+//      older ones and fall off the end of a capped page.
+
+type GmailListItem = Record<string, unknown> & {
+  date?: string;
+  internalDateIso?: string;
+};
+
+// Sort key for newest-first. internalDateIso is Gmail's own internalDate and is
+// what a parser should read; `date` parses the sender-written Date header and
+// can be skewed, malformed, or in another zone, so it is only a fallback.
+// Anything unparseable sorts LAST rather than being silently treated as the
+// epoch — which would rank it as the oldest result, the exact failure this
+// guarantee exists to remove.
+function sortKey(item: GmailListItem): number {
+  for (const raw of [item.internalDateIso, item.date]) {
+    if (typeof raw !== 'string' || !raw) continue;
+    const t = Date.parse(raw);
+    if (!Number.isNaN(t)) return t;
+  }
+  return Number.NEGATIVE_INFINITY;
+}
+
+// Array.prototype.sort is stable per spec, so equal keys — and the whole
+// undated tail, which shares NEGATIVE_INFINITY — keep their original order.
+function sortNewestFirst(items: GmailListItem[]): GmailListItem[] {
+  return [...items].sort((a, b) => {
+    const ka = sortKey(a);
+    const kb = sortKey(b);
+    // Compare before subtracting: (-Infinity) - (-Infinity) is NaN, which would
+    // make the comparator incoherent for every undated pair.
+    return ka === kb ? 0 : kb - ka;
+  });
+}
+
+export type GmailListMethod = 'users.threads.list' | 'users.messages.list';
+
+// The largest page Gmail's list endpoints will serve. One page at this size is
+// enough to count the whole match set for all but the broadest queries.
+const COUNT_PROBE_PAGE_SIZE = 500;
+
+// Count how many matches the query REALLY has.
+//
+// Deliberately NOT Gmail's own resultSizeEstimate, which is the obvious source
+// and is worthless: measured against a live mailbox on 2026-08-12 it returned
+// exactly 201 for every non-empty query tried — `from:freshbooks.com` (21 real
+// matches), `from:housecallpro.com` (6), `from:thumbtack.com newer_than:30d`
+// (3) — and 0 for a query with no matches. It saturates, so it is a
+// has-results boolean wearing a number's clothes. Reporting "3 of ~201" when
+// the truth is 3 of 6 would invent a figure, which is a worse failure than the
+// missing count this whole block exists to supply.
+//
+// So: ask for one maximal page of bare ids and count them. `fields` keeps the
+// response to ids alone, and the count is EXACT whenever the result set fits in
+// a page — which is the common case, and always the case for the narrow queries
+// a caller is most likely to draw a false negative from. A full page with more
+// behind it yields an honest lower bound instead.
+//
+// gog CAN now supply this itself — `--count` on `gmail search` / `gmail
+// messages search` (gog >= 0.36.0, openclaw/gogcli#985) is this same probe,
+// upstreamed, down to the page size and the exact/lower-bound split. The probe
+// stays here anyway, for two differences that both matter at this seam:
+//
+//   * It is spent ONLY on a result set already known to be truncated. --count
+//     is decided before the search runs, so adopting it would cost every
+//     search an extra Gmail request to answer a question most of them never
+//     raise.
+//   * It is best-effort. gog returns the count probe's error from the whole
+//     command, so a failed count would turn a search that DID succeed into an
+//     error — trading a missing warning for a missing answer.
+//
+// Keep the two in step: a change to what "exact" means on either side should
+// be made on both.
+//
+// Best-effort by construction: any failure must degrade the warning, never the
+// search.
+async function countMatches(
+  method: GmailListMethod,
+  itemsKey: 'threads' | 'messages',
+  query: string,
+  account: string | undefined,
+): Promise<MatchCount> {
+  try {
+    const params = JSON.stringify({
+      userId: 'me',
+      q: query,
+      maxResults: COUNT_PROBE_PAGE_SIZE,
+      fields: `${itemsKey}/id,nextPageToken`,
+    });
+    const raw = await run(['api', 'call', 'gmail', 'v1', method, `--params=${params}`], { account });
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const items = parsed[itemsKey];
+    if (!Array.isArray(items)) return {};
+    const more = typeof parsed.nextPageToken === 'string' && parsed.nextPageToken !== '';
+    return more ? { atLeast: items.length } : { total: items.length };
+  } catch {
+    return {};
+  }
+}
+
+export interface FinalizeOptions {
+  /** Which array in gog's payload holds the results. */
+  itemsKey: 'threads' | 'messages';
+  /** The Discovery method whose resultSizeEstimate matches that array. */
+  method: GmailListMethod;
+  /** The query as the caller wrote it. */
+  query: string;
+  account?: string;
+  /**
+   * False when gog rewrote the query server-side (--from-contact resolves a
+   * contact through the People API to addresses we cannot reproduce). An
+   * estimate for a DIFFERENT query is worse than none, so the field is skipped
+   * rather than guessed.
+   */
+  queryIsExact?: boolean;
+}
+
+// The single seam every Gmail search result passes through: guarantee the
+// ordering, and make a capped result set say so out loud. Any output that is
+// not the JSON shape this understands — an error, a plain "No results" — is
+// returned untouched.
+export async function finalizeGmailSearch(
+  result: CallToolResult,
+  options: FinalizeOptions,
+): Promise<CallToolResult> {
+  const { itemsKey, method, query, account, queryIsExact = true } = options;
+  const first = result.content[0];
+  if (result.isError || first?.type !== 'text') return result;
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(first.text) as Record<string, unknown>;
+  } catch {
+    return result;
+  }
+  const items = parsed[itemsKey];
+  if (!Array.isArray(items)) return result;
+
+  const sorted = sortNewestFirst(items as GmailListItem[]);
+  const out: Record<string, unknown> = { ...parsed, [itemsKey]: sorted };
+
+  // The presence of the block is itself the signal, so it is added ONLY for a
+  // genuinely capped set. gog leaves nextPageToken empty when --all exhausted
+  // the pages, which is why --all needs no special case here.
+  if (hasMorePages(parsed)) {
+    const count = queryIsExact ? await countMatches(method, itemsKey, query, account) : {};
+    annotateTruncation(out, sorted.length, count);
+  }
+
+  return rawTextResult(JSON.stringify(out));
+}
+
+// Walk up to `maxPages` pages and merge them into one payload.
+//
+// The point is the existence question — "is there any mail matching X?" — which
+// a single page cannot answer and which is exactly where a truncated response
+// gets misread as a negative. gog has `--all`, but that is unbounded: on a
+// broad query it walks the entire mailbox. This is the bounded form, so a
+// caller can say "look at up to 5 pages" and get either a real answer or an
+// honestly-still-truncated one.
+//
+// The merged payload keeps a nextPageToken only if pages remain when the cap is
+// hit, so finalizeGmailSearch still marks it truncated — running out of budget
+// is not the same as reaching the end, and must not read like it.
+export async function fetchGmailPages(
+  runPage: (token: string | undefined) => Promise<CallToolResult>,
+  itemsKey: 'threads' | 'messages',
+  maxPages: number,
+  startToken: string | undefined,
+): Promise<CallToolResult> {
+  const merged: unknown[] = [];
+  let base: Record<string, unknown> | undefined;
+  let token = startToken;
+
+  for (let pages = 0; pages < maxPages; pages++) {
+    const result = await runPage(token);
+    const parsed = parsePage(result, itemsKey);
+    // An error, or output this does not understand, part-way through the walk.
+    // Nothing collected yet means the caller should just see that result; once
+    // pages ARE collected, return them WITH the cursor that was about to be
+    // consumed, so the set still reads as truncated rather than complete.
+    if (parsed === undefined) {
+      return base === undefined ? result : finish(base, itemsKey, merged, token);
+    }
+    base = parsed;
+    merged.push(...(parsed[itemsKey] as unknown[]));
+    token = typeof parsed.nextPageToken === 'string' && parsed.nextPageToken !== ''
+      ? parsed.nextPageToken
+      : undefined;
+    if (token === undefined) break;
+  }
+
+  return finish(base as Record<string, unknown>, itemsKey, merged, token);
+}
+
+// A page's payload, or undefined if it is not a usable list response.
+function parsePage(
+  result: CallToolResult,
+  itemsKey: string,
+): Record<string, unknown> | undefined {
+  const first = result.content[0];
+  if (result.isError || first?.type !== 'text') return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(first.text);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== 'object') return undefined;
+  const obj = parsed as Record<string, unknown>;
+  return Array.isArray(obj[itemsKey]) ? obj : undefined;
+}
+
+function finish(
+  base: Record<string, unknown>,
+  itemsKey: string,
+  merged: unknown[],
+  token: string | undefined,
+): CallToolResult {
+  const out: Record<string, unknown> = { ...base, [itemsKey]: merged };
+  if (token === undefined) delete out.nextPageToken;
+  else out.nextPageToken = token;
+  return rawTextResult(JSON.stringify(out));
+}

package/src/lib.ts

@@ -19,6 +19,12 @@ export { run, runBinary, runExecutor, isGogFileArg, MIN_GOG_VERSION } from './ru
 // `runOrDiagnose` seam) must still apply this, or their timestamps skip the
 // offset repair and the `<field>Display` sibling every other tool returns.
 export { normalizeTimestamps } from './timestamps.js';
+export { annotateTruncatedList, stripConsumedPageToken } from './pagination.js';
+// Search-result finalization (newest-first ordering + loud truncation metadata).
+// Sub-package search tools must route their output through this or they lose both
+// guarantees the base gog_gmail_search makes.
+export { finalizeGmailSearch, fetchGmailPages } from './gmail-results.js';
+export type { FinalizeOptions, GmailListMethod } from './gmail-results.js';
 export { useRemoteGogRunner } from './remote-runner.js';
 export type { RunOptions, Spawner, GogExecutor, GogArg, GogFileArg } from './runner.js';
 export {
@@ -31,5 +37,8 @@ export {
   ids,
   paginationParams,
   pushPaginationFlags,
+  pageTokenParam,
+  pageAliasParam,
+  resolvePageToken,
   registerRunTool,
 } from './tools/utils.js';

package/src/pagination.ts

@@ -0,0 +1,108 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { rawTextResult } from '@chrischall/mcp-utils';
+
+// gog reports an exhausted cursor as `"nextPageToken": ""` rather than omitting
+// the field. That empty string is worse than nothing: the natural reading of a
+// paginated response is "the cursor key is there, so there is another page",
+// and a caller acting on the key's PRESENCE pages forever or, worse, concludes
+// the opposite of the truth. Strip it so the field means exactly one thing —
+// present iff another page exists.
+//
+// Deliberately top-level only. A nested `nextPageToken` belongs to some
+// embedded resource whose paging semantics are not ours to reinterpret.
+
+// Byte-identical passthrough is the contract when nothing was removed — see
+// normalizeTimestamps, which this sits beside on the same seam and whose
+// indent-preserving discipline it copies.
+function detectIndent(text: string): number {
+  const match = /\n(\s+)\S/.exec(text);
+  return match ? match[1].replace(/\t/g, '  ').length : 0;
+}
+
+export function stripConsumedPageToken(text: string): string {
+  const trimmed = text.trim();
+  if (trimmed === '' || !trimmed.startsWith('{')) return text;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return text;
+  }
+  // The `{` guard above means anything that parses here is a plain object —
+  // never null, an array, or a scalar — so no further shape check is needed.
+  const obj = parsed as Record<string, unknown>;
+  if (obj.nextPageToken !== '') return text;
+  delete obj.nextPageToken;
+  return JSON.stringify(obj, null, detectIndent(text));
+}
+
+// ---------------------------------------------------------------------------
+// Truncation metadata
+// ---------------------------------------------------------------------------
+
+// How many items the query really has, when we were able to find out.
+export interface MatchCount {
+  /** Exact total — the probe reached the end of the result set. */
+  total?: number;
+  /** Lower bound — the probe filled its page and more remain. */
+  atLeast?: number;
+}
+
+// The prose matters more than the boolean. A bare `truncated: true` is exactly
+// the kind of structured field a model client skims past — which is how a
+// non-empty nextPageToken produced a confident "no such email exists". This
+// says, in words, the one conclusion the caller must not draw.
+export function truncationWarning(returned: number, count: MatchCount): string {
+  const scope = count.total !== undefined
+    ? `returned ${returned} of ${count.total} matches`
+    : count.atLeast !== undefined
+      ? `returned ${returned} of at least ${count.atLeast} matches`
+      : `returned ${returned} matches and MORE EXIST beyond this page`;
+  return `INCOMPLETE RESULT SET: ${scope}. Do not report an absence of results based on ` +
+    'this response. Page with nextPageToken or narrow the query.';
+}
+
+// Add the truncation block to a parsed payload, in place.
+//
+// Only ever called for a genuinely capped set, so the block's PRESENCE is
+// itself the signal and a complete response stays clean. By the time this runs
+// an exhausted cursor has already been stripped by stripConsumedPageToken, so
+// "has a nextPageToken" and "has another page" are the same question.
+export function annotateTruncation(
+  out: Record<string, unknown>,
+  returned: number,
+  count: MatchCount,
+): void {
+  out.truncated = true;
+  out.returned = returned;
+  if (count.total !== undefined) out.totalMatches = count.total;
+  if (count.atLeast !== undefined) out.totalMatchesAtLeast = count.atLeast;
+  out.warning = truncationWarning(returned, count);
+}
+
+// True when the payload still carries a live cursor.
+export function hasMorePages(parsed: Record<string, unknown>): boolean {
+  return typeof parsed.nextPageToken === 'string' && parsed.nextPageToken !== '';
+}
+
+// Attach the truncation block to a tool result whose payload we cannot cheaply
+// count — the fact of truncation without a fabricated total. Anything that is
+// not the JSON shape this understands passes through untouched.
+export function annotateTruncatedList(
+  result: CallToolResult,
+  itemsKey: string,
+): CallToolResult {
+  const first = result.content[0];
+  if (result.isError || first?.type !== 'text') return result;
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(first.text) as Record<string, unknown>;
+  } catch {
+    return result;
+  }
+  const items = parsed[itemsKey];
+  if (!Array.isArray(items) || !hasMorePages(parsed)) return result;
+  const out: Record<string, unknown> = { ...parsed };
+  annotateTruncation(out, items.length, {});
+  return rawTextResult(JSON.stringify(out));
+}

package/src/runner.ts

@@ -167,7 +167,7 @@ const TIMEOUT_MS = 30_000;
 // so the requirement change is surfaced in the release notes (see
 // .github/release.yml). This is the single source of truth for the required
 // version; keep the README/CLAUDE.md mention in sync.
-export const MIN_GOG_VERSION = '0.35.0';
+export const MIN_GOG_VERSION = '0.37.0';
 
 // Interpret the GOG_READONLY kill-switch. `readEnvVar` already treats blank
 // values, 'undefined'/'null' sentinels, and unresolved .mcpb placeholders

package/src/tools/auth.ts

@@ -13,6 +13,20 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     `Default: "${defaultServices}". Prefer the narrowest set you need — requesting a service whose ` +
     `Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request ` +
     `with invalid_scope.`;
+  // Additional raw OAuth scope URIs, appended after the service scopes gog
+  // derives from `services`. This exists for scopes no service selection can
+  // ask for: notably bigquery.readonly, which Google demands whenever a Sheets
+  // response CONTAINS BigQuery Connected Sheets data (gog_sheets_datasource_*)
+  // and which ordinary `sheets` authorization deliberately does not request.
+  // Same invalid_scope caveat as `services`: Google rejects the WHOLE request
+  // if the scope's API is not enabled on the OAuth client's project, and that
+  // happens in the user's browser, so this wrapper cannot catch it.
+  const extraScopesDescribe =
+    'Additional raw OAuth scope URIs to request, comma-separated, on top of the ones `services` implies. ' +
+    'Use for scopes no service covers — 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 ' +
@@ -91,10 +105,19 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     inputSchema: {
       email: z.string().describe('Google account email to authorize'),
       services: z.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: z.string().optional().describe(extraScopesDescribe),
     },
-  }, async ({ email, services = defaultServices }) => {
+  }, async ({ email, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(['auth', 'add', email, '--services', services], {
+      const args = ['auth', 'add', email, '--services', services];
+      // --force-consent rides along with extraScopes and only with them. Google
+      // re-prompts for a NEW scope only when consent is forced; without it the
+      // account can come back still missing the scope, with a success message —
+      // the exact shape of failure the caller cannot see. The other two tools
+      // force consent unconditionally; this one does not, so it must be added
+      // here rather than assumed.
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`, '--force-consent');
+      return rawTextResult(await run(args, {
         interactive: true,
         timeout: 300_000,
       }));
@@ -115,17 +138,17 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     inputSchema: {
       email: z.string().describe('Google account email to authorize'),
       services: z.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: z.string().optional().describe(`${extraScopesDescribe} Pass the SAME value to gog_auth_add_complete.`),
     },
-  }, async ({ email, services = defaultServices }) => {
+  }, async ({ email, services = defaultServices, extraScopes }) => {
     try {
       // --force-consent guarantees a refresh token even if a prior grant exists
       // (the whole point when recovering from a dead one). redactMode 'tokens'
       // keeps the consent URL's scope names intact (the shared redactor mangles
       // them) while still stripping any real token — a step-1 URL carries none.
-      return rawTextResult(await run(
-        ['auth', 'add', email, '--remote', '--step', '1', '--services', services, '--force-consent'],
-        { redactMode: 'tokens' },
-      ));
+      const args = ['auth', 'add', email, '--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));
     }
@@ -147,13 +170,17 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
       services: z.string().optional().default(defaultServices).describe(
         `Services authorized — MUST match the value passed to gog_auth_add_url. Default: "${defaultServices}".`,
       ),
+      extraScopes: z.string().optional().describe(
+        'Extra OAuth scope URIs — 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, redirectUrl, services = defaultServices }) => {
+  }, async ({ email, redirectUrl, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(
-        ['auth', 'add', email, '--remote', '--step', '2', '--auth-url', redirectUrl,
-          '--services', services, '--force-consent'],
-      ));
+      const args = ['auth', 'add', email, '--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));
     }

package/src/tools/calendar.ts

@@ -1,33 +1,54 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool, pageTokenParam, pageAliasParam, resolvePageToken } from './utils.js';
+import { annotateTruncatedList } from '../pagination.js';
 
 export function registerCalendarTools(server: McpServer): void {
   server.registerTool('gog_calendar_events', {
-    description: 'List calendar events. Filters can be combined (e.g. --from + --to for a range, or --today for just today).',
+    description: 'List calendar events. Describe the window ONE way and one way only (gog >= 0.36.0 rejects the rest as ambiguous rather than silently discarding a flag): '
+      + 'today on its own; or from + to; or from + days; or days on its own (a window of that many days starting today). today cannot be combined with from, to or days, and days cannot be combined with to. '
+      + 'gog returns only 10 events by default, so a wide date range is USUALLY INCOMPLETE: raise max, or page with pageToken until the response carries no nextPageToken. '
+      + 'A response carrying "truncated": true is an incomplete view — never conclude an event does not exist from one.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       calendarId: z.string().optional().describe('Calendar ID (default: primary calendar)'),
       from: z.string().optional().describe('Start time filter (RFC3339, date, or natural language)'),
-      to: z.string().optional().describe('End time filter (RFC3339, date, or natural language)'),
-      today: z.boolean().optional().describe('Only show today\'s events'),
+      to: z.string().optional().describe('End time filter (RFC3339, date, or natural language). Mutually exclusive with today and with days.'),
+      // gog >= 0.36.0 (openclaw/gogcli#981). Before that release --days sat in
+      // a switch arm evaluated ahead of --from, so `--from 2026-09-25 --days 5`
+      // silently threw --from away and answered for today instead — at exit 0,
+      // in a well-formed table. It is only exposed here now that it means what
+      // it says.
+      days: z.number().int().positive().optional().describe('Window LENGTH in days (calendar days, DST-aware), measured from `from` when one is given and from today otherwise. Use from + days for "the week of the 25th"; days alone for "the next N days". Mutually exclusive with to and with today.'),
+      today: z.boolean().optional().describe('Only show today\'s events. A complete window on its own — mutually exclusive with from, to and days.'),
       query: z.string().optional().describe('Free text search within events'),
-      all: z.boolean().optional().describe('Fetch events from all calendars'),
+      max: z.number().int().optional().describe('Max events to return. gog defaults to 10, which silently hides the rest — raise it, or page with pageToken.'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
+      all: z.boolean().optional().describe('Fetch events from ALL CALENDARS. NOTE: unlike the gmail search tools, this does NOT mean "all pages" — it widens the calendar set, not the page window. Use pageToken to reach later pages.'),
       eventTypes: z.array(z.enum(['default', 'birthday', 'focus-time', 'from-gmail', 'out-of-office', 'working-location'])).optional().describe('Filter to specific event types (repeatable)'),
       timezone: z.string().optional().describe('Display timezone for event times (IANA name, e.g. America/New_York, or "local" for the system timezone). Default: each event\'s timezone, then its calendar\'s timezone.'),
       account: accountParam,
     },
-  }, async ({ calendarId, from, to, today, query, all, eventTypes, timezone, account }) => {
+  }, async ({ calendarId, from, to, days, today, query, max, pageToken, page, all, eventTypes, timezone, account }) => {
     const args = ['calendar', 'events'];
     if (calendarId) args.push(calendarId);
     if (from) args.push(`--from=${from}`);
     if (to) args.push(`--to=${to}`);
+    if (days !== undefined) args.push(`--days=${days}`);
     if (today) args.push('--today');
     if (query) args.push(`--query=${query}`);
+    if (max !== undefined) args.push(`--max=${max}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push('--all');
     if (eventTypes) for (const t of eventTypes) args.push(`--event-types=${t}`);
     if (timezone) args.push(`--timezone=${timezone}`);
-    return runOrDiagnose(args, { account });
+    const result = await runOrDiagnose(args, { account });
+    // No count probe here: unlike Gmail's list endpoints, the Calendar API has
+    // no cheap way to count a range exactly, so the warning carries the fact of
+    // truncation without inventing a total.
+    return annotateTruncatedList(result, 'events');
   });
 
   server.registerTool('gog_calendar_get', {