Available MCP tools

The server exposes 14 read-only tools. You do not call these yourself — you ask your assistant a question and it picks the tool. This page is here so you know what it can reach, and what each call costs you.

All tools

Tool	Purpose	Paginated
Users
get_user_by_username	Look up a profile by handle	–
get_user_by_id	Look up a profile by numeric ID	–
search_users	Find profiles by name or handle	–
Tweets
get_tweet	Fetch a single post	–
get_tweet_thread	Fetch a thread from any post in it	yes
get_tweet_comments	Fetch replies to a post	yes
Timelines
get_user_tweets	A user’s own posts	yes
get_user_tweets_and_replies	A user’s posts including replies	yes
get_user_mentions	Posts mentioning a user	yes
get_list_tweets	Posts from a list	yes
Social graph
get_user_followers	Who follows a user	yes
get_user_following	Who a user follows	yes
check_is_following	Whether one user follows another	–
Search
search_tweets	Search posts	yes

How pagination and billing relate

A paginated tool returns one page and a next_cursor. One call is one page and one charge. No tool pages automatically — to get the next page, the assistant makes another billed call with the cursor.

Two tools are much more expensive than the rest

get_user_followers and get_user_following bill for a full page of user records on every call — far more than a single lookup. Fetching the followers of a large account means many such calls.

When the question is only whether one specific account follows another, check_is_following answers it for a fraction of the cost.

A note on IDs

Twitter/X IDs are passed as strings, not numbers — they are large enough to lose precision when handled as floating-point numbers, which silently corrupts them. Your assistant handles this; it matters if you are reading the output yourself.

Four tools need a numeric user ID rather than a handle: get_user_tweets, get_user_tweets_and_replies, get_user_followers and get_user_following. If you give your assistant a handle, it will typically call get_user_by_username first to resolve it, which is an additional billed call.

Users

get_user_by_username

Look up a profile by handle.

Parameter	Required	Notes
username	yes	Handle with or without a leading @. 1–15 characters, letters, digits and underscores.

Returns a single user object.

get_user_by_id

Look up a profile by numeric user ID.

Parameter	Required	Notes
user_id	yes	Numeric ID as a string.

Returns a single user object.

search_users

Find profiles by name or handle — useful when you know roughly who someone is but not their exact handle.

Parameter	Required	Notes
query	yes	Max 100 characters.

Returns a list of user objects. Not paginated.

Tweets

get_tweet

Fetch a single post, including engagement counts.

Parameter	Required	Notes
tweet_id	yes	Numeric ID as a string.

Returns a single tweet object.

get_tweet_thread

Fetch a thread given the ID of any post in it. Returns posts in order.

Parameter	Required	Notes
tweet_id	yes	Numeric ID as a string.
cursor	no	From a previous call’s next_cursor. Omit for the first page.

Returns tweets and next_cursor.

get_tweet_comments

Fetch replies to a post — up to 20 per page.

Parameter	Required	Notes
tweet_id	yes	Numeric ID as a string.
cursor	no	From a previous call’s next_cursor.

Returns tweets and next_cursor.

Timelines

get_user_tweets

A user’s own posts, newest first, excluding replies. Up to 20 per page.

Parameter	Required	Notes
user_id	yes	Numeric ID as a string — not a handle.
cursor	no	From a previous call’s next_cursor.

Returns tweets and next_cursor.

get_user_tweets_and_replies

The same, but including the user’s replies.

Parameter	Required	Notes
user_id	yes	Numeric ID as a string — not a handle.
cursor	no	From a previous call’s next_cursor.

Returns tweets and next_cursor.

get_user_mentions

Posts mentioning a given user, newest first.

Parameter	Required	Notes
username	yes	Handle with or without a leading @.
cursor	no	From a previous call’s next_cursor.

Returns tweets and next_cursor.

get_list_tweets

Posts from a Twitter/X list, newest first.

Parameter	Required	Notes
list_id	yes	Numeric list ID as a string.
cursor	no	From a previous call’s next_cursor.

Returns tweets and next_cursor.

Social graph

get_user_followers

One page of a user’s followers. Expensive — see the warning above.

Parameter	Required	Notes
user_id	yes	Numeric ID as a string — not a handle.
cursor	no	From a previous call’s next_cursor.

Returns users and next_cursor.

get_user_following

One page of the accounts a user follows. Expensive — see the warning above.

Parameter	Required	Notes
user_id	yes	Numeric ID as a string — not a handle.
cursor	no	From a previous call’s next_cursor.

Returns users and next_cursor.

check_is_following

Whether one user follows another. The cheap way to answer a question about a specific pair of accounts.

Parameter	Required	Notes
source_user_id	yes	Numeric ID of the account that might be following.
target_user_id	yes	Numeric ID of the account that might be followed.

Returns source_user_id, target_user_id and is_following.

Search

search_tweets

Search posts. This is the most capable tool on the server.

Parameter	Required	Notes
query	yes	Max 512 characters. Supports advanced search operators.
type	no	Latest (default) or Top.
cursor	no	From a previous call’s next_cursor.

Returns tweets and next_cursor.

The query supports the full range of Twitter search operators — from:, to:, since:, until:, min_faves:, min_retweets:, filter:links, -filter:replies, exact phrases, and combinations:

from:elonmusk min_faves:1000 since:2026-01-01

Using operators is usually much cheaper than a broad keyword search, because it takes one well-targeted call instead of several vague ones. Telling your assistant the operators you want is worth doing.

What the tools return

Results are trimmed compared with the REST API. Each object carries the fields below and nothing else — the raw payloads include large amounts of data that would fill an assistant’s context window without helping it answer.

If you need full fidelity, use the REST API directly.

Fields that are empty upstream are omitted rather than returned as null.

Tweet fields

id, text, created_at, author, reply_count, retweet_count, like_count, quote_count, view_count, bookmark_count, is_retweet, quoted_tweet_id, in_reply_to_tweet_id, conversation_id, lang, urls, media

author is a reduced user object — id, username, name, verified, followers_count — rather than a full profile, because the full profile repeated on every post in a page is the single largest source of wasted space.

Quoted and retweeted posts appear as IDs (quoted_tweet_id) rather than nested objects. Your assistant can fetch them with get_tweet if it needs them.

User fields

id, username, name, description, location, url, created_at, followers_count, following_count, tweet_count, listed_count, verified, protected, profile_image_url

Errors

Tool errors come back as readable messages rather than status codes, and tell the assistant whether retrying is worthwhile.

Situation	What happens
User or post not found	The assistant is told it does not exist. This is an answer, not a failure.
Out of credit	The assistant is told to stop and that you need to top up. It will not retry.
Rate limit reached	The assistant is told to stop and let you know to slow down.
Upstream error	The assistant is told the request failed and was not billed.

See Errors for the equivalent REST behaviour.