@twitterapis/mcp 0.9.5 → 0.9.7

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.9.7 (2026-09-04)
+
+### Fixed
+
+- **`twitter_feedback_send` no longer holds the local queue lock while it talks to the API.** The lock's stale threshold is 10s and a request may take up to 30s, so a send that held it let a second MCP process reclaim the lock, write its draft, and then lose that draft to the sender's pre-send snapshot. Drafts to send are now picked under the lock, posted with it released, and after each success the lock is re-taken, the queue re-read and exactly that draft removed. A draft added by another process mid-send survives; a crash mid-batch still never resends a posted report. If the per-success removal itself cannot take the lock, the report is still shown as posted with its server id and the caller is told to discard that draft rather than send it again.
+
+### Added
+
+- **`twitter_feedback_send` and `twitter_feedback_get`, report a bug or a gap to the twitterapis.com team from inside the session you are already in.** Modelled on Claude Code's own feedback tool: the model drafts a report at a high-signal moment (a call failed in a way that is not your key, credits, session or a rate limit and you had to work around it; you asked for something no tool covers; a documented field came back empty or wrong; you were plainly frustrated with a result) into a local queue at `~/.twitterapis/feedback-queue.json`, and nothing is sent until you review the queue and name the drafts to send. Each draft carries the last failing call's endpoint, status and request id, your MCP client's name and this package's version, filled in automatically, so a report is actionable without a follow-up. `twitter_feedback_send` takes `action` (`draft`, `list`, `send`, `discard`); `twitter_feedback_get` reads a sent report's status and the team's response. Both are free. The trigger list also ships as the server's MCP `instructions`, so a client that honours them nudges its model at the right moments. Every non-credential error body now ends with a one-line pointer to the tool. This takes the catalog to 98 tools, 62 reads and 36 writes, still exact parity with the API's own endpoint count.
+- **Catalog support for local handlers.** A tool may declare `local: "<handler>"` in `scripts/tools.overrides.mjs`, and args flagged `local: true` are consumed in this package instead of being sent to the API. The generator refuses a `local: true` arg on a tool with no handler, and refuses a `local` handler name `src/index.js` does not implement at boot, so neither flag can turn into a silent passthrough. A new `strings` arg type renders `z.array(z.string())`.
+
 ## 0.9.5 (2026-08-31)
 
 ### Added

package/README.md

@@ -91,9 +91,9 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 ## Tools
 
-96 tools: 61 reads and 35 write actions. Most user endpoints accept `username` (handle without @) **or** `user_id` (`twitter_user_likes` and `twitter_user_tweets_complete` require `user_id`); tweet endpoints accept `id` **or** `url`; paginated endpoints return a `cursor` you pass back to get the next page. Two of the reads are free account/billing lookups (`twitter_account_me`, `twitter_account_payments`); the 14 monitoring tools are also free (account administration, not metered reads).
+98 tools: 62 reads and 36 write actions. Most user endpoints accept `username` (handle without @) **or** `user_id` (`twitter_user_likes` and `twitter_user_tweets_complete` require `user_id`); tweet endpoints accept `id` **or** `url`; paginated endpoints return a `cursor` you pass back to get the next page. Three of the reads are free account lookups (`twitter_account_me`, `twitter_account_payments`, `twitter_feedback_get`); the 14 monitoring tools and `twitter_feedback_send` are also free (account administration, not metered reads).
 
-Public reads (search, profiles, tweets, followers, likes) work with just your API key. The **account-only** reads (bookmarks, DMs, home timeline, followers-you-know) and **most write actions** act AS an authenticated X account, so they need a session linked to your key first (returns HTTP 409 until then). Link a session either by registering your x.com cookies (`twitter_customer_session`) or by logging in with a username/password (`twitter_user_login`). Alternatively, pass **per-call inline credentials** on any of those tools (`auth_token` + `ct0`, with optional `proxy_url` / `user_agent`) to act AS that account for a single call without pre-registering a session, so one API key can act as many accounts. For write actions, set `proxy_url` to a residential proxy, since X soft-blocks writes that egress from datacenter IPs. Each write tool is annotated `readOnlyHint: false`; reversing actions (delete, unfollow, unlike, unretweet, unbookmark, monitor/webhook delete) are annotated `destructiveHint: true` so MCP clients can prompt before running them. The **monitoring** tools (see below) are the one exception: they administer your twitterapis.com account, not an X session, so they need only your API key, no linked session and no inline credentials.
+Public reads (search, profiles, tweets, followers, likes) work with just your API key. The **account-only** reads (bookmarks, DMs, home timeline, followers-you-know) and **most write actions** act AS an authenticated X account, so they need a session linked to your key first (returns HTTP 409 until then). Link a session either by registering your x.com cookies (`twitter_customer_session`) or by logging in with a username/password (`twitter_user_login`). Alternatively, pass **per-call inline credentials** on any of those tools (`auth_token` + `ct0`, with optional `proxy_url` / `user_agent`) to act AS that account for a single call without pre-registering a session, so one API key can act as many accounts. For write actions, set `proxy_url` to a residential proxy, since X soft-blocks writes that egress from datacenter IPs. Each write tool is annotated `readOnlyHint: false`; reversing actions (delete, unfollow, unlike, unretweet, unbookmark, monitor/webhook delete) are annotated `destructiveHint: true` so MCP clients can prompt before running them. The **monitoring** and **feedback** tools (see below) are the exception: they administer your twitterapis.com account, not an X session, so they need only your API key, no linked session and no inline credentials.
 
 ### Reads
 
@@ -206,6 +206,15 @@ Watch an X account for new posts and get them pushed to your own HTTPS endpoint,
 | `twitter_monitor_webhook_test` | Send one signed test event to a webhook right now, synchronously |
 | `twitter_monitor_webhook_redrive` | Replay deliveries that dead-lettered while your endpoint was down, oldest first |
 
+### Feedback _(report a bug or a gap to the twitterapis.com team without leaving your session; free)_
+
+Modelled on Claude Code's own feedback tool. When a call fails in a way that is not your key, credits, session or a rate limit, when you ask for something no tool covers, or when a result is plainly wrong, the model can **draft** a report into a local queue (`~/.twitterapis/feedback-queue.json`, at most 10 drafts, override the directory with `TWITTERAPIS_FEEDBACK_DIR`). Nothing is sent until you ask to review the queue and name the drafts to send. Each report carries the last failing call's endpoint, status and request id, your client name and this package's version, so the team can act on it without a follow-up. Use `twitter_feedback_get` with the returned server id to see whether it was triaged, shipped or declined.
+
+| Tool | What it does |
+|---|---|
+| `twitter_feedback_send` | `action: "draft"` (default) queues a report locally and sends nothing; `"list"` shows the queue; `"send"` posts only the drafts you name to `POST /feedback`; `"discard"` drops them |
+| `twitter_feedback_get` | Read a sent report's status (`new`, `triaged`, `shipped`, `declined`) and the team's response |
+
 ### Session setup
 
 Link an X account to your key once, so the account-only reads and write actions act as it (or pass per-call `auth_token`/`ct0` instead).
@@ -297,7 +306,7 @@ Calls are billed to your twitterapis.com account. Almost every endpoint is $0.00
 
 **Do I need an X (Twitter) developer account?** No. Get an API key at [twitterapis.com/signup](https://www.twitterapis.com/signup); there is no application or approval step.
 
-**Is it read-only?** No. 61 read tools work with just your API key; 35 write actions (post, like, retweet, follow, DM, media upload, List create/add member/remove member, article create/edit/publish/delete, monitor/webhook create/update/delete) act as a linked X account or per-call inline credentials, except monitor/webhook CRUD, which is account administration and needs only your API key.
+**Is it read-only?** No. 62 read tools work with just your API key; 36 write actions (post, like, retweet, follow, DM, media upload, List create/add member/remove member, article create/edit/publish/delete, monitor/webhook create/update/delete, feedback send) act as a linked X account or per-call inline credentials, except monitor/webhook CRUD and feedback, which are account administration and need only your API key.
 
 **Which clients are supported?** Claude Desktop, Cursor, Windsurf, and VS Code (Copilot agent mode), or any Model Context Protocol client.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@twitterapis/mcp",
   "mcpName": "io.github.TwitterAPIs/twitterapis-mcp",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "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",
@@ -28,7 +28,7 @@
     "build": "node scripts/gen-tools.mjs --write",
     "build:check": "node scripts/gen-tools.mjs --check",
     "openapi:refresh": "node scripts/openapi-refresh.mjs",
-    "test": "node scripts/gen-tools.mjs --check && node test/gen-tools-endpoints.mjs && node test/catalog-identity.mjs && node test/tools.test.mjs && node test/smoke.mjs && node test/openapi-parity.mjs && node test/body-mode-parity.mjs && node test/readme-parity.mjs && node test/firewall.mjs && node test/registry-manifests.mjs",
+    "test": "node scripts/gen-tools.mjs --check && node test/gen-tools-endpoints.mjs && node test/catalog-identity.mjs && node test/tools.test.mjs && node test/feedback.test.mjs && node test/smoke.mjs && node test/openapi-parity.mjs && node test/body-mode-parity.mjs && node test/readme-parity.mjs && node test/firewall.mjs && node test/registry-manifests.mjs",
     "prepublishOnly": "npm test && node test/publish-provenance.mjs",
     "check:openapi-parity": "node test/openapi-parity.mjs",
     "check:body-mode-parity": "node test/body-mode-parity.mjs",

package/src/feedback.js

@@ -0,0 +1,268 @@
+// src/feedback.js, the local half of twitter_feedback_send.
+//
+// Claude Code's own feedback tool works like this: the model drafts a report at
+// a high-signal moment, the harness writes it to a LOCAL queue, and nothing
+// leaves the machine until the user reviews the queue and approves. That
+// consent step is what makes it safe to let a model draft freely. This module
+// gives twitterapis.com customers the same loop inside whatever MCP client
+// they already use: action "draft" appends to ~/.twitterapis/feedback-queue.json
+// and sends nothing; "list" shows the drafts; "send" posts ONLY the ids the user
+// named to POST /feedback (free, not metered); "discard" drops them.
+//
+// The tool DESCRIPTION in scripts/tools.overrides.mjs is the product: it names
+// the trigger moments and the four-bullet format. This file enforces the same
+// rules mechanically so a draft that reaches the server is well-formed, and it
+// auto-attaches the evidence the server already holds (the last failing call,
+// the client name from the MCP handshake, this package's version), so the model
+// never has to type identifiers it might get wrong.
+//
+// STATE ON DISK, ON PURPOSE. The queue outlives the session: a user can review
+// tomorrow what an agent drafted today. Writes are atomic (temp file + rename)
+// because two MCP clients can share one home directory.
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const QUEUE_CAP = 10;
+export const TYPES = ["bug", "idea", "missing_capability"];
+export const ACTIONS = ["draft", "list", "send", "discard"];
+const MAX = { title: 120, details: 8000, area: 80 };
+const EVIDENCE_MAX_BYTES = 4096;
+
+/** Where drafts live. TWITTERAPIS_FEEDBACK_DIR overrides the default ~/.twitterapis. */
+export function queuePath(env = process.env) {
+  const dir = env.TWITTERAPIS_FEEDBACK_DIR || join(homedir(), ".twitterapis");
+  return join(dir, "feedback-queue.json");
+}
+
+/** A draft this module can act on. Anything else in the file (a hand edit, an
+ * older shape, a null) is skipped rather than allowed to throw on every call. */
+function isDraft(d) {
+  return d && typeof d === "object" && !Array.isArray(d)
+    && typeof d.id === "string" && typeof d.type === "string"
+    && typeof d.title === "string" && typeof d.details === "string";
+}
+
+export function readQueue(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(parsed?.drafts) ? parsed.drafts.filter(isDraft) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeQueue(path, drafts) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, drafts }, null, 2) + "\n");
+  renameSync(tmp, path);
+}
+
+// Two MCP servers can share one home directory, and temp+rename only keeps the
+// file well-formed: without a lock a read-modify-write from each loses one
+// side's drafts (measured 2026-09-04: two writers, five of ten drafts gone).
+// mkdir is atomic on every platform node runs on, so a lock DIRECTORY is the
+// mutex; a holder that died leaves it behind, so one older than STALE_MS is
+// reclaimed.
+const LOCK_STALE_MS = 10_000;
+const LOCK_WAIT_MS = 3_000;
+async function withLock(path, fn) {
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = `${path}.lock`;
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      mkdirSync(lock);
+      break;
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) { rmSync(lock, { recursive: true, force: true }); continue; }
+      } catch { /* vanished between checks; retry */ }
+      if (Date.now() > deadline) throw new Error(`feedback queue is locked by another process (${lock}); retry in a moment`);
+      await new Promise((r) => setTimeout(r, 25 + Math.floor(Math.random() * 50)));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+/** Stable per-issue id: the same type + title redrafted replaces itself. */
+export function draftId(type, title) {
+  return createHash("sha256").update(`${type}\n${title.trim().toLowerCase()}`).digest("hex").slice(0, 8);
+}
+
+const CLIENT_MAX = 120; // billing rejects longer; the model never types this field
+function clientString(clientInfo, version) {
+  const name = clientInfo?.name ? `${clientInfo.name}${clientInfo.version ? `/${clientInfo.version}` : ""}` : "unknown-client";
+  return `${name} via @twitterapis/mcp@${version}`.slice(0, CLIENT_MAX);
+}
+
+// The last failing call is worth attaching only while it is plausibly the call
+// the draft is about: recent, and not the feedback endpoint's own failure.
+const LAST_ERROR_TTL_MS = 10 * 60 * 1000;
+function usableLastError(last) {
+  if (!last || typeof last !== "object") return null;
+  if (typeof last.ts === "number" && Date.now() - last.ts > LAST_ERROR_TTL_MS) return null;
+  if (last.path === "/feedback" || (typeof last.path === "string" && last.path.startsWith("/feedback/"))) return null;
+  return last;
+}
+
+const text = (t, isError = false) => ({ isError, content: [{ type: "text", text: t }] });
+
+function summarize(d) {
+  const first = d.details.split("\n")[0].slice(0, 140);
+  return `${d.id}  [${d.type}] ${d.title}${d.area ? ` (${d.area})` : ""}  drafted ${d.ts}\n    ${first}`;
+}
+
+/**
+ * @param {object} deps
+ * @param {(path:string, args:object, method:string, jsonBody:boolean)=>Promise<object>} deps.callEndpoint
+ * @param {string} deps.version            this package's version
+ * @param {() => ({name?:string, version?:string}|undefined)} [deps.getClientInfo]
+ * @param {() => (object|null)} [deps.getLastError]   the last failing tool call, if any
+ * @param {object} [deps.env]
+ */
+export function createFeedbackHandler({ callEndpoint, version, getClientInfo, getLastError, env = process.env }) {
+  return async function feedbackTool(args = {}) {
+    const action = args.action || "draft";
+    if (!ACTIONS.includes(action)) return text(`action must be one of ${ACTIONS.join(", ")}.`, true);
+    const path = queuePath(env);
+    try {
+      if (action === "send") return await send(args, path);
+      return await withLock(path, () => run(action, args, path));
+    } catch (err) {
+      return text(err?.message || String(err), true);
+    }
+  };
+
+  // send: NEVER hold the lock across a network call. LOCK_STALE_MS is 10s and a
+  // request may take up to the client timeout (30s), so a send that held the lock
+  // let a concurrent draft reclaim it as stale and then overwrote that draft with
+  // the sender's pre-send snapshot (measured 2026-09-04: A sends with an 11.5s
+  // upstream, B drafts at t=8.5s, B's draft is gone). Now: pick the drafts under
+  // the lock, release, post each without it, and after every success re-take the
+  // lock, RE-READ the queue and remove exactly that id. A draft added meanwhile
+  // survives; a crash mid-batch still never resends a report the server holds.
+  async function send(args, path) {
+    const ids = [...new Set((Array.isArray(args.ids) ? args.ids : []).map(String))];
+    if (ids.length === 0) return text(`action "send" needs ids: the draft ids the user named (from action "list").`, true);
+    const picked = await withLock(path, () => {
+      const drafts = readQueue(path);
+      const unknown = ids.filter((id) => !drafts.some((d) => d.id === id));
+      if (unknown.length) return { unknown };
+      return { drafts: ids.map((id) => drafts.find((x) => x.id === id)) };
+    });
+    if (picked.unknown) return text(`Unknown draft id(s): ${picked.unknown.join(", ")}. Run action "list" to see the current ids.`, true);
+
+    const sent = [];
+    const failed = [];
+    const stuck = [];
+    for (const d of picked.drafts) {
+      const body = { type: d.type, title: d.title, details: d.details, evidence: d.evidence, client: d.client };
+      if (d.area) body.area = d.area;
+      const res = await callEndpoint("/feedback", body, "POST", true);
+      const out = res?.content?.[0]?.text ?? "";
+      if (res?.isError) {
+        failed.push(`${d.id}: ${out.slice(0, 300)}`);
+        continue;
+      }
+      let serverId = null;
+      try { serverId = JSON.parse(out).id ?? null; } catch { /* body was not JSON; keep null */ }
+      sent.push(`${d.id} -> ${serverId ?? "sent"}`);
+      // Persist after EACH success against the CURRENT queue, so a process that
+      // dies mid-loop cannot re-send, and a draft another process added while
+      // this one was on the network is kept. The server already holds this
+      // report, so a lock that cannot be re-taken (a foreign holder past the
+      // wait) must NOT turn into an error that hides the server id and leaves
+      // the draft re-sendable: report it as posted and name the draft to discard.
+      try {
+        await withLock(path, () => writeQueue(path, readQueue(path).filter((x) => x.id !== d.id)));
+      } catch (err) {
+        stuck.push(`${d.id} (server id ${serverId ?? "unknown"}): ${err?.message || String(err)}`);
+      }
+    }
+    let remaining;
+    try { remaining = await withLock(path, () => readQueue(path).length); } catch { remaining = readQueue(path).length; }
+    const lines = [];
+    if (sent.length) lines.push(`Sent ${sent.length} report(s) to twitterapis.com (free, not metered):\n  ${sent.join("\n  ")}\nCheck one later with twitter_feedback_get using the server id.`);
+    if (failed.length) lines.push(`${failed.length} draft(s) stayed in the queue because the send failed:\n  ${failed.join("\n  ")}`);
+    if (stuck.length) lines.push(`${stuck.length} report(s) WERE posted but the local draft could not be removed (the queue was locked). Do not send these ids again; remove them with action "discard":\n  ${stuck.join("\n  ")}`);
+    lines.push(`${remaining} draft(s) still pending.`);
+    return text(lines.join("\n\n"), sent.length === 0);
+  }
+
+  async function run(action, args, path) {
+    if (action === "draft") {
+      if (!TYPES.includes(args.type)) return text(`type is required for a draft and must be one of ${TYPES.join(", ")}.`, true);
+      const title = String(args.title ?? "").trim();
+      if (!title || title.length > MAX.title) return text(`title is required for a draft, at most ${MAX.title} characters.`, true);
+      const details = String(args.details ?? "").trim();
+      if (!details || details.length > MAX.details) return text(`details is required for a draft, at most ${MAX.details} characters. Use the four labelled bullets: What happened, What the user said, Repro, Evidence.`, true);
+      const area = args.area ? String(args.area).trim().slice(0, MAX.area) : undefined;
+
+      const client = clientString(getClientInfo?.(), version);
+      const evidence = { ...(args.evidence && typeof args.evidence === "object" && !Array.isArray(args.evidence) ? args.evidence : {}) };
+      const last = usableLastError(getLastError?.());
+      // Fill only what the model did not supply: its own evidence wins.
+      if (last) {
+        if (evidence.tool === undefined && last.tool) evidence.tool = last.tool;
+        if (evidence.endpoint === undefined && last.path) evidence.endpoint = last.path;
+        if (evidence.status === undefined && last.status) evidence.status = last.status;
+        if (evidence.request_id === undefined && last.requestId) evidence.request_id = last.requestId;
+      }
+      evidence.mcp_version = version;
+      evidence.client = client;
+      if (Buffer.byteLength(JSON.stringify(evidence), "utf8") > EVIDENCE_MAX_BYTES) {
+        return text(`evidence must serialize to ${EVIDENCE_MAX_BYTES} bytes or fewer. Send identifiers (tool, endpoint, status, request id), never payloads.`, true);
+      }
+
+      const drafts = readQueue(path);
+      const draft = { id: draftId(args.type, title), ts: new Date().toISOString(), type: args.type, title, details, area, evidence, client };
+      const idx = drafts.findIndex((d) => d.id === draft.id);
+      if (idx >= 0) {
+        drafts[idx] = draft;
+      } else {
+        if (drafts.length >= QUEUE_CAP) {
+          return text(`The local feedback queue already holds ${QUEUE_CAP} drafts. Ask the user to review them (action "list", then "send" or "discard") before drafting more.`, true);
+        }
+        drafts.push(draft);
+      }
+      writeQueue(path, drafts);
+      return text(
+        `Queued locally as draft ${draft.id}${idx >= 0 ? " (replaced an earlier draft with the same title)" : ""}. ${drafts.length} draft(s) pending in ${path}. ` +
+          `Nothing was sent and nothing needs to be said to the user right now. When the user asks to review or send feedback, call this tool with action "list", ` +
+          `then action "send" with only the ids the user names, or "discard".`,
+      );
+    }
+
+    const drafts = readQueue(path);
+
+    if (action === "list") {
+      if (drafts.length === 0) return text(`No feedback drafts pending (${path}).`);
+      return text(
+        `${drafts.length} feedback draft(s) pending in ${path}. Show these to the user and send only the ids they name:\n\n` +
+          drafts.map(summarize).join("\n"),
+      );
+    }
+
+    const ids = [...new Set((Array.isArray(args.ids) ? args.ids : []).map(String))];
+    if (ids.length === 0) return text(`action "${action}" needs ids: the draft ids the user named (from action "list").`, true);
+    const unknown = ids.filter((id) => !drafts.some((d) => d.id === id));
+    if (unknown.length) return text(`Unknown draft id(s): ${unknown.join(", ")}. Run action "list" to see the current ids.`, true);
+
+    if (action === "discard") {
+      const kept = drafts.filter((d) => !ids.includes(d.id));
+      writeQueue(path, kept);
+      return text(`Discarded ${ids.length} draft(s): ${ids.join(", ")}. ${kept.length} still pending.`);
+    }
+
+    return text(`action "${action}" is not handled here.`, true);
+  }
+}

package/src/index.js

@@ -25,6 +25,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // outbound user-agent both still advertised 0.3.0.
 const VERSION = createRequire(import.meta.url)("../package.json").version;
 import { TOOLS, buildQuery, resolvePathParams, MissingPathParamError } from "./tools.js";
+import { createFeedbackHandler } from "./feedback.js";
 
 const API_KEY = process.env.TWITTERAPIS_KEY;
 const BASE_URL = (
@@ -81,6 +82,11 @@ if (!API_KEY) {
 // 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.
+// The last tool call that failed, so a feedback draft can carry the endpoint,
+// status and request id without the model retyping them. Set in callEndpoint's
+// error branch; the tool name is added by the registration wrapper below.
+let lastError = null;
+
 async function callEndpoint(path, args, method = "GET", jsonBody = false, pathParams = []) {
   if (!API_KEY) {
     return {
@@ -168,11 +174,31 @@ async function callEndpoint(path, args, method = "GET", jsonBody = false, pathPa
                   : res.status >= 500
                     ? " (upstream API error. Retry in a moment; if persistent, check https://www.twitterapis.com/status)"
                     : "";
-      return { isError: true, content: [{ type: "text", text: `HTTP ${res.status}${hint}: ${body.slice(0, 1200)}` }] };
+      lastError = {
+        path: resolvedPath,
+        method,
+        status: res.status,
+        requestId: res.headers.get("x-request-id") || undefined,
+        ts: Date.now(),
+      };
+      // Credential, credit, session, rate-limit and not-found failures are the
+      // caller's situation (a 404 is almost always a wrong id), not a product
+      // defect; everything else may be one, and the model reads error bodies
+      // closely, so the pointer lives here.
+      const feedbackHint =
+        res.status === 401 || res.status === 402 || res.status === 404 || res.status === 409 || res.status === 429
+          ? ""
+          : " If this blocked the user's task and looks like a defect or a missing capability, draft a report with twitter_feedback_send (queued locally until the user reviews it).";
+      return { isError: true, content: [{ type: "text", text: `HTTP ${res.status}${hint}: ${body.slice(0, 1200)}${feedbackHint}` }] };
     }
+    // A success clears the record so a later draft never inherits an old
+    // failure's endpoint or request id (review 2026-09-04: a delete's draft
+    // carried the previous update's 404).
+    lastError = null;
     return { content: [{ type: "text", text: body }] };
   } catch (err) {
     const msg = err?.name === "AbortError" ? `timed out after ${REQUEST_TIMEOUT_MS}ms` : err?.message || String(err);
+    lastError = { path: resolvedPath, method, status: null, error: msg.slice(0, 200), ts: Date.now() };
     return { isError: true, content: [{ type: "text", text: `Request failed: ${msg}` }] };
   } finally {
     clearTimeout(timer);
@@ -180,7 +206,27 @@ async function callEndpoint(path, args, method = "GET", jsonBody = false, pathPa
 }
 
 // ── MCP server ───────────────────────────────────────────────────────────────
-const server = new McpServer({ name: "twitterapis", version: VERSION });
+// Standing instructions the client hands its model alongside the tool list.
+// This is the trigger list for feedback, in the place a model actually reads.
+const INSTRUCTIONS =
+  "twitterapis.com MCP server. Read tools cost credits per call (most $0.0008); account, monitoring and feedback tools are free. " +
+  "If a twitterapis tool call fails with an error other than 401/402/409/429 and the user has to work around it, if the user asks for something no twitterapis tool covers, " +
+  "if a documented field comes back empty or wrong, or if the user is clearly frustrated with a result, draft a report with twitter_feedback_send (action \"draft\"). " +
+  "Drafting is local and silent; never send a draft unless the user names it after reviewing action \"list\".";
+
+const server = new McpServer({ name: "twitterapis", version: VERSION }, { instructions: INSTRUCTIONS });
+
+// Handlers for tools that carry local: "<name>" in the catalog. A name the
+// catalog uses and this map lacks is a boot-time failure, never a silent
+// passthrough to the API with the local args attached.
+const LOCAL_HANDLERS = {
+  feedback: createFeedbackHandler({
+    callEndpoint,
+    version: VERSION,
+    getClientInfo: () => server.server.getClientVersion(),
+    getLastError: () => lastError,
+  }),
+};
 
 for (const tool of TOOLS) {
   const method = tool.method || "GET";
@@ -192,10 +238,27 @@ for (const tool of TOOLS) {
     destructiveHint: Boolean(tool.destructive),
     openWorldHint: true,
   };
+  let handler;
+  if (tool.local) {
+    handler = LOCAL_HANDLERS[tool.local];
+    if (!handler) throw new Error(`[twitterapis-mcp] tool ${tool.name} declares local handler "${tool.local}" but src/index.js has none`);
+  } else {
+    handler = async (args) => {
+      const result = await callEndpoint(tool.path, args, method, Boolean(tool.jsonBody), tool.pathParams || []);
+      if (result?.isError && lastError) {
+        let resolved = null;
+        try { resolved = resolvePathParams(tool.path, tool.pathParams || [], args).path; } catch { resolved = null; }
+        // Name the tool only when BOTH method and path match the recorded
+        // failure; two tools share /monitor/{id} (POST update, DELETE remove).
+        if (resolved === lastError.path && method === lastError.method) lastError.tool = tool.name;
+      }
+      return result;
+    };
+  }
   server.registerTool(
     tool.name,
     { description: tool.description, inputSchema: tool.shape, annotations },
-    async (args) => callEndpoint(tool.path, args, method, Boolean(tool.jsonBody), tool.pathParams || []),
+    handler,
   );
 }
 

package/src/tools.js

@@ -8,12 +8,12 @@
 // file in memory and fails if it does not match what is committed, so a hand edit
 // here is caught rather than shipped.
 //
-// Catalog: 96 tools (61 reads, 35 writes).
+// Catalog: 98 tools (62 reads, 36 writes).
 //
 // Each tool maps 1:1 to a REST endpoint at https://api.twitterapis.com. Tool arg
 // names map 1:1 to endpoint query params (every endpoint, including the POST
 // write actions, reads its params from the query string), except the per-call
-// inline credentials, which travel as x-* request headers, the 10
+// inline credentials, which travel as x-* request headers, the 11
 // jsonBody tools, whose fields travel in a JSON request body, and any arg listed
 // in pathParams, which is substituted into the URL path (e.g. {id}) instead. A
 // tool with `method: "POST"` or `method: "DELETE"` is a write that acts on
@@ -22,6 +22,10 @@
 //
 // write:true       -> action mutates account/Twitter state (readOnlyHint:false)
 // destructive:true -> action removes/reverses state (delete, un-follow/like/RT/bookmark)
+// local:"<name>"   -> src/index.js dispatches the call to a handler in this
+//                     package instead of a plain passthrough (feedback's draft
+//                     queue); args flagged local:true in the overrides are
+//                     consumed there and never reach the API
 // pathParams        -> arg names substituted into the URL template, not sent as
 //                      query-string or body fields (e.g. ["id"] for /monitor/{id})
 import { z } from "zod";
@@ -40,7 +44,7 @@ export const TOOLS = [
         "Result ranking mode. 'Latest' = reverse-chronological (best for monitoring). 'Top' = engagement-ranked (best for finding popular tweets, default when omitted). 'Media' = tweets with images/video. 'People' = matching user accounts.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -57,7 +61,7 @@ export const TOOLS = [
         "Name, keyword, or topic to search accounts for. Examples: 'OpenAI', 'AI researcher', 'tech founder'.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -127,7 +131,7 @@ export const TOOLS = [
         "Optional team/sub-group name to filter affiliates by, when the org exposes named teams.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -161,7 +165,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -181,7 +185,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -215,7 +219,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -232,7 +236,7 @@ export const TOOLS = [
         "Twitter/X handle WITHOUT the leading @ of the user to find mentions for (e.g. 'openai' to find tweets mentioning @openai).",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -249,7 +253,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. '44196397'). Required: this endpoint does not accept a username. Resolve a handle to a user_id first with twitter_user_info.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -269,7 +273,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -289,7 +293,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -309,7 +313,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -329,7 +333,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -349,7 +353,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -366,7 +370,7 @@ export const TOOLS = [
         "Numeric user id of the target account to compute shared followers against.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -443,7 +447,7 @@ export const TOOLS = [
         "Full tweet URL, e.g. \"https://x.com/elonmusk/status/1789012345678901234\". Provide exactly one of id or url.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -486,7 +490,7 @@ export const TOOLS = [
         "Numeric Twitter/X List id. Found in the list URL: x.com/i/lists/<list_id>.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -775,6 +779,52 @@ export const TOOLS = [
       "Get YOUR twitterapis.com payment history: the list of top-ups and charges on your account. Authenticated by your API key. This is an account read, not Twitter data, and is free (it does not spend credits).",
     shape: {},
   },
+  {
+    name: "twitter_feedback_send",
+    path: "/feedback",
+    method: "POST",
+    write: true,
+    jsonBody: true,
+    local: "feedback",
+    localArgs: ["action","ids"],
+    description:
+      "Report a product problem or gap in twitterapis.com to its team from inside this session, the way Claude Code's own feedback tool works: a report is DRAFTED to a local queue first (action \"draft\", the default) and SENT only after the user reviews it. Drafting sends nothing, needs no confirmation, and should not be announced mid-task. WHEN TO DRAFT, only at high-signal moments: a twitterapis tool call failed with an error that was not a missing key (401), credits (402), no linked session (409) or a rate limit (429), and the user had to work around it; the user asked for something no twitterapis tool covers; a documented field came back empty or wrong; the user was clearly frustrated with a result. One draft per distinct issue, never twice for the same one. FORMAT for details, four labelled bullets in this order: 'What happened:' observed vs expected, exact error text if short. 'What the user said:' quoted verbatim, or 'user did not comment'. 'Repro:' the minimal call that reproduces it. 'Evidence:' tool name, endpoint, HTTP status, request id (the last failing call is attached automatically where you leave a gap). Facts only: no guessing, no API keys or secrets, no personal names. REVIEW: when the user asks to see or send feedback, call action \"list\", then action \"send\" with ONLY the draft ids the user named in their own message, or action \"discard\". Sending posts each draft to POST /feedback (free) and returns a server id that twitter_feedback_get can check later.",
+    shape: {
+      action: z.enum(["draft","list","send","discard"]).optional().describe(
+        "What to do. \"draft\" (default) queues a new report locally and sends nothing. \"list\" shows the pending drafts with their ids. \"send\" posts the drafts named in ids to twitterapis.com; use it only for ids the user named. \"discard\" drops the drafts named in ids.",
+      ),
+      type: z.enum(["bug","idea","missing_capability"]).optional().describe(
+        "Required for a draft. \"bug\": a tool or endpoint misbehaved. \"idea\": a change that would have made the task easier. \"missing_capability\": the user needed something no tool provides.",
+      ),
+      title: z.string().optional().describe(
+        "Required for a draft. One specific line, at most 120 characters, naming the tool or endpoint and the defect, e.g. \"twitter_tweet_thread returns 502 when the root tweet is deleted\".",
+      ),
+      details: z.string().optional().describe(
+        "Required for a draft. At most 8000 characters, four labelled bullets in order: What happened, What the user said (verbatim), Repro, Evidence.",
+      ),
+      area: z.string().optional().describe(
+        "Optional. The endpoint or feature the report is about, e.g. \"tweet/thread\" or \"monitoring\". At most 80 characters.",
+      ),
+      evidence: z.record(z.string(), z.unknown()).optional().describe(
+        "Optional identifiers only, never payloads: {tool, endpoint, status, request_id}. Whatever you leave out is filled from the last failing call in this session; mcp_version and client are always attached.",
+      ),
+      ids: z.array(z.string()).optional().describe(
+        "For action \"send\" or \"discard\": the draft ids to act on, exactly as shown by action \"list\" and named by the user.",
+      ),
+    },
+  },
+  {
+    name: "twitter_feedback_get",
+    path: "/feedback/{id}",
+    pathParams: ["id"],
+    description:
+      "Check the status of a feedback report this account sent earlier (the server id returned by twitter_feedback_send action \"send\"): status new, triaged, shipped or declined, the team's response text if any, and updated_at, which moves only when the team acts on it. Free per call. 404 if the id is not on this account.",
+    shape: {
+      id: z.string().describe(
+        "The server id of a sent report, as returned by twitter_feedback_send action \"send\" (a UUID). Not a local draft id.",
+      ),
+    },
+  },
   {
     name: "twitter_home_timeline",
     path: "/twitter/user/home_timeline",
@@ -782,7 +832,7 @@ export const TOOLS = [
       "Get YOUR authenticated account's Home timeline (the 'Following'/'For you' feed), most recent first. Requires an authenticated session behind your key. Returns tweets with author and metrics plus a cursor. Use this to read what your account would see when it opens X.",
     shape: {
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -808,7 +858,7 @@ export const TOOLS = [
       "List YOUR authenticated account's bookmarked tweets, most recent first. Requires an authenticated session behind your key. Returns each bookmarked tweet with author and metrics plus a cursor.",
     shape: {
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -834,7 +884,7 @@ export const TOOLS = [
       "List the accounts YOUR authenticated account has BLOCKED, as full user objects, cursor-paginated. Requires an authenticated session behind your key. There is no user_id argument: X provides no way to read another account's block list, so this reads yours only. An empty users array is a real answer meaning you block nobody, never a silent failure, because the endpoint returns an error status rather than an empty page when it cannot read the list.",
     shape: {
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -860,7 +910,7 @@ export const TOOLS = [
       "List the accounts YOUR authenticated account has MUTED, as full user objects, cursor-paginated. Muting hides an account's posts from your timeline without blocking it, so this is a different list from twitter_blocking and an account can appear in one and not the other. Requires an authenticated session behind your key. There is no user_id argument: X provides no way to read another account's mute list. An empty users array means you mute nobody, never a silent failure.",
     shape: {
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
@@ -889,7 +939,7 @@ export const TOOLS = [
         "Search terms to match against your bookmarked tweets' text.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
-        "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       cursor: z.string().optional().describe(
         "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",