gogcli-mcp-gmail 2.23.1 → 2.23.2

package/dist/index.js

@@ -31547,6 +31547,40 @@ function normalizeTimestamps(text, tz = displayTimeZone(), naiveTz = naiveSource
   return JSON.stringify(parsed, null, detectIndent(text));
 }
 
+// ../gogcli-mcp/src/pagination.ts
+function detectIndent2(text) {
+  const match = /\n(\s+)\S/.exec(text);
+  return match ? match[1].replace(/\t/g, "  ").length : 0;
+}
+function stripConsumedPageToken(text) {
+  const trimmed = text.trim();
+  if (trimmed === "" || !trimmed.startsWith("{")) return text;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return text;
+  }
+  const obj = parsed;
+  if (obj.nextPageToken !== "") return text;
+  delete obj.nextPageToken;
+  return JSON.stringify(obj, null, detectIndent2(text));
+}
+function truncationWarning(returned, count) {
+  const scope = count.total !== void 0 ? `returned ${returned} of ${count.total} matches` : count.atLeast !== void 0 ? `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.`;
+}
+function annotateTruncation(out, returned, count) {
+  out.truncated = true;
+  out.returned = returned;
+  if (count.total !== void 0) out.totalMatches = count.total;
+  if (count.atLeast !== void 0) out.totalMatchesAtLeast = count.atLeast;
+  out.warning = truncationWarning(returned, count);
+}
+function hasMorePages(parsed) {
+  return typeof parsed.nextPageToken === "string" && parsed.nextPageToken !== "";
+}
+
 // ../gogcli-mcp/src/tools/utils.ts
 var PAYLOAD_INLINE_MAX = 4096;
 function payloadArg(inlineFlag, fileFlag, value, ext) {
@@ -31582,9 +31616,19 @@ var ids = {
   // People API uses fully-qualified resource names ("people/c123") not bare IDs.
   person: external_exports.string().describe("Person resource name (people/...) or email")
 };
+var pageTokenParam = external_exports.string().optional().describe(
+  "Cursor for the NEXT page. Pass back the nextPageToken from a previous response verbatim, keeping the query and max identical: call once, then call again with pageToken=<that value>. A response with NO nextPageToken is the last page."
+);
+var pageAliasParam = external_exports.string().optional().describe(
+  "Deprecated alias for pageToken, accepted so existing callers keep working. Use pageToken \u2014 it matches the nextPageToken field in the response."
+);
+function resolvePageToken(p) {
+  return p.pageToken ?? p.page;
+}
 var paginationParams = {
   max: external_exports.number().int().optional().describe("Max results"),
-  page: external_exports.string().optional().describe("Page token"),
+  pageToken: pageTokenParam,
+  page: pageAliasParam,
   all: external_exports.boolean().optional().describe("Fetch all pages")
 };
 function registerRunTool(server, options) {
@@ -31659,7 +31703,7 @@ ${accounts || "(none)"}${hint}`);
 async function runOrDiagnose(args, options) {
   try {
     const raw = await run(args, options);
-    return rawTextResult(options.lossless ? raw : normalizeTimestamps(raw));
+    return rawTextResult(options.lossless ? raw : stripConsumedPageToken(normalizeTimestamps(raw)));
   } catch (err) {
     return diagnose(err);
   }
@@ -31830,22 +31874,130 @@ function authToolsFor(defaultServices) {
   return (server) => registerAuthToolsWith(server, defaultServices);
 }
 
+// ../gogcli-mcp/src/gmail-results.ts
+function sortKey(item) {
+  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;
+}
+function sortNewestFirst(items) {
+  return [...items].sort((a, b) => {
+    const ka = sortKey(a);
+    const kb = sortKey(b);
+    return ka === kb ? 0 : kb - ka;
+  });
+}
+var COUNT_PROBE_PAGE_SIZE = 500;
+async function countMatches(method, itemsKey, query, account) {
+  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);
+    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 {};
+  }
+}
+async function finalizeGmailSearch(result, options) {
+  const { itemsKey, method, query, account, queryIsExact = true } = options;
+  const first = result.content[0];
+  if (result.isError || first?.type !== "text") return result;
+  let parsed;
+  try {
+    parsed = JSON.parse(first.text);
+  } catch {
+    return result;
+  }
+  const items = parsed[itemsKey];
+  if (!Array.isArray(items)) return result;
+  const sorted = sortNewestFirst(items);
+  const out = { ...parsed, [itemsKey]: sorted };
+  if (hasMorePages(parsed)) {
+    const count = queryIsExact ? await countMatches(method, itemsKey, query, account) : {};
+    annotateTruncation(out, sorted.length, count);
+  }
+  return rawTextResult(JSON.stringify(out));
+}
+async function fetchGmailPages(runPage, itemsKey, maxPages, startToken) {
+  const merged = [];
+  let base;
+  let token = startToken;
+  for (let pages = 0; pages < maxPages; pages++) {
+    const result = await runPage(token);
+    const parsed = parsePage(result, itemsKey);
+    if (parsed === void 0) {
+      return base === void 0 ? result : finish(base, itemsKey, merged, token);
+    }
+    base = parsed;
+    merged.push(...parsed[itemsKey]);
+    token = typeof parsed.nextPageToken === "string" && parsed.nextPageToken !== "" ? parsed.nextPageToken : void 0;
+    if (token === void 0) break;
+  }
+  return finish(base, itemsKey, merged, token);
+}
+function parsePage(result, itemsKey) {
+  const first = result.content[0];
+  if (result.isError || first?.type !== "text") return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(first.text);
+  } catch {
+    return void 0;
+  }
+  if (parsed === null || typeof parsed !== "object") return void 0;
+  const obj = parsed;
+  return Array.isArray(obj[itemsKey]) ? obj : void 0;
+}
+function finish(base, itemsKey, merged, token) {
+  const out = { ...base, [itemsKey]: merged };
+  if (token === void 0) delete out.nextPageToken;
+  else out.nextPageToken = token;
+  return rawTextResult(JSON.stringify(out));
+}
+
 // ../gogcli-mcp/src/tools/gmail.ts
 function registerGmailTools(server) {
   server.registerTool("gog_gmail_search", {
-    description: `Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread"). The query is passed verbatim to Gmail; a bare name token (from:alison) matches per Gmail's own heuristics, a full address (from:alison@example.com) is exact. To match a contact across several addresses, OR them: from:(a@x.com OR b@y.com).`,
+    description: 'Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread"). The query is passed verbatim to Gmail; a bare name token (from:alison) matches per Gmail\'s own heuristics, a full address (from:alison@example.com) is exact. To match a contact across several addresses, OR them: from:(a@x.com OR b@y.com). Results are ALWAYS newest-first by Gmail\'s internalDate \u2014 the wrapper sorts them, so the first result is the most recent match and a recent message can never be buried below older ones. IMPORTANT \u2014 a response carrying "truncated": true is an INCOMPLETE view of the matches: NEVER report that a message does not exist, or that there is no such mail, on the strength of one. Page through it (pass nextPageToken back as `pageToken`), set maxPages to walk several pages in one call, or narrow the query, and only then draw a conclusion. If you already know the thread, do not search for it at all \u2014 read it directly with gog_gmail_thread_get, which returns the whole thread and cannot be truncated or mis-ranked.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: external_exports.string().describe("Gmail search query"),
       max: external_exports.number().int().optional().describe("Max results to return (default: 10)"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
+      maxPages: external_exports.number().int().positive().max(20).optional().describe('Walk up to this many pages in ONE call and merge the results, instead of returning a single page. Use it for existence questions ("is there any mail matching X?"), which a single page cannot answer. Stops early at the last page; if pages remain when the cap is hit the response is still marked truncated. Prefer this over all=true, which is unbounded.'),
+      all: external_exports.boolean().optional().describe('Fetch every page instead of one. Removes truncation entirely, at the cost of one API round-trip per page \u2014 the reliable way to answer "does any message match?" for a query with few expected hits.'),
       fromContact: external_exports.string().optional().describe("Resolve a Google Contact (name or email) to its addresses and AND a from:(addr OR addr) clause onto the query \u2014 saves looking the contact up first when you only know who, not which address."),
       account: accountParam
     }
-  }, async ({ query, max, fromContact, account }) => {
+  }, async ({ query, max, pageToken, page, maxPages, all, fromContact, account }) => {
     const args = ["gmail", "search", query];
     if (max !== void 0) args.push(`--max=${max}`);
+    if (all) args.push("--all");
     if (fromContact) args.push(`--from-contact=${fromContact}`);
-    return runOrDiagnose(args, { account });
+    const runPage = (tok) => runOrDiagnose(tok ? [...args, `--page=${tok}`] : args, { account });
+    const token = resolvePageToken({ pageToken, page });
+    const result = maxPages !== void 0 ? await fetchGmailPages(runPage, "threads", maxPages, token) : await runPage(token);
+    return finalizeGmailSearch(result, {
+      itemsKey: "threads",
+      method: "users.threads.list",
+      query,
+      account,
+      // --from-contact is expanded INSIDE gog, against the People API, so the
+      // query Gmail actually saw is not the one we hold here.
+      queryIsExact: !fromContact
+    });
   });
   server.registerTool("gog_gmail_get", {
     description: "Get a Gmail message by ID.",
@@ -31896,7 +32048,7 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.23.1" : "0.0.0";
+var VERSION = true ? "2.23.2" : "0.0.0";
 
 // ../gogcli-mcp/src/auth-log.ts
 var FAILURES = /* @__PURE__ */ new Set([
@@ -33464,15 +33616,17 @@ function registerExtraGmailTools(server) {
     inputSchema: {
       since: external_exports.string().optional().describe("Start history ID"),
       max: external_exports.number().optional().describe("Max results (default: 100)"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       account: accountParam
     }
-  }, async ({ since, max, page, all, account }) => {
+  }, async ({ since, max, pageToken, page, all, account }) => {
     const args = ["gmail", "history"];
     if (since) args.push(`--since=${since}`);
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
@@ -33567,7 +33721,7 @@ function registerExtraGmailTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_thread_get", {
-    description: "Get a Gmail thread with all messages. For long threads that overflow context, use latestN to fetch only the most recent messages and/or snippetsOnly for a lightweight per-message headers+snippet view; sanitizeContent strips raw payloads/HTML and is the biggest size reducer when you do need bodies. Note each message carries two distinct id concepts: the top-level `id` (the Gmail short hex message id \u2014 pass THIS as replyToMessageId to reply) and the `Message-Id` header (the RFC822 `<\u2026@host>` value used in In-Reply-To/References) \u2014 don't confuse either with the `threadId`. To reply to the thread itself, pass the thread's id as replyToThreadId on gog_gmail_drafts_create.",
+    description: "Get a Gmail thread with all messages. THIS IS THE CORRECT TOOL WHEN YOU ALREADY KNOW THE threadId \u2014 it returns the thread in full, so unlike a search it can never be truncated, mis-ranked, or come back empty because the query missed. Never re-discover a known thread with gog_gmail_search; read it here. For long threads that overflow context, use latestN to fetch only the most recent messages and/or snippetsOnly for a lightweight per-message headers+snippet view; sanitizeContent strips raw payloads/HTML and is the biggest size reducer when you do need bodies. Note each message carries two distinct id concepts: the top-level `id` (the Gmail short hex message id \u2014 pass THIS as replyToMessageId to reply) and the `Message-Id` header (the RFC822 `<\u2026@host>` value used in In-Reply-To/References) \u2014 don't confuse either with the `threadId`. To reply to the thread itself, pass the thread's id as replyToThreadId on gog_gmail_drafts_create.",
     annotations: { readOnlyHint: true },
     inputSchema: {
       threadId: external_exports.string().describe("Gmail thread ID"),
@@ -33692,17 +33846,19 @@ function registerExtraGmailTools(server) {
     annotations: { readOnlyHint: true },
     inputSchema: {
       max: external_exports.number().optional().describe("Max results (default: 20)"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       enrich: external_exports.boolean().optional().describe(
         "Add subject, from and internalDateIso to each draft. Costs ONE extra gog invocation (`gmail messages search in:drafts`) regardless of how many drafts there are \u2014 but that single command makes gog fetch every matching draft server-side at concurrency 10, so Google reads and wall-clock are linear in the result count even though gog spawns are not. Narrow `max` before enabling it. If the search fails the listing silently degrades to the free fields rather than erroring."
       ),
       account: accountParam
     }
-  }, async ({ max, page, all, enrich, account }) => {
+  }, async ({ max, pageToken, page, all, enrich, account }) => {
     const args = ["gmail", "drafts", "list"];
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     const result = await runOrDiagnose(args, { account });
     let parsed;
@@ -33720,7 +33876,7 @@ function registerExtraGmailTools(server) {
     if (enrich) {
       const searchArgs = ["gmail", "messages", "search", "in:drafts", `--max=${max ?? GOG_DRAFTS_LIST_DEFAULT_MAX}`];
       if (all) searchArgs.push("--all");
-      if (page) searchArgs.push(`--page=${page}`);
+      if (token) searchArgs.push(`--page=${token}`);
       searchArgs.push("--include-attachments=false", "--use-indexed-attachment-ids=false");
       try {
         const messages = JSON.parse(await runNormalized(searchArgs, { account })).messages;
@@ -34121,12 +34277,14 @@ function registerExtraGmailTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_messages_search", {
-    description: "Search individual messages (not threads) using Gmail query syntax. Returns one result per matching message.",
+    description: 'Search individual messages (not threads) using Gmail query syntax. Returns one result per matching message. Results are ALWAYS newest-first by Gmail\'s internalDate \u2014 the wrapper sorts them, so the first result is the most recent match. IMPORTANT \u2014 a response carrying "truncated": true is an INCOMPLETE view of the matches: NEVER report that a message does not exist on the strength of one. Page through it (pass nextPageToken back as `pageToken`), set maxPages to walk several pages in one call, or narrow the query first. If you already know the thread, read it with gog_gmail_thread_get instead of searching for it.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: external_exports.string().describe('Gmail search query (e.g. "from:alice is:unread has:attachment")'),
       max: external_exports.number().optional().describe("Max results"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
+      maxPages: external_exports.number().int().positive().max(20).optional().describe('Walk up to this many pages in ONE call and merge the results, instead of returning a single page. Use it for existence questions ("is there any mail matching X?"), which a single page cannot answer. Stops early at the last page; if pages remain when the cap is hit the response is still marked truncated. Prefer this over all=true, which is unbounded.'),
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       includeBody: external_exports.boolean().optional().describe("Include the decoded message body in each result"),
       full: external_exports.boolean().optional().describe("Show full message bodies without truncation (implies includeBody)"),
@@ -34135,17 +34293,24 @@ function registerExtraGmailTools(server) {
       useIndexedAttachmentIds: external_exports.boolean().optional().describe("Report each attachment as a 0-based `attachmentIndex` within its message instead of an opaque `attachmentId` (stable across calls, unlike the id). Only has an effect alongside includeAttachments or includeBody."),
       account: accountParam
     }
-  }, async ({ query, max, page, all, includeBody, full, bodyFormat, includeAttachments, useIndexedAttachmentIds, account }) => {
+  }, async ({ query, max, pageToken, page, maxPages, all, includeBody, full, bodyFormat, includeAttachments, useIndexedAttachmentIds, account }) => {
     const args = ["gmail", "messages", "search", query];
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
     if (all) args.push("--all");
     if (includeBody) args.push("--include-body");
     if (full) args.push("--full");
     if (bodyFormat) args.push(`--body-format=${bodyFormat}`);
     args.push(includeAttachments ? "--include-attachments" : "--include-attachments=false");
     args.push(useIndexedAttachmentIds ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
-    return runOrDiagnose(args, { account });
+    const runPage = (tok) => runOrDiagnose(tok ? [...args, `--page=${tok}`] : args, { account });
+    const token = resolvePageToken({ pageToken, page });
+    const result = maxPages !== void 0 ? await fetchGmailPages(runPage, "messages", maxPages, token) : await runPage(token);
+    return finalizeGmailSearch(result, {
+      itemsKey: "messages",
+      method: "users.messages.list",
+      query,
+      account
+    });
   });
   server.registerTool("gog_gmail_labels_style", {
     description: "Change a user label's color or visibility (background/text color from Gmail's palette, label-list and message-list visibility).",

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-gmail",
   "display_name": "gogcli (Gmail)",
-  "version": "2.23.1",
+  "version": "2.23.2",
   "description": "Extended Gmail for Claude via gogcli — auth + full Gmail support (threads, labels, drafts, attachments, forward, autoreply, bulk operations)",
   "author": {
     "name": "Chris Hall",
@@ -91,7 +91,7 @@
     },
     {
       "name": "gog_gmail_search",
-      "description": "Search Gmail threads using Gmail query syntax"
+      "description": "Search Gmail threads using Gmail query syntax; newest-first, and flags a truncated result set"
     },
     {
       "name": "gog_gmail_get",
@@ -151,7 +151,7 @@
     },
     {
       "name": "gog_gmail_thread_get",
-      "description": "Get a thread with all messages"
+      "description": "Get a Gmail thread with all messages — the right tool when the threadId is already known"
     },
     {
       "name": "gog_gmail_thread_modify",
@@ -235,7 +235,7 @@
     },
     {
       "name": "gog_gmail_messages_search",
-      "description": "Search individual messages (not threads) using Gmail query syntax"
+      "description": "Search individual messages; newest-first, and flags a truncated result set"
     },
     {
       "name": "gog_gmail_labels_style",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-gmail",
-  "version": "2.23.1",
+  "version": "2.23.2",
   "mcpName": "io.github.chrischall/gogcli-mcp-gmail",
   "description": "Extended Gmail MCP server via gogcli — auth + full Gmail support (threads, labels, drafts, attachments, forward, autoreply, bulk operations)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/src/tools/gmail-extra.ts

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { rawTextResult, textResult, errorResult } from '@chrischall/mcp-utils';
-import { accountParam, runOrDiagnose, run, diagnose, payloadArg, runExecutor, normalizeTimestamps } from '../../../gogcli-mcp/src/lib.js';
+import { accountParam, runOrDiagnose, run, diagnose, payloadArg, runExecutor, normalizeTimestamps, finalizeGmailSearch, fetchGmailPages, pageTokenParam, pageAliasParam, resolvePageToken} from '../../../gogcli-mcp/src/lib.js';
 import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
 
 // gog rejects an inline flag together with its --*-file twin — `gmail drafts
@@ -2365,15 +2365,17 @@ export function registerExtraGmailTools(server: McpServer): void {
     inputSchema: {
       since: z.string().optional().describe('Start history ID'),
       max: z.number().optional().describe('Max results (default: 100)'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       account: accountParam,
     },
-  }, async ({ since, max, page, all, account }) => {
+  }, async ({ since, max, pageToken, page, all, account }) => {
     const args = ['gmail', 'history'];
     if (since) args.push(`--since=${since}`);
     if (max !== undefined) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push('--all');
     return runOrDiagnose(args, { account });
   });
@@ -2476,7 +2478,7 @@ export function registerExtraGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_thread_get', {
-    description: 'Get a Gmail thread with all messages. For long threads that overflow context, use latestN to fetch only the most recent messages and/or snippetsOnly for a lightweight per-message headers+snippet view; sanitizeContent strips raw payloads/HTML and is the biggest size reducer when you do need bodies. Note each message carries two distinct id concepts: the top-level `id` (the Gmail short hex message id — pass THIS as replyToMessageId to reply) and the `Message-Id` header (the RFC822 `<…@host>` value used in In-Reply-To/References) — don\'t confuse either with the `threadId`. To reply to the thread itself, pass the thread\'s id as replyToThreadId on gog_gmail_drafts_create.',
+    description: 'Get a Gmail thread with all messages. THIS IS THE CORRECT TOOL WHEN YOU ALREADY KNOW THE threadId — it returns the thread in full, so unlike a search it can never be truncated, mis-ranked, or come back empty because the query missed. Never re-discover a known thread with gog_gmail_search; read it here. For long threads that overflow context, use latestN to fetch only the most recent messages and/or snippetsOnly for a lightweight per-message headers+snippet view; sanitizeContent strips raw payloads/HTML and is the biggest size reducer when you do need bodies. Note each message carries two distinct id concepts: the top-level `id` (the Gmail short hex message id — pass THIS as replyToMessageId to reply) and the `Message-Id` header (the RFC822 `<…@host>` value used in In-Reply-To/References) — don\'t confuse either with the `threadId`. To reply to the thread itself, pass the thread\'s id as replyToThreadId on gog_gmail_drafts_create.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       threadId: z.string().describe('Gmail thread ID'),
@@ -2624,7 +2626,8 @@ export function registerExtraGmailTools(server: McpServer): void {
     annotations: { readOnlyHint: true },
     inputSchema: {
       max: z.number().optional().describe('Max results (default: 20)'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       enrich: z.boolean().optional().describe(
         'Add subject, from and internalDateIso to each draft. Costs ONE extra gog invocation (`gmail messages search in:drafts`) ' +
@@ -2634,10 +2637,11 @@ export function registerExtraGmailTools(server: McpServer): void {
       ),
       account: accountParam,
     },
-  }, async ({ max, page, all, enrich, account }) => {
+  }, async ({ max, pageToken, page, all, enrich, account }) => {
     const args = ['gmail', 'drafts', 'list'];
     if (max !== undefined) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push('--all');
     const result = await runOrDiagnose(args, { account });
 
@@ -2668,7 +2672,7 @@ export function registerExtraGmailTools(server: McpServer): void {
       // list is on page N: an extra gog spawn that joins ZERO rows and still
       // reported applied:true. The token is a drafts-list cursor, so it is only
       // meaningful to the paged search.
-      if (page) searchArgs.push(`--page=${page}`);
+      if (token) searchArgs.push(`--page=${token}`);
       // Both PINNED for the same reason as gog_gmail_messages_search: the env
       // vars behind them change the result shape (and the per-message cost).
       searchArgs.push('--include-attachments=false', '--use-indexed-attachment-ids=false');
@@ -3278,12 +3282,17 @@ export function registerExtraGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_messages_search', {
-    description: 'Search individual messages (not threads) using Gmail query syntax. Returns one result per matching message.',
+    description: 'Search individual messages (not threads) using Gmail query syntax. Returns one result per matching message. '
+      + 'Results are ALWAYS newest-first by Gmail\'s internalDate — the wrapper sorts them, so the first result is the most recent match. '
+      + 'IMPORTANT — a response carrying "truncated": true is an INCOMPLETE view of the matches: NEVER report that a message does not exist on the strength of one. Page through it (pass nextPageToken back as `pageToken`), set maxPages to walk several pages in one call, or narrow the query first. '
+      + 'If you already know the thread, read it with gog_gmail_thread_get instead of searching for it.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: z.string().describe('Gmail search query (e.g. "from:alice is:unread has:attachment")'),
       max: z.number().optional().describe('Max results'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
+      maxPages: z.number().int().positive().max(20).optional().describe('Walk up to this many pages in ONE call and merge the results, instead of returning a single page. Use it for existence questions (\"is there any mail matching X?\"), which a single page cannot answer. Stops early at the last page; if pages remain when the cap is hit the response is still marked truncated. Prefer this over all=true, which is unbounded.'),
       all: z.boolean().optional().describe('Fetch all pages'),
       includeBody: z.boolean().optional().describe('Include the decoded message body in each result'),
       full: z.boolean().optional().describe('Show full message bodies without truncation (implies includeBody)'),
@@ -3292,10 +3301,9 @@ export function registerExtraGmailTools(server: McpServer): void {
       useIndexedAttachmentIds: z.boolean().optional().describe('Report each attachment as a 0-based `attachmentIndex` within its message instead of an opaque `attachmentId` (stable across calls, unlike the id). Only has an effect alongside includeAttachments or includeBody.'),
       account: accountParam,
     },
-  }, async ({ query, max, page, all, includeBody, full, bodyFormat, includeAttachments, useIndexedAttachmentIds, account }) => {
+  }, async ({ query, max, pageToken, page, maxPages, all, includeBody, full, bodyFormat, includeAttachments, useIndexedAttachmentIds, account }) => {
     const args = ['gmail', 'messages', 'search', query];
     if (max !== undefined) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
     if (all) args.push('--all');
     if (includeBody) args.push('--include-body');
     if (full) args.push('--full');
@@ -3305,7 +3313,19 @@ export function registerExtraGmailTools(server: McpServer): void {
     // nothing in the arg array to show for it. See gog_gmail_thread_get.
     args.push(includeAttachments ? '--include-attachments' : '--include-attachments=false');
     args.push(useIndexedAttachmentIds ? '--use-indexed-attachment-ids' : '--use-indexed-attachment-ids=false');
-    return runOrDiagnose(args, { account });
+    // See gog_gmail_search: the cursor rides per page so the walk can advance it.
+    const runPage = (tok: string | undefined) =>
+      runOrDiagnose(tok ? [...args, `--page=${tok}`] : args, { account });
+    const token = resolvePageToken({ pageToken, page });
+    const result = maxPages !== undefined
+      ? await fetchGmailPages(runPage, 'messages', maxPages, token)
+      : await runPage(token);
+    return finalizeGmailSearch(result, {
+      itemsKey: 'messages',
+      method: 'users.messages.list',
+      query,
+      account,
+    });
   });
 
   server.registerTool('gog_gmail_labels_style', {

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

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { registerExtraGmailTools } from '../../src/tools/gmail-extra.js';
 import * as lib from '../../../gogcli-mcp/src/lib.js';
+import * as runner from '../../../gogcli-mcp/src/runner.js';
 import { createTestHarness, type TestHarness } from '@chrischall/mcp-utils/test';
 import { rawTextResult, errorResult } from '@chrischall/mcp-utils';
 
@@ -14,6 +15,16 @@ vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   };
 });
 
+// finalizeGmailSearch reaches for runner.run DIRECTLY (not the lib re-export
+// the mock above replaces) to count matches behind a truncated result set.
+// Without this the probe would spawn the real `gog` and hit the live Gmail API
+// from a unit test. Only `run` is replaced — runExecutor is a real
+// AsyncLocalStorage the connector-shape tests depend on.
+vi.mock('../../../gogcli-mcp/src/runner.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof runner>();
+  return { ...actual, run: vi.fn() };
+});
+
 let harness: TestHarness;
 
 beforeEach(async () => {
@@ -21,6 +32,9 @@ beforeEach(async () => {
   vi.mocked(lib.run).mockResolvedValue('{}');
   vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
   vi.mocked(lib.diagnose).mockResolvedValue(errorResult('diagnosed'));
+  // Default: the match-count probe finds nothing to report, so no test depends
+  // on a live call. Tests that care stub it explicitly.
+  vi.mocked(runner.run).mockRejectedValue(new Error('no count probe stubbed'));
   harness = await createTestHarness(registerExtraGmailTools);
 });
 
@@ -1735,7 +1749,7 @@ describe('gog_gmail_messages_search', () => {
     await harness.callTool('gog_gmail_messages_search', {
       query: 'is:unread',
       max: 10,
-      page: 'tok',
+      pageToken: 'tok',
       all: true,
       includeBody: true,
       full: true,
@@ -1743,7 +1757,7 @@ describe('gog_gmail_messages_search', () => {
       account: 'me@x.com',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['gmail', 'messages', 'search', 'is:unread', '--max=10', '--page=tok', '--all', '--include-body', '--full', '--body-format=html', '--include-attachments=false', '--use-indexed-attachment-ids=false'],
+      ['gmail', 'messages', 'search', 'is:unread', '--max=10', '--all', '--include-body', '--full', '--body-format=html', '--include-attachments=false', '--use-indexed-attachment-ids=false', '--page=tok'],
       { account: 'me@x.com' },
     );
   });
@@ -1757,6 +1771,98 @@ describe('gog_gmail_messages_search', () => {
   });
 });
 
+describe('page-cursor contract', () => {
+  it('never steers a caller to the deprecated `page` alias', async () => {
+    const { tools } = await harness.client.listTools();
+    const offenders = (tools as { name: string; description?: string }[])
+      .filter((t) => /`page`|\bas page\b/i.test(t.description ?? ''))
+      .map((t) => t.name);
+    expect(offenders).toEqual([]);
+  });
+
+  it('offers the alias wherever pageToken is accepted', async () => {
+    const { tools } = await harness.client.listTools();
+    const withCursor = (tools as { name: string; inputSchema?: { properties?: Record<string, unknown> } }[])
+      .filter((t) => 'pageToken' in (t.inputSchema?.properties ?? {}));
+    expect(withCursor.length).toBeGreaterThan(0);
+    expect(withCursor.filter((t) => !('page' in (t.inputSchema?.properties ?? {}))).map((t) => t.name)).toEqual([]);
+  });
+});
+
+describe('gog_gmail_messages_search — the page cursor reaches the API', () => {
+  it('threads a pageToken through to the gog invocation', async () => {
+    await harness.callTool('gog_gmail_messages_search', { query: 'x', pageToken: 'CURSOR' });
+    const args = vi.mocked(lib.runOrDiagnose).mock.calls[0][0] as string[];
+    expect(args).toContain('--page=CURSOR');
+  });
+
+  it('still accepts the deprecated page alias, and pageToken wins over it', async () => {
+    await harness.callTool('gog_gmail_messages_search', { query: 'x', page: 'OLD' });
+    expect(vi.mocked(lib.runOrDiagnose).mock.calls[0][0]).toContain('--page=OLD');
+    vi.mocked(lib.runOrDiagnose).mockClear();
+    await harness.callTool('gog_gmail_messages_search', { query: 'x', pageToken: 'NEW', page: 'OLD' });
+    expect(vi.mocked(lib.runOrDiagnose).mock.calls[0][0]).toContain('--page=NEW');
+  });
+
+  it('walks and merges pages under maxPages', async () => {
+    vi.mocked(lib.runOrDiagnose)
+      .mockResolvedValueOnce(rawTextResult(JSON.stringify({ messages: [{ id: 'a' }], nextPageToken: 'T1' })))
+      .mockResolvedValueOnce(rawTextResult(JSON.stringify({ messages: [{ id: 'b' }] })));
+    const result = await harness.callTool('gog_gmail_messages_search', { query: 'x', maxPages: 4 });
+    const out = JSON.parse(result.content[0].text as string);
+    expect(out.messages.map((m: { id: string }) => m.id)).toEqual(['a', 'b']);
+    expect(out).not.toHaveProperty('nextPageToken');
+    expect(vi.mocked(lib.runOrDiagnose).mock.calls[1][0]).toContain('--page=T1');
+  });
+});
+
+describe('gog_gmail_messages_search — result finalization', () => {
+  it('sorts results newest-first', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult(JSON.stringify({
+      messages: [
+        { id: 'old', internalDateIso: '2026-08-01T09:00:00-04:00' },
+        { id: 'new', internalDateIso: '2026-08-12T12:36:00-04:00' },
+        { id: 'mid', internalDateIso: '2026-08-05T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    })));
+    const result = await harness.callTool('gog_gmail_messages_search', { query: 'x' });
+    const out = JSON.parse(result.content[0].text as string);
+    expect(out.messages.map((m: { id: string }) => m.id)).toEqual(['new', 'mid', 'old']);
+    expect(out).not.toHaveProperty('truncated');
+  });
+
+  it('marks a capped result set truncated and counts the real total', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult(JSON.stringify({
+      messages: [{ id: 'a' }, { id: 'b' }],
+      nextPageToken: 'tok',
+    })));
+    vi.mocked(runner.run).mockResolvedValue(JSON.stringify({
+      messages: [{ id: 'a' }, { id: 'b' }, { id: 'c' }, { id: 'd' }, { id: 'e' }],
+    }));
+    const result = await harness.callTool('gog_gmail_messages_search', { query: 'x', max: 2 });
+    const out = JSON.parse(result.content[0].text as string);
+    expect(out.truncated).toBe(true);
+    expect(out.returned).toBe(2);
+    expect(out.totalMatches).toBe(5);
+    expect(out.warning).toBe(
+      'INCOMPLETE RESULT SET: returned 2 of 5 matches. Do not report an absence of results ' +
+      'based on this response. Page with nextPageToken or narrow the query.',
+    );
+    expect(runner.run).toHaveBeenCalledWith(
+      ['api', 'call', 'gmail', 'v1', 'users.messages.list',
+        '--params={"userId":"me","q":"x","maxResults":500,"fields":"messages/id,nextPageToken"}'],
+      { account: undefined },
+    );
+  });
+
+  it('leaves output it does not recognise untouched', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('No results'));
+    const result = await harness.callTool('gog_gmail_messages_search', { query: 'x' });
+    expect(result.content[0].text).toBe('No results');
+  });
+});
+
 describe('gog_gmail_labels_style', () => {
   it('calls runOrDiagnose with just the label', async () => {
     await harness.callTool('gog_gmail_labels_style', { labelIdOrName: 'Work' });