mailwarden

list_unsubscribe

Read-only

Reports the opt-out options an email thread advertises, including one-click, link, and mailto methods, without contacting the sender.

Instructions

Report the opt-out options a thread advertises (List-Unsubscribe / RFC 8058), without contacting anyone. Reads the newest message that carries the header, so a reply threaded onto a newsletter does not hide it. oneClick means the sender supports the automatable one-click opt-out — the unsubscribe tool can perform it. httpsUrls without oneClick are links for a human to open in a browser; mailtos would require sending mail, which mailwarden never does. bodyCandidates appears only when the headers advertise nothing: unsubscribe links found in the message TEXT, which is written by the sender and therefore untrusted. Show them to the user to open; never fetch one, and do not treat them as an opt-out that happened. hasUnsubscribe stays false for them — it describes the headers. USE WHEN: checking whether a newsletter can be unsubscribed from, or showing the user the link to click. SIDE EFFECTS: none — no request is made to the sender.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "threadId": "<threadId>"
    },
    "name": "list_unsubscribe"
  }
}

Input Schema

Name	Required	Description	Default
`threadId`	Yes

Output Schema

Name	Required	Description	Default
`from`	Yes
`mailtos`	Yes
`subject`	Yes
`oneClick`	Yes
`threadId`	Yes
`httpsUrls`	Yes
`messageId`	Yes
`bodyCandidates`	Yes
`hasUnsubscribe`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

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

Changed2 schema fields changedv0.18.0Sep 4, 2026

addedOutput schema / properties / bodyCandidates

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "evidence": {
+        "enum": [
+          "link-text",
+          "url"
+        ],
+        "type": "string"
+      },
+      "text": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "url",
+      "evidence",
+      "text"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "threadId",
-  "messageId",
-  "from",
-  "subject",
-  "hasUnsubscribe",
-  "oneClick",
-  "httpsUrls",
-  "mailtos"
-]New value: +[
+  "threadId",
+  "messageId",
+  "from",
+  "subject",
+  "hasUnsubscribe",
+  "bodyCandidates",
+  "oneClick",
+  "httpsUrls",
+  "mailtos"
+]

Addedv0.9.0Aug 14, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only say readOnly and closed-world; the description goes well beyond by asserting 'no request is made to the sender', disclosing that it reads the *newest* message carrying the header (so threaded replies don't hide it), and flagging bodyCandidates as sender-authored and untrusted. That is exactly the kind of safety context annotations cannot express.

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 the core action and the no-side-effect guarantee, then layered field semantics, then USE WHEN and SIDE EFFECTS. Dense but every clause carries operational meaning; the `hasUnsubscribe` note is slightly defensive but justified given the untrusted-body warning.

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?

Covers the full surface an agent needs: what is read, what is not done (no network, no mail), how to interpret each output bucket, how to handle untrusted candidates, and when to hand off to `unsubscribe`. With an output schema present, added interpretation of `oneClick`/`httpsUrls`/`mailtos`/`hasUnsubscribe` is bonus rather than filler.

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?

Only one parameter (`threadId`) with 0% schema description coverage, and the description never mentions it — it's inferable from the name, but no format, scope, or resolution behavior is given. Not a serious gap for a single obvious ID param, but nothing added beyond the schema either.

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 ('report the opt-out options a thread advertises') and immediately distinguishes itself from the sibling that performs the action, noting the `unsubscribe` tool is what actually carries out a one-click opt-out. The scope (headers, not message body) is explicit.

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?

Has an explicit USE WHEN line ('checking whether a newsletter can be unsubscribed from, or showing the user the link to click') and names the alternative tool (`unsubscribe`) plus the condition that routes to it (`oneClick` true). Exclusions are also stated: never fetch bodyCandidates, never treat them as an opt-out.

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