Skip to main content
Glama
Sign In

TokConnect: TikTok Research

by com.tokconnect.mcp
OverviewDiscussionsAdmin

One TikTok LIVE

live
Read-onlyIdempotent

One LIVE room (id = room id from live_search or live_top_selling). Live: now (title, creator, live or ended, viewers, Shop selling). [Shop Analytics, any market via region]: sales (revenue, units, duration), history, products (products sold), strategy (price bands), top_categories, stream_urls. Example: {"id":"7695846289116416799","method":"products"}.

Input Schema

NameRequiredDescriptionDefault
idYesLIVE room id.
endNoShop Analytics methods: custom range end, YYYY-MM-DD (capped at the last complete day).
limitNoResults per page. Shop Analytics methods max 100. Values above a method's maximum are lowered and reported in notes.
startNoShop Analytics methods: custom range start, YYYY-MM-DD.
cursorNoPaging: pass the next value from the previous response unchanged. Omit on the first page.
detailNocompact (default) returns the useful fields; full adds the full raw record (large).compact
methodNoWhat to get. now: live status, viewers, likes, Shop selling | sales [Shop Analytics]: revenue, units, duration, viewers | history [Shop Analytics]: performance over the broadcast | products [Shop Analytics]: products sold in the LIVE, with revenue | strategy [Shop Analytics]: price bands of what was sold | top_categories [Shop Analytics]: top categories sold | stream_urls [Shop Analytics]: recording and stream URLsnow
regionNoMarket 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.
windowNoShop Analytics methods: date range ending at the last complete day (about 2 days ago). Default 30d. Use start/end for a custom range.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • 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)."
  2. Changed1 schema field changed
    • 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."
  3. Changed1 schema field changed
    • 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"
+}
  4. Added

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that status may be live or ended and lists analytics outputs, but it gives no auth, rate-limit, pagination, or freshness caveats, and its 'any market via region' wording is narrower than the schema's supported-region rules.

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?

The description is front-loaded and compact, moving from resource identification to method options to an example. The bracketed notation and dense method list slightly reduce readability, but every part contributes useful selection information.

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

Completeness4/5

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

Given the 9 parameters, rich annotations, 100% schema coverage, and an output schema, the description supplies enough to select a method and provide the required id. The main small gap is that region restrictions are left to the schema, but the overall definition is complete enough for correct invocation.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful id provenance and a concrete example, but method, region, window, cursor, and detail semantics are already fully documented in the input schema.

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 identifies a specific resource, one TikTok LIVE room, and scopes it by requiring an id sourced from live_search or live_top_selling. It also lists the available data methods, making it distinguishable from the search/ranking siblings, though it does not begin with an explicit verb.

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?

It gives clear usage context by saying the id comes from live_search or live_top_selling and by explaining what the method values retrieve. It does not explicitly state when not to use this tool versus those siblings, but the intended workflow is clear.

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 toolsInspect
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