---
title: "Available MCP tools"
description: "The 14 read-only tools exposed by the SocialData MCP server, their parameters and the data they return"
source: "https://docs.socialdata.tools/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](#user-fields).

### `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](#user-fields).

### `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](#user-fields). 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](#tweet-fields).

### `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](https://docs.socialdata.tools/resources/twitter-search-operators/) — `from:`, `to:`, `since:`, `until:`, `min_faves:`, `min_retweets:`, `filter:links`, `-filter:replies`, exact phrases, and combinations:

```plaintext
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](https://docs.socialdata.tools/reference/get-user-profile/) 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](https://docs.socialdata.tools/getting-started/errors/) for the equivalent REST behaviour.