Skip to main content
Glama
Sign In
Timbre

Timbre

by alejandrosml
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

mail_stats

Read-only

Generates email statistics for a selected period, including received, unread, flagged, and sent counts by account and mailbox, top senders, and newsletters with unsubscribe guidance.

Instructions

Figures for a period (default the last 30 days), for all mail, an account or a mailbox: messages received, unread, flagged and sent, by account and mailbox, the most frequent senders, and the newsletters among them with how to leave each.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "mail_stats"
  }
}

Input Schema

NameRequiredDescriptionDefault
topNoHow many top senders and newsletters (default 10, max 25).
afterNoFrom this date (YYYY-MM-DD; default 30 days ago).
beforeNoBefore this date (YYYY-MM-DD; default now).
accountNoAccount name, as list_mailboxes gives it.
mailboxNoA mailbox name or path.

Output Schema

NameRequiredDescriptionDefault
fromYes
sentYesMessages the user sent.
untilYes
unreadYes
flaggedYes
receivedYesMessages received (sent mail, drafts, junk and trash aside).
by_accountYes
by_mailboxYesThe mailboxes holding most of what was received.
newslettersYesNewsletters and mailing lists among the senders, most frequent first.
top_sendersYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.7.2

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description is free to add aggregation semantics instead. It does add useful behavior: a default rolling 30-day window, per-account and per-mailbox breakdowns, and top-N sender/newsletter rankings. It does not mention cost, latency, or how large a mailbox affects the response, but the added context is meaningful beyond the annotations.

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?

A single front-loaded sentence that leads with the scope and default period before enumerating outputs; every clause carries information about what the tool returns. It is a long, comma-heavy run-on, which slightly reduces scanability, but there is no filler.

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

Completeness4/5

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

With an output schema present, the description need not explain return shapes, and it correctly focuses on scope, defaults and metric families. Parameter coverage is complete and annotations cover safety, so an agent has enough to call it correctly; only the absence of any sibling routing guidance leaves a small gap.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by framing account and mailbox as optional scoping filters and stating that omitting both yields statistics for all mail. It also reinforces the default period, tying the date parameters together conceptually rather than restating them individually.

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

Purpose4/5

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

The description names the resource (mail statistics) and enumerates the specific metrics returned: received, unread, flagged, sent, top senders and newsletters by account/mailbox. That is far more specific than a tautology and clearly separates it from a search or listing tool. It stops short of naming a sibling such as mail_status or history, so the differentiation is implied rather than explicit.

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

Usage Guidelines3/5

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

Usage is implied by the scoping language ('for all mail, an account or a mailbox') and the default 30-day window, which tells an agent this is the aggregation entry point. There is no explicit statement of when to prefer this over mail_status, search_mail or history, and no exclusions or prerequisites are given.

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