listMessages: resultSizeEstimate silently caps at ~201, making counts unusable; expose a real total or document the cap

[ElliotDrel]

Description

listMessages returns Gmail's resultSizeEstimate, which caps at ~201 regardless of how many messages actually match. Two separate broad queries in one session both returned exactly "resultSizeEstimate": 201 while matching far more.

This is a trap for callers. The field reads like a count, so the natural move is to report it or branch on it, and it is silently wrong for any query matching more than ~201 messages. There is no signal in the response distinguishing "201 matches" from "at least 201 matches."

Two things would help, either independently:

1. Rename or wrap the field so the cap is self-evident, e.g. resultSizeEstimate: {value: 201, capped: true}, or emit resultSizeEstimateCapped: true alongside it whenever the value is at the cap.
2. Offer an opt-in accurate count. Gmail exposes exact messagesTotal / threadsTotal per label via users.labels.get, which manageLabel action: "get" already surfaces, so a countOnly: true mode on listMessages (paging IDs and returning only the total) would close the gap for arbitrary queries.

At minimum, documenting the cap in the listMessages tool description would stop callers from quoting it as a real number.

Context: hit while auditing which messages matched a set of Gmail filter criteria, where knowing "how many messages does this criterion actually match" is the whole question, and the capped estimate could not answer it.

Environment: server 3.4.6, node v22.22.3, win32 10.0.26200, stdio transport.

Diagnostic Info

• Server version: 3.4.6
• Node version: v22.22.3
• OS: win32 10.0.26200 (x64)
• Auth status: valid
• Scopes: documents, drive, spreadsheets, script.external_request, gmail.modify, gmail.compose, gmail.send, gmail.settings.basic, gmail.settings.sharing, calendar, forms.body, forms.body.readonly, forms.responses.readonly, presentations, tasks, service.management