🔴 Routing Rule — Composio vs Native Twitter Tools
If the user has connected Twitter via Composio (OAuth), use Composio for account actions on their own profile:
| User intent | Use |
|---|---|
| Post a tweet / 发推 | Composio TWITTER_CREATION_OF_A_POST |
| Query own profile / 查自己的资料 | Composio TWITTER_USER_LOOKUP_ME |
| Delete own tweet / 删自己的推 | Composio TWITTER_POST_DELETE_BY_POST_ID |
| Lookup someone else's profile or tweets | This skill (twitter_user_info, twitter_user_tweets) |
| Search tweets about a topic | This skill (twitter_search_tweets) |
| Fetch tweets by URL or ID | This skill (twitter_get_tweets) |
Rationale: Composio uses the user's own OAuth-connected Twitter account, so it can post, delete, and access self-endpoints. This skill uses a separate API key that is read-only and cannot act on the user's behalf.
🔴 HARD LIMITS — READ FIRST
⛔ CALL AT MOST 3 TWITTER TOOLS PER RESPONSE. STOP AFTER 3 CALLS. After each tool call, check: "Do I have enough data to answer?" If yes → STOP AND REPLY. ⛔ NEVER callbashorwrite_filefor any twitter task — reason inline, no scripts. ⛔ NEVER paginate unless user explicitly asks for more — first page is enough. ⛔ NEVER calllunar_coin,lunar_coin_time_series, or any LunarCrush/CoinGecko tool — Twitter sentiment 问题只用twitter_search_tweets回答，不跨 skill。 ⛔ NEVER callcoin_price,cg_trending,cg_coins_markets— 价格数据超出 Twitter skill 范围。
🔗 URL Handling — x.com / twitter.com
⛔ NEVER useweb_fetchfor x.com or twitter.com URLs — Twitter blocks scraping, you'll only get a login wall. ✅ ALWAYS extract the tweet ID from the URL and usetwitter_get_tweets.
| URL pattern | Extract | Tool call |
|---|---|---|
x.com/{user}/status/{id} | tweet ID = {id} | twitter_get_tweets(tweet_ids=["{id}"]) |
twitter.com/{user}/status/{id} | tweet ID = {id} | twitter_get_tweets(tweet_ids=["{id}"]) |
x.com/{user} | username = {user} | twitter_user_info(username="{user}") |
Example: User sends https://x.com/zerohedge/status/2042670029548794219 → Extract ID: 2042670029548794219 → Call: twitter_get_tweets(tweet_ids=["2042670029548794219"]) → Never: web_fetch("https://x.com/...")
💡 Few-Shot Examples
Q: 找 3 个关于 BTC ETF 的高赞推文，只要 ID 和点赞数 → PLAN: 1 call twitter_search_tweets("BTC ETF min_faves:100") → pick top 3 from results → reply JSON → STOP after 1 call. Total tools: 1
Q: @elonmusk 最近发的推文哪条点赞最多？只要数字 → PLAN: 1 call twitter_user_tweets("elonmusk") → find max likes in results → reply number → STOP after 1 call. Total tools: 1
Q: 搜索 solana 推文，找点赞最多那条的作者 → PLAN: 1 call twitter_search_tweets("solana") → find tweet with most likes → extract username → STOP after 1 call. Total tools: 1
Q: 对比 @A 和 @B 谁粉丝多，再看粉丝多的最新推文 → PLAN: call twitter_user_info("A") + twitter_user_info("B") → determine winner → call twitter_user_tweets(winner) → Total tools: 3. STOP.
⚡ FAST PATHS (act immediately, no clarification needed)
| Trigger keywords | Action |
|---|---|
x.com or twitter.com URL with /status/{id} | Extract tweet ID → twitter_get_tweets(tweet_ids=["{id}"]) — never web_fetch |
x.com or twitter.com URL with /{username} only | Extract username → twitter_user_info(username="{username}") |
| crypto sentiment / 情绪扫描 / market mood / BTC ETH SOL 讨论 | Call twitter_search_tweets once per coin: "$BTC", "$ETH", "$SOL" — summarize tone, no user profile lookups |
| search tweets about X | Call twitter_search_tweets with the topic |
| who is @username | Call twitter_user_info |
| what did @username post | Call twitter_user_tweets |
Tool Decision Tree
"Search for tweets about a topic" → twitter_search_tweets Advanced query with operators: keywords, from:user, #hashtag, $cashtag, min_faves, date ranges.
"Look up a specific tweet or set of tweets" → twitter_get_tweets Pass one or more tweet IDs directly.
"Who is this Twitter account?" → twitter_user_info Profile data: bio, follower count, tweet count, verification.
"What has this account been posting?" → twitter_user_tweets Recent tweets from a specific user.
"Who follows this account?" → twitter_user_followers List of followers for a user.
"Who does this account follow?" → twitter_user_followings List of accounts a user follows.
"What are people saying in reply to this tweet?" → twitter_tweet_replies Replies to a specific tweet by ID.
"Who retweeted this?" → twitter_tweet_retweeters Users who retweeted a specific tweet.
"Find accounts related to a topic" → twitter_search_users Search users by name or keyword.
"Read a long X article" → twitter_get_article Pass the article tweet ID. Returns title, preview, cover, and content blocks.
"Get full thread context" → twitter_tweet_thread_context One call returns parent chain + direct replies for the target tweet.
"Who quoted this tweet?" → twitter_tweet_quote Get quote tweets for a specific tweet ID.
"What is trending now?" → twitter_get_trends Get trends with optional woeid, country, category, limit.
"Crypto sentiment scan / 情绪扫描 / market mood" → twitter_search_tweets (call once per coin) For BTC/ETH/SOL sentiment: search "$BTC", "$ETH", "$SOL" separately, then summarize tone inline. ⛔ NEVER call twitter_user_info, twitter_user_followers, or twitter_user_tweets during a sentiment scan — text analysis only.
Available Tools
| Tool | Description | Key Params |
|---|---|---|
twitter_search_tweets | Advanced tweet search | query (required), cursor |
twitter_get_tweets | Get tweets by ID | tweet_ids (array, required) |
twitter_user_info | User profile lookup | username (required) |
twitter_user_tweets | User's recent tweets | username (required), cursor |
twitter_user_followers | User's followers | username (required), cursor |
twitter_user_followings | User's followings | username (required), cursor |
twitter_tweet_replies | Replies to a tweet | tweet_id (required), cursor |
twitter_tweet_retweeters | Who retweeted | tweet_id (required), cursor |
twitter_search_users | Search for users | query (required), cursor |
twitter_get_article | Get long-form article | tweet_id (required) |
twitter_tweet_thread_context | Get full thread context | tweet_id (required) |
twitter_tweet_quote | Get quote tweets | tweet_id (required), cursor |
twitter_get_trends | Get trends | woeid, country, category, limit |
Usage Patterns
⚠️ Token Budget Rules
- Sentiment scan: max 3
twitter_search_tweetscalls (one per coin), then summarize. Stop. - Account research: max 2 tool calls total unless user asks for more depth.
- Never chain more than 5 Twitter tool calls in one response.
Research an account
twitter_user_info— get profile, follower count, biotwitter_user_tweets— see what they've been postingtwitter_user_followings— who they follow (reveals interests)
Track a topic or token
twitter_search_tweetswith query like"$SOL min_faves:50"— find popular tweetstwitter_search_userswith the topic — find relevant accounts
Output Constraints (IMPORTANT for small models)
- Max 1
twitter_search_tweetscall per coin/topic — do not repeat searches for same query. First result set is sufficient. - Max 3
twitter_user_infocalls per response — only look up the most relevant accounts. - Never call
bashorwrite_filefor Twitter data — reason inline directly from tool results. - Sentiment summaries: after 1 search call, summarize tone inline in 3–5 sentences. Done.
- Pagination: only fetch next page if user explicitly asks for more results.
- After getting search results: sort/filter in your head, do not call bash to sort.
Analyze engagement on a tweet
twitter_get_tweets— get the tweet and its metricstwitter_tweet_replies— see the conversationtwitter_tweet_retweeters— see who amplified it
Find influencers in a space
twitter_search_userswith keyword (e.g. "DeFi analyst")twitter_user_infoon top results to compare follower countstwitter_user_tweetsto check content quality
Search Query Operators
The twitter_search_tweets tool supports advanced operators:
| Operator | Example | Description |
|---|---|---|
| keyword | bitcoin | Tweets containing the word |
| exact phrase | "ethereum merge" | Exact phrase match |
from: | from:elonmusk | Tweets by a specific user |
to: | to:elonmusk | Tweets replying to a user |
#hashtag | #crypto | Tweets with hashtag |
$cashtag | $BTC | Tweets with cashtag |
lang: | lang:en | Filter by language |
has:media | has:media | Tweets with images/video |
has:links | has:links | Tweets with URLs |
is:reply | is:reply | Only replies |
min_faves: | min_faves:100 | Minimum likes |
min_retweets: | min_retweets:50 | Minimum retweets |
since: | since:2024-01-01 | Tweets after date |
until: | until:2024-12-31 | Tweets before date |
Combine operators: from:VitalikButerin $ETH min_faves:100 since:2024-01-01
Pagination
Most endpoints support cursor-based pagination. When a response includes a cursor value, pass it as the cursor parameter to get the next page. If no cursor is returned, you've reached the end.
Notes
- API key required: Set
TWITTER_API_KEYenvironment variable. Tools will error without it. - Read-only: These tools only retrieve data. No posting, liking, or following.
- For posting, deleting, or accessing the user's own Twitter account: use the composio skill (see
TWITTER_CREATION_OF_A_POST,TWITTER_USER_LOOKUP_ME,TWITTER_POST_DELETE_BY_POST_ID). This skill cannot act on the user's behalf. - Usernames: Always pass without the
@prefix (e.g."elonmusk"not"@elonmusk"). - Tweet IDs: Use string format for tweet IDs to avoid integer overflow issues.
- Rate limits: The API has rate limits. If you get rate-limited, wait before retrying.