mailwarden

create_filter

Destructive

Create a Gmail filter to auto-label or archive incoming mail by sender, subject, size, or query. Optionally apply the same label changes to existing messages to clean your inbox.

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). USE WHEN: setting up a persistent auto-triage rule (e.g. 'always archive + label newsletters from x'), optionally cleaning up the existing backlog too. 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.

Input Schema

TableJSON Schema

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

Output Schema

TableJSON 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. Dates show when Glama detected each change.

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.7/5.0

Behavior5/5

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

The description goes well beyond the destructiveHint annotation by disclosing that a server-side rule is created, affecting future mail, and that it is reversible via delete_filter. It also explains the applyToExisting behavior, the unverified-index caveat, the default maxMessages, label auto-creation, and the required permission 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-organized with clear sections: common recipes, USE WHEN, NOTE, and SIDE EFFECTS. Every sentence adds actionable information, and the most important usage constraints are front-loaded.

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 13 optional parameters and significant side effects, the description covers the core contract: at least one criterion and one action, action types, persistence behavior, backlog modification, caveats, permissions, and reversibility. The output schema exists, so return-value documentation is not needed here.

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?

With 0% schema description coverage, the description adds crucial meaning for addLabels/removeLabels, including label auto-creation and the special label shortcuts like INBOX, UNREAD, TRASH, and STARRED. It also clarifies applyToExisting and maxMessages semantics, though individual criteria parameters like negatedQuery, excludeChats, and sizeComparison are left to their self-explanatory names.

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 description opens with a specific verb and resource: 'Create a Gmail filter' and then explains exactly what it does with matching incoming mail. It distinguishes this tool from siblings by focusing on persistent filter creation, labeling actions, and the applyToExisting backlog sweep.

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?

The 'USE WHEN' section explicitly identifies the intended scenario: setting up persistent auto-triage rules and optionally cleaning up existing mail. It also notes forwarding filters are unsupported, but it does not name an alternative tool for one-off bulk actions, so it stops just short of full when-not/alternative guidance.

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

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/csitte/mailwarden'

If you have feedback or need assistance with the MCP directory API, please join our Discord server