mailwarden

sweep_snoozed

Idempotent

Resurface due snoozed email threads by returning them to the inbox marked unread; set dryRun to preview due items without waking them.

Instructions

Resurface all snoozed threads whose date is due (<= today), batched at 1000 messages per API request. Set dryRun:true to rehearse: reports the due labels and threads (dueLabels/dueThreads) as the sweep would find them (from the live label listing; a single snooze label with more than 5000 messages is under-counted in the rehearsal), and wakes nothing. USE WHEN: the user asks to process due snoozes, or as a scheduled maintenance call; dryRun to answer 'what is due right now?' without acting. SIDE EFFECTS: due threads return to the inbox marked unread (none with dryRun); safe to run repeatedly. failedCount/errors report messages a batch could not wake (their label is kept for the next sweep).

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

Input Schema

Name	Required	Description	Default
`dryRun`	No

Output Schema

Name	Required	Description	Default
`date`	Yes
`woken`	Yes
`dryRun`	Yes
`errors`	Yes
`dueLabels`	Yes
`dueThreads`	Yes
`wokenCount`	Yes
`failedCount`	Yes
`dueThreadCount`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

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

Changed8 schema fields changedv0.11.0Aug 16, 2026

addedInput schema / $schema

Added value: +"http://json-schema.org/draft-07/schema#"

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / dryRun

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedOutput schema / properties / dryRun
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / dueLabels

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / dueThreadCount
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / dueThreads

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "date",
-  "wokenCount",
-  "woken",
-  "failedCount",
-  "errors"
-]New value: +[
+  "date",
+  "dryRun",
+  "dueLabels",
+  "dueThreadCount",
+  "dueThreads",
+  "wokenCount",
+  "woken",
+  "failedCount",
+  "errors"
+]

First observedv0.1.8Jul 24, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Goes well beyond annotations: discloses side effects (due threads return to inbox marked unread; none with dryRun), idempotency (safe to run repeatedly, consistent with idempotentHint), partial-failure behavior (failedCount/errors, label kept for next sweep), and a rehearsal under-counting caveat. Consistent with readOnlyHint=false and destructiveHint=false.

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, then USE WHEN and SIDE EFFECTS in clear labeled chunks. Dense and largely justified, though the parenthetical under-counting caveat and error-reporting detail add length that only some callers will need.

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 mutating, idempotent, single-param tool with an output schema, the description covers side effects, dry-run behavior, partial failures, and repeat-safety. Nothing an agent needs to call it correctly is missing.

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?

The single parameter (dryRun) has 0% schema coverage, but the description fully compensates: it explains what dryRun:true does, that it wakes nothing, what it returns (dueLabels/dueThreads), and even a caveat about a >5000-message label being under-counted in rehearsal.

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?

States a specific verb and resource with scope: resurface snoozed threads whose date is due (<= today), batched at 1000 per request. This clearly distinguishes it from list_snoozed (listing) and snooze/unsnooze (individual actions).

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

Usage Guidelines4/5

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

Explicit 'USE WHEN' condition (process due snoozes, scheduled maintenance) and a dryRun variant for 'what is due right now?'. Does not explicitly name siblings like list_snoozed as the read-only alternative, but the use-case conditions are clearly stated.

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