TokConnect: TikTok Research

One TikTok video

video

Read-onlyIdempotent

Everything about one video or photo post: detail, comments, replies, caption transcript, similar videos, and [Shop Analytics; region picks the market] the revenue it drove and the products it sold. Use the post id or link from any other tool. Examples: {"id":"https://vt.tiktok.com/...","method":"transcript"}, {"id":"7694...","method":"sales"}. method=comment_themes lists the keywords TikTok extracts from the comments, each with sample comments. Example: {"id":"7691388445251439924","method":"comment_themes"}.

Input Schema

Name	Required	Description	Default
`id`	No	Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (videos[].id). Not needed for method=captions.
`end`	No	Shop Analytics methods: custom range end, YYYY-MM-DD (capped at the last complete day).
`sort`	No	method=comments: relevant (TikTok's order, default) or newest.
`limit`	No	Results per page. comments and replies max 50, similar max 30; Shop Analytics methods max 100. Values above a method's maximum are lowered and reported in notes.
`start`	No	Shop Analytics methods: custom range start, YYYY-MM-DD.
`cursor`	No	Paging: pass the next value from the previous response unchanged. Omit on the first page.
`detail`	No	compact (default) returns the useful fields; full adds the full raw record (large).	compact
`method`	No	What to get. detail: counts, creator, hashtags, sound, place, linked products, caption tracks \| comments: top-level comments \| replies: replies to one comment (comment_id) \| transcript: existing captions as plain text (nothing is transcribed) \| captions: one caption file as WebVTT (subtitle_url, or the video id: English track first) \| similar: videos TikTok relates to this one \| sales [Shop Analytics]: revenue, units and ad metrics the video drove \| products [Shop Analytics]: products sold through the video, with revenue \| product_trend [Shop Analytics]: daily sales of the video's products \| similar_revenue [Shop Analytics]: how similar videos performed \| comment_themes: keywords TikTok extracts from the comments, with sample comments	detail
`region`	No	Market as an ISO country code, default US. Shop Analytics methods: sales data for that market, amounts in its currency. Live methods that take it (search, video detail, creator posts, Shop pages): TikTok as seen in that market where TikTok serves it. Core: US, GB, DE, FR, ES, JP, TH, VN, ID, MY, PH, BR, MX. Extended: PL, IT, NL, IE. Other countries are refused. See shop_regions.
`window`	No	Shop Analytics methods: date range ending at the last complete day (about 2 days ago). Default 30d. Use start/end for a custom range.
`language`	No	method=transcript: preferred caption language, e.g. en.
`comment_id`	No	method=replies: the comment id from method=comments.
`subtitle_url`	No	method=captions: a caption URL from method=detail (captions[].url).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 2, 2026

changedInput schema / properties / detail / description

Previous value: -"compact (default) returns the useful fields; full adds the raw upstream payload (large)."New value: +"compact (default) returns the useful fields; full adds the full raw record (large)."

Changed1 schema field changedOct 31, 2026

changedInput schema / properties / method / description

Previous value: -"What to get. detail: counts, creator, hashtags, sound, place, linked products, caption tracks | comments: top-level comments | replies: replies to one comment (comment_id) | transcript: existing captions as plain text (nothing is transcribed) | captions: one caption file as WebVTT (subtitle_url) | similar: videos TikTok relates to this one | sales [Shop Analytics]: revenue, units and ad metrics the video drove | products [Shop Analytics]: products sold through the video, with revenue | product_trend [Shop Analytics]: daily sales of the video's products | similar_revenue [Shop Analytics]: how similar videos performed | comment_themes: keywords TikTok extracts from the comments, with sample comments"New value: +"What to get. detail: counts, creator, hashtags, sound, place, linked products, caption tracks | comments: top-level comments | replies: replies to one comment (comment_id) | transcript: existing captions as plain text (nothing is transcribed) | captions: one caption file as WebVTT (subtitle_url, or the video id: English track first) | similar: videos TikTok relates to this one | sales [Shop Analytics]: revenue, units and ad metrics the video drove | products [Shop Analytics]: products sold through the video, with revenue | product_trend [Shop Analytics]: daily sales of the video's products | similar_revenue [Shop Analytics]: how similar videos performed | comment_themes: keywords TikTok extracts from the comments, with sample comments"

Changed3 schema fields changedOct 31, 2026

changedInput schema / properties / method / description

Previous value: -"What to get. detail: counts, creator, hashtags, sound, place, linked products, caption tracks | comments: top-level comments | replies: replies to one comment (comment_id) | transcript: existing captions as plain text (nothing is transcribed) | captions: one caption file as WebVTT (subtitle_url) | similar: videos TikTok relates to this one | sales [Shop Analytics]: revenue, units and ad metrics the video drove | products [Shop Analytics]: products sold through the video, with revenue | product_trend [Shop Analytics]: daily sales of the video's products | similar_revenue [Shop Analytics]: how similar videos performed"New value: +"What to get. detail: counts, creator, hashtags, sound, place, linked products, caption tracks | comments: top-level comments | replies: replies to one comment (comment_id) | transcript: existing captions as plain text (nothing is transcribed) | captions: one caption file as WebVTT (subtitle_url) | similar: videos TikTok relates to this one | sales [Shop Analytics]: revenue, units and ad metrics the video drove | products [Shop Analytics]: products sold through the video, with revenue | product_trend [Shop Analytics]: daily sales of the video's products | similar_revenue [Shop Analytics]: how similar videos performed | comment_themes: keywords TikTok extracts from the comments, with sample comments"

changedInput schema / properties / method / enum

Previous value: -[
-  "detail",
-  "comments",
-  "replies",
-  "transcript",
-  "captions",
-  "similar",
-  "sales",
-  "products",
-  "product_trend",
-  "similar_revenue"
-]New value: +[
+  "detail",
+  "comments",
+  "replies",
+  "transcript",
+  "captions",
+  "similar",
+  "sales",
+  "products",
+  "product_trend",
+  "similar_revenue",
+  "comment_themes"
+]

changedInput schema / properties / region / description

Previous value: -"Shop Analytics methods: market as an ISO country code, default US. Core: US, GB, DE, FR, ES, JP, TH, VN, ID, MY, PH, BR, MX. Extended: PL, IT, NL, IE. Other countries are refused. Amounts are in the market's currency. See shop_regions."New value: +"Market as an ISO country code, default US. Shop Analytics methods: sales data for that market, amounts in its currency. Live methods that take it (search, video detail, creator posts, Shop pages): TikTok as seen in that market where TikTok serves it. Core: US, GB, DE, FR, ES, JP, TH, VN, ID, MY, PH, BR, MX. Extended: PL, IT, NL, IE. Other countries are refused. See shop_regions."

Changed1 schema field changedOct 21, 2026

addedInput schema / properties / region

Added value: +{
+  "description": "Shop Analytics methods: market as an ISO country code, default US. Core: US, GB, DE, FR, ES, JP, TH, VN, ID, MY, PH, BR, MX. Extended: PL, IT, NL, IE. Other countries are refused. Amounts are in the market's currency. See shop_regions.",
+  "maxLength": 2048,
+  "type": "string"
+}

AddedOct 20, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive behavior, so safety is covered. The description adds the non-obvious behavioral split that Shop Analytics methods are region-scoped and priced in the market's currency, which materially affects result interpretation. It omits operational behavior such as capping/pagination consequences, which live only in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the scope sentence, then capabilities, then usage, then a targeted comment_themes clarification with its own example. Dense but every clause carries information; the appended comment_themes paragraph is slightly tacked-on after the general examples.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and 100% schema description coverage, the description need not explain return values, and it covers every method family an agent would need at selection time. The remaining details (limits, cursors, region refusals) are fully handled in the schema, so nothing required to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns one more by giving concrete invocation shapes for two different methods plus a dedicated comment_themes example, which reduces method/parameter mismatches in a 13-parameter dispatcher. The added meaning is mostly illustrative rather than new semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource — one video or photo post — and enumerates the retrievable facets (detail, comments, replies, transcript, similar, Shop Analytics revenue/products), so an agent can immediately tell it is a single-post lookup rather than a discovery tool. It never explicitly contrasts itself with video_search or video_feed, which is the only thing keeping it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use the post id or link from any other tool" tells the agent this is the follow-up call after a search, and the worked examples show correct id+method pairings. It stops short of stating when to prefer comments over comment_themes or transcript over captions beyond what the method prose implies, and names no alternatives to itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All TokConnect: TikTok Research tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?