linkfox-wb-kalodata-tiktok

[!IMPORTANT] This Skill must rely on the MCP "LinkFox". If this MCP is not installed, please clearly notify the user: Please install the LinkFox connector first:

In WorkBuddy's left sidebar, find "Experts · Skills · Connectors" → "Connectors";

Search for the keyword "LinkFox" and install the connector "LinkFox" (note: it is linkfox, not linkfox-product-selection), and complete login authorization following the instructions;

Return to WorkBuddy and retry.

LinkFox TikTok Product Selection

This is a market data capability for TikTok Shop business decisions: first discover high-performing products, shops, creators, shoppable videos, or livestreams by market and time window, then use the string IDs in the rankings to drill into a single object's sales, traffic, engagement, commission, channel revenue, and relationships. It is suitable for preliminary product selection screening, competitor breakdown, creator collaboration lead discovery, content/livestream performance comparison, and detail verification; it returns raw business data and key metrics that can be analyzed directly.

The associated tool key is kalodata_tiktok. The current capability covers 5 business modules and 10 API operations:linkfox-kalodata-tiktok-product、linkfox-kalodata-tiktok-shop、linkfox-kalodata-tiktok-creator、linkfox-kalodata-tiktok-video、linkfox-kalodata-tiktok-livestream, and each module contains one rank operation and one detail operation.

Capability boundaries

✅ Capability scope

Product selection and product verification（linkfox-kalodata-tiktok-product): use POST /kalodata/product/rank to view best-selling products and compare price, sales, GMV, video/livestream/showcase revenue, growth rate, commission rate, and listing date; use POST /kalodata/product/detail to view price range, reviews, category, shipping, owning shop, and associated videos/livestreams/creators.
Shop competitive research（linkfox-kalodata-tiktok-shop): use POST /kalodata/shop/rank to view TikTok Shop shop rankings and the revenue breakdown for self-operated, creator affiliate, and mall revenue; use POST /kalodata/shop/detail to view shop scale and the number of products, creators, videos, and livestreams.
Creator collaboration and sales performance（linkfox-kalodata-tiktok-creator): use POST /kalodata/creator/rank to discover high-performing creators and compare followers, content views, sales, video/livestream revenue, and growth rate; use POST /kalodata/creator/detail to view region, status, bio, video/livestream GPM, associated products/shops, and any provided contact information.
Shoppable video research（linkfox-kalodata-tiktok-video): use POST /kalodata/video/rank to view high-performing videos, supporting revenue_range GMV range and sortField; use POST /kalodata/video/detail to view plays, likes, comments, shares, sales, video GPM, ad plays, ROAS, CPA, campaign period, duration, and associated products.
Shoppable livestream research（linkfox-kalodata-tiktok-livestream): use POST /kalodata/livestream/rank to view the livestream rankings by region/time window; use POST /kalodata/livestream/detail to view the viewer count, GMV, GPM, duration, and number of products sold for a specified livestream.
Path from discovery to detail: The product_id、shop_id、creator_id、video_id、livestream_id returned by rank must all be preserved as strings and passed respectively to the camelCase parameters of the corresponding detail; for each module's fields, examples, and error codes, see the reference of the same name.
Unified query conditions and result handling: rank can be queried by region、dateRange、language、currency , and typically pagination can use pageNumber 1–5 and pageSize 5–100; results are returned directly by the MCP and parsed according to the response fields in the corresponding reference.

❌ Boundaries and limitations

Rankings are not keyword search: these rank operations browse rankings by market and time window and do not support retrieval by product name, shop name, creator nickname, video title, or livestream title; to get details you must first obtain a valid ID. A valid query with no data may return errcode=200 with no data, and may still be billed.
Pagination and data freshness: responses usually do not provide a trustworthy total or total page count; use data.length to determine the current page, and stop when the returned count is less than pageSize or page 5 is reached. Data may have a T+1 statistical delay and is not equivalent to real-time backend data.
Fields must be distinguished by operation: all sales fields use the API's original spelling sales_volumn; livestream rank uses views, the string-type revenue/unit_price, detail uses viewers, the numeric-type revenue and detail-only gpm; the channel fields for shop rank/detail are self_promotion_revenue/shopping_mall_revenue and self_account_revenue/shoppingmall_revenuerespectively. Fields must not be mixed across operations.
Sorting and filtering restrictions: the default sort is revenue (GMV) descending; the acceptable structure ofsortField is determined by the gateway. When an unsupported sort field is received, fall back to the default order and inform the user; do not invent fields or bypass validation; the GMV range for videos uses only revenue_range。
IDs and metric definitions: overly long IDs must not be converted to floating point; revenue is GMV/sales, not profit, ad spend, or net income;commission_rate、revenue_growth_rate is a direct percentage value. Monetary amounts must always state both the requested currency、region and dateRange。
Authentication, billing, and retries: WorkBuddy authorizes automatically via the MCP connection; adding headers、Authorization, API key, or token to call parameters is prohibited. Every business call may consume credits; on failure, empty results, or unsupported parameters, do not automatically retry, automatically change parameters, automatically probe pagination, or repeatedly probe. To call again, first explain the reason and obtain user confirmation.
Businesses not provided: not responsible for TikTok ad delivery or ad account management, content creation/editing/downloading, shop orders/inventory/ERP, logistics and supply chain, platform account operations, keyword search, cross-platform product research, legal/financial conclusions, or direct communication with platforms/sellers.

Tool selection guide

Choose rank or detail based on the object and metric the user actually wants to observe; first use rank to discover objects, then use the corresponding detail for deep inspection. When different needs can all map to "product/shop/creator/video/livestream", prioritize choosing based on the decision object the user wants to act on, rather than choosing solely based on the common metric "sales".

Need / user says	Default recommendation	When to switch to another
TikTok product selection, hit products, best-selling products, product rankings	`linkfox-kalodata-tiktok-product` 's `product/rank`	When you need to verify a known `productId` 's price range, reviews, channels, and associated objects, switch to `product/detail`
Sales and association analysis for a known product ID	`linkfox-kalodata-tiktok-product` 's `product/detail`	When you only have the product name and not yet the `productId` , first go back to `product/rank`; it does not support search by name
TikTok shop rankings, best-selling shops, competitor shops	`linkfox-kalodata-tiktok-shop` 's `shop/rank`	To view single-store creator collaborations, video/live counts, and channel breakdowns, switch to `shop/detail`
Store profile for a known store ID	`linkfox-kalodata-tiktok-shop` for `shop/detail`	When you only have a store name, first use `shop/rank`; do not treat the store name directly as `shopId`
TikTok creator leaderboard, influencer collaboration leads, creator comparison	`linkfox-kalodata-tiktok-creator` for `creator/rank`	To view a single creator's follower changes, video/live GPM, or contact details, switch to `creator/detail`
Sales data for a known creator ID	`linkfox-kalodata-tiktok-creator` for `creator/detail`	When you only have a nickname or handle, first use `creator/rank`; details are not searched by nickname
Trending sales videos, video GMV/view rankings	`linkfox-kalodata-tiktok-video` for `video/rank`	For a GMV range, use `revenue_range`; for single-video ad and engagement details, switch to `video/detail`
Video virality, engagement, ad metrics, or video GPM	`linkfox-kalodata-tiktok-video` for `video/detail`	Without `videoId` , first use `video/rank`; titles cannot directly locate a video
TikTok sales live leaderboard, live rankings	`linkfox-kalodata-tiktok-livestream` for `livestream/rank`	To view a single live session's viewer count, duration, GPM, and number of products sold, switch to `livestream/detail`
Live data for a known live ID	`linkfox-kalodata-tiktok-livestream` for `livestream/detail`	Without `livestreamId` , first use `livestream/rank`; live titles cannot directly locate details
Make a round of product selection judgments across objects	First call `product/rank`, then select the corresponding detail based on the store/creator/video/live IDs in the leaderboard	If the user clearly focuses on content, streamers, or stores, directly select the corresponding rank to avoid paying for irrelevant objects

Selection approach: when the user asks "what to sell", look at products; when asking "who is selling", look at stores or creators; when asking "how to sell/content performance", look at videos or live streams. rank is only for discovery and comparison; detail is only for verification of a single entity with an existing ID. If multiple objects are requested, first explain that multiple API calls will be consumed, and let the user decide whether to continue.

Business requirement routing quick reference

The reference in the table below includes the module's parameters, complete response fields, error codes, MCP examples, display limitations, and feedback API.toolName Must use the exact value after removing the leading slash from the endpoint.

Sub-capability	Business capability	reference	`toolName`
`linkfox-kalodata-tiktok-product`	Product leaderboard discovery	`references/linkfox-kalodata-tiktok-product.md`	`kalodata/product/rank`
`linkfox-kalodata-tiktok-product`	Single product details	`references/linkfox-kalodata-tiktok-product.md`	`kalodata/product/detail`
`linkfox-kalodata-tiktok-shop`	Store leaderboard discovery	`references/linkfox-kalodata-tiktok-shop.md`	`kalodata/shop/rank`
`linkfox-kalodata-tiktok-shop`	Single store details	`references/linkfox-kalodata-tiktok-shop.md`	`kalodata/shop/detail`
`linkfox-kalodata-tiktok-creator`	Creator leaderboard discovery	`references/linkfox-kalodata-tiktok-creator.md`	`kalodata/creator/rank`
`linkfox-kalodata-tiktok-creator`	Single creator details	`references/linkfox-kalodata-tiktok-creator.md`	`kalodata/creator/detail`
`linkfox-kalodata-tiktok-video`	Sales video leaderboard discovery	`references/linkfox-kalodata-tiktok-video.md`	`kalodata/video/rank`
`linkfox-kalodata-tiktok-video`	Single video details	`references/linkfox-kalodata-tiktok-video.md`	`kalodata/video/detail`
`linkfox-kalodata-tiktok-livestream`	Sales live leaderboard discovery	`references/linkfox-kalodata-tiktok-livestream.md`	`kalodata/livestream/rank`
`linkfox-kalodata-tiktok-livestream`	Single live details	`references/linkfox-kalodata-tiktok-livestream.md`	`kalodata/livestream/detail`

Invocation method

MCP Server：LinkFox
MCP URL：https://mcp-tool-gateway.linkfox.com/mcp/any-tool
MCP tool: only call proxy_call。
Parameter wrapping: the outer layer always contains toolName and arguments；arguments directly place the original business request object. For example, POST /kalodata/product/rank corresponds to toolName: "kalodata/product/rank"。
Automatic authorization: WorkBuddy automatically injects authorization information; business parameters and examples must not contain headers、Authorization, API key, or token.
Result handling: first check the MCP connection, tool schema, and isErrorAfter a successful proxy call, read the text/structured content; if text is a JSON string, parse it only once; then check the downstream errcode/errmsg, and finally read the business fields. Do not treat the MCP outer object as the downstream response, and do not repeatedly parse stringified JSON. No local caching, response persistence, or stdout summary is promised; for complete request/response/error/feedback details, see the corresponding reference.
Fallback prohibited: do not use curl,urllib、requests、httpx , or any other method to directly connect to the tool gateway; if MCP or proxy_call is missing, the connection fails, or an error is returned, stop. Do not silently fall back to HTTP, and do not guess other toolName。
Calling discipline: by default, call only once per session with the same parameters. Do not automatically retry, switch regions, change the time range, change IDs, change filters, or page continuously because of empty results, failures, or missing fields. If the next page or another call is needed, first explain the additional credit cost and obtain user confirmation; rank is limited to page 5 at most.

Usage examples

The following examples are near-executable JSON parameters; omitted fields are handled by the gateway. String IDs in a single rank result can be used directly as the camelCase ID of the corresponding detail, but do not treat example IDs as real objects that the user did not provide.

1. Product selection: ranking to detail

{
  "toolName": "kalodata/product/rank",
  "arguments": {
    "region": "US",
    "dateRange": "last7Day",
    "currency": "USD",
    "language": "en-US",
    "pageSize": 20,
    "pageNumber": 1
  }
}

Call MCP proxy_call（toolName: "kalodata/product/rank"), focusing on product_id、product_name、unit_price、sales_volumn、revenue、video_revenue、live_revenue、showcase_revenue、commission_rate and launch_date. After selecting product_id :

{
  "toolName": "kalodata/product/detail",
  "arguments": {
    "productId": "1729508370969629931",
    "region": "US",
    "dateRange": "last7Day",
    "currency": "USD"
  }
}

Call MCP proxy_call（toolName: "kalodata/product/detail"), focusing on min_price/max_price、product_review_count、product_shop_id、delivery_type、creator_number、video_number、live_number and the detail's shopping_mall_revenue. Channel revenue is summed according to the interface definition; detail GMV may differ slightly due to independent rounding.

2. Store competition: ranking to store profile

{
  "toolName": "kalodata/shop/rank",
  "arguments": {
    "region": "US",
    "dateRange": "last30Day",
    "currency": "USD",
    "pageSize": 10,
    "pageNumber": 1,
    "sortField": {}
  }
}

Call MCP proxy_call（toolName: "kalodata/shop/rank"), showing rank, store,revenue、sales_volumn、on_sell_product_count、unit_price , and channel breakdown. After selecting ranking shop_id :

{
  "toolName": "kalodata/shop/detail",
  "arguments": {
    "shopId": "7495514739648989419",
    "region": "US",
    "dateRange": "last7Day",
    "currency": "USD"
  }
}

Call MCP proxy_call（toolName: "kalodata/shop/detail"), using the detail's seller_type、self_account_revenue、shoppingmall_revenue、creator_number、video_number、live_number、product_number; do not carry the rank's shop_type、self_promotion_revenue、shopping_mall_revenue into detail extraction.

3. Creator collaboration: ranking to creator detail

{
  "toolName": "kalodata/creator/rank",
  "arguments": {
    "region": "US",
    "dateRange": "last7Day",
    "currency": "USD",
    "language": "en-US",
    "pageSize": 10,
    "pageNumber": 1,
    "sortField": {}
  }
}

Call MCP proxy_call（toolName: "kalodata/creator/rank"), showing nickname, handle,creator_id, followers, content views,sales_volumn, total/video/live revenue and growth rate. After selecting an ID:

{
  "toolName": "kalodata/creator/detail",
  "arguments": {
    "creatorId": "7153432386608251946",
    "region": "US",
    "dateRange": "last7Day",
    "currency": "USD"
  }
}

Call MCP proxy_call（toolName: "kalodata/creator/detail"), view creator_followers、new_followers、video_gpm、live_gpm、product_number、shop_number and contact information; do not fabricate content for empty contact information.

4. Commerce videos: GMV filter to video detail

{
  "toolName": "kalodata/video/rank",
  "arguments": {
    "region": "US",
    "dateRange": "last7Day",
    "currency": "USD",
    "revenue_range": "1-1000",
    "sortField": {
      "field": "revenue",
      "type": "DESC"
    },
    "pageSize": 10,
    "pageNumber": 1
  }
}

Call MCP proxy_call（toolName: "kalodata/video/rank"), this is ranking browsing rather than title keyword search; focus on video_id, views/interactions,revenue, ad share, and creator handle. After selecting an ID:

{
  "toolName": "kalodata/video/detail",
  "arguments": {
    "videoId": "7659161409279806734",
    "region": "US",
    "dateRange": "last7Day",
    "currency": "USD"
  }
}

Call MCP proxy_call（toolName: "kalodata/video/detail"), focusing on sales_volumn、video_gpm、ads_views、ads_roas、ad_cpa、ads_period、duration and product_number；video_gpm is GMV per thousand views, not a percentage.

5. Commerce livestreams: livestream ranking to single-session detail

{
  "toolName": "kalodata/livestream/rank",
  "arguments": {
    "region": "US",
    "dateRange": "last7Day",
    "currency": "USD",
    "language": "en-US",
    "pageSize": 10,
    "pageNumber": 1,
    "sortField": {}
  }
}

Call MCP proxy_call（toolName: "kalodata/livestream/rank"), showing title, creator handle, rank-implied order, string revenue/unit_price、views, duration, and start/end times. After selecting livestream_id :

{
  "toolName": "kalodata/livestream/detail",
  "arguments": {
    "livestreamId": "7661409374878878494",
    "region": "US",
    "dateRange": "last7Day",
    "currency": "USD"
  }
}

Call MCP proxy_call（toolName: "kalodata/livestream/detail"), showing the single livestream's viewers, numeric revenue、gpm、product_number , and duration. Timestamps are epoch milliseconds, and duration is in seconds; do not present the detail as a ranking.

Display rules

First label the query scope: any amount, sales, views, or growth metric must be labeled with region、dateRange, with the amount also labeled currency; state that the data comes from the Kalodata TikTok Shop data API and the specific business object.
Ranking tables: the product table must show at least product name/ID, price,sales_volumn, GMV, channel revenue, growth rate, commission rate, and listing date; the shop table shows rank, shop, type, GMV, sales, products on sale, unit price, and growth rate; the creator table shows nickname, handle, followers, content views, sales, total/video/live GMV, and growth rate; the video table shows title/ID, views, engagement, GMV, ad metrics, and creator; the live table shows title, creator, GMV,views, duration, unit price, and start/end time.
Detail grouping: a single-entity detail is not displayed as a ranking. Products are grouped by identity/price/sales/channel/commission/category/shop/related objects; shops by identity/scale/channel/creator-video-live; creators by identity/audience/revenue/video/live/products-shops/contact info; videos by identity/engagement/monetization/ads/creator/duration/related products; lives by identity/time/views/GMV/GPM/product count.
Strictly use field names and types: write all sales fields as sales_volumn; creator creator_followers、content_views is a string count; the video detail's sales_volumn spelling is preserved; the live rank's views and the detail's viewers are not mixed, the rank's revenue/unit_price is parsed from a string first, and the detail's revenue is a number; the shop's rank/detail channel fields take values according to their respective references.
Percentages and GPM：commission_rate、revenue_growth_rate, the ad share carries %; a commission value of 25.0 means 25%, not basis points;video_gpm、live_gpm、gpm is the GMV per thousand impressions/views, not a percentage.
Time and order: live start/end times are formatted from epoch milliseconds into readable local time, and live duration is in seconds; keep the server-side default revenue descending order and return order, and apply sortFieldonly when the user explicitly requests it and the gateway supports it. When a rank page is full, indicate that the next page is available, up to page 5; when there is no total , do not fabricate a total count.
Unavailable and empty fields: missing, empty-string, 0, or explicitly unavailable values must be labeled N/A or omitted, and no data may be fabricated; creator contact info is shown only when the field has a value, otherwise note that it was not provided. When channel breakdowns are affected by rounding, label them as "approximately equal".
Errors and suggestions: show the actual meaning of errcode/errmsg . If a 501 points to a Kalodata 522/554 upstream error, explain it to the user and stop; retry with the same parameters only when the user explicitly agrees. If it is a page number, missing ID, or unsupported field, point out the specific correction. For 401/402, first distinguish the MCP layer from the downstream business layer, and do not treat error responses as normal data.
Objective presentation: by default present only metrics, time windows, field meanings, and limitations; do not describe GMV directly as profit or a guarantee, and do not give business, legal, or financial conclusions that the user did not request; group multi-module results by object and retain the source and time window.

Resolve authentication and credit issues

When an exception occurs, read references/onboarding.md, and first determine which layer the error occurred in:

MCP is not installed, not connected, or proxy_callcannot be found: this is a LinkFox MCP configuration issue; check the connection according to the fixed server, URL, and tool name in onboarding.
MCP layer 401: This is an authorization issue for the connection from WorkBuddy to MCP. Check or reconnect MCP. Do not put the token, API key, or Authorization into arguments。
Downstream business errcode=401: MCP is connected, but business authorization failed; retain the actual errcode/errmsg and handle it according to the onboarding guidance.
Downstream business errcode=402: Insufficient credits or balance; note that business calls may incur charges. Guide the user to the top-up entry provided by onboarding.
Downstream business errcode=403: Insufficient permissions. Handle separately from 401/402 and do not retry automatically.
Other business errors: Pass through errmsgand correct the parameters according to the corresponding reference; obtain user confirmation before any further call.

Credit consumption notice

Users will be charged due to credit consumption. Evaluate carefully: when this skill needs to be called frequently, or when the user's expectation of credit consumption is insufficient, be sure to remind the user and let the user decide whether to continue.