redditapis-mcp 0.1.12 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.2.0
+- **10 new monitor/webhook management tools** (task #43), the first WRITES this
+  catalog has ever carried. Unlike the reddit comment/vote/DM writes this MCP
+  still excludes, these configure the caller's OWN redditapis.com account (an
+  alerting subscription), never Reddit itself:
+  - **`reddit_monitor_add`** / **`reddit_monitor_list`** / **`reddit_monitor_update`** /
+    **`reddit_monitor_remove`** — create, list, update (pause/resume/re-filter/
+    re-cadence), and permanently delete a monitor. Requires an active plan to
+    create/update (monitoring has no free tier); reading your own list never does.
+  - **`reddit_monitor_health`** — per-monitor delivered/failed/suppressed counts and
+    whether the delivery ceiling has been hit.
+  - **`reddit_monitor_deliveries`** — the actual Reddit posts a monitor's webhook
+    has received, not just counts (task #47, the feature the operator asked for
+    directly: "can they check which all posts their webhook has received").
+  - **`reddit_monitor_webhook_create`** / **`reddit_monitor_webhook_list`** /
+    **`reddit_monitor_webhook_test`** / **`reddit_monitor_webhook_delete`** —
+    register a delivery target (secret shown once), list registered webhooks
+    (secret never re-shown), send a one-off test delivery, and permanently
+    delete one.
+  - All 10 verified live end to end against production (real create/update/
+    pause/resume/remove/re-add round trips, a real signed test delivery), not
+    just unit-tested against a mock.
+  - `remove`/`webhook_delete` are marked `destructive: true`; every write is
+    `write: true`; every other tool remains a pure, `readOnlyHint: true` read.
+  - Fixed two pre-existing drifts found while touching this file: the reported
+    `VERSION` was hardcoded `"0.1.0"` while the package had shipped up to
+    0.1.12 for months (now read live from package.json, so it can't drift
+    again), and `test/tools.test.mjs` / `test/smoke.mjs` both hardcoded stale
+    tool counts (12 and 11) against an actual catalog of 22 -- neither test
+    file had been updated as the catalog grew.
+  - Brings the tool count to 32 (22 reads + 10 monitor/webhook writes).
+
 ## 0.1.12
 - reddit_search gains advanced filters applied to the returned page (the pullpush
   filter-power model): min_score/max_score, min_comments/max_comments, is_video,

package/README.md

@@ -4,13 +4,13 @@
 [![npm downloads](https://img.shields.io/npm/dm/redditapis-mcp)](https://www.npmjs.com/package/redditapis-mcp)
 [![license](https://img.shields.io/npm/l/redditapis-mcp)](./LICENSE)
 
-Official **Model Context Protocol** server for [redditapis.com](https://www.redditapis.com), the Reddit API as native tools for Claude, Cursor, Windsurf, and any MCP client. It turns Reddit reads (search, subreddit listings, comment trees, user profiles, community metadata) into typed tools your agent can call directly.
+Official **Model Context Protocol** server for [redditapis.com](https://www.redditapis.com), the Reddit API as native tools for Claude, Cursor, Windsurf, and any MCP client. It turns Reddit reads (search, subreddit listings, comment trees, user profiles, community metadata) into typed tools your agent can call directly, plus (since 0.2.0) managing your own redditapis.com monitors and webhooks.
 
-Ask your agent to search Reddit for a topic, read a community's top posts of the week, pull a user's comment history, surface the redditors talking about a product, or read a subreddit's rules before you engage, and it calls the API for you. Every tool maps to a REST endpoint at `https://api.redditapis.com`; the server holds no state and forwards your API key on each call.
+Ask your agent to search Reddit for a topic, read a community's top posts of the week, pull a user's comment history, surface the redditors talking about a product, or read a subreddit's rules before you engage, and it calls the API for you. It can also set up a monitor that watches a subreddit for new posts matching a filter and delivers them to a webhook, then check what it's actually delivered. Every tool maps to a REST endpoint at `https://api.redditapis.com`; the server holds no state and forwards your API key on each call.
 
 ## Quick start
 
-No install needed. Run with `npx`. You need one thing: an API key from **[redditapis.com](https://www.redditapis.com)**. Reads work with just that key, so there is no account login or session step to set up.
+No install needed. Run with `npx`. You need one thing: an API key from **[redditapis.com](https://www.redditapis.com)**. Reads work with just that key, so there is no account login or session step to set up. Monitor/webhook management additionally requires an active monitoring plan (monitoring has no free tier).
 
 ## Setup
 
@@ -99,12 +99,13 @@ Authentication is a Bearer token: the server sends `Authorization: Bearer <REDDI
 
 ## Tools
 
-22 tools, all reads. This server is **read-only** by design. Reddit writes (posting, commenting, voting, DMs) are a separate authenticated surface and are intentionally out of scope here, so every tool below works with just your API key, with no account login or session step.
+32 tools: 22 reads plus 10 monitor/webhook management tools. Reddit writes (posting, commenting, voting, DMs) remain a separate authenticated surface and are intentionally out of scope here -- monitor/webhook tools configure your OWN redditapis.com account (an alerting subscription), never Reddit itself. Every read works with just your API key; the 6 monitor/webhook writes additionally need an active monitoring plan (see Monitoring below).
 
 A few conventions across the catalog:
 
 - Subreddit names go in **without** the `r/` prefix, and usernames **without** the `u/` prefix. `reddit_subreddit_posts` takes its community as `subreddit`; the `/sub/{name}/...` tools take it as `name`.
-- Listing and search tools return an `after` cursor. Pass it back as `after` to fetch the next page. `limit` accepts 1 to 100 (the API clamps out-of-range values).
+- Listing and search tools return an `after` cursor. Pass it back as `after` to fetch the next page, exactly as it was returned. `limit` accepts 1 to 100 (the API clamps out-of-range values).
+- When `after` comes back `null` there is no next page to ask for. That does not always mean you have every item: Reddit often stops serving a busy listing long before it runs out. The final response also carries `listing_status`, which reads `complete`, `truncated` or `unknown`. Only `complete` means nothing is missing. Treat the other two as a partial answer and widen across sorts, timeframes or search terms rather than paging deeper.
 - `t` (`hour`, `day`, `week`, `month`, `year`, `all`) sets the time window; on subreddit listings it applies to the `top` and `controversial` sorts, and on search it bounds the whole result set.
 
 ### Search and discovery
@@ -154,6 +155,23 @@ A few conventions across the catalog:
 | `reddit_subreddits_new` | `GET /api/reddit/subreddits/new` | Browse the newest subreddits, most recently created first. |
 | `reddit_subreddits_default` | `GET /api/reddit/subreddits/default` | Browse Reddit's default front-page set of subreddits. |
 
+### Monitoring: manage your own monitors and webhooks
+
+v1 monitors are **subreddit-scoped, posts-only** (no all-of-Reddit keyword watch, no comment monitoring yet). Creating or updating a monitor or webhook needs an active plan; reading your own list/health/deliveries never does.
+
+| Tool | Endpoint | What it does |
+|---|---|---|
+| `reddit_monitor_add` | `POST /api/reddit/monitor/add` | Create a monitor: subreddits to watch plus an optional filter (keyword, author, domain, include/exclude terms, min score, NSFW). Forward-looking only from creation (or from `baseline_item_id`). |
+| `reddit_monitor_list` | `GET /api/reddit/monitor/list` | List every monitor on your account, plus `slots` ({used, total, tier}). |
+| `reddit_monitor_update` | `POST /api/reddit/monitor/update` | Pause/resume (`active`), re-cadence, or replace a monitor's filter. Passing any filter field REPLACES the whole filter -- resupply everything you want kept. |
+| `reddit_monitor_remove` | `POST /api/reddit/monitor/remove` | Permanently delete a monitor. Cannot be undone. |
+| `reddit_monitor_health` | `GET /api/reddit/monitor/health` | Per-monitor delivered/failed/suppressed counts (last 24h), `suppressed_breakdown` splitting those suppressions into `ceiling` and `stale` reasons, and whether the delivery ceiling specifically has been hit. |
+| `reddit_monitor_deliveries` | `GET /api/reddit/monitor/deliveries` | The actual posts delivered (or attempted), newest first, with real content -- not just counts. Omit `id` to aggregate across every monitor you own. |
+| `reddit_monitor_webhook_create` | `POST /api/reddit/monitor/webhook/create` | Register a delivery target (`webhook`/`slack`/`discord`). Returns a signing secret shown ONCE. |
+| `reddit_monitor_webhook_list` | `GET /api/reddit/monitor/webhook/list` | List your webhooks. Never returns the secret. |
+| `reddit_monitor_webhook_test` | `POST /api/reddit/monitor/webhook/test` | Send a one-off test delivery to confirm a webhook is wired up correctly. |
+| `reddit_monitor_webhook_delete` | `POST /api/reddit/monitor/webhook/delete` | Permanently delete a webhook. Does not cascade-pause monitors still pointing at it. |
+
 ## Usage examples
 
 ### Research a topic across Reddit
@@ -210,15 +228,35 @@ t: "year"
 
 Then `reddit_subreddit_rules` with `{ name: "webdev" }`, and finally `reddit_post_comments` with the `permalink` from a search result, for example `{ permalink: "/r/webdev/comments/abc123/some_title/" }`, to pull the post and its comment tree.
 
-## Reads only, no session needed
+### Set up brand monitoring and check what came in
+
+> "Watch r/SaaS and r/startups for mentions of my product, send matches to my Slack, and show me what's come in so far."
+
+The agent calls `reddit_monitor_webhook_create` with:
+
+```
+url: "https://hooks.slack.com/services/..."
+kind: "slack"
+```
+
+Then `reddit_monitor_add` with:
+
+```
+subreddit: ["SaaS", "startups"]
+q: "my product name"
+```
+
+Later, `reddit_monitor_deliveries` with `{ id: "<monitor id from the add response>" }` returns the actual matching posts sent so far, or `reddit_monitor_health` for just the counts.
+
+## No session needed for reads; monitor/webhook writes need an active plan
 
-Because this server exposes reads and nothing that writes, there is no account linking, login, or cookie step: your API key alone authorizes every call. Reddit write actions (posting, commenting, voting, sending DMs) are handled by a separate authenticated surface outside this package and are deliberately not exposed here, so an agent using this server cannot take an action on any account.
+Reads need nothing but your API key -- no account linking, login, or cookie step. Reddit write actions (posting, commenting, voting, sending DMs) are handled by a separate authenticated surface outside this package and remain deliberately not exposed here, so an agent using this server can never post, vote, or DM as you on Reddit. Monitor/webhook management tools are a different kind of write: they configure your OWN redditapis.com account (an alerting subscription) and require an active monitoring plan for anything that creates or changes state (`reddit_monitor_add`/`update`/`remove`, `reddit_monitor_webhook_create`/`test`/`delete`); reading your own list, health, or delivery history never does.
 
 ## Troubleshooting
 
 **`HTTP 401 (invalid or missing API key)`** Check that `REDDITAPIS_KEY` is set correctly in your MCP client config and matches the key from [redditapis.com](https://www.redditapis.com).
 
-**`HTTP 402 (insufficient credits)`** Top up your account at [redditapis.com](https://www.redditapis.com).
+**`HTTP 402 (insufficient credits)`** Top up your account at [redditapis.com](https://www.redditapis.com). For a monitor/webhook write specifically, a 402 body of `subscription_required` means there is no active monitoring plan (monitoring has no free tier); `monitor_slots_exhausted` means the plan's monitor slot limit is already in use -- `reddit_monitor_list`'s `slots` field shows used vs total.
 
 **`HTTP 403 (access forbidden)`** The subreddit or user may be private, banned, or quarantined, or your plan may not include this endpoint.
 
@@ -248,7 +286,7 @@ npm start       # run the stdio server (needs REDDITAPIS_KEY)
 
 **Do I need a Reddit developer account?** No. Get an API key at [redditapis.com](https://www.redditapis.com); there is no application or approval step.
 
-**Can it post, comment, or vote?** No. This server is read-only. All 22 tools read Reddit; writes are a separate authenticated surface and are not exposed here.
+**Can it post, comment, or vote?** No. All 22 Reddit-facing tools read Reddit; posting, commenting, voting, and DMs are a separate authenticated surface and are not exposed here. The other 10 tools manage your OWN redditapis.com monitors/webhooks, which is a write, but never a write to Reddit itself.
 
 **Which clients are supported?** Claude Desktop, Claude Code, Cursor, Windsurf, and VS Code (Copilot agent mode), or any Model Context Protocol client.
 

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "redditapis-mcp",
-  "version": "0.1.12",
-  "description": "Official MCP server for redditapis.com, the Reddit API (subreddit listings, post + comment + community + user + media search, comment trees, top posts, user profiles) as native tools for Claude, Cursor, and any MCP client.",
+  "version": "0.2.1",
+  "mcpName": "io.github.redditapis/redditapis-mcp",
+  "description": "Official MCP server for redditapis.com, the Reddit API (subreddit listings, post + comment + community + user + media search, comment trees, top posts, user profiles) plus monitor/webhook management (create/list/update/remove a monitor, register/test/delete a webhook, read delivery history) as native tools for Claude, Cursor, and any MCP client.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/redditapis/redditapis-mcp.git"
@@ -25,7 +26,8 @@
   "scripts": {
     "start": "node src/index.js",
     "check": "node --check src/index.js && node --check src/tools.js",
-    "test": "node test/tools.test.mjs"
+    "test": "node test/tools.test.mjs",
+    "prepublishOnly": "node scripts/prepublish-tenant-check.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/src/index.js

@@ -3,8 +3,10 @@
 //
 // Exposes the Reddit API as native MCP tools for Claude, Cursor, and any MCP
 // client: subreddit listings, post + comment search, community/user/media/comment
-// search, a post's comment tree, subreddit top posts, and user profile/comments.
-// Each tool is a thin, typed wrapper over a REST endpoint at
+// search, a post's comment tree, subreddit top posts, user profile/comments, and
+// (since 0.2.0) managing your own redditapis.com monitors and webhooks -- create/
+// list/update/remove a monitor, register/list/test/delete a webhook, and read
+// delivery history. Each tool is a thin, typed wrapper over a REST endpoint at
 // https://api.redditapis.com. The server holds no state and forwards your API
 // key on every call. The tool catalog lives in ./tools.js.
 //
@@ -16,16 +18,20 @@
 //
 // Run:  npx -y redditapis-mcp@latest   (stdio transport)
 
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { TOOLS, buildQuery, buildPath } from "./tools.js";
+import { TOOLS, buildQuery, buildPath, buildBody } from "./tools.js";
 
 const API_KEY = process.env.REDDITAPIS_KEY || process.env.REDDIT_APIS_KEY;
 const BASE_URL = (
   process.env.REDDITAPIS_BASE_URL || "https://api.redditapis.com"
 ).replace(/\/+$/, "");
 const REQUEST_TIMEOUT_MS = Number(process.env.REDDITAPIS_TIMEOUT_MS || 30000);
-const VERSION = "0.1.0";
+// Read from package.json rather than a hand-maintained literal -- this drifted
+// silently to "0.1.0" while the published package reached 0.1.12, so every
+// User-Agent and MCP server handshake understated its own version for months.
+const { version: VERSION } = createRequire(import.meta.url)("../package.json");
 
 if (!API_KEY) {
   console.error(
@@ -34,12 +40,15 @@ if (!API_KEY) {
   process.exit(1);
 }
 
-// REST call. Resolves any {param} path placeholders from args, sends the rest as
-// the query string, and forwards the API key as a Bearer token (redditapis.com
+// REST call. Resolves any {param} path placeholders from args, and for GET
+// sends the rest as a query string; for POST it sends the rest as a JSON body
+// (see buildBody -- `tool` is passed through only to read its
+// `filterSpecFields`). Forwards the API key as a Bearer token (redditapis.com
 // authenticates via `Authorization: Bearer <key>` only).
-async function callEndpoint(pathTemplate, args, method = "GET") {
+async function callEndpoint(pathTemplate, args, method = "GET", tool = null) {
   const { path, rest } = buildPath(pathTemplate, args);
-  const q = buildQuery(rest);
+  const isWrite = method !== "GET";
+  const q = isWrite ? "" : buildQuery(rest);
   const url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
 
   const headers = {
@@ -47,11 +56,16 @@ async function callEndpoint(pathTemplate, args, method = "GET") {
     accept: "application/json",
     "user-agent": `reddit-mcp/${VERSION}`,
   };
+  let requestBody;
+  if (isWrite) {
+    headers["content-type"] = "application/json";
+    requestBody = JSON.stringify(buildBody(tool || {}, rest));
+  }
 
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
   try {
-    const res = await fetch(url, { method, headers, signal: ctrl.signal });
+    const res = await fetch(url, { method, headers, body: requestBody, signal: ctrl.signal });
     const body = await res.text();
     if (!res.ok) {
       const hint =
@@ -85,14 +99,14 @@ for (const tool of TOOLS) {
   const method = tool.method || "GET";
   const annotations = {
     title: tool.name,
-    readOnlyHint: !tool.write, // every tool here is a read
+    readOnlyHint: !tool.write,
     destructiveHint: Boolean(tool.destructive),
     openWorldHint: true,
   };
   server.registerTool(
     tool.name,
     { description: tool.description, inputSchema: tool.shape, annotations },
-    async (args) => callEndpoint(tool.path, args, method),
+    async (args) => callEndpoint(tool.path, args, method, tool),
   );
 }
 

package/src/tools.js

@@ -5,9 +5,22 @@
 // Each tool maps 1:1 to a REST endpoint at https://api.redditapis.com/api/reddit.
 // Tool arg names map 1:1 to endpoint query params, EXCEPT path params written as
 // {name}/{id} in a tool's `path` (e.g. /api/reddit/sub/{name}/top), which are
-// interpolated into the URL and removed from the query string. Every tool here
-// is a READ (GET); reddit writes (comment/vote/DM) are a separate authenticated
-// surface and are intentionally out of scope for this reads MCP.
+// interpolated into the URL and removed from the query string.
+//
+// WRITES: reddit writes (comment/vote/DM -- posting AS the customer to Reddit
+// itself) are a separate authenticated surface and remain intentionally out of
+// scope here, that boundary is unchanged. Monitor/webhook management (2026-08-11,
+// task #43) is a DIFFERENT kind of write: it configures the customer's OWN
+// redditapis.com account (an alerting subscription), the same risk class as
+// reading their own usage -- it never posts, votes, or DMs anywhere. Those tools
+// are marked `write: true` (and `destructive: true` for remove/delete), which
+// index.js turns into MCP's `readOnlyHint`/`destructiveHint` annotations so a
+// client can surface a confirmation before calling them.
+//
+// BODY-BEARING TOOLS: a POST tool's args become a JSON request body instead of
+// a query string (see buildBody below). `filterSpecFields` on a tool declares
+// which of its args nest under `filter_spec` in that body; everything else in
+// `shape` stays top-level (id, cadence_s, active, url, kind, ...).
 import { z } from "zod";
 
 // Shared Zod input-schema fragments.
@@ -16,9 +29,13 @@ const LIMIT = {
     "Max items to return (1 to 100). The API clamps out-of-range values; endpoint default applies if omitted.",
   ),
 };
+// Shared by every listing and search tool, so the rule about what an EMPTY
+// cursor means is stated once rather than pasted into a dozen tool descriptions
+// where one of them would eventually be missed.
 const AFTER = {
   after: z.string().optional().describe(
-    "Opaque Reddit pagination cursor from the previous response's `after` field (a fullname like `t3_abc123`). Omit on the first call; pass it to fetch the next page.",
+    "Opaque pagination cursor. Pass back the previous response's `after` value EXACTLY as it was returned; the format is not stable and a hand-written Reddit fullname loses the paging depth the cursor carries. Omit on the first call. " +
+      "When `after` comes back null there is no next page to request, and that does NOT reliably mean you have every item: Reddit often stops serving a busy listing long before it runs out. Read `listing_status` on that final response instead. It is `complete`, `truncated` or `unknown`, and ONLY `complete` means nothing is missing. Never report `truncated` or `unknown` to a user as the end of the data; say the answer is partial and widen across sorts, timeframes or search terms.",
   ),
 };
 // Sort vocabularies differ by endpoint (they map to different Reddit listings):
@@ -62,14 +79,105 @@ const QUERY = {
     "Search query text. Supports Reddit search syntax (e.g. `subreddit:webdev`, `author:spez`, `\"exact phrase\"`, `title:...`).",
   ),
 };
+// Auth-scoped private-listing cookie fragment (upvoted/saved/hidden/gilded).
+// These four are READS, but of PRIVATE data Reddit only serves to the account
+// that owns it, so -- unlike every other read tool above -- they need the
+// caller's own Reddit session cookies, obtained from POST /api/reddit/login
+// (a REST call, not an MCP tool here). GET can't carry cookies as a body, so
+// they travel as flat query-string args, same convention routes/vote.js uses
+// for its flat POST-body cookie fields.
+const LISTING_COOKIES = {
+  reddit_session: z.string().min(1).describe(
+    "Reddit account session cookie. Obtain it by calling POST /api/reddit/login on the REST API first (not an MCP tool) and reusing the `reddit_session` cookie it returns. Required.",
+  ),
+  loid: z.string().min(1).describe(
+    "Reddit account loid cookie, from the same POST /api/reddit/login response. Required.",
+  ),
+  csrf_token: z.string().optional().describe(
+    "Reddit CSRF cookie, from the same login response. Not required for a read (CSRF only guards state-changing calls) but harmless to pass if you have it.",
+  ),
+};
+
+// ── monitoring filter_spec fragments, shared by monitor_add and monitor_update ──
+// v1 is SUBREDDIT-SCOPED ONLY (all-Reddit keyword monitoring is not available),
+// matching apps/api/src/lib/monitor-filter.js's own validation exactly, so a
+// tool call fails fast in the client rather than round-tripping a 400.
+//
+// THE "POSTS ONLY" HALF OF THIS COMMENT WAS STALE AND COST A REAL GAP. It said
+// comment monitoring was "validated but rejected server-side", which stopped
+// being true when comment monitoring shipped (migrations 009/010, PRs
+// #532/#537/#541). Because `kind` was never added here, the capability was
+// unreachable from MCP entirely: verified live 2026-08-13 by setting
+// filter_spec.kind="both" over raw REST and watching real comment deliveries
+// land within two minutes, on a tier the pricing page sells as "posts and
+// comments". A stale comment is a defect report, not documentation.
+// SITEWIDE (2026-08-13). `subreddit` is OPTIONAL now: omit it and pass `q` to
+// watch ALL of Reddit for that keyword. Leaving it required here would repeat
+// the exact failure the comment above describes -- a shipped, sold capability
+// that no MCP client can reach because one schema field was never relaxed,
+// with nothing anywhere reporting an error.
+const MONITOR_SUBREDDIT_DESC =
+  "Subreddits to watch, without the r/ prefix (e.g. ['SaaS', 'startups']). 1 to 50. " +
+  "OMIT this entirely (and set `q`) to watch ALL of Reddit for a keyword -- a monitor must be anchored by " +
+  "either a subreddit list or a keyword, never neither. Do NOT pass ['all']: r/all is Reddit's site-wide " +
+  "listing rather than a subreddit, so it is refused with 400 subreddit_reserved. Sitewide monitors are " +
+  "capped per plan tier (see reddit_monitor_list's `slots`) and cover POSTS only.";
+const MONITOR_SUBREDDIT = {
+  subreddit: z.array(z.string().min(1)).min(1).max(50).optional().describe(MONITOR_SUBREDDIT_DESC),
+};
+const MONITOR_FILTER_FIELDS = {
+  q: z.string().max(200).optional().describe(
+    "Free-text keyword or phrase to match. Matched against the fields in `search_in` (default title+body+url). Omit to match every new post in the watched subreddits.",
+  ),
+  author: z.string().max(200).optional().describe("Only match posts by this Reddit username (without u/)."),
+  exclude_terms: z.array(z.string().min(1).max(200)).max(50).optional().describe(
+    "Posts containing any of these terms are suppressed even if they otherwise match. Use to cut noise (e.g. exclude 'giveaway' from a brand-mention monitor).",
+  ),
+  domain: z.array(z.string().min(1).max(200)).max(50).optional().describe(
+    "Outbound link domains to watch for (e.g. ['example.com']). Matches the post's link URL, any URL inside a self-post/comment body, and a crosspost's original link, including one that only appeared in the original post's body. Exact-or-subdomain match only: 'example.com' matches 'blog.example.com' but never 'notexample.com'. Does NOT resolve shortened links (bit.ly, t.co).",
+  ),
+  include_any: z.array(z.string().min(1).max(200)).max(50).optional().describe(
+    "At least ONE of these terms must appear (OR match) for the post to qualify, on top of any `q`."
+  ),
+  include_all: z.array(z.string().min(1).max(200)).max(50).optional().describe(
+    "EVERY one of these terms must appear (AND match) for the post to qualify, on top of any `q`."
+  ),
+  search_in: z.array(z.enum(["title", "body", "url", "permalink"])).min(1).optional().describe(
+    "Which fields keyword/term matching is scoped to. Default ['title', 'body', 'url']. Narrow to avoid false positives, e.g. a term that only appears in a URL slug matching a post that never mentions it in prose. All four resolve on comments as well as posts: on a comment, 'title' matches the title of the THREAD the comment sits under (a comment has no title of its own), which also applies through the default scope and can deliver every comment under a busy matching thread. Scope to ['body'] if you only want comments that say the term themselves.",
+  ),
+  group: z.string().max(64).optional().describe(
+    "Optional label to bundle multiple matches into one delivery instead of one webhook call per match. Omit for one delivery per matching item.",
+  ),
+  kind: z.enum(["post", "comment", "both"]).optional().describe(
+    "What to watch in the named subreddits: 'post' (default when omitted), 'comment', or 'both'. Comment monitoring requires a Growth, Pro or Scale plan -- on a lower tier this returns `comment_monitoring_requires_higher_tier` (402). Comments run roughly 7x the volume of posts, so expect proportionally more deliveries and check reddit_monitor_health's delivery ceiling before enabling it on a busy subreddit.",
+  ),
+  min_score: z.number().int().optional().describe("Only match posts with at least this many upvotes."),
+  nsfw: z.boolean().optional().describe("Set false to EXCLUDE NSFW/over-18 posts. Omitted or true both mean NSFW is allowed through -- there is no exclude-by-default; you must explicitly pass false to filter it out. POSTS ONLY: nsfw=false is REJECTED with a field-level 400 when kind is 'comment' or 'both', because Reddit flags NSFW on a post and never on an individual comment, so there is no field to filter a comment on. Run a kind='post' monitor to keep NSFW filtering, and cut unwanted comment text with exclude_terms."),
+};
+// Per-monitor webhook targeting (task #66, migration 009). NOT a filter_spec
+// field -- stays top-level in the request body, same as cadence_s/active, so
+// it is deliberately absent from MONITOR_FILTER_FIELDS/filterSpecFields.
+const MONITOR_WEBHOOK_IDS = {
+  webhook_ids: z.array(z.string().min(1)).max(20).optional().describe(
+    "Restrict delivery to specific webhook(s) instead of every active webhook on the account. Pass id(s) from reddit_monitor_webhook_create/reddit_monitor_webhook_list. Omit (or pass an empty array) for the default: deliver to every active webhook you've registered. Every id must be a webhook you own -- returns `webhook_not_found` (400) otherwise.",
+  ),
+};
+const MONITOR_ID = {
+  id: z.string().min(1).describe("The monitor's id, from reddit_monitor_add's response or reddit_monitor_list."),
+};
+const WEBHOOK_ID = {
+  id: z.string().min(1).describe("The webhook's id, from reddit_monitor_webhook_create's response or reddit_monitor_webhook_list."),
+};
 
-// The tool catalog. All reads (GET). Path params are {name}/{id} placeholders.
+// The tool catalog. Path params are {name}/{id} placeholders. Monitor/webhook
+// tools additionally carry `write`/`destructive` and, for POST tools whose
+// body nests a filter_spec, `filterSpecFields` (see buildBody below).
 export const TOOLS = [
   {
     name: "reddit_subreddit_posts",
     path: "/api/reddit/posts",
     description:
-      "List posts from a subreddit by sort order. Use this to read a community's feed: newest, hot/trending, top-of-week, rising, etc. Returns post title, author, score, comment count, and permalink, plus an `after` cursor for paging. Example: subreddit='programming' sort='top' t='week'.",
+      "List posts from a subreddit by sort order. Use this to read a community's feed: newest, hot/trending, top-of-week, rising, etc. Returns post title, author, score, comment count, and permalink, plus an `after` cursor for paging. When `after` comes back null the response carries `listing_status`: `complete` means no older posts and is only claimed when the whole run came back in under one page, `truncated` means Reddit's cap cut you off, and `unknown` means we cannot tell, so do NOT report `unknown` as the end of the data. A busy feed that Reddit simply stops serving reports `unknown`, not `complete`, so treat `unknown` as an incomplete answer and widen across sorts, timeframes or search rather than paging deeper. Example: subreddit='programming' sort='top' t='week'.",
     shape: {
       subreddit: z.string().min(1).describe(
         "Subreddit name WITHOUT the r/ prefix (e.g. 'programming', 'AskReddit'). Required.",
@@ -248,6 +356,70 @@ export const TOOLS = [
       ...LIMIT,
     },
   },
+  {
+    name: "reddit_user_upvoted",
+    path: "/api/reddit/user/{name}/upvoted",
+    description:
+      "List the posts and comments a Reddit account has UPVOTED. PRIVATE data -- Reddit only serves it to the account that owns it, so you must be logged in as `name` (see the `reddit_session`/`loid` args) or this returns 403. Mixed listing: each item is a post or a comment, tagged `kind`. Requires calling POST /api/reddit/login on the REST API first to get session cookies (not an MCP tool). Example: name='spez' (must match the logged-in account).",
+    shape: {
+      name: z.string().min(1).describe(
+        "Reddit username WITHOUT the u/ prefix. Must be the SAME account the supplied cookies belong to, or Reddit returns 403. Required (path parameter).",
+      ),
+      ...LISTING_COOKIES,
+      ...SORT_USER,
+      ...TIME,
+      ...AFTER,
+      ...LIMIT,
+    },
+  },
+  {
+    name: "reddit_user_saved",
+    path: "/api/reddit/user/{name}/saved",
+    description:
+      "List the posts and comments a Reddit account has SAVED. PRIVATE data -- Reddit only serves it to the account that owns it, so you must be logged in as `name` (see the `reddit_session`/`loid` args) or this returns 403. Mixed listing: each item is a post or a comment, tagged `kind`. Requires calling POST /api/reddit/login on the REST API first to get session cookies (not an MCP tool). Example: name='spez' (must match the logged-in account).",
+    shape: {
+      name: z.string().min(1).describe(
+        "Reddit username WITHOUT the u/ prefix. Must be the SAME account the supplied cookies belong to, or Reddit returns 403. Required (path parameter).",
+      ),
+      ...LISTING_COOKIES,
+      ...SORT_USER,
+      ...TIME,
+      ...AFTER,
+      ...LIMIT,
+    },
+  },
+  {
+    name: "reddit_user_hidden",
+    path: "/api/reddit/user/{name}/hidden",
+    description:
+      "List the posts and comments a Reddit account has HIDDEN. PRIVATE data -- Reddit only serves it to the account that owns it, so you must be logged in as `name` (see the `reddit_session`/`loid` args) or this returns 403. Mixed listing: each item is a post or a comment, tagged `kind`. Requires calling POST /api/reddit/login on the REST API first to get session cookies (not an MCP tool). Example: name='spez' (must match the logged-in account).",
+    shape: {
+      name: z.string().min(1).describe(
+        "Reddit username WITHOUT the u/ prefix. Must be the SAME account the supplied cookies belong to, or Reddit returns 403. Required (path parameter).",
+      ),
+      ...LISTING_COOKIES,
+      ...SORT_USER,
+      ...TIME,
+      ...AFTER,
+      ...LIMIT,
+    },
+  },
+  {
+    name: "reddit_user_gilded",
+    path: "/api/reddit/user/{name}/gilded",
+    description:
+      "List the posts and comments a Reddit account has received an award (gold) on. PRIVATE data -- Reddit only serves it to the account that owns it, so you must be logged in as `name` (see the `reddit_session`/`loid` args) or this returns 403. Mixed listing: each item is a post or a comment, tagged `kind`. Requires calling POST /api/reddit/login on the REST API first to get session cookies (not an MCP tool). Example: name='spez' (must match the logged-in account).",
+    shape: {
+      name: z.string().min(1).describe(
+        "Reddit username WITHOUT the u/ prefix. Must be the SAME account the supplied cookies belong to, or Reddit returns 403. Required (path parameter).",
+      ),
+      ...LISTING_COOKIES,
+      ...SORT_USER,
+      ...TIME,
+      ...AFTER,
+      ...LIMIT,
+    },
+  },
   {
     name: "reddit_subreddit_comments",
     path: "/api/reddit/sub/{name}/comments",
@@ -312,7 +484,7 @@ export const TOOLS = [
     name: "reddit_by_id",
     path: "/api/reddit/by_id/{fullnames}",
     description:
-      "Bulk-fetch posts by their t3_ fullnames in ONE call (up to 100), instead of a request per post. Pass a comma-separated list of fullnames you already have from a search or listing to hydrate them. Returns posts with title, author, score, comment count, and permalink — the same post shape as the listing endpoints. An unknown id is simply absent from the result. Example: fullnames='t3_abc123,t3_def456'.",
+      "Bulk-fetch posts by their t3_ fullnames in ONE call (up to 100), instead of a request per post. Pass a comma-separated list of fullnames you already have from a search or listing to hydrate them. Returns posts with title, author, score, comment count, and permalink, the same post shape as the listing endpoints. The result is NOT always one-to-one with your request, so read `meta`: `listing_status` is `complete` only when every fullname came back, `truncated` is the boolean to branch on, and `missing_fullnames` names exactly which ids did not. Example: fullnames='t3_abc123,t3_def456'.",
     shape: {
       fullnames: z.string().min(1).describe(
         "Comma-separated post fullnames, each a t3_ prefix followed by the base-36 id (e.g. 't3_abc123,t3_def456'). Up to 100. Required (path parameter).",
@@ -340,6 +512,127 @@ export const TOOLS = [
       "Browse Reddit's default front-page set of subreddits, no keyword needed. Returns a `subreddits` list (each with name, title, subscriber count, description, type, and NSFW flag) plus an `after` cursor for paging. This BROWSES the default communities; use reddit_search_communities instead to SEARCH communities by keyword.",
     shape: { ...AFTER, ...LIMIT },
   },
+
+  // ── monitoring: manage the caller's own account, never posts/votes/DMs Reddit itself ──
+  {
+    name: "reddit_monitor_add",
+    path: "/api/reddit/monitor/add",
+    method: "POST",
+    write: true,
+    filterSpecFields: ["subreddit", "kind", "q", "author", "exclude_terms", "domain", "include_any", "include_all", "search_in", "group", "min_score", "nsfw"],
+    description:
+      "Create a new Reddit monitor: watch one or more subreddits, or ALL of Reddit, for new posts (or comments, via `kind`) matching a filter, and get every match delivered to a webhook you've registered with reddit_monitor_webhook_create. Omit `subreddit` and set `q` for a sitewide keyword monitor covering every subreddit at once (posts only). By default matches go to EVERY active webhook on your account; pass `webhook_ids` to route this monitor's matches to only specific webhook(s). Every redditapis.com account holds a free entitlement of ONE all-of-Reddit post watch at a 60s cadence (up to 10,000 deliveries a day), so no subscription is needed to create that monitor. Naming a `subreddit`, matching comments, a faster cadence and any additional watch require a paid plan. Needs at least one monitor slot free (see reddit_monitor_list's `slots`). Forward-looking only from the moment of creation, or from `baseline_item_id` if given -- it never backfills posts that already existed. Returns the created monitor (with its `id`) on success, or `subscription_required` (402) if the account holds no recognised entitlement at all, `subreddit_scope_requires_paid_plan` (402) if a free account named a `subreddit`, `monitor_slots_exhausted` (402) if the plan's slot limit is reached, `sitewide_slots_exhausted` (402) if the plan's separate sitewide cap is reached, `distinct_subreddit_limit_reached` (402) if the account already watches as many DIFFERENT subreddits as the plan covers (the limit counts distinct subreddits across all your monitors, not monitors, and the same subreddit in two monitors counts once; see reddit_monitor_list's `slots.distinct_subreddits_total`), `sitewide_comment_monitoring_not_available` (501) if a sitewide monitor asks for comments, `subreddit_reserved` (400) if `subreddit` names 'all', `subreddit_not_found` (400) if a named subreddit does not exist, or `webhook_not_found` (400) if a `webhook_ids` entry is not yours.",
+    shape: {
+      ...MONITOR_SUBREDDIT,
+      ...MONITOR_FILTER_FIELDS,
+      cadence_s: z.number().int().positive().optional().describe(
+        "Requested poll interval in seconds. May only be SLOWER than the plan tier's floor, never faster -- a too-low value is silently clamped up to the tier's minimum. Omit to use the tier's default.",
+      ),
+      baseline_item_id: z.string().optional().describe(
+        "A Reddit post fullname (e.g. 't3_abc123') to use as the starting point instead of 'now' -- matching starts strictly after this item. Omit to start from the moment of creation.",
+      ),
+      ...MONITOR_WEBHOOK_IDS,
+    },
+  },
+  {
+    name: "reddit_monitor_list",
+    path: "/api/reddit/monitor/list",
+    description:
+      "List every monitor on the caller's account, with each one's filter, active state, and cadence, plus a `slots` object ({used, total, tier}) showing how many monitor slots are purchased vs in use. Reading your own list never requires an active plan (a lapsed subscription shows an empty or paused list, not an error). `webhook_ids` NULL DOES NOT MEAN THE MONITOR HAS NO DESTINATION: null is the default and means matches go to EVERY active webhook on the account, which is the normal healthy state. A non-empty array narrows delivery to just those webhook ids. Never report a monitor as having no delivery target on the strength of a null here -- to see where a monitor's matches actually went, read reddit_monitor_deliveries, whose rows carry the resolved `webhook_id`.",
+    shape: {},
+  },
+  {
+    name: "reddit_monitor_update",
+    path: "/api/reddit/monitor/update",
+    method: "POST",
+    write: true,
+    filterSpecFields: ["subreddit", "kind", "q", "author", "exclude_terms", "domain", "include_any", "include_all", "search_in", "group", "min_score", "nsfw"],
+    description:
+      "Update an existing monitor: pause/resume it (`active`), change its poll interval (`cadence_s`), switch between posts and comments (`kind`), replace its filter entirely, or re-target which webhook(s) it delivers to (`webhook_ids`). IMPORTANT: if you pass ANY filter field (subreddit, q, kind, domain, etc.), it REPLACES the whole filter, it does not merge with the existing one -- resupply every field you want kept, including `subreddit` AND `kind` (omitting `kind` reverts that monitor to posts-only). Same rule for `webhook_ids`: passing it REPLACES the monitor's targeting outright (an empty array clears back to 'every active webhook'); omitting it entirely leaves the monitor's existing targeting untouched. Omit all filter/webhook_ids fields to change only `active`/`cadence_s`. Returns 404 `monitor_not_found` if the id does not exist or is not yours, or 400 `webhook_not_found` if a `webhook_ids` entry is not yours.",
+    shape: {
+      ...MONITOR_ID,
+      ...{
+        subreddit: z.array(z.string().min(1)).min(1).max(50).optional().describe(
+          MONITOR_SUBREDDIT_DESC +
+            " On an update, omitting this while passing another filter field makes the monitor SITEWIDE (the filter is replaced wholesale, not merged), so resupply it if you meant to keep the monitor scoped.",
+        ),
+      },
+      ...MONITOR_FILTER_FIELDS,
+      active: z.boolean().optional().describe("Set false to pause the monitor (stops matching/delivering), true to resume it."),
+      cadence_s: z.number().int().positive().optional().describe("New poll interval in seconds, same tier-floor clamping as reddit_monitor_add."),
+      ...MONITOR_WEBHOOK_IDS,
+    },
+  },
+  {
+    name: "reddit_monitor_remove",
+    path: "/api/reddit/monitor/remove",
+    method: "POST",
+    write: true,
+    destructive: true,
+    description:
+      "Delete a monitor. There is no undo endpoint -- it stops matching immediately, its slot is freed for a new monitor, and it disappears from reddit_monitor_list. Its past deliveries are NOT erased: they remain queryable via reddit_monitor_deliveries (both scoped by monitor_id and in the aggregate, no-id view) forever. Returns 404 `monitor_not_found` if the id does not exist or is not yours.",
+    shape: { ...MONITOR_ID },
+  },
+  {
+    name: "reddit_monitor_health",
+    path: "/api/reddit/monitor/health",
+    description:
+      "Per-monitor health: whether it's active, its poll cadence, when it last matched something, and delivery counts for the last 24h (`delivered_24h`, `failed_24h`, `suppressed_24h`) plus whether its delivery ceiling has been hit (`ceiling_reached`) and what that ceiling is (`daily_delivery_ceiling`). `suppressed_24h` COUNTS TWO DIFFERENT THINGS AND `suppressed_breakdown` SPLITS THEM: `ceiling` (the monitor's daily cap was reached) and `stale` (the item was already older than the freshness window when we first saw it, so it was withheld rather than delivered as if it were new). A stale withhold is the usual reason a monitor's delivered count sits far below its matched count with no error anywhere, and it is the freshness gate working as intended -- nothing failed, the endpoint is fine, no limit on the plan rejected them, and retrying cannot recover the items. Do NOT read `suppressed_24h > 0` as 'this monitor is over its limit': `ceiling_reached` is the field that answers that, and a stale withhold deliberately does not set it. When `suppressed_breakdown.resolved` is false the counts do not add up to the total and `unresolved_reason` says why, so do not report a split off them; `ceiling_reached` stays conservative in that case rather than being cleared. THOSE COUNTS ONLY COVER POSTS WE FETCHED. A post we never fetched was never matched and leaves no row behind, so it is absent from all three counters rather than counted in any of them -- zeros there mean 'no matches recorded', never 'nothing was missed'. `coverage_24h` is the separate field that speaks to fetching, and its `status` is the one to read first: `complete` (every poll reached the point where the previous poll finished), `degraded` (at least one poll was truncated and posts were lost unrecoverably -- see `gaps[]`, `posts_in_window_at_least` and the estimated `posts_missed_estimate`), `partial` (nothing found, but not every kind of loss was checked -- see `unobserved_events`), or `unknown` (the check could not be run at all -- see `reason`). Do NOT report a monitor as healthy on `unknown` or `partial`, and do not treat a null count as zero: both mean the question went unanswered. `coverage_24h` is fed by the poll log and covers BOTH ways a poll loses posts unrecoverably (`listing_exhausted`, where Reddit stopped serving older posts, and `poll_overflow`, where the feed outran one poll's page budget); `observed_events` names what was actually checked, and a status of `complete` is only ever awarded when both were. WHAT `complete` DOES AND DOES NOT ESTABLISH: it means every poll that RAN got back to where the previous poll finished, AND that every feed was actually polled. The second half is `stream_liveness`, the field to read FIRST. `coverage_24h` is computed from the poll log, and a feed that is never polled writes nothing to that log, so it records no truncated poll and the coverage read comes back clean -- identical to a healthy monitor. `stream_liveness` reads a different source (the polling registry plus the per-feed last-successful-poll stamp), neither of which a poll that never ran can produce. Its `status` is `live` (every feed checked within three times its own interval), `degraded` (at least one is not: see `streams[]` for `never_polled`, `stalled` or `unregistered` per feed), or `unknown` (could not be established, including `streams_awaiting_first_poll` on a monitor created moments ago, which clears itself). `coverage_24h` can never read `complete` while this is anything but `live`. Do NOT report a monitor as healthy unless `stream_liveness.status` is `live`, and do not read a zero delivery count on a `never_polled` feed as a quiet subreddit: nothing was checked, so nothing could match. `gaps[]` IS A SAMPLE, NOT THE WHOLE LIST: it carries the most recent gaps only, `gaps_returned` says how many are in it, `gaps_truncated` says whether more exist, and `gap_events_24h` is always the true total. Count gaps from `gap_events_24h` and never from the length of `gaps[]`. FINALLY, `cadence` ANSWERS 'AM I BEING CHECKED AS OFTEN AS I PAY TO BE', which none of the fields above can. Cadence is a priced feature, so this is the field that says whether the monitor is being served the interval its plan sells. `promised_cadence_s` is the floor the account's CURRENT plan includes and `requested_cadence_s` is what this monitor is actually set to; `meets_entitlement` false means the monitor is set slower than the plan allows, which happens because a plan upgrade does NOT re-cadence monitors that already exist -- the fix is to set `cadence_s` on the monitor, and a deliberately slower cadence is also a legitimate choice. `last_checked_s_ago`, `freshness_ratio` and `within_margin` describe the slowest feed feeding this monitor, named in `slowest_stream`. READ `freshness_reading` BEFORE QUOTING ANY OF THEM: it is ONE INSTANTANEOUS SAMPLE, not an average and not a sustained verdict, so a single reading past the margin is not by itself proof of under-service. Every one of these is TRI-STATE and null NEVER means fine: a null `within_margin` or `meets_entitlement` means the question could not be answered, and `unknown_reason` says why. Do not report a monitor as on-cadence on a null.",
+    shape: { ...MONITOR_ID },
+  },
+  {
+    name: "reddit_monitor_deliveries",
+    path: "/api/reddit/monitor/deliveries",
+    description:
+      "Delivery history: the actual Reddit posts a monitor's webhook has received (or attempted), newest first, including the real post content (title, subreddit, permalink, author). Answers 'what did I actually get sent', not just 'how many' (see reddit_monitor_health for counts). Omit `id` to aggregate history across every monitor you own.",
+    shape: {
+      id: z.string().optional().describe("Narrow to one monitor's history. Omit to aggregate across every monitor you own."),
+      status: z.enum(["pending", "delivered", "failed", "dead", "suppressed"]).optional().describe(
+        "Filter to one delivery status. 'dead' = retries exhausted, gave up. 'suppressed' = matched but deliberately not sent, and `payload.suppressed.reason` says which of the two reasons applied: 'delivery_ceiling' (the monitor's daily cap) or 'stale_item' (the item was already older than the freshness window when we first saw it, so it was withheld rather than delivered as if it were new). A 'stale_item' row is NOT a fault and was NOT rejected by any plan limit, and retrying cannot recover it; `payload.suppressed` carries the age and the threshold. Omit for all statuses.",
+      ),
+      limit: z.number().int().min(1).max(200).optional().describe("Max rows to return, 1 to 200. Default 50."),
+      before: z.string().optional().describe("ISO 8601 timestamp cursor for pagination -- pass the `created_at` of the oldest row from the previous page to fetch older deliveries."),
+    },
+  },
+  {
+    name: "reddit_monitor_webhook_create",
+    path: "/api/reddit/monitor/webhook/create",
+    method: "POST",
+    write: true,
+    description:
+      "Register a delivery target for monitors to send matches to. Requires an active monitoring plan (a webhook with no plan could never receive anything). Returns the webhook with its signing `secret` SHOWN ONCE -- store it immediately, it is never returned again by reddit_monitor_webhook_list. HTTPS only; the URL is re-validated (including a fresh DNS check) at every delivery, not just at creation.",
+    shape: {
+      url: z.string().url().describe("HTTPS URL to deliver matches to. Must be publicly reachable HTTPS, no embedded credentials, no loopback/private/link-local address."),
+      kind: z.enum(["webhook", "slack", "discord", "email"]).optional().describe(
+        "Payload shape to send. PREFER OMITTING THIS: for a hooks.slack.com or discord.com/api/webhooks URL the kind is inferred from the host, and the response reports what it inferred in `kind_inferred_from`. 'slack'/'discord' format as native incoming-webhook messages; 'webhook' sends redditapis' generic signed JSON envelope and is the fallback only for a host we do not recognise; 'email' is not yet a real delivery transport. Passing 'webhook' for a Slack or Discord URL does NOT force the generic envelope (that combination can never deliver -- Slack answers 400 invalid_payload); the host wins and `kind_corrected_from` says so. Passing one SPECIFIC kind for a different platform's host (e.g. 'discord' with a hooks.slack.com URL) is refused with `webhook_kind_mismatch` (400) rather than stored.",
+      ),
+    },
+  },
+  {
+    name: "reddit_monitor_webhook_list",
+    path: "/api/reddit/monitor/webhook/list",
+    description: "List every webhook registered on the caller's account. Never returns the signing secret (shown once, at creation, by reddit_monitor_webhook_create).",
+    shape: {},
+  },
+  {
+    name: "reddit_monitor_webhook_test",
+    path: "/api/reddit/monitor/webhook/test",
+    method: "POST",
+    write: true,
+    description:
+      "Send a one-off test delivery to a registered webhook (rate-limited to 10/min) so you can confirm it's wired up correctly before waiting for a real match. Uses the webhook's `kind` to format the test payload the same way a real delivery would. On failure the response carries `reason` and `status` plus TWO fields that say what to actually do: `hint`, our sentence naming the fix (most often that the target's `kind` does not match its host, which no test can succeed through), and `detail`, a bounded, sanitised copy of what the destination itself replied. Report `hint` to the user rather than the bare `reason` -- `http_error` with a 400 names no field, no value and no remedy. Returns 404 `webhook_not_found` if the id does not exist or is not yours, or `webhook_url_rejected` if the URL fails re-validation (e.g. now resolves to a private address).",
+    shape: { ...WEBHOOK_ID },
+  },
+  {
+    name: "reddit_monitor_webhook_delete",
+    path: "/api/reddit/monitor/webhook/delete",
+    method: "POST",
+    write: true,
+    destructive: true,
+    description:
+      "Permanently delete a webhook. Any monitor still pointing at it will fail to deliver until repointed at a different webhook -- this does NOT cascade-delete or pause the monitors using it. Cannot be undone. Returns 404 `webhook_not_found` if the id does not exist or is not yours.",
+    shape: { ...WEBHOOK_ID },
+  },
 ];
 
 // Turn tool args into a URL query string. Skips undefined/null/empty values.
@@ -366,3 +659,27 @@ export function buildPath(template, args) {
   for (const [k, v] of Object.entries(args || {})) if (!used.has(k)) rest[k] = v;
   return { path, rest };
 }
+
+// Turn a POST tool's args into the JSON body the REST endpoint expects. A field
+// named in `tool.filterSpecFields` nests under `filter_spec`; everything else
+// stays top-level (id, cadence_s, active, url, kind, ...). Skips undefined so
+// an omitted optional arg is genuinely absent from the body, never sent as
+// `null` -- monitor-handlers.js tells "field not provided" apart from "field
+// explicitly cleared" (e.g. updateMonitor only replaces filter_spec when at
+// least one filter field is present at all).
+export function buildBody(tool, args) {
+  const filterFields = new Set(tool.filterSpecFields || []);
+  const body = {};
+  let filterSpec = null;
+  for (const [k, v] of Object.entries(args || {})) {
+    if (v === undefined) continue;
+    if (filterFields.has(k)) {
+      filterSpec = filterSpec || {};
+      filterSpec[k] = v;
+    } else {
+      body[k] = v;
+    }
+  }
+  if (filterSpec) body.filter_spec = filterSpec;
+  return body;
+}