mailwarden

list_subscriptions

Read-only

Identifies subscriptions by grouping mailbox senders and showing opt-out options, so you can pick targets for bulk unsubscribe.

Instructions

Who keeps writing, how often, and whether you can get off the list — a mailbox slice grouped by SENDER, each row carrying its opt-out options. Contacts nobody: opt-out options come from the List-Unsubscribe header of each sender's newest thread (one metadata fetch per sender, not per thread). optOut is 'one-click' (the unsubscribe tool can perform it), 'link' (a human opens it in a browser), 'mailto' (would need sending, which mailwarden never does), 'none', or 'unknown' when that sender's header fetch failed or was never made because Gmail's quota ran out mid-listing. oldestDate/newestDate bound what the SAMPLE saw of that sender, not the sender's whole history — a query capped at max reaches back only as far as those threads go, which on a busy mailbox is days. There is deliberately NO precomputed frequency: judge it from threads across that span, with the sampling caveat in view. newestThreadId is what to hand to unsubscribe or bulk_unsubscribe. sendersFound is how many DISTINCT senders the sample held — when it exceeds topN, the list is truncated and raising topN shows more. USE WHEN: 'what am I subscribed to', 'which newsletters flood me', or picking targets before a bulk unsubscribe. DO NOT USE: for a general inbox overview (use triage_digest — it buckets by label and age too), or for one known thread (use list_unsubscribe). SIDE EFFECTS: none.

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": "list_subscriptions"
  }
}

Input Schema

Name	Required	Default
`max`	No
`topN`	No
`query`	No	category:promotions

Output Schema

Name	Required	Description	Default
`query`	Yes
`hasMore`	Yes
`sampled`	Yes
`sendersFound`	Yes
`subscriptions`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.25.0Oct 29, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
Addedv0.9.0Aug 14, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Even though annotations already declare readOnlyHint=true and openWorldHint=false, the description adds substantial behavioral context: 'Contacts nobody', one metadata fetch per sender, optOut value meanings, Gmail quota failure handling, and sampling limitations. This is exactly the kind of beyond-annotation detail that helps an agent reason about results.

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 purpose is front-loaded and the USE WHEN / DO NOT USE / SIDE EFFECTS structure helps scanning. However, the description is long and dense, and the 'how often' opener is slightly misleading before the later clarification that there is deliberately no precomputed frequency.

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?

Because an output schema exists, the description does not need to explain return values, yet it usefully covers sampling limits, quota failure, truncation via sendersFound, optOut meanings, and handoff fields. The missing query-parameter semantics is a notable gap, but the overall definition is still complete enough for correct use.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must carry all three parameters. It explains topN via sendersFound truncation and max as the sample cap, but it never defines the query parameter or mentions its default category:promotions, leaving one of three parameters largely undocumented.

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?

The opening states the resource clearly: a mailbox slice grouped by SENDER, with each row carrying opt-out options. The USE WHEN / DO NOT USE block further distinguishes it from triage_digest and list_unsubscribe, so an agent can identify its role without opening the schema.

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?

The description gives explicit USE WHEN triggers such as 'what am I subscribed to' and 'which newsletters flood me', and explicit DO NOT USE cases with named alternatives. It also explains that it is meant for picking targets before bulk_unsubscribe, which is strong routing guidance.

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