Inbox Reads and Triage

Reading the inbox

list-inbox-threads is the inbox view itself: it returns the tab bar (Important, pinned labels, saved filters, Other — or one combined Inbox tab when the user has "combine inbox" on), each tab's total/unread counts, and the active tab's rows, all computed from one partition over the synced inbox store. A tab's badge can never disagree with the rows it returns, and the read never waits on a live Gmail call. tab accepts any id from the returned tabs list; an unrecognized or omitted id falls back to the first tab. Use list-emails/search-emails for every other view (Sent, Archive, Trash, All Mail) or an ad hoc query — not for the inbox.

Membership is Superhuman-style, not Gmail's own IMPORTANT label: a thread shows in every pinned-label/saved-filter tab whose query it matches (a thread can appear in more than one). A thread matching no custom tab falls to Important, unless its latest message classifies as automated (bulk senders, List-Unsubscribe, notification-style from:), in which case it falls to Other.

During an initial sync or older-mail backfill, rows and computed tab totals are partial; totals marked as lower bounds display with +. Call sync-inbox to advance one bounded step, then read list-inbox-threads to see committed rows. Repeat while an account is initial, has a pending push, or has backfill pending. When the sync result includes retryAfterSeconds, wait that long before the next step. The inbox client follows this cadence automatically. A plain list-inbox-threads call never starts Gmail work. Use resync-inbox only to reset and restart an account's local inbox sync; it performs one bounded step.

Coverage-aware inventory reads

list-emails remains the compatibility list action for the UI and internal callers. External MCP callers receive its structured inventory envelope by default (or pass format: "inventory"). Inventory reads use accountEmails for an explicit set; the legacy singular account alias cannot be combined with it. The response reports each account's success, empty result, exhaustion or bounded error, so partial coverage must never be described as complete. Inventory items are intentionally compact metadata only — use get-email or get-thread only after selecting a specific result when body content is needed.

Refresh after mutations

After backend mail mutations (archive, trash, star, mark-read, move, send), call refresh-list so the UI refetches. Actions that already write refresh-signal internally (e.g. mark-thread-read, move-email, respond-calendar-invite) don't need a second call.

Bulk unread cleanup

For broad unread cleanup in one account, call mark-read once with scope: "all-unread", the exact accountEmail, and any protected conversation IDs in excludeThreadIds. Do not loop mark-thread-read over many conversations. The bulk result's matched, excluded, changed, failure, and remaining-unread counts are the proof of completion.

Knowing what the user is looking at

Use view-screen when the active thread, selected message, draft, or queue item is unclear. Use get-thread for full conversation context instead of relying on ambient screen text.

Moving the UI

navigate accepts view (inbox, starred, sent, drafts, scheduled, archive, trash, draft-queue, settings), plus tab (an inbox tab id from list-inbox-threads; label/filter are accepted aliases), threadId, settingsSection, queuedDraftId, or composeDraftId.

settingsSection opens Settings in the user's tab. general, drafting, snippets, rules, ai-filter, gmail-filters, aliases, and tracking are tabs on Mail › General (/settings/app/<id>). rules is Mail's inbox rules; the core Automations page is the agent's scheduled and event automations. slack opens Channels › Slack, where Slack draft requests and the agent's Slack connection live, and members opens Organization › Members.

Related Skills

• mail-backends — whether a read hit real Gmail or the local fallback.
• provider-api-scans — reads beyond the canned actions, and staging large scans for analysis.
• email-drafts — replying to something you just read.
• inbox-automations — automating recurring triage instead of repeating it.