Skip to main content
Glama
gwsadm-mcp

gwsadm-mcp

by shigechika

gmail_user_usage

Retrieve daily Gmail send, receive, exchange, and spam counts for one account to investigate suspected spam bursts or account compromise.

Instructions

Daily Gmail send/receive counts for ONE account (Admin SDK userUsageReport).

Answers "did this account send a burst of mail on day X" -- the question after Google restricts an account for suspected spamming, or after a compromise. gmail_usage_report is the domain-wide total and cannot single one account out; this is the per-account counter.

Per day (newest first): num_emails_sent, num_emails_received, num_emails_exchanged and num_spam_emails_received. totals sums the days that returned a report; a counter that one of those days lacks has a None total (unknown), never a partial sum, and when no day reported at all every total is None. A day Google has no report for (not processed yet -- these counters lag by days, and Google answers such a day with a "not yet available" 400 -- or before the account existed) is listed in missing_dates, never counted as zero. A day Google answered with PARTIAL_DATA_AVAILABLE carries partial: true and is listed in partial_dates; while that list is non-empty the totals are lower bounds. A single day's fetch failing lands in date_errors; the other days still answer. A missing DWD scope or a rejected credential is a whole-call {"error": ...}.

Dates are the Reports API's own UTC-08:00 days (Pacific Standard Time, no DST): one such day runs 17:00 to 17:00 the next day in JST (UTC+09:00).

Read-only: only userUsageReport().get() is issued, on the same admin.reports.usage.readonly DWD scope gmail_usage_report uses, so a tenant already running that tool needs no additional grant.

Args: username: Exact user email, passed through as the Reports API userKey. days: How many days to report, ending at end_date. 1..:data:MAX_USAGE_REPORT_DAYS. end_date: Last day of the window, yyyy-mm-dd in UTC-08:00. Default: yesterday there. Must not be later than that. 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_user_usage"
  }
}

Input Schema

NameRequiredDescriptionDefault
daysNo
domainNo
end_dateNo
usernameYes

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?

No annotations exist, so the description carries the full burden and does: it declares read-only behavior (only userUsageReport().get() is issued), the exact DWD scope and that no new grant is needed, failure semantics (whole-call error on missing scope or rejected credential, per-day failures isolated in date_errors), and that results lag by days.

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?

Front-loaded with purpose and the sibling contrast, then Args, then return semantics — good ordering. It is dense and long, and the totals/missing_dates/partial_dates paragraph is heavy, but nearly every sentence carries information the agent cannot get from the schema.

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?

With no output schema, the description supplies the return shape (per-day counters, totals, missing_dates, partial_dates, date_errors), explains that None totals mean unknown rather than zero, and defines the UTC-08:00 reporting day against JST — everything needed 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%, yet the Args section documents all four parameters meaningfully: username is passed through as userKey, days has a bounded range, end_date has format, default and a not-in-the-future constraint, and domain selects a configured section or is inferred from the address suffix.

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 — daily Gmail send/receive counts for ONE account via Admin SDK userUsageReport — and immediately distinguishes itself from gmail_usage_report, which is the domain-wide total that cannot single out an account.

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 an explicit investigative trigger (after Google restricts an account for suspected spamming, or after a compromise) and names the sibling alternative plus the precise reason it is unsuitable. The agent knows both when to pick this tool and when not to.

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