@twitterapis/mcp 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.17.0 (2026-09-30)
+
+### Added
+
+- **`paid_promotion` on the 17 tweet-list tools.** `"only"` keeps tweets X labels
+  Paid partnership (`is_paid_promotion` true), `"exclude"` keeps the rest. It filters
+  the page the API returned, so `next_cursor` still pages on, and the response carries
+  `paid_promotion_filter { mode, kept, removed }`. Same cost as without it.
+
+## 0.16.1 (2026-09-29)
+
+### Changed
+
+- **A restart answered in JSON is ridden out too.** The gateway now answers a
+  restart with a JSON 503 (`"error": "gateway_restarting"`, `Retry-After`)
+  instead of its HTML page; a read retries on either. Any other JSON 503 from
+  the API, and that code on any other status, is still never retried.
+- **A cancelled call stops.** When the MCP client cancels a tool call, the
+  request in flight is aborted and the wait before a retry ends at once; the
+  result says "Request cancelled by the caller." instead of reporting a timeout.
+
 ## 0.16.0 (2026-09-29)
 
 ### Changed

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@twitterapis/mcp",
   "mcpName": "io.github.TwitterAPIs/twitterapis-mcp",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Official MCP server for twitterapis.com, the Twitter/X API (search, users, followers, tweets, threads, lists, likes, bookmarks, DMs) plus write actions (post/like/retweet/follow) as native tools for Claude, Cursor, and any MCP client.",
   "repository": {
     "type": "git",
@@ -43,7 +43,9 @@
     "check:manifest-tools": "node scripts/gen-manifest-tools.mjs --check",
     "bundle": "node scripts/gen-manifest-tools.mjs --write && npx -y @anthropic-ai/mcpb@2.1.2 pack .",
     "check:mcpb": "npx -y @anthropic-ai/mcpb@2.1.2 validate manifest.json",
-    "check:publish-provenance": "node test/publish-provenance.mjs"
+    "check:publish-provenance": "node test/publish-provenance.mjs",
+    "postpublish": "node scripts/registry-drift.mjs --publish",
+    "check:registry-drift": "node scripts/registry-drift.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/src/server.js

@@ -204,7 +204,7 @@ export function createServer({
   // substitute into the URL template) and callEndpoint splices them into path
   // before building the query string or body, so a pathParams arg never leaks
   // into either.
-  async function callEndpoint(path, args, method = "GET", jsonBody = false, pathParams = []) {
+  async function callEndpoint(path, args, method = "GET", jsonBody = false, pathParams = [], { signal: callerSignal } = {}) {
     if (!apiKey && !authHeaders) return paywallResult("no_key");
     // Fill {name} URL segments from args and strip those keys, so a pathParams arg
     // (e.g. a monitor/webhook id) never also leaks into the query string or JSON
@@ -272,16 +272,34 @@ export function createServer({
     // socket dropped mid-answer can all happen after the API did the work, and
     // "fetch failed" alone also covers DNS and TLS errors that retrying cannot fix.
     const RETRYABLE_NET = new Set(["ECONNREFUSED"]);
-    const gatewayFailure = (status, text) =>
-      (status === 502 || status === 503) && /^\s*<(!doctype|html)/i.test(text);
+    // The gateway answers a restart two ways: nginx's stock HTML 502/503 page,
+    // or (since 2026-09-29) its own JSON 503 whose error is "gateway_restarting".
+    // Nginx sends that JSON only when it could not reach the API at all, so the
+    // API's own JSON errors (which never use that code) are still never retried.
+    const gatewayFailure = (status, text) => {
+      if ((status === 502 || status === 503) && /^\s*<(!doctype|html)/i.test(text)) return true;
+      if (status !== 503) return false;
+      try { return JSON.parse(text)?.error === "gateway_restarting"; } catch { return false; }
+    };
+    // The MCP caller's cancel (notifications/cancelled) aborts the request in
+    // flight and any wait between retries, so a cancelled call stops at once.
+    const cancelled = () => Boolean(callerSignal?.aborted);
+    const pause = (ms) => cancelled() ? Promise.resolve() : new Promise((resolve) => {
+      const done = () => { callerSignal?.removeEventListener?.("abort", done); resolve(); };
+      Promise.resolve(sleepImpl(ms)).then(done, done);
+      callerSignal?.addEventListener?.("abort", done, { once: true });
+    });
     const transientNetwork = (err) =>
       !gotResponse && err?.name !== "AbortError" && RETRYABLE_NET.has(err?.cause?.code ?? err?.code);
     let attempt = 0;
     let gotResponse = false;
     for (;;) {
     gotResponse = false;
+    if (cancelled()) return { isError: true, content: [{ type: "text", text: "Request cancelled by the caller." }] };
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+    const onCancel = () => ctrl.abort();
+    callerSignal?.addEventListener?.("abort", onCancel, { once: true });
     try {
       const res = await fetchImpl(url, {
         method,
@@ -291,9 +309,10 @@ export function createServer({
       });
       gotResponse = true;
       const body = await res.text();
-      if (canRetry && attempt < retryDelaysMs.length && gatewayFailure(res.status, body)) {
+      if (canRetry && !cancelled() && attempt < retryDelaysMs.length && gatewayFailure(res.status, body)) {
         clearTimeout(timer);
-        await sleepImpl(retryDelaysMs[attempt++]);
+        callerSignal?.removeEventListener?.("abort", onCancel);
+        await pause(retryDelaysMs[attempt++]);
         continue;
       }
       if (!res.ok) {
@@ -323,11 +342,13 @@ export function createServer({
       lastError = null;
       return { content: [{ type: "text", text: body }] };
     } catch (err) {
-      if (canRetry && attempt < retryDelaysMs.length && transientNetwork(err)) {
+      if (canRetry && !cancelled() && attempt < retryDelaysMs.length && transientNetwork(err)) {
         clearTimeout(timer);
-        await sleepImpl(retryDelaysMs[attempt++]);
+        callerSignal?.removeEventListener?.("abort", onCancel);
+        await pause(retryDelaysMs[attempt++]);
         continue;
       }
+      if (cancelled()) return { isError: true, content: [{ type: "text", text: "Request cancelled by the caller." }] };
       const code = err?.cause?.code ?? err?.code;
       const msg = err?.name === "AbortError"
         ? `timed out after ${REQUEST_TIMEOUT_MS}ms`
@@ -336,6 +357,7 @@ export function createServer({
       return { isError: true, content: [{ type: "text", text: `Request failed: ${msg}` }] };
     } finally {
       clearTimeout(timer);
+      callerSignal?.removeEventListener?.("abort", onCancel);
     }
     }
   }
@@ -370,8 +392,8 @@ export function createServer({
       handler = LOCAL_HANDLERS[tool.local];
       if (!handler) throw new Error(`[twitterapis-mcp] tool ${tool.name} declares local handler "${tool.local}" but src/server.js has none`);
     } else {
-      handler = async (args) => {
-        const result = await callEndpoint(tool.path, args, method, Boolean(tool.jsonBody), tool.pathParams || []);
+      handler = async (args, extra) => {
+        const result = await callEndpoint(tool.path, args, method, Boolean(tool.jsonBody), tool.pathParams || [], { signal: extra?.signal });
         if (result?.isError && lastError) {
           let resolved = null;
           try { resolved = resolvePathParams(tool.path, tool.pathParams || [], args).path; } catch { resolved = null; }

package/src/tools.js

@@ -55,6 +55,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -224,6 +227,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -250,6 +256,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -273,6 +282,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -299,6 +311,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -322,6 +337,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -345,6 +363,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -553,6 +574,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -573,6 +597,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -631,6 +658,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -712,6 +742,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -735,6 +768,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -884,6 +920,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -1119,6 +1158,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -1151,6 +1193,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -1250,6 +1295,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {
@@ -1308,6 +1356,9 @@ export const TOOLS = [
       compact: z.enum(["1","true"]).optional().describe(
         "Optional. Set to \"1\" for the built-in compact preset: ids, url, text, created_at, lang, engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. Trims what it recognises and, on its own, never turns a body into {}. Combine with fields to keep extra paths (then only the named paths and the envelope keys survive).",
       ),
+      paid_promotion: z.enum(["only","exclude"]).optional().describe(
+        "Optional. Filter this page's tweets by X's Paid partnership label: \"only\" keeps tweets whose is_paid_promotion is true, \"exclude\" keeps the rest. It filters the page X returned and does not fetch more, so a page can hold fewer tweets than asked for, or none, while next_cursor still pages on; the response carries paid_promotion_filter { mode, kept, removed }. A retweet is judged by its own flag, not the retweeted post's. Same cost as without it.",
+      ),
     },
   },
   {