@twitterapis/mcp 0.9.8 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.10.0 (2026-09-13)
+
+### Added
+
+- **Seven compose tools: private drafts and scheduled posts.** `twitter_draft_create`, `twitter_draft_edit`, `twitter_draft_delete`, `twitter_draft_list`, `twitter_scheduled_create`, `twitter_scheduled_delete`, `twitter_scheduled_list`. Catalog is now **106 tools, 65 reads and 41 writes**, still exact parity with the API's endpoint count. A MINOR bump, not a patch: the catalog grew, so a consumer pinned to `0.9.x` opts in rather than receiving seven new tools silently, which is exactly what `scripts/prepublish-version-class.mjs` refuses.
+- **The one thing a model cannot read off a schema is said in every one of the seven descriptions: a DRAFT is private and never posts; a SCHEDULED post WILL publish publicly at its `execute_at` unless it is cancelled first.** A model choosing between `twitter_draft_create` and `twitter_scheduled_create` on the word "create" alone gets it wrong, and the failure is a real post going out. The descriptions also carry the routing to their siblings (`twitter_create_tweet` to post now) and the `execute_at` unit trap: epoch SECONDS, never the milliseconds `Date.now()` returns, with a value at or above 1e12 refused by the API rather than scheduled tens of thousands of years out.
+- **Both list tools document `partial`.** True means X's answer was read but not fully understood; it is ABSENT on a clean read, so an empty array with no flag means the account genuinely has nothing. That distinction is what stops a model reporting "you have no drafts" when the real answer is "we could not read the reply".
+
+### Notes
+
+- The routes these tools call were built, merged and deployed on 2026-09-13 behind two env flags (`DRAFT_TWEETS_ENABLED`, `SCHEDULED_TWEETS_ENABLED`, both answering 503 while off), verified end to end against a real customer session, then published and their flags removed. The snapshot in `test/openapi.snapshot.json` was refreshed from the LIVE published spec after the docs site deployed, which is the only order that works: the refresh fetches `docs.twitterapis.com/openapi.json`, never a local file.
+
+## 0.9.9 (2026-09-11)
+
+### Changed
+
+- **The server instructions now ask for a control before an "ignored parameter" report.** A generic query on a score-ordered sort returns the site-wide listing, which reads exactly like a dropped parameter and is not one. Before drafting a report that a parameter is ignored or a field is empty, the model is told to re-run with a distinctive value that could only match if the parameter was honoured, and with the phrase quoted, then title the report by what the control showed.
+- **`scripts/prepublish-version-class.mjs`, run by `prepublishOnly`, refuses a patch bump when the tool catalog grew.** It reads the published tarball from npm, counts the catalog on both sides, and blocks a publish whose version is a patch over the published one while the catalog is larger. Fails closed when npm cannot be read. `--selftest` covers both directions offline.
+
 ## 0.9.8 (2026-09-04)
 
 ### Added

package/README.md

@@ -91,7 +91,7 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 ## Tools
 
-99 tools: 63 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. Four of the reads are free account lookups (`twitter_account_me`, `twitter_account_payments`, `twitter_feedback_get`, `twitter_feedback_list`); the 14 monitoring tools and `twitter_feedback_send` are also free (account administration, not metered reads).
+106 tools: 65 reads and 41 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. Four of the reads are free account lookups (`twitter_account_me`, `twitter_account_payments`, `twitter_feedback_get`, `twitter_feedback_list`); 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** 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.
 
@@ -170,6 +170,22 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 | `twitter_list_add_member` / `twitter_list_remove_member` | Add / remove one account on a List you own; `member_count` comes back as proof the write landed |
 | `twitter_media_upload` | Upload a base64 image, returns a `media_id` for `twitter_create_tweet` |
 
+### Drafts and scheduled posts _(require a linked X session)_
+
+A **draft** is private and never posts. A **scheduled** post **will publish publicly** at its `execute_at` unless you cancel it first. Both lists read only your own account.
+
+| Tool | What it does |
+|---|---|
+| `twitter_draft_create` | Save a private draft on your account; nothing is posted |
+| `twitter_draft_edit` | Replace one draft's contents by `id`; the fields you send become the draft |
+| `twitter_draft_delete` | Delete a draft by `id`; it was never public, so nothing is retracted |
+| `twitter_draft_list` | List your drafts, each with `text` and `thread_truncated` |
+| `twitter_scheduled_create` | Schedule a post for a future `execute_at` in epoch **seconds**, not milliseconds |
+| `twitter_scheduled_delete` | Cancel a pending scheduled post before it sends |
+| `twitter_scheduled_list` | List your pending queue; `execute_at` comes back in epoch seconds |
+
+Both list tools can return `partial: true`, which means X's answer was read but not fully understood. It is **not** the same as an empty list: on a clean read the flag is absent entirely, so an empty array with no `partial` means you genuinely have nothing queued or drafted.
+
 ### Articles _(X's long-form "Notes" feature; writes require a linked X session)_
 
 | Tool | What it does |
@@ -310,7 +326,7 @@ count: 50
 
 ## Pricing
 
-Calls are billed to your twitterapis.com account. Almost every endpoint is $0.0008/call: all reads (search, profiles, tweets, followers, likes) plus the simple write actions (like, retweet, bookmark, follow and their undos, delete). At the read rate that works out to $0.04 per 1,000 tweets, since each call returns about 20 tweets. The premium endpoints cost a little more: tweet creation, sending a DM (`twitter_dm_send`), and DM reads (`twitter_dm_list`, `twitter_dm_conversation`) at $0.0016/call, full tweet history (`twitter_user_tweets_complete`) at $0.0024/call, a full tweet thread (`twitter_tweet_thread`) and a Grok answer (`twitter_grok_chat`) at $0.004/call, and the article-editing writes (`twitter_article_create`, `twitter_article_update_title`, `twitter_article_update_cover_media`, `twitter_article_update_content`, `twitter_article_publish`, `twitter_article_unpublish`) at $0.0016/call (`twitter_article_get`, `twitter_article_list`, and `twitter_article_delete` stay at the standard $0.0008/call). Your first $0.50 is free. See [twitterapis.com/pricing](https://www.twitterapis.com/pricing).
+Calls are billed to your twitterapis.com account. Most endpoints are $0.0008/call: nearly every read (search, profiles, tweets, followers, likes) plus the simple write actions (like, retweet, bookmark, follow and their undos, delete). At the read rate that works out to $0.04 per 1,000 tweets, since each call returns about 20 tweets. The premium endpoints cost a little more: tweet creation, sending a DM (`twitter_dm_send`), and DM reads (`twitter_dm_list`, `twitter_dm_conversation`) at $0.0016/call, full tweet history (`twitter_user_tweets_complete`) at $0.0024/call, a full tweet thread (`twitter_tweet_thread`) and a Grok answer (`twitter_grok_chat`) at $0.004/call, and the article-editing writes (`twitter_article_create`, `twitter_article_update_title`, `twitter_article_update_cover_media`, `twitter_article_update_content`, `twitter_article_publish`, `twitter_article_unpublish`) at $0.0016. The compose surface is $0.0016 for `twitter_draft_create`, `twitter_draft_edit`, `twitter_scheduled_create` and, note, BOTH LIST READS (`twitter_draft_list`, `twitter_scheduled_list`), which are the two reads that are not at the read rate; `twitter_draft_delete` and `twitter_scheduled_delete` are $0.0008/call (`twitter_article_get`, `twitter_article_list`, and `twitter_article_delete` stay at the standard $0.0008/call). Your first $0.50 is free. See [twitterapis.com/pricing](https://www.twitterapis.com/pricing).
 
 ## Links
 
@@ -323,7 +339,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. 63 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.
+**Is it read-only?** No. 65 read tools work with just your API key; 41 write actions (post, save or schedule a 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.8",
+  "version": "0.10.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",
@@ -29,7 +29,7 @@
     "build:check": "node scripts/gen-tools.mjs --check",
     "openapi:refresh": "node scripts/openapi-refresh.mjs",
     "test": "node scripts/gen-tools.mjs --check && node scripts/gen-manifest-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/hint-for.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 && node scripts/__tests__/reconcile-mcp-publish-chain.test.mjs",
-    "prepublishOnly": "npm test && node test/publish-provenance.mjs",
+    "prepublishOnly": "npm test && node test/publish-provenance.mjs && node scripts/prepublish-version-class.mjs",
     "check:openapi-parity": "node test/openapi-parity.mjs",
     "check:body-mode-parity": "node test/body-mode-parity.mjs",
     "check:firewall": "node test/firewall.mjs",

package/src/index.js

@@ -229,7 +229,9 @@ 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\".";
+  "Drafting is local and silent; never send a draft unless the user names it after reviewing action \"list\". " +
+  "Before drafting a report that a parameter is IGNORED or a field is EMPTY, re-run the call with a distinctive value that could only match if the parameter was honoured, and with the phrase quoted; " +
+  "if either comes back on topic the issue is ranking or matching, so title it that way and say what the control showed.";
 
 const server = new McpServer({ name: "twitterapis", version: VERSION }, { instructions: INSTRUCTIONS });
 

package/src/tools.js

@@ -8,7 +8,7 @@
 // file in memory and fails if it does not match what is committed, so a hand edit
 // here is caught rather than shipped.
 //
-// Catalog: 99 tools (63 reads, 36 writes).
+// Catalog: 106 tools (65 reads, 41 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
@@ -1161,6 +1161,212 @@ export const TOOLS = [
       ),
     },
   },
+  {
+    name: "twitter_draft_create",
+    path: "/twitter/draft/create",
+    method: "POST",
+    write: true,
+    description:
+      "Save a PRIVATE draft tweet on your authenticated account. Nothing is posted and nobody can see it: the draft lands in X's own composer under Drafts until a human publishes or deletes it. Use this when a person still has to approve the wording. Use twitter_create_tweet to post right now, and twitter_scheduled_create when it should go out on its own at a known time. Requires an authenticated session behind your key. Returns ok and draft_tweet_id. A null draft_tweet_id means X refused the create, answers 422, and is not billed.",
+    shape: {
+      text: z.string().min(1).describe(
+        "The draft body text. Required: a draft with no text is refused with 400, so a media-only draft cannot be created through this API.",
+      ),
+      reply_to: z.string().optional().describe(
+        "Optional. Numeric id of the tweet this draft replies to. Send it as a string; X ids are 19 digits and an unquoted number is refused rather than silently rounded to a different tweet.",
+      ),
+      quote: z.string().optional().describe(
+        "Optional. Numeric id of the tweet this draft quotes. Send it as a string, same reason as reply_to.",
+      ),
+      media_ids: z.string().optional().describe(
+        "Optional. Comma-separated media id(s) from a prior media upload to attach. Up to 4.",
+      ),
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
+  {
+    name: "twitter_draft_edit",
+    path: "/twitter/draft/edit",
+    method: "POST",
+    write: true,
+    description:
+      "Replace the contents of one existing PRIVATE draft on your authenticated account. The fields you send BECOME the draft rather than merging into it, so anything you leave out is dropped, including media. Get the id from twitter_draft_list or from the twitter_draft_create call that saved it. Still posts nothing. Requires an authenticated session behind your key. Returns ok and the draft_tweet_id you edited.",
+    shape: {
+      id: z.string().describe(
+        "Numeric id of the draft to edit, from twitter_draft_list. Also accepted by the API as draft_tweet_id.",
+      ),
+      text: z.string().min(1).describe(
+        "The replacement draft body text. Required: an edit with no text is refused with 400.",
+      ),
+      reply_to: z.string().optional().describe(
+        "Optional. Numeric id of the tweet this draft replies to. Send it as a string.",
+      ),
+      quote: z.string().optional().describe(
+        "Optional. Numeric id of the tweet this draft quotes. Send it as a string.",
+      ),
+      media_ids: z.string().optional().describe(
+        "Optional. Comma-separated media id(s) to attach. Omitting this drops whatever media the draft had; it is not merged.",
+      ),
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
+  {
+    name: "twitter_draft_delete",
+    path: "/twitter/draft/delete",
+    method: "POST",
+    write: true,
+    destructive: true,
+    description:
+      "Delete one PRIVATE draft from your authenticated account by id. Irreversible, but low-stakes in a way twitter_delete_tweet is not: a draft was never public, so this retracts nothing and notifies nobody. Use twitter_delete_tweet for a post that is already live. Requires an authenticated session behind your key. Returns ok, deleted, and the draft_tweet_id you targeted.",
+    shape: {
+      id: z.string().describe(
+        "Numeric id of the draft to delete, from twitter_draft_list. Also accepted by the API as draft_tweet_id.",
+      ),
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
+  {
+    name: "twitter_draft_list",
+    path: "/twitter/draft/list",
+    description:
+      "List the PRIVATE drafts saved on your authenticated account. This is where a draft id comes from for an edit or a delete. Reads only your own account: drafts are private to the account that holds them, so there is no way to read anyone else's. Requires an authenticated session behind your key. Returns drafts (each with draft_tweet_id, text, thread_truncated), count, and sometimes partial. thread_truncated true means the draft is a THREAD and text is only its first tweet, which is a parse that succeeded. partial true means X's answer was read but not fully understood, which is NOT 'you have no drafts': it is absent entirely on a clean read, so an empty drafts array with no partial flag means the account genuinely has none. One call returns the whole list; there is no cursor and no timestamp on a draft row.",
+    shape: {
+      ascending: z.string().optional().describe(
+        "Optional. Pass the STRING \"true\" to ask X for the oldest draft first. Anything else, including omitting it, sends ascending=false, which is what X's own composer sends. The resulting order is X's and is not re-sorted, so do not promise a user newest-first.",
+      ),
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
+  {
+    name: "twitter_scheduled_create",
+    path: "/twitter/scheduled/create",
+    method: "POST",
+    write: true,
+    description:
+      "Schedule a tweet to POST PUBLICLY at a future instant from your authenticated account. This is NOT a draft: it goes out on its own at execute_at whether or not anyone is watching, unless it is cancelled first with twitter_scheduled_delete. Use twitter_draft_create when a human still has to approve the wording. execute_at is epoch SECONDS, never milliseconds: Date.now() returns milliseconds, so divide by 1000, and a millisecond value is refused with a message naming the unit rather than scheduling the post tens of thousands of years out. It must also be strictly in the future. Requires an authenticated session behind your key. Returns ok, scheduled_tweet_id, and the execute_at you sent.",
+    shape: {
+      text: z.string().min(1).describe(
+        "The tweet body text that will be published. Required: a scheduled post with no text is refused with 400.",
+      ),
+      execute_at: z.number().int().describe(
+        "When to post, as epoch SECONDS in the future (for example 1829752200). NOT milliseconds: a value of 1000000000000 or more is rejected as a millisecond timestamp. Also accepted by the API as schedule_at.",
+      ),
+      reply_to: z.string().optional().describe(
+        "Optional. Numeric id of the tweet this post replies to. Send it as a string.",
+      ),
+      quote: z.string().optional().describe(
+        "Optional. Numeric id of the tweet this post quotes. Send it as a string.",
+      ),
+      media_ids: z.string().optional().describe(
+        "Optional. Comma-separated media id(s) from a prior media upload to attach. Up to 4.",
+      ),
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
+  {
+    name: "twitter_scheduled_delete",
+    path: "/twitter/scheduled/delete",
+    method: "POST",
+    write: true,
+    destructive: true,
+    description:
+      "Cancel one PENDING scheduled post on your authenticated account so it never publishes. Only works before its execute_at: once the post has gone out there is no scheduled row left to cancel, and the thing to remove is the resulting tweet, with twitter_delete_tweet. Get the id from twitter_scheduled_list. Requires an authenticated session behind your key. Returns ok, deleted, and the scheduled_tweet_id you targeted.",
+    shape: {
+      id: z.string().describe(
+        "Numeric id of the scheduled post to cancel, from twitter_scheduled_list. Also accepted by the API as scheduled_tweet_id.",
+      ),
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
+  {
+    name: "twitter_scheduled_list",
+    path: "/twitter/scheduled/list",
+    description:
+      "List the posts QUEUED to publish on your authenticated account. This is where a scheduled id comes from for a cancel, and it is worth reading before scheduling anything so a retry in your own code does not quietly queue the same post twice. Rows carry X's own state label verbatim (for example Scheduled), and a row that has already published leaves the queue and becomes an ordinary tweet. Requires an authenticated session behind your key. Returns scheduled (each with scheduled_tweet_id, text, thread_truncated, execute_at, state), count, and sometimes partial. thread_truncated is INFERRED on this endpoint rather than captured: a scheduled row carries the same compose payload a draft row does, and the captured scheduled row elides that body, so the flag is sound and fail-safe (an absent key yields false) but has not been seen true. execute_at comes back in epoch SECONDS: X answers this operation in milliseconds and the value is normalised, so a timestamp read here can be passed straight back into twitter_scheduled_create. partial true means X's answer was read but not fully understood, which is not the same as an empty queue; on a clean read it is absent entirely.",
+    shape: {
+      ascending: z.string().optional().describe(
+        "Optional. Pass the STRING \"true\" for the oldest row first. Anything else, including omitting it, returns X's default order.",
+      ),
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
   {
     name: "twitter_favorite_tweet",
     path: "/twitter/tweet/favorite",