Skip to main content
Glama
gwsadm-mcp

gwsadm-mcp

by shigechika

gmail_log_search

Search one Gmail account's log metadata to trace message delivery, find Google notices by subject, or check bounce and throttle replies.

Instructions

Search ONE account's Gmail log (metadata only), one row per message.

The Admin console's "Email log search" for one account: which messages reached or left the mailbox in a window, with their subject, Message-ID, destinations and Google's delivery reply. Use it to find a notice Google sent the account (filter by subject), to confirm one message's delivery (message_id), or to see what Google answered when mail to or from the account bounced or was throttled (responses). It never reads a message body: it issues only Reports API activities().list for the gmail application under userKey=<username>, on the same admin.reports.audit.readonly DWD scope as user_activity. The tenant must have Gmail log events in the Reports API.

The log does not carry the sender's address (its source is empty in the API), so a sender is recognisable only by the domain on the right of the Message-ID and by link_domains. Events are grouped by rfc2822_message_id; per message: first / last event time, events (deliveries etc. counted raw), event_names, action_types (Google's numeric codes, undocumented, passed through), destinations (as Google flattens them, channel::address), spam (any event marked it), attachments, link_domains, and responses -- the distinct non-empty description replies other than the 250 accepted ones. Rows are newest last first, cut at max_messages with truncated saying so.

Filters select messages, not events: a message is kept when any of its events matches, and its row then aggregates all of its events (a throttle reply that carries no subject stays on the row). subject and recipient are case-insensitive substrings (of the subject / of the flattened destinations), message_id is exact (angle brackets optional). events_scanned counts events before filtering. capped means more pages existed beyond max_pages (1000 events per page) -- the older part of the window was not read, so "not found" does not hold. Today's log can lag by hours.

Args: username: Exact user email, passed through as the Reports API userKey. hours: Window length ending at end, 1..:data:GMAIL_LOG_MAX_HOURS (the API refuses a gmail scan longer than 30 days). end: End of the window, ISO 8601 with an offset (2026-10-26T00:00:00+09:00). Default: now. Must not be in the future. subject: Keep messages whose subject contains this text. message_id: Keep the message with this RFC 822 Message-ID. recipient: Keep messages whose destinations contain this text (an address or a domain). max_pages: Page budget, 1..:data:GMAIL_LOG_MAX_PAGES. max_messages: Rows returned, 1..:data:GMAIL_LOG_MAX_MESSAGES. domain: Configured [domain.*] section to route the lookup through. Default: resolved from the username's suffix.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "username": "<username>"
    },
    "name": "gmail_log_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNo
hoursNo
domainNo
subjectNo
usernameYes
max_pagesNo
recipientNo
message_idNo
max_messagesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.24.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses the read-only nature (only activities().list, no body access), the required admin.reports.audit.readonly DWD scope, the tenant prerequisite of Gmail log events, and the fact that today's log can lag by hours. It also surfaces data-shape limits the caller cannot infer, notably that the sender address is absent so senders are recognizable only via Message-ID domain and link_domains, plus the semantics of truncated, capped, and events_scanned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The lead sentence and the 'Use it to...' clause are front-loaded and the args block is well organized, with no filler sentences. It is long overall and the aggregated-fields sentence packs a lot of enumeration into one dense run, which costs some readability, but nearly every sentence carries decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description fully specifies the returned row shape (first/last, events, event_names, action_types, destinations, spam, attachments, link_domains, responses), the ordering (newest last first), and the truncation signalling (truncated, capped, events_scanned). For a nine-parameter, filter-heavy audit tool that is everything an agent needs to interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must document all nine parameters, and it does: username is passed through as userKey, hours has an explicit API-enforced 30-day ceiling, end requires ISO 8601 with an offset, defaults to now and must not be in the future, and subject/recipient are case-insensitive substrings while message_id is exact with optional angle brackets. It also clarifies the critical filtering semantics that filters select messages rather than events, which the bare schema could never convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource, 'Search ONE account's Gmail log (metadata only), one row per message', and immediately fixes the scope (single account, metadata only, one row per message) that separates it from multi-user siblings like gmail_usage_report. It also names the underlying API call and the DWD scope tied to user_activity, so the agent knows exactly which data plane this touches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives three concrete when-to-use cases mapped to the filter that serves each: finding a Google notice via subject, confirming delivery via message_id, and reading bounce/throttle replies via responses. It also states a clear when-not ('never reads a message body') and warns that a capped scan invalidates a 'not found' conclusion, which is exactly the failure mode an agent would otherwise misread.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.