Skip to main content
Glama

TokConnect: TikTok Research

Top-selling TikTok Shop creators

creator_top_selling
Read-onlyIdempotent

[Shop Analytics] Creators (affiliates) ranked by the sales they drove over a date range: revenue, units, followers, engagement, views, trend. keyword = words in creator names, handles and bios (not the products they sell); category = a category name or id (levels 1-3: the creators selling in it, no keyword needed); both together narrow further. With neither, the result is the top 10 creators for the most recent days (about 6). Up to 100 rows per page with cursor paging, about 700 rows per keyword. sort: revenue, units, followers or growth; order=asc lists lowest first. Filters: revenue, followers, engagement, average views, price, growth, video or LIVE, gender, language, contact channel, MCN, audience age/language. region picks the market (default US). Examples: {"category":"Pet Supplies","followers":"10000-500000","contact":"EMAIL"}, {"keyword":"beauty","window":"7d","sort":"units"}.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "creator_top_selling"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoShop Analytics methods: custom range end, YYYY-MM-DD (capped at the last complete day).
mcnNoFilter. Signed to an MCN (agency) or not.
sortNoRanking metric: followers, growth, revenue, units. Default revenue. growth favours brand-new items (shown as >999.9%); pair it with a revenue or units filter. Applies with a keyword or category.
debutNoFilter. Days since the creator started selling: <4, <8, <31, or >30.
limitNoResults per page. Max 100 per page; pass next as cursor for the following page. Up to about 700 rows per keyword. Without a keyword or category: 10 rows. Values above a method's maximum are lowered and reported in notes.
orderNodesc (default, highest first) or asc (lowest first among the matching rows; pair it with a revenue or units filter to skip dead listings). Applies with a keyword or category.
priceNoFilter. Average price of what they sell, in the market's currency, e.g. <20.
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
genderNoFilter. Creator gender as the feed classifies it.
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.
contactNoFilter. Only creators who list this contact channel. Several: comma separated, e.g. EMAIL,INSTAGRAM. Values: EMAIL, WHATSAPP, INSTAGRAM, YOUTUBE, FACEBOOK, TWITTER.
growingNoFilter. true = only creators whose revenue is growing.
keywordNoMatched against creator names, handles and bios (not the products they sell): 'pet' finds accounts like 'Pet Finds'. For the affiliates of a product type, pass category, or rank products with product_top_selling and call product method=creators on the top items. If keyword and category are both omitted, the result is the top 10 creators for the most recent days (about 6), whatever window is set: pass a keyword or category when the user wants more than 10 rows or a specific window.
revenueNoFilter. Revenue the creator drove in the market's currency over the window, e.g. >10000.
categoryNoNarrow to one or more Shop categories (up to 5), by name or numeric id, levels 1 to 3: ["Skincare"], ["Pet Supplies"], ["Beauty & Personal Care","Health"] or ["601450"]. Without a keyword the creators of the category are found by merging several generic keyword searches (a keyword is needed), and the result says how many keyword sweeps and distinct rows that gave. Find names and ids with category_trends method=tree.
languageNoFilter. Creator language.
avg_viewsNoFilter. Average video views, e.g. >10000.
followersNoFilter. Followers, e.g. 50000-500000.
engagementNoFilter. Video engagement rate percent, e.g. >8.
account_typeNoFilter. BELONGED_TO_SELLER = a brand's own account; INDEPENDENT = affiliate creator.
audience_ageNoFilter. Main follower age band.
revenue_sourceNoFilter. Main revenue source: VIDEO or LIVE.
audience_languageNoFilter. Main follower language.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / category / description
      Previous value: -"Narrow to one or more Shop categories (up to 5), by name or numeric id, levels 1 to 3: [\"Skincare\"], [\"Pet Supplies\"], [\"Beauty & Personal Care\",\"Health\"] or [\"601450\"]. Without a keyword the creators of the category are found by merging several generic keyword searches (the source needs a keyword), and the result says how many keyword sweeps and distinct rows that gave. Find names and ids with category_trends method=tree."New value: +"Narrow to one or more Shop categories (up to 5), by name or numeric id, levels 1 to 3: [\"Skincare\"], [\"Pet Supplies\"], [\"Beauty & Personal Care\",\"Health\"] or [\"601450\"]. Without a keyword the creators of the category are found by merging several generic keyword searches (a keyword is needed), and the result says how many keyword sweeps and distinct rows that gave. Find names and ids with category_trends method=tree."
    • 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. Changed3 schema fields changed
    • changedInput schema / properties / keyword / description
      Previous value: -"Matched against creator names, handles and bios (not the products they sell): 'pet' finds accounts like 'Pet Finds'. For a niche's affiliates, rank the niche with product_top_selling, then call product method=creators on the top items. Omit for the overall top 10, or pass category."New value: +"Matched against creator names, handles and bios (not the products they sell): 'pet' finds accounts like 'Pet Finds'. For the affiliates of a product type, pass category, or rank products with product_top_selling and call product method=creators on the top items. If keyword and category are both omitted, the result is the top 10 creators for the most recent days (about 6), whatever window is set: pass a keyword or category when the user wants more than 10 rows or a specific window."
    • changedInput schema / properties / limit / description
      Previous value: -"Results per page. Max 100 per page; up to 700 rows per keyword. Values above a method's maximum are lowered and reported in notes."New value: +"Results per page. Max 100 per page; pass next as cursor for the following page. Up to about 700 rows per keyword. Without a keyword or category: 10 rows. Values above a method's maximum are lowered and reported in notes."
    • changedInput schema / properties / sort / description
      Previous value: -"Ranking metric. Default revenue. growth favours brand-new items (shown as >999.9%); pair it with a revenue or units filter."New value: +"Ranking metric: followers, growth, revenue, units. Default revenue. growth favours brand-new items (shown as >999.9%); pair it with a revenue or units filter. Applies with a keyword or category."
  4. Changed7 schema fields changed
    • addedInput schema / properties / category
      Added value: +{
      +  "description": "Narrow to one or more Shop categories (up to 5), by name or numeric id, levels 1 to 3: [\"Skincare\"], [\"Pet Supplies\"], [\"Beauty & Personal Care\",\"Health\"] or [\"601450\"]. Without a keyword the creators of the category are found by merging several generic keyword searches (the source needs a keyword), and the result says how many keyword sweeps and distinct rows that gave. Find names and ids with category_trends method=tree.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "maxItems": 5,
      +  "type": "array"
      +}
    • changedInput schema / properties / keyword / description
      Previous value: -"Matched against creator names, handles and bios (not the products they sell): 'pet' finds accounts like 'Pet Finds'. For a niche's affiliates, rank the niche with product_top_selling, then call product method=creators on the top items. Omit for the overall top 10."New value: +"Matched against creator names, handles and bios (not the products they sell): 'pet' finds accounts like 'Pet Finds'. For a niche's affiliates, rank the niche with product_top_selling, then call product method=creators on the top items. Omit for the overall top 10, or pass category."
    • addedInput schema / properties / order
      Added value: +{
      +  "description": "desc (default, highest first) or asc (lowest first among the matching rows; pair it with a revenue or units filter to skip dead listings). Applies with a keyword or category.",
      +  "enum": [
      +    "desc",
      +    "asc"
      +  ],
      +  "maxLength": 2048,
      +  "type": "string"
      +}
    • changedInput schema / properties / price / description
      Previous value: -"Filter. Average price of what they sell, USD, e.g. <20."New value: +"Filter. Average price of what they sell, in the market's currency, e.g. <20."
    • 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"
      +}
    • changedInput schema / properties / revenue / description
      Previous value: -"Filter. Revenue the creator drove in USD over the window, e.g. >10000."New value: +"Filter. Revenue the creator drove in the market's currency over the window, e.g. >10000."
    • changedInput schema / properties / sort / description
      Previous value: -"Ranking metric, highest first. Default revenue. growth favours brand-new items (shown as >999.9%); pair it with a revenue or units filter."New value: +"Ranking metric. Default revenue. growth favours brand-new items (shown as >999.9%); pair it with a revenue or units filter."
  5. Changed1 schema field changed
    • changedInput schema / properties / keyword / description
      Previous value: -"Niche, product type or brand whose creators you want, e.g. 'fitness' or 'medicube'. Omit for the overall top 10."New value: +"Matched against creator names, handles and bios (not the products they sell): 'pet' finds accounts like 'Pet Finds'. For a niche's affiliates, rank the niche with product_top_selling, then call product method=creators on the top items. Omit for the overall top 10."
  6. Added

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: the window is silently ignored when neither keyword nor category is supplied, category-only queries internally run several keyword sweeps and report sweep/row counts, limit caps at 100 with ~700 rows per keyword, and sort=growth favors brand-new items (>999.9%) requiring a revenue/units filter.

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 purpose, then a compact semicolon-driven map of keyword/category, defaults, paging, sort/order and filters, ending with examples. Efficient overall, but the mid-sentence filter enumeration ('Filters: revenue, followers, engagement, ...') is a dense run-on that partly duplicates the schema and could be trimmed.

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?

For a 26-parameter, zero-required analytics query with an output schema, the description covers the axes an agent needs: scoping (keyword/category/both/neither), default window and row count, paging, sort/order semantics, region validity, and filter families. Nothing needed 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 an extra point by explaining parameter interactions and defaults in one place — keyword excludes product text, category accepts names or numeric ids at levels 1-3 and merges generic sweeps, order=asc should be paired with a revenue/units filter, region defaults to US. Much of this restates schema text rather than adding new meaning, which keeps it below 5.

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

Purpose5/5

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

The first sentence names a specific resource (creators/affiliates), the metric they are ranked by (sales driven), and the output dimensions, so it is instantly distinguishable from sibling tools like creator_search or product_top_selling. It also explicitly clarifies what the keyword does NOT search (products they sell), heading off a likely confusion.

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

Usage Guidelines5/5

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

Gives explicit routing: keyword vs category vs neither, how the two combine, what happens when both are omitted (top 10 for the most recent ~6 days regardless of window), and the alternative path (rank products with product_top_selling and call product method=creators). Two concrete example payloads seal it.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources