From d2ba88f77b59da7771e0f1b55083e321176a5998 Mon Sep 17 00:00:00 2001 From: Paul Vann Date: Thu, 27 Aug 2026 14:50:02 -0400 Subject: [PATCH 1/2] Rewrite the X MCP guide for auto-credits and connector-only auth. On connect, fetch credits, congratulate without a gift amount, and always state remaining balance. Treat connected-but-no-tools as account-not-ready, 503s as an X outage, and never sign in via browser or Bearer tokens. Co-authored-by: Cursor --- third_party/x/.cursor-plugin/plugin.json | 2 +- third_party/x/CHANGELOG.md | 7 + third_party/x/skills/x-api-mcp-guide/SKILL.md | 219 +++++++++++++++--- .../x-api-mcp-guide/references/pricing.md | 2 + 4 files changed, 194 insertions(+), 36 deletions(-) diff --git a/third_party/x/.cursor-plugin/plugin.json b/third_party/x/.cursor-plugin/plugin.json index 129505b8..5ca54ee8 100644 --- a/third_party/x/.cursor-plugin/plugin.json +++ b/third_party/x/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "x", "displayName": "X", - "version": "2.1.0", + "version": "2.2.0", "minClientVersions": { "cursor": "3.13.0" }, diff --git a/third_party/x/CHANGELOG.md b/third_party/x/CHANGELOG.md index dcde62a2..d8dd2eec 100644 --- a/third_party/x/CHANGELOG.md +++ b/third_party/x/CHANGELOG.md @@ -2,6 +2,13 @@ All notable changes to this plugin will be documented here. +## 2.2.0 — Auto credits, missing-tools failure, never pay first + +- Developer accounts are auto-created and auto-credited. On connect, agents confirm X tools exist, fetch `get_usage_credits`, then congratulate with “you've received free X API credits to get started” (no dollar amount). Starter amounts by plan (Ultra $100, SuperGrok Plus $50, Pro+ $30, Pro $10) only if the user asks how much they received. Remaining balance (`total_balance`) is for budgets and “what's left.” +- Connected-but-no-tools (`user-X-*` not found, `tools=0`) is the account-not-ready failure: clear/reinstall the X connection, then console.x.com developer account + Default Project + App if it still fails. Old 403 enrollment is the same error. Do not treat this as a paywall. +- Never tell the user to buy credits until after `get_usage_credits`. ~$0 remaining still goes to https://console.x.com. Added budget-tier workflows keyed off `total_balance`. +- Do not sign in via GrokBot's browser or ask for Bearer tokens — X plugin Connect only. + ## 2.1.0 — X MCP guide skill - Added the X MCP guide skill: tells agents how to handle sign-in, onboarding, and out-of-credits errors with simple user-facing messages, plus session-start, search, pagination, and cost-aware workflow rules. diff --git a/third_party/x/skills/x-api-mcp-guide/SKILL.md b/third_party/x/skills/x-api-mcp-guide/SKILL.md index 1fb1d089..e89eab58 100644 --- a/third_party/x/skills/x-api-mcp-guide/SKILL.md +++ b/third_party/x/skills/x-api-mcp-guide/SKILL.md @@ -3,19 +3,86 @@ name: X MCP guide description: >- ALWAYS read this when a user connects the X plugin or any X MCP, before using any X connection, and again on any X error. Do not call an X tool until this - file has been read in the current turn. On first connect, send the user the - capabilities message defined here. Estimate the cost of every X call before - making it and confirm with the user before anything expensive. + file has been read in the current turn. On first connect, confirm X tools are + available, fetch get_usage_credits BEFORE any user-facing text, then send the + congrats + capabilities message. Never tell the user to buy credits until that + check returns ~$0 or a job would exceed the balance. If X is connected but + tools are missing (tools=0, user-X-* not found), that is a setup failure — not + a paywall. Estimate the cost of every X call before making it and confirm with + the user before anything expensive. --- # X MCP guide -This plugin uses **X MCP**. The user taps Connect and signs in with X. They are not setting up an API app. +This plugin uses **X MCP**. The user taps Connect and signs in with X. Developer accounts are auto-created and auto-credited. They are not setting up an API app. -Probe the current user before search, timeline, bookmarks, or news. On a core error, stop. Name the simple issue, then the next step. Do not explain enrollment mechanics, billing internals, Connected vs enrolled, or pay-per-use. Never retry 401 / 403-enrollment / credits-blocked unchanged. Never ask for keys. Never tell them to create an app, Project, or Production env. +On a core error, stop. Name the simple issue, then the next step. Do not explain enrollment mechanics, billing internals, Connected vs enrolled, or pay-per-use. Never retry 401 / 403-enrollment / credits-blocked / missing-tools unchanged. Never ask for keys. Never tell them to create an app, Project, or Production env except the quoted [error 2](#2-account-not-ready) steps. + +**Never tell the user to buy, purchase, or add credits until `get_usage_credits` has returned and `{credits}` is ~$0 or the planned job would exceed it.** Do not use “you’ll need to purchase credits at https://console.x.com” (or any “buy credits first” variant) on connect or before that check. Missing tools is not a pay CTA. + +## Connect order + +Do this **before any user-facing X copy**: + +1. Confirm X tools exist (tool list / server status). +2. If the plugin looks connected but tools are missing, that is [error 2](#2-account-not-ready) — stop. You cannot check credits without tools. +3. If not signed in / 401, that is [error 1](#1-sign-in-failed). +4. `get_users_me` (`user.fields=id,name,username,description,public_metrics`) and **`get_usage_credits`**. Cache `id` as `{me}` and `data.total_balance` as `{credits}`. +5. Then the [On connect](#on-connect) message. + +## Credit balance + +Call **`get_usage_credits`** (`GET /2/usage/credits`). It is free. + +Response (values are **USD dollars and cents**; `20.0` = $20.00): + +```json +{ + "data": { + "free_balance": 20.0, + "free_grants": [ + { "amount": 10.0, "expires_at": "2026-11-19T02:14:28.000Z" }, + { "amount": 10.0, "expires_at": "2026-11-19T16:02:51.000Z" } + ], + "prepaid_balance": 0.0, + "total_balance": 20.0 + } +} +``` + +- **`data.total_balance`** → `{credits}`. Use this for budgets and the ~$0 check. **Always tell the user how many credits they have** (`You have about $X.XX in credits.`), including $0.00. That is remaining balance, not the welcome gift. +- **`data.free_balance`** → if `> 0` on first connect, they got the auto starter grant. Do **not** say “you received $X”. Prepaid users can have a large total that is not the gift. +- Ignore `free_grants` and `prepaid_balance` for user-facing copy. Do not choose what to spend. + +Fetch it: + +1. **On connect** — after tools exist, before any capabilities / congrats text. +2. **When a session starts and X calls are required** — alongside `get_users_me`. +3. **When the user asks what they can do** — ideas, a setup, a budget, remaining credits. + +Do not fetch on every message. + +### If they ask how much they received / starter credits + +Do **not** dump `total_balance` or `free_grants` as the gift amount. Starter credits depend on their Cursor plan: + +| Plan | Starter credits | +| ---- | --------------- | +| Cursor Ultra | $100 | +| SuperGrok Plus | $50 | +| Cursor Pro+ | $30 | +| Cursor Pro | $10 | + +If they ask how much they have **left**, quote `{credits}` (`total_balance`) — same number you already state on connect. ## On connect -The first time the user connects X — or on their first X interaction in a session — send this capabilities message once. Adapt the wording to your voice, keep every line of content: +Once tools exist and `{credits}` is cached, send this once. Adapt the wording to your voice. Keep every capability bullet. + +If `free_balance` **> 0**, lead with: + +> Congrats, you've received free X API credits to get started! + +Then: > You're connected to X. Here's what I can do: > @@ -26,17 +93,27 @@ The first time the user connects X — or on their first X interaction in a sess > - **News & trends** — search X news stories and get trends by location > - **Bookmarks** — list, add, and remove bookmarks, and organize them into folders > -> Requests use credits: you'll need to purchase credits at https://console.x.com for this to work. I'll show you a cost estimate before anything expensive. +> You have about $X.XX in credits. +> +> With that, we could: (2–3 ideas from the matching [By budget](#by-budget) row, using `{credits}`). +> +> I'll show a cost estimate before anything expensive. + +Always include the **You have about $X.XX** line (`total_balance`). Do **not** say “you received $X” — that is the gift size; only the starter table if they ask how much they were given. Do not mention purchasing or console.x.com unless `{credits}` is ~$0. -Send it once per session, not on every message. If their first message already contains an ask, send this first, then do the ask. +If `free_balance` is ~$0 but `{credits}` is above $0, skip the congrats line; keep capabilities, the remaining-balance line, and ideas. + +If `{credits}` is ~$0, keep the bullets, say **You have $0.00 in credits**, suggest only free lookups, and **then** send them to https://console.x.com to add credits — skip congrats and “With that, we could.” Do **not** use the error-3 quote; a successful ~$0 read is not error 3. Do not skip the $0.00 line. + +Send it once per session. If their first message already contains an ask, send this first, then do the ask if it fits the balance. Later in the session, skip “Congrats, you've received…”. ## The three errors -Match `type`, `reason`, `title`, `detail`. Then say the quoted line. Nothing else. +Match `type`, `reason`, `title`, `detail`, or the missing-tools signatures below. Then say the quoted line. For **#1 and #2**, nothing else. For **#3**, the quoted line plus the free-only follow-up. ### 1. Sign-in failed -**When:** X tools unavailable; connect prompt; 401; Unauthorized; login loop; token refresh failed. +**When:** not signed in; connect prompt; 401; Unauthorized; login loop; token refresh failed. Plugin is **not** connected. **Say:** @@ -44,25 +121,37 @@ Match `type`, `reason`, `title`, `detail`. Then say the quoted line. Nothing els Trigger reconnect if you can. Probe once after. If it still 401s, stop. -### 2. Not onboarded (403) +If status is `connected` but tools=0, that is #2, not this. + +### 2. Account not ready + +**When (primary):** X is connected but the agent has **no tools** — the developer account is not set up or not enabled. Signatures: -**When:** `client-forbidden`; `user-not-enrolled`; `client-not-enrolled`; Client Forbidden; 403 on timeline / mentions / search / bookmarks after Connect. +- `Tool user-X-get_users_me was not found` (or any `user-X-*` / `get_users_me` / `get_usage_credits` not found) +- `Use GetDynamicTools to discover available servers` and the X namespace is missing +- Server status: `X [connected]` with `tools=0` + +**When (fallback):** `client-forbidden`; `user-not-enrolled`; `client-not-enrolled`; Client Forbidden; 403 on timeline / mentions / search / bookmarks after Connect. **Say:** -> This X account isn't set up yet. Go to https://console.x.com, register and onboard with this same X account, then come back and I'll retry. +> X is connected, but this account isn't ready yet. Please try clearing out and re-installing the X connection, then reconnect again. If this doesn't work, please try the following: +> +> 1. Visiting https://console.x.com and creating a developer account +> 2. Ensure you have a Default Project created in the console +> 3. Ensure you have an App created in the console -Do not retry. Do not search. Do not mention apps, projects, or pay-per-use. If they already did that, ask them to reconnect, probe once, and if it still 403s say the same line again. +Do not retry in a loop. Do not search. Do not send them to pay. Do not add extra enrollment speech beyond the quoted steps. Do not use “This X account isn't set up yet. Go to https://console.x.com, register and onboard…”. ### 3. Out of credits -**When:** no credits; balance zero or negative; “does not have any credits”; requests blocked until credits are added. +**When:** a billed request is blocked until credits are added; “does not have any credits”; credits-blocked. **Not** a successful `get_usage_credits` with `total_balance` ~$0 — that uses the [On connect](#on-connect) $0 copy (or the ~$0 [By budget](#by-budget) row). **Not** missing tools (#2). **Say:** > You're out of credits. Go to https://console.x.com and add credits, then I'll retry. -Stop. Do not retry. +Stop. Do not retry billed calls. Cache `{credits}` as $0. After the quoted line, you may offer **only free lookups** from the ~$0 [By budget](#by-budget) row: `{me}`, likers of a post, bookmark folders. Do not offer a cheaper paid search or timeline. After they add credits, re-fetch `{credits}` before retrying. If the payload is only `usage-capped` (no enrollment reason): @@ -70,6 +159,34 @@ If the payload is only `usage-capped` (no enrollment reason): If `user-not-enrolled` or `client-not-enrolled` is present, that is #2, not this. +## Edge cases + +If the X connector is failing, stay on errors 1–3 or the 5xx outage line. Do **not** invent another way in. + +### No browser / computer sign-in + +**When:** you would open x.com (or console.x.com) in GrokBot's browser or on this computer to log the user in; type their X username, password, or 2FA; complete Google SSO for them. + +You cannot sign into the user's X account that way. Stop. Do not navigate to login, fill a form, or ask them to type a password into your browser. + +**Say:** + +> I can't sign into X from this browser or computer. Use the X plugin in this chat: tap Connect on the X card and sign in there. Don't paste keys or passwords. + +Then follow [error 1](#1-sign-in-failed) or [error 2](#2-account-not-ready) if that is the real failure. + +### No Bearer tokens / direct API + +**When:** the connector is missing, 401s, or has no tools, and you would ask for a Bearer token, API key, app token, `X_BEARER_TOKEN`, or an Authorization header; or call `api.x.com` yourself with a pasted secret. + +Do not ask. Do not accept one if they offer. This plugin is OAuth via the X connector only. + +**Say:** + +> Don't paste a Bearer token or API key. I only use the X plugin in this chat — tap Connect on the X card and sign in with X. + +Then follow [error 1](#1-sign-in-failed) or [error 2](#2-account-not-ready). Do not curl, set headers, or stand up a local MCP with their token. + ## Other errors `not-authorized-for-resource` (private account they don't own): stop. Their own timeline/bookmarks: probe current user, retry once with that id. @@ -97,22 +214,28 @@ If `user-not-enrolled` or `client-not-enrolled` is present, that is #2, not this 400 `invalid-request`: fix params, don't retry unchanged. -5xx: backoff. Check [https://developer.x.com/status](https://developer.x.com/status) if it keeps failing. +5xx / **503**: backoff once or twice. Do not treat it as $0 credits, a missing app, or [error 2](#2-account-not-ready). Other endpoints may still work. Then say: -200 + `errors[]`: use `data`, skip listed ids. +> X's API looks like it's having an outage (this one isn't on you). Try again in a bit. -## Session start +If it keeps failing, check [https://developer.x.com/status](https://developer.x.com/status). Do not start billed work without a credits read; wait for a successful `get_usage_credits` or for the user to say go. -Resolve the current user (`user.fields=id,name,username,description,public_metrics`). +200 + `errors[]`: use `data`, skip listed ids. +## Session start -| Result | Next | -| ---------------- | ------------------------------------------------------------------------------------ | -| Success | Cache `id` as `{me}`. Do their ask. Prefer `{me}` for timeline, mentions, bookmarks. | -| Error 1, 2, or 3 | Stop. Say that error's line. Do not search. | -| 200 + `errors[]` | Keep `data`. | +When X calls are required this session: confirm tools exist, then `get_users_me` and `get_usage_credits`. +| Result | Next | +| ------------------------------ | ---- | +| Tools missing / not found | [Error 2](#2-account-not-ready). Stop. | +| Success | Cache `{me}` and `{credits}`. If `{credits}` is ~$0, use the On connect $0 copy — not error 3. Otherwise do their ask if it fits. Prefer `{me}` for timeline, mentions, bookmarks. | +| Error 1 | Quoted line only. Do not search. | +| Error 2 | Quoted line only. Do not search. | +| Error 3 | Follow [Out of credits](#3-out-of-credits). | +| 5xx / 503 | Outage copy. Not $0, not error 2. Retry later. | +| 200 + `errors[]` | Keep `data`. | ## Cost awareness @@ -123,11 +246,11 @@ The live payload: - `eventTypePricing` — price **per resource returned** (each post, user, news story…). - `requestTypePricing` — price **per request** (writes, counts, trends…). -- All prices are **USD dollars**: `0.005` = $0.005 = half a cent. Fractional cents to 3 decimal places are normal. $1.00 = 1,000 credits — that conversion is for your own math; quote costs to the user in dollars only. +- All prices are **USD dollars**: `0.005` = $0.005 = half a cent. Fractional cents to 3 decimal places are normal. $1.00 = 1,000 credits — that conversion is for your own math; quote costs to the user in dollars only. `{credits}` from `/2/usage/credits` is already dollars. Estimate = (resources requested × per-resource price) + per-request price. `max_results` bounds a read: a search with `max_results=100` returning posts + expanded authors can cost ~100 × $0.005 + 100 × $0.01. Each pagination page bills again. Only request expansions you'll use — expanded objects bill too. -**Under ~$0.25:** just do it — don't nag about pennies. Keep `max_results` small (10–25) unless they asked for more. +**Under ~$0.25, and it fits `{credits}`:** just do it — don't nag about pennies. Keep `max_results` small (10–25) unless they asked for more. **Over ~$0.25, or any pagination loop / bulk job:** stop first. Give a one-line estimate and ask: @@ -135,6 +258,8 @@ Estimate = (resources requested × per-resource price) + per-request price. `max Wait for a yes. Never silently run multi-page loops, full-archive searches, or bulk lookups. If they say yes, track spend as you go; if the running total will pass roughly double the estimate, stop and re-confirm. +**Estimate larger than `{credits}`:** do not run it. If `{credits}` is ~$0, use the ~$0 [By budget](#by-budget) row (free lookups, then console.x.com). Do not use the error-3 quote unless a billed call was actually blocked. If they still have some balance, offer a cheaper alternative that **fits `{credits}`**, and send them to https://console.x.com only if they still want the larger job. After they top up, re-fetch `{credits}` before retrying. + ## Fields, pagination Request fields. If the tool takes `tweet.fields` or `post.fields`, send `created_at,public_metrics,author_id,lang,conversation_id`. Also `user.fields=created_at,description,public_metrics,verified,location` and `expansions=author_id,referenced_tweets.id`. @@ -166,7 +291,30 @@ Spaces = AND. Recent query max 512 characters; full-archive 1,024. Use `min_like ## Workflows -Current user first. Stop on errors 1–3. +Current user first. Confirm tools exist. Stop on error 1 or 2 with the quoted line only. On API error 3, quoted line plus free lookups only. A successful `{credits}` of ~$0 is **not** error 3. Tailor suggestions to `{credits}`. + +### By budget + +Pick from the **matching row**, not above it. Larger jobs still need an estimate and a yes. `$0.005`/post, `$0.01`/user, expansions bill too. + + +| `{credits}` | Suggest | +| ----------- | ------- | +| ~$0 | Say they have **$0.00 in credits**. `{me}` (free). Likers of a post (free). Bookmark folders (free). Then: add credits at https://console.x.com. | +| under ~$0.25 | One post from a link. One user by handle. Recent post counts on a topic. | +| ~$0.25–$1 | A small search (10–25 posts). One page of home or mentions. | +| ~$1–$5 | A few targeted searches. News on a topic plus trends for a location. Tidy bookmarks. | +| ~$5–$20 | Compare 2–3 accounts (profile + recent posts). A short research pass: counts, then a couple of search angles. | +| ~$20–$50 | Deeper research: several angles, a handful of accounts, news on the topic. One account’s recent posts across a few pages (confirm). | +| ~$50–$100 | A full-archive slice on one query. A competitive set of ~5–10 accounts. Paginated timelines (confirm). | +| ~$100–$500 | Large archive jobs. Many queries or many accounts. Broad topic monitoring across pages — always confirm. | +| ~$500–$1,000 | Org-scale historical pulls. Multi-query archive. Large comparative studies — confirm each large chunk. | +| $1,000+ | Very large archive / bulk historical. Long-running research. Never silent pagination; confirm every large chunk. | + + +When they ask what they can do, re-fetch `{credits}`, say how many they have left, then give 2–3 ideas from the matching row. + +### Common tasks - Home / mentions / my posts: `{me}`, modest `max_results`. Paginate only if asked. - Handle: username → posts. Else user search, then ask. @@ -174,13 +322,14 @@ Current user first. Stop on errors 1–3. - Bookmarks: list `{me}`. Save: parse status id, create bookmark. - One post: parse status id, lookup. - - ## Don't -- Explain deep details (pay-per-use, Connected vs enrolled, billing internals). Do name the simple issue. -- Say pay-per-use, Project, Production, or "create an app". -- Ask for secrets. -- Retry 403 or credits-blocked in a loop. +- Explain deep details (pay-per-use, Connected vs enrolled, billing internals, free vs prepaid grants). Do name the simple issue. +- Say pay-per-use or Production. Do not tell them to create an app or Project except the quoted [error 2](#2-account-not-ready) steps. +- Ask for secrets, Bearer tokens, API keys, or passwords. Do not sign the user into X in GrokBot's browser or on this computer. +- Retry 403, missing-tools, or credits-blocked in a loop. +- Tell the user to buy / purchase / add credits before `get_usage_credits` has returned. Never use “you’ll need to purchase credits at https://console.x.com” unless the check showed ~$0 or a job would exceed `{credits}`. +- Quote `total_balance` or `free_grants` as “you received $X”. Congrats is the free-credits line only; gift size by plan is the starter table, and only if they ask. Always say remaining balance (`You have about $X.XX in credits.`, including $0.00). +- Treat tools=0 / `user-X-*` not found as a paywall. That is [error 2](#2-account-not-ready). +- Pitch or run work above `{credits}`. If `{credits}` is ~$0, only free lookups. If they have some balance, offer a cheaper alternative that fits. - Run an expensive request (over ~$0.25, pagination loops, bulk lookups) without giving an estimate and getting a yes. - diff --git a/third_party/x/skills/x-api-mcp-guide/references/pricing.md b/third_party/x/skills/x-api-mcp-guide/references/pricing.md index 07852593..f59240b5 100644 --- a/third_party/x/skills/x-api-mcp-guide/references/pricing.md +++ b/third_party/x/skills/x-api-mcp-guide/references/pricing.md @@ -14,6 +14,7 @@ Reference prices for cost estimates. May drift; the live endpoint https://consol | Tool | Wraps | Cost | |---|---|---| | `get_users_me` | `GET /2/users/me` | free | +| `get_usage_credits` | `GET /2/usage/credits` | free | | `get_users_by_id` / `get_users_by_username` / `get_users_by_usernames` / `search_users` | user lookup/search | $0.01/user | | `get_posts_by_id` / `get_posts_by_ids` / `search_posts_all` / `get_posts_quoted_posts` | post lookup/search | $0.005/post | | `get_users_posts` / `get_users_mentions` / `get_users_timeline` / `get_users_bookmarks` | user timelines | $0.005/post ($0.001 own data) | @@ -116,6 +117,7 @@ Reference prices for cost estimates. May drift; the live endpoint https://consol ## Free endpoints (no per-use charge) - `GET /2/users/me` +- `GET /2/usage/credits` (MCP: `get_usage_credits`) - `GET /2/tweets/:id/liking_users` - `GET /2/media` · `GET /2/media/:media_key` - Bookmark folders: `GET /2/users/:id/bookmarks/folders` (and by folder id) · folder create From 4a5bc623674c6af2a56aa7659bff4b521dc37f40 Mon Sep 17 00:00:00 2001 From: Paul Vann Date: Thu, 27 Aug 2026 17:07:33 -0400 Subject: [PATCH 2/2] Tighten X MCP guide from review: congrats, credits-tool, and copy. Congrats only on just-connected, $0 remaining wins over leftover free_balance, and a missing get_usage_credits tool is an outage not account-not-ready. Co-authored-by: Cursor --- third_party/x/CHANGELOG.md | 2 +- third_party/x/skills/x-api-mcp-guide/SKILL.md | 34 +++++++++++-------- 2 files changed, 20 insertions(+), 16 deletions(-) diff --git a/third_party/x/CHANGELOG.md b/third_party/x/CHANGELOG.md index d8dd2eec..0e72e553 100644 --- a/third_party/x/CHANGELOG.md +++ b/third_party/x/CHANGELOG.md @@ -7,7 +7,7 @@ All notable changes to this plugin will be documented here. - Developer accounts are auto-created and auto-credited. On connect, agents confirm X tools exist, fetch `get_usage_credits`, then congratulate with “you've received free X API credits to get started” (no dollar amount). Starter amounts by plan (Ultra $100, SuperGrok Plus $50, Pro+ $30, Pro $10) only if the user asks how much they received. Remaining balance (`total_balance`) is for budgets and “what's left.” - Connected-but-no-tools (`user-X-*` not found, `tools=0`) is the account-not-ready failure: clear/reinstall the X connection, then console.x.com developer account + Default Project + App if it still fails. Old 403 enrollment is the same error. Do not treat this as a paywall. - Never tell the user to buy credits until after `get_usage_credits`. ~$0 remaining still goes to https://console.x.com. Added budget-tier workflows keyed off `total_balance`. -- Do not sign in via GrokBot's browser or ask for Bearer tokens — X plugin Connect only. +- Do not sign in via the agent browser or ask for Bearer tokens — X plugin Connect only. ## 2.1.0 — X MCP guide skill diff --git a/third_party/x/skills/x-api-mcp-guide/SKILL.md b/third_party/x/skills/x-api-mcp-guide/SKILL.md index e89eab58..ec8daa05 100644 --- a/third_party/x/skills/x-api-mcp-guide/SKILL.md +++ b/third_party/x/skills/x-api-mcp-guide/SKILL.md @@ -50,7 +50,7 @@ Response (values are **USD dollars and cents**; `20.0` = $20.00): ``` - **`data.total_balance`** → `{credits}`. Use this for budgets and the ~$0 check. **Always tell the user how many credits they have** (`You have about $X.XX in credits.`), including $0.00. That is remaining balance, not the welcome gift. -- **`data.free_balance`** → if `> 0` on first connect, they got the auto starter grant. Do **not** say “you received $X”. Prepaid users can have a large total that is not the gift. +- **`data.free_balance`** → leftover starter grant, if any. Do **not** say “you received $X”. Do **not** congrats just because this is `> 0` (returning sessions still have leftover free grants). Prepaid can be negative, so `free_balance > 0` and `{credits}` ~$0 can both be true — `{credits}` ~$0 wins. - Ignore `free_grants` and `prepaid_balance` for user-facing copy. Do not choose what to spend. Fetch it: @@ -63,7 +63,7 @@ Do not fetch on every message. ### If they ask how much they received / starter credits -Do **not** dump `total_balance` or `free_grants` as the gift amount. Starter credits depend on their Cursor plan: +Do **not** dump `total_balance` or `free_grants` as the gift amount. Starter credits depend on their Cursor plan. **Only quote a row if you actually know their plan.** Do not guess. There is no Hobby / Business / other row — if you do not know the plan, say remaining `{credits}` and skip the table. | Plan | Starter credits | | ---- | --------------- | @@ -78,7 +78,11 @@ If they ask how much they have **left**, quote `{credits}` (`total_balance`) — Once tools exist and `{credits}` is cached, send this once. Adapt the wording to your voice. Keep every capability bullet. -If `free_balance` **> 0**, lead with: +**`{credits}` ~$0 always wins:** skip congrats. Keep the bullets, say **You have $0.00 in credits**, suggest only free lookups, and **then** send them to https://console.x.com to add credits — skip “With that, we could.” Do **not** use the error-3 quote. Do not skip the $0.00 line. + +**Congrats** only if `{credits}` is above $0 **and** they **just connected in this chat** (Connect completed this turn, first successful credits read right after signing in). Leftover `free_balance` on a later session is not a new gift — skip congrats. + +If they just connected and `{credits}` is above $0, lead with: > Congrats, you've received free X API credits to get started! @@ -99,11 +103,9 @@ Then: > > I'll show a cost estimate before anything expensive. -Always include the **You have about $X.XX** line (`total_balance`). Do **not** say “you received $X” — that is the gift size; only the starter table if they ask how much they were given. Do not mention purchasing or console.x.com unless `{credits}` is ~$0. +Always include the **You have about $X.XX** line (`total_balance`). Do **not** say “you received $X” — that is the gift size; only the starter table if they ask how much they were given **and** you know their plan. Do not mention purchasing or console.x.com unless `{credits}` is ~$0. -If `free_balance` is ~$0 but `{credits}` is above $0, skip the congrats line; keep capabilities, the remaining-balance line, and ideas. - -If `{credits}` is ~$0, keep the bullets, say **You have $0.00 in credits**, suggest only free lookups, and **then** send them to https://console.x.com to add credits — skip congrats and “With that, we could.” Do **not** use the error-3 quote; a successful ~$0 read is not error 3. Do not skip the $0.00 line. +If they did **not** just connect this turn, skip the congrats line; keep capabilities, the remaining-balance line, and ideas. Send it once per session. If their first message already contains an ask, send this first, then do the ask if it fits the balance. Later in the session, skip “Congrats, you've received…”. @@ -127,15 +129,17 @@ If status is `connected` but tools=0, that is #2, not this. **When (primary):** X is connected but the agent has **no tools** — the developer account is not set up or not enabled. Signatures: -- `Tool user-X-get_users_me was not found` (or any `user-X-*` / `get_users_me` / `get_usage_credits` not found) -- `Use GetDynamicTools to discover available servers` and the X namespace is missing - Server status: `X [connected]` with `tools=0` +- X namespace missing (`Use GetDynamicTools to discover available servers` and no X / `user-X` namespace) +- **Every** X tool missing (`user-X-get_users_me` not found **and** no other `user-X-*` tools) + +Do **not** treat `get_usage_credits` not found as #2 by itself. If other `user-X-*` tools work, that is a missing endpoint or an outage — follow the 5xx / could-not-read-balance copy, not “create a Default Project and App.” **When (fallback):** `client-forbidden`; `user-not-enrolled`; `client-not-enrolled`; Client Forbidden; 403 on timeline / mentions / search / bookmarks after Connect. **Say:** -> X is connected, but this account isn't ready yet. Please try clearing out and re-installing the X connection, then reconnect again. If this doesn't work, please try the following: +> X is connected, but this account isn't ready yet. Please remove and reinstall the X connection, then reconnect. If this doesn't work, please try the following: > > 1. Visiting https://console.x.com and creating a developer account > 2. Ensure you have a Default Project created in the console @@ -165,9 +169,9 @@ If the X connector is failing, stay on errors 1–3 or the 5xx outage line. Do * ### No browser / computer sign-in -**When:** you would open x.com (or console.x.com) in GrokBot's browser or on this computer to log the user in; type their X username, password, or 2FA; complete Google SSO for them. +**When:** you would open x.com (or console.x.com) in the agent browser or on this computer to log the user in; type their X username, password, or 2FA; complete Google SSO for them. -You cannot sign into the user's X account that way. Stop. Do not navigate to login, fill a form, or ask them to type a password into your browser. +You cannot sign into the user's X account that way. Stop. Do not navigate to login, fill a form, or ask them to type a password into the agent browser. **Say:** @@ -214,7 +218,7 @@ Then follow [error 1](#1-sign-in-failed) or [error 2](#2-account-not-ready). Do 400 `invalid-request`: fix params, don't retry unchanged. -5xx / **503**: backoff once or twice. Do not treat it as $0 credits, a missing app, or [error 2](#2-account-not-ready). Other endpoints may still work. Then say: +5xx / **503** / **`get_usage_credits` missing while other X tools work**: backoff once or twice. Do not treat it as $0 credits, a missing app, or [error 2](#2-account-not-ready). Other endpoints may still work. Then say: > X's API looks like it's having an outage (this one isn't on you). Try again in a bit. @@ -326,10 +330,10 @@ When they ask what they can do, re-fetch `{credits}`, say how many they have lef - Explain deep details (pay-per-use, Connected vs enrolled, billing internals, free vs prepaid grants). Do name the simple issue. - Say pay-per-use or Production. Do not tell them to create an app or Project except the quoted [error 2](#2-account-not-ready) steps. -- Ask for secrets, Bearer tokens, API keys, or passwords. Do not sign the user into X in GrokBot's browser or on this computer. +- Ask for secrets, Bearer tokens, API keys, or passwords. Do not sign the user into X in the agent browser or on this computer. - Retry 403, missing-tools, or credits-blocked in a loop. - Tell the user to buy / purchase / add credits before `get_usage_credits` has returned. Never use “you’ll need to purchase credits at https://console.x.com” unless the check showed ~$0 or a job would exceed `{credits}`. -- Quote `total_balance` or `free_grants` as “you received $X”. Congrats is the free-credits line only; gift size by plan is the starter table, and only if they ask. Always say remaining balance (`You have about $X.XX in credits.`, including $0.00). +- Quote `total_balance` or `free_grants` as “you received $X”. Congrats is the free-credits line only, and only when they **just connected this chat**. Gift size by plan is the starter table, and only if they ask **and** you know the plan. Always say remaining balance (`You have about $X.XX in credits.`, including $0.00). `{credits}` ~$0 skips congrats. - Treat tools=0 / `user-X-*` not found as a paywall. That is [error 2](#2-account-not-ready). - Pitch or run work above `{credits}`. If `{credits}` is ~$0, only free lookups. If they have some balance, offer a cheaper alternative that fits. - Run an expensive request (over ~$0.25, pagination loops, bulk lookups) without giving an estimate and getting a yes.