mailwarden

create_filter

Destructive

Creates Gmail filters that auto-label, archive, mark read, star, or trash incoming mail based on criteria. Optionally applies the same actions to existing messages.

Instructions

Create a Gmail filter: matching incoming mail automatically gets the given label actions. Give at least one criterion and at least one action. Actions are label add/remove only (labels by name or id; an unknown name in addLabels is auto-created). Common recipes: skip the inbox → removeLabels ['INBOX']; auto-mark-read → removeLabels ['UNREAD']; auto-trash → addLabels ['TRASH']; star → addLabels ['STARRED']; file under a label → addLabels ['Receipts']. A filter only affects mail arriving AFTER it's created; set applyToExisting:true to ALSO apply the same actions once to mail already in the mailbox (builds a Gmail search from the criteria and runs a bulk modify — same unverified-index caveat as bulk_modify — the sweep acts on what the index returns, which can be badly stale on read state; up to maxMessages, default 1000). The sweep's applied.submittedMessages is how many ids were handed to the API, NOT how many messages changed; set verify:true alongside applyToExisting to read the labels back afterwards and get applied.verified {applied, notApplied[], unverifiable[]}. It costs one extra read per affected thread, so it is off by default; a read-back that fails lands in unverifiable and never fails the call — the filter stands either way. USE WHEN: setting up a persistent auto-triage rule (e.g. 'always archive + label newsletters from x'), optionally cleaning up the existing backlog too — preview_filter first to see how much mail it would catch today and whether an existing filter already covers it. NOTE: forwarding filters are intentionally not supported — mailwarden creates no send/exfiltration path. SIDE EFFECTS: adds a server-side rule affecting future mail (reversible via delete_filter); with applyToExisting also modifies existing messages. Requires gmail.settings.basic.

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

Input Schema

Name	Required	Description	Default
`to`	No
`from`	No
`size`	No
`query`	No
`verify`	No
`subject`	No
`addLabels`	No
`maxMessages`	No
`excludeChats`	No
`negatedQuery`	No
`removeLabels`	No
`hasAttachment`	No
`sizeComparison`	No
`applyToExisting`	No

Output Schema

Name	Required	Description	Default
`id`	Yes
`applied`	Yes
`forward`	No
`criteria`	Yes
`addLabelIds`	Yes
`removeLabelIds`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.25.0Oct 29, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / size / maximum
```
Added value: +9007199254740991
```

Changed2 schema fields changedv0.21.0Sep 14, 2026

addedInput schema / properties / verify

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

changedOutput schema / properties / applied / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "capped": {
-        "type": "boolean"
-      },
-      "error": {
-        "type": "string"
-      },
-      "failed": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "error": {
-              "type": "string"
-            },
-            "messageIds": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            }
-          },
-          "required": [
-            "messageIds",
-            "error"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "matchedMessages": {
-        "type": "number"
-      },
-      "query": {
-        "type": "string"
-      },
-      "submittedMessages": {
-        "type": "number"
-      },
-      "submittedThreadCount": {
-        "type": "number"
-      }
-    },
-    "required": [
-      "query",
-      "matchedMessages",
-      "submittedMessages",
-      "submittedThreadCount",
-      "capped",
-      "failed"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "capped": {
+        "type": "boolean"
+      },
+      "error": {
+        "type": "string"
+      },
+      "failed": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "error": {
+              "type": "string"
+            },
+            "messageIds": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "messageIds",
+            "error"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "matchedMessages": {
+        "type": "number"
+      },
+      "query": {
+        "type": "string"
+      },
+      "submittedMessages": {
+        "type": "number"
+      },
+      "submittedThreadCount": {
+        "type": "number"
+      },
+      "verified": {
+        "additionalProperties": false,
+        "properties": {
+          "applied": {
+            "type": "number"
+          },
+          "notApplied": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "unverifiable": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "applied",
+          "notApplied",
+          "unverifiable"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "query",
+      "matchedMessages",
+      "submittedMessages",
+      "submittedThreadCount",
+      "capped",
+      "failed"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed1 schema field changedv0.15.1Aug 26, 2026

changedOutput schema / properties / applied / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "capped": {
-        "type": "boolean"
-      },
-      "error": {
-        "type": "string"
-      },
-      "failed": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "error": {
-              "type": "string"
-            },
-            "messageIds": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            }
-          },
-          "required": [
-            "messageIds",
-            "error"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "matchedMessages": {
-        "type": "number"
-      },
-      "modifiedMessages": {
-        "type": "number"
-      },
-      "modifiedThreadCount": {
-        "type": "number"
-      },
-      "query": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "query",
-      "matchedMessages",
-      "modifiedMessages",
-      "modifiedThreadCount",
-      "capped",
-      "failed"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "capped": {
+        "type": "boolean"
+      },
+      "error": {
+        "type": "string"
+      },
+      "failed": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "error": {
+              "type": "string"
+            },
+            "messageIds": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "messageIds",
+            "error"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "matchedMessages": {
+        "type": "number"
+      },
+      "query": {
+        "type": "string"
+      },
+      "submittedMessages": {
+        "type": "number"
+      },
+      "submittedThreadCount": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "query",
+      "matchedMessages",
+      "submittedMessages",
+      "submittedThreadCount",
+      "capped",
+      "failed"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Addedv0.6.0Aug 7, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond: it says a filter only affects future mail, that applyToExisting also mutates existing messages via a bulk-modify sweep with a stale-index caveat, that applied.submittedMessages counts submissions not changes, that verify costs an extra read per thread and never fails the call, and that the rule is reversible via delete_filter. It also names the required scope (gmail.settings.basic).

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?

Purpose is front-loaded in the first sentence and the recipe list speeds up common cases, but the verify/applyToExisting paragraph is dense and repeats the unverified-index point. Most sentences earn their place; a small amount could be tightened.

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?

For a 14-param destructive tool this is close to complete: auth scope, side effects, reversibility, and the verify output fields are all covered even though an output schema exists. The remaining gap is the criteria parameters, which an agent must guess at from Gmail search familiarity.

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% across 14 params, so the description must carry the load. It does well on the tricky ones — addLabels (names or ids, unknown names auto-created), removeLabels, maxMessages, verify, applyToExisting — but nine criteria params (from, to, subject, query, negatedQuery, hasAttachment, size, sizeComparison, excludeChats) are never explained beyond 'give at least one criterion'.

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 ('Create a Gmail filter') plus the effect on matching mail, and immediately contrasts itself with sibling operations (preview_filter, delete_filter, bulk_modify). An agent can tell this apart from modify_labels or bulk_modify without opening any 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?

An explicit USE WHEN block names the scenario (persistent auto-triage rule) and the alternative (preview_filter first, to size the catch and detect an existing filter). It also states an exclusion — forwarding filters are not supported — and explains the filter-vs-applyToExisting split that routes the agent between this tool and bulk_modify.

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