Skip to main content
Glama
shigechika

gwsadm-mcp

by shigechika
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

gmail_usage_report

Retrieve daily Gmail send and receive counts per domain for a specified number of days. Solves the need to know how much Gmail traffic each domain sent or received on any given day.

Instructions

Daily Gmail send/receive counts per domain (Admin SDK customerUsageReports).

Answers "how much Gmail traffic did this domain send/receive on day X" -- a customer-level daily counter, NOT a per-user or per-message breakdown (the Reports API has no such thing; login_audit's activity stream is the per-event alternative for that, at the cost of no volume total).

Each day's fetch is independent: a domain missing the DWD scope reports one whole-domain error (there is no point retrying days times for an identical scope failure), but a single date's fetch failing for some other reason (Google's processing for that day not finished yet is a known lag on this API family; a transient error) only skips that one date, recorded in date_errors -- the rest of the window still comes back. The per-domain result also carries capped -- true if ANY date's fetch hit the (rare, since a single day's customer report is normally one record) pagination limit -- so a truncated day's counters are never mistaken for the complete picture.

Requires the admin.reports.usage.readonly DWD scope, granted PER SERVICE ACCOUNT CLIENT ID in the Admin console (Security > API controls > Domain-wide delegation) -- a DIFFERENT scope from admin.reports.audit.readonly (the one login_audit, drive_external_sharing, drive_doc_activity, shared_drive_membership_changes and daily_brief use), even though both live under the same Admin SDK Reports API. Having one does not imply the other; grant this one separately.

Read-only: only customerUsageReports().get() is issued, restricted to the two Gmail counters this tool reports via the API's own parameters filter (:data:GMAIL_USAGE_PARAMETERS) rather than pulling every application's counters.

Args: days: How many days back to report, ending YESTERDAY (not today -- the current day's data is not final until it ends) in the Reports API's own UTC-8:00/Pacific-Standard-Time date anchor. Must be 1..:data:MAX_USAGE_REPORT_DAYS -- 0/negative would otherwise silently return a well-formed, error-free empty result indistinguishable from "queried correctly, zero Gmail traffic that window", and an unbounded value drives an unbounded (domain x date) fan-out (one blocking API call per task, even though they run concurrently). domain: Configured [domain.*] section to report on. Default: all configured domains.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
daysNo
domainNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.17.0

TDQS

A4.9/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full burden and meets it thoroughly: discloses read-only nature (only customerUsageReports().get() issued), the per-domain error vs date_errors partial-failure model, the capped pagination flag, the separate DWD scope requirement distinct from the audit scope, and the UTC-8 date anchor. Exceptionally rich behavioral disclosure.

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 scope before behavioral detail, with a clearly marked Args section. The description is long but every sentence carries operational value given the tool's complexity (auth, failure modes, pagination). Slight deduction for density, but no wasted words.

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?

For a tool with 2 params, no output schema, no annotations, and 0% schema coverage, the description is essentially complete: it covers return behavior (error vs date_errors), the capped truncation signal, auth prerequisites, and full parameter semantics. An agent could call this correctly with zero additional research.

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 compensate and does so fully. For days it explains the 'ending YESTERDAY' semantics, the range constraint, and the silent-failure trap of 0/negative values producing an indistinguishable empty result. For domain it explains the configured [domain.*] section concept and the default. No meaning is left to schema inference.

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+resource: 'Daily Gmail send/receive counts per domain (Admin SDK customerUsageReports)'. Immediately states what it is NOT (per-user or per-message breakdown) and names login_audit as the per-event alternative, clearly distinguishing it from the 15 siblings without requiring schema inspection.

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?

Explicitly names login_audit as the alternative for per-event breakdown and explains the tradeoff (no volume total). States when this tool fits ('how much Gmail traffic did this domain send/receive on day X') and the scope precondition. Also explains the non-retry behavior on scope failure, giving the agent a clear decision rule.

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

Deploy Server

Other Tools