# MCP tool list

The SocialToAI MCP server lists 16 tools at https://mcp.socialtoai.com/mcp. Each is read-only and carries a short description with its price in credits, so your AI knows when to use it and what it will cost. A call that fails costs nothing, and every answer states the credits charged and the balance.

- Page: https://socialtoai.com/docs/mcp/tools/
- Last updated: 2026-10-17

To connect a client, see [the MCP page](https://socialtoai.com/mcp.md). This page is what the server answers to `tools/list`.

## Tools

| Tool | What it does | Credits per call |
| --- | --- | --- |
| [`search`](https://socialtoai.com/docs/mcp/tools.md) | Find posts or accounts by keyword | 2–12 credits |
| [`trending`](https://socialtoai.com/docs/mcp/tools.md) | What is hot right now | 2–12 credits |
| [`detail`](https://socialtoai.com/docs/mcp/tools.md) | One post: text and numbers | 1–12 credits |
| [`comments`](https://socialtoai.com/docs/mcp/tools.md) | Comments under a post | 2–12 credits |
| [`user_profile`](https://socialtoai.com/docs/mcp/tools.md) | One account: bio and counts | 1–12 credits |
| [`user_posts`](https://socialtoai.com/docs/mcp/tools.md) | Posts from one account | 2–12 credits |
| [`find`](https://socialtoai.com/docs/mcp/tools.md) | Find what can be called by what it does, in plain words, English or Chinese | Free |
| [`call`](https://socialtoai.com/docs/mcp/tools.md) | Call one platform-specific capability by its op ("platform.name"): what the six actions do not cover | By what it runs |
| [`capabilities`](https://socialtoai.com/docs/mcp/tools.md) | List what can be called now: each action per platform and each op, with its parameters (type, values, default), its credits per call, its page size, the fields it cannot give and a call that works | Free |
| [`account`](https://socialtoai.com/docs/mcp/tools.md) | Whose key or connected app this connection is and where it stands: the plan (free or paid), the credit balance, and today's spend, daily limit and room left of the connection and of its account | Free |
| [`brand_buzz`](https://socialtoai.com/docs/mcp/tools.md) | What people say about a brand or product on each platform: the share of each attitude, what is mentioned most, and the posts with the most engagement, each with its source link | By what it runs |
| [`comment_insights`](https://socialtoai.com/docs/mcp/tools.md) | What the comments under your posts are about: the topics and their shares, the questions asked, who wants to buy and what is complained about, with the comments quoted | By what it runs |
| [`find_creators`](https://socialtoai.com/docs/mcp/tools.md) | Creators on one platform for a niche: their size, their recent posts, and how well each fits what you asked for, with the reasons | By what it runs |
| [`account_watch`](https://socialtoai.com/docs/mcp/tools.md) | What a set of accounts published lately and which posts did clearly better than each account's usual | By what it runs |
| [`creator_card`](https://socialtoai.com/docs/mcp/tools.md) | One creator across platforms: the accounts found for the same person, with followers, posts, engagement and how strong the evidence is that each is theirs | By what it runs |
| [`research`](https://socialtoai.com/docs/mcp/tools.md) | Run one of these by its name, on our side | By what it runs |

Every tool that charges takes `handle`: it reads a result an earlier answer gave a handle for, free, and runs nothing else. A large answer comes in parts, each with the handle for the next. [Results and handles](https://socialtoai.com/docs/api/results.md) explains both.

## Each tool

### `search` (2–12 credits, read-only)

**The description your AI is given**

```
Search a platform for content. Read-only. Each line: what to pass, then its platforms, 2 credits a call unless numbered. A list of platforms is one call each. Failed calls cost 0.
Give query: bilibili, douyin 12, kuaishou 12, linkedin, pinterest, reddit, threads, tiktok, wechat 12, wechat_channels 12, weibo, x, xiaohongshu 12, youtube, zhihu
With type=user: douyin, instagram 3, tiktok, weibo, x 5, xiaohongshu 12, zhihu
With sort=latest: x
With type=image: xiaohongshu 12
Each platform's own parameters: capabilities. On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `platform` | string \| array | Yes | One, or a list. |
| `query` | string | No | Search terms |
| `sort` | string | No | By platform: relevance, latest, popular |
| `published_within` | string | No | By platform: day, week, half_year, month, year |
| `type` | string | No | Answers only, or articles only; both when left out. By platform: answer, article, user, image |
| `since` | string | No | Published on or after this day (filtered by UTC date; the time of day is ignored) |
| `until` | string | No | Published on or before this day (filtered by UTC date; the time of day is ignored) |
| `cursor` | string | No | page.cursor of the last answer, other arguments unchanged. |
| `max_cost_credits` | integer | No | Refused, free, if the call would cost more. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `trending` (2–12 credits, read-only)

**The description your AI is given**

```
Read a platform's trending list. Read-only. Each line: what to pass, then its platforms, 2 credits a call unless numbered. A list of platforms is one call each. Failed calls cost 0.
Needs no parameter: bilibili, douyin, kuaishou, reddit, weibo, x 6, xiaohongshu 12, zhihu
With type=videos: bilibili, douyin
With type=trends: reddit
Each platform's own parameters: capabilities. On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `platform` | string \| array | Yes | One, or a list. |
| `board` | string | No | By platform: hot_search, rising, topics, searches, music, low_fan, high_like, high_completion, high_follow, popular, trends, inspiration, hot |
| `type` | string | No | By platform: videos, trends |
| `region` | string | No | Which country's trends, by its two-letter code: US, GB, CA, AU, IN, JP, DE, FR, BR or MX; worldwide when left out |
| `cursor` | string | No | page.cursor of the last answer, other arguments unchanged. |
| `max_cost_credits` | integer | No | Refused, free, if the call would cost more. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `detail` (1–12 credits, read-only)

**The description your AI is given**

```
Get one piece of content by its id or link. Read-only. Each line: what to pass (a|b: either one), then its platforms, 2 credits a call unless numbered. A list of platforms, ids or links is one call each. Failed calls cost 0.
Give id|url: bilibili, douyin, instagram, kuaishou, linkedin, pinterest, reddit, telegram, threads, tiktok, x 1, xiaohongshu 12, youtube, zhihu
Give url: facebook, wechat 12
Give id: wechat_channels 12, weibo
With type=article|pin|question: zhihu
Add include=transcript, charged on top: instagram, linkedin, reddit, tiktok, youtube
Each platform's own parameters: capabilities. Pass links whole, as given. On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `platform` | string \| array | Yes | One, or a list. |
| `id` | string \| array | No | Video ID, a string of digits |
| `url` | string \| array | No | Web link to the video |
| `type` | string | No | By platform: article, pin, question |
| `include` | string \| array | No | Fetched beside each result: transcript. |
| `max_cost_credits` | integer | No | Refused, free, if the call would cost more. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `comments` (2–12 credits, read-only)

**The description your AI is given**

```
Read the comments under one piece of content. Read-only. Each line: what to pass (a|b: either one), then its platforms, 2 credits a call unless numbered. A list of platforms, ids or links is one call each. Failed calls cost 0.
Give id: bilibili, douyin, facebook, kuaishou, wechat_channels 12, weibo, x, zhihu
Give id|url: instagram, reddit, tiktok, xiaohongshu 12, youtube
Give url: wechat 12
With reply_of: bilibili, douyin, instagram, kuaishou, tiktok, xiaohongshu 12, youtube, zhihu
Each platform's own parameters: capabilities. Pass links whole, as given. On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `platform` | string \| array | Yes | One, or a list. |
| `id` | string \| array | No | Video ID, a string of digits |
| `reply_of` | string \| array | No |  |
| `url` | string \| array | No | Web link to the video |
| `sort` | string | No | By platform: best, latest, popular |
| `cursor` | string | No | page.cursor of the last answer, other arguments unchanged. |
| `max_cost_credits` | integer | No | Refused, free, if the call would cost more. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `user_profile` (1–12 credits, read-only)

**The description your AI is given**

```
Get one account's public profile: name, bio, verification and follower counts. Read-only. Each line: what to pass (a|b: either one), then its platforms, 2 credits a call unless numbered. A list of platforms is one call each. Failed calls cost 0.
Give id: bilibili, kuaishou 12, wechat 12, wechat_channels 12, weibo
Give id|url: douyin, xiaohongshu 12
Give id|username|url: facebook
Give username: instagram, reddit, telegram, threads, zhihu
Give username|url: linkedin
Give id|username: tiktok, x 1, youtube
Each platform's own parameters: capabilities. Pass links whole, as given. On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `platform` | string \| array | Yes | One, or a list. |
| `id` | string | No | TikTok user ID, a string of digits |
| `url` | string | No | Link to the page, written facebook.com/handle |
| `username` | string | No | TikTok handle, without the @ |
| `max_cost_credits` | integer | No | Refused, free, if the call would cost more. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `user_posts` (2–12 credits, read-only)

**The description your AI is given**

```
List what one account has published. Read-only. Each line: what to pass (a|b: either one), then its platforms, 2 credits a call unless numbered. A list of platforms is one call each. Failed calls cost 0.
Give id: bilibili, douyin, kuaishou 12, wechat 12, wechat_channels 12
Give id|username|url: facebook
Give username: instagram, reddit, telegram, threads, tiktok, x, zhihu
Give username|url: linkedin
Give id|url: xiaohongshu 12
With type=answer|pin: zhihu
Each platform's own parameters: capabilities. Pass links whole, as given. On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `platform` | string \| array | Yes | One, or a list. |
| `id` | string | No | Page ID, a string of digits; faster than the handle |
| `username` | string | No | TikTok handle, without the @ |
| `url` | string | No | Link to the page, written facebook.com/handle |
| `type` | string | No | Every post, or reels only. By platform: all, reel, answer, pin |
| `sort` | string | No | Newest first, or most popular first. By platform: latest, popular |
| `tab` | string | No | Which tab of the profile: posts (retweets among them), replies (with the posts replied to), or media. By platform: posts, replies, media |
| `cursor` | string | No | page.cursor of the last answer, other arguments unchanged. |
| `max_cost_credits` | integer | No | Refused, free, if the call would cost more. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `find` (Free, read-only)

**The description your AI is given**

```
Find what can be called by what it does, in plain words, English or Chinese. Answers the matching actions and ops, best first, each with its parameters, its credits per call and a call that works. Free. Then use the action's tool, or call with the op.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `query` | string | Yes | What it should do, in 1 to 500 characters. |
| `platform` | string | No | Only this platform. |
| `limit` | integer | No | How many, 1 to 50; 10 unless given. |

### `call` (By what it runs, read-only)

**The description your AI is given**

```
Call one platform-specific capability by its op ("platform.name"): what the six actions do not cover. find finds an op by what it does; capabilities lists each with its parameters and its credits per call (1 to 24). Read-only. A failed call costs 0.
Ops per platform now: douyin 24, google 3, instagram 1, linkedin 2, meta 4, reddit 3, tiktok 10, wechat 1, wechat_channels 2, weibo 2, x 12, xiaohongshu 5, youtube 2, zhihu 3.
Pass links whole, as given. On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `op` | string | Yes | As find and capabilities give it, like douyin.account_audience. |
| `params` | object | No | The op's own parameters, by name. |
| `cursor` | string | No | page.cursor of the last answer, other arguments unchanged. |
| `max_cost_credits` | integer | No | Refused, free, if the call would cost more. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `capabilities` (Free, read-only)

**The description your AI is given**

```
List what can be called now: each action per platform and each op, with its parameters (type, values, default), its credits per call, its page size, the fields it cannot give and a call that works. Free. The whole list is long: pass platform.
Platforms now: bilibili, douyin, facebook, google, instagram, kuaishou, linkedin, meta, pinterest, reddit, telegram, threads, tiktok, wechat, wechat_channels, weibo, x, xiaohongshu, youtube, zhihu.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `platform` | string | No | Only this platform. |

### `account` (Free, read-only)

**The description your AI is given**

```
Whose key or connected app this connection is and where it stands: the plan (free or paid), the credit balance, and today's spend, daily limit and room left of the connection and of its account. Free.
```

### `brand_buzz` (By what it runs)

**The description your AI is given**

```
What people say about a brand or product on each platform: the share of each attitude, what is mentioned most, and the posts with the most engagement, each with its source link. Runs on our side. A costly or background run answers its price first.
Credits by scale small/medium/large, for one name on one platform: bilibili, youtube 16/100/284; douyin 60/180/420; kuaishou 60/210/540; reddit 20/76/210; wechat 36/270/834; weibo 20/100/282; x 16/124/368; xiaohongshu 36/258/780; zhihu 18/90/234; instagram 16/92/254; linkedin 20/-/-; threads, pinterest 16/-/-; tiktok 16/140/440; wechat_channels 60/306/906.
On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `brand` | string | Yes | The brand, product or topic by its name. |
| `about` | string | No | What it is, in a sentence: keeps out other things of the same name. |
| `compare_with` | array | No | Up to 2 competitors. Each is read by the same plan and priced on its own. |
| `platforms` | array | No | 1 to 5 platforms. Left out: the usual three for the language the name is written in, as far as each is offered; the answer names them. |
| `window` | string | No | How far back to read. One of 7d, 30d, 90d. |
| `scale` | string | No | small reads up to 40 posts a platform and no comments; medium about 100 posts and 2 pages of comments of 6 of them; large about 200 posts and 3 pages of comments of 15. |
| `max_cost_credits` | integer | No | Refused, free, with the quote, if the run would cost more. |
| `confirm` | boolean | No | true: run it whatever it costs. false: answer the plan and its price, and run nothing. Left out: a costly run, and one that runs in the background, answers its price first. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `comment_insights` (By what it runs)

**The description your AI is given**

```
What the comments under your posts are about: the topics and their shares, the questions asked, who wants to buy and what is complained about, with the comments quoted. Runs on our side. A costly or background run answers its price first.
Credits by scale small/medium/large, for one post: bilibili, douyin, weibo, youtube 50/232/672; kuaishou 40/182/522; reddit 80/382/1122; wechat 150/732/-; x 42/190/544; xiaohongshu 270/672/-; zhihu, facebook 70/332/972; instagram 58/266/772; tiktok 38/172/492; wechat_channels 138/636/-.
Pass links whole, as given. On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `targets` | array | Yes | 1 to 20 links to posts; they may be of different platforms. |
| `focus` | string | No | What you want to know, in a sentence: adds the comments that speak to it. |
| `topics` | array | No | Your own topics, up to 10: the step that finds topics is then left out. |
| `scale` | string | No | The most comments read in all, shared by the posts: small 200, medium 1,000, large 3,000; fewer on a platform whose comments cost more, as the answer says. |
| `max_cost_credits` | integer | No | Refused, free, with the quote, if the run would cost more. |
| `confirm` | boolean | No | true: run it whatever it costs. false: answer the plan and its price, and run nothing. Left out: a costly run, and one that runs in the background, answers its price first. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `find_creators` (By what it runs)

**The description your AI is given**

```
Creators on one platform for a niche: their size, their recent posts, and how well each fits what you asked for, with the reasons. Runs on our side. A costly or background run answers its price first.
Credits by scale small/medium/large, for one search on one platform: bilibili 90/226/442; douyin 9/27/75; x 75/181/347; instagram 93/229/445; tiktok 92/228/444.
On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `query` | string | Yes | The niche, as keywords. |
| `platform` | string | Yes | One platform. |
| `followers_min` | integer | No | The fewest followers a creator may have. |
| `followers_max` | integer | No | The most followers a creator may have. |
| `brief` | string | No | Who you are looking for, in a sentence: what each creator is judged against. |
| `scale` | string | No | Creators whose profile and posts are fetched: small 20, medium 50, large 100. |
| `max_cost_credits` | integer | No | Refused, free, with the quote, if the run would cost more. |
| `confirm` | boolean | No | true: run it whatever it costs. false: answer the plan and its price, and run nothing. Left out: a costly run, and one that runs in the background, answers its price first. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `account_watch` (By what it runs)

**The description your AI is given**

```
What a set of accounts published lately and which posts did clearly better than each account's usual. Runs on our side. A costly or background run answers its price first.
Credits by scale small/medium/large, for one account: bilibili 10/12/22; douyin, reddit, zhihu 10/14/24; kuaishou 30/54/70; wechat 42/90/120; x 9/13/29; xiaohongshu 30/54/84; facebook 12/20/30; instagram 12/18/28; linkedin 12/20/-; telegram 10/14/-; threads 12/16/-; tiktok 12/20/36; wechat_channels 42/66/96.
Pass links whole, as given. On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `accounts` | array | Yes | 1 to 20 links to account pages; they may be of different platforms. |
| `window` | string | No | How far back to look for new posts. One of 7d, 30d. |
| `scale` | string | No | Per account: small about 20 posts, medium about 60, large as medium and the comments of 2 posts that took off. |
| `max_cost_credits` | integer | No | Refused, free, with the quote, if the run would cost more. |
| `confirm` | boolean | No | true: run it whatever it costs. false: answer the plan and its price, and run nothing. Left out: a costly run, and one that runs in the background, answers its price first. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `creator_card` (By what it runs)

**The description your AI is given**

```
One creator across platforms: the accounts found for the same person, with followers, posts, engagement and how strong the evidence is that each is theirs. Runs on our side. A costly or background run answers its price first.
Credits by scale small/medium, for one creator, starting on this platform, looked for on the default platforms: bilibili, x 22/46; douyin 14/38; kuaishou 46/76; reddit, facebook 35/47; wechat, wechat_channels 46/100; xiaohongshu 46/-; zhihu 26/44; instagram 22/34; linkedin, telegram, threads 35/-; tiktok 35/59.
Pass links whole, as given. On error, follow error.fix. Tell the user billing.display.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `creator` | string | Yes | A link to the creator's page. |
| `platforms` | array | No | The other platforms to look on: up to 3, or 6 with scale medium. Left out: the usual three for the platform the creator starts on, as far as each is offered; the answer names them. |
| `scale` | string | No | medium adds a sample of the comments under the creator's latest posts and, where the platform has one, the creator's marketplace profile. |
| `max_cost_credits` | integer | No | Refused, free, with the quote, if the run would cost more. |
| `confirm` | boolean | No | true: run it whatever it costs. false: answer the plan and its price, and run nothing. Left out: a costly run, and one that runs in the background, answers its price first. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |

### `research` (By what it runs)

**The description your AI is given**

```
Run one of these by its name, on our side. A costly or background run answers its price first. Pass links whole, as given. On error, follow error.fix. Tell the user billing.display.
batch_stats (Bulk link data): urls, max_cost_credits?, confirm?. Credits a link, post/account: bilibili, douyin, reddit, weibo, youtube, zhihu, facebook, instagram, linkedin, telegram, threads, tiktok 2/2; kuaishou 2/12; wechat 24/12; x 1/1; xiaohongshu, wechat_channels 12/12.
viral_finder (Viral finder): query, platform, window?, scale?, max_cost_credits?, confirm?. Credits by scale small/medium/large: bilibili 24/64/160; douyin 48/88/192; x 24/54/130; xiaohongshu 54/294/810; youtube 24/-/-; tiktok 36/76/178.
```

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `tool` | string | Yes | One of batch_stats, viral_finder. |
| `inputs` | object | Yes | That tool's inputs, by name. |
| `handle` | string | No | A handle an earlier answer gave: reads that result, free. Nothing else is run. |