product_scout
Find and rank current TikTok Shop / social-commerce product opportunities using evidence rather than opinion. Use it to answer questions like 'what skincare products are breaking out in the US under $40', 'show me products with strong reviews but low competition', or 'what is worth testing in this niche right now'. Returns products ranked by a deterministic 9-component engine (demand, momentum, creator_adoption, competition, saturation, review_strength, price_attractiveness, creator_concentration, freshness), each carrying an opportunity status (emerging | promising | crowded | mature | cooling | insufficient_data), a qualification record (what passed, failed and is unknown), a confidence band, evidence-cited why_now[], risks[], insufficient_signals[] and history_coverage. Status comes from a qualification gate, never from the score: emerging needs measured sold-count growth across 3+ dated observations spanning 7+ days plus an independent signal (review growth or creator adoption over time); mature means established demand without verified growth; insufficient_data means trajectory cannot be verified yet, however high the score. verification_summary.outcome is NO_VERIFIED_OPPORTUNITIES whenever no returned product passed the gate - say so plainly instead of presenting the list as opportunities, and use verification_summary.by_status to explain whether the category or the filters were the limit. Amazon competition is never measured (AMAZON_COMPETITION_UNVERIFIED); never describe a product as unsaturated on Amazon. The ranking is deterministic and contains no model output - read qualification, why_now, risks and components to explain to the user WHY something ranked where it did, and never present the score on its own. Provider-reported fields live under provider_reported.* and are null when TikTok did not expose them; null means unknown, never zero, and sold counts are never multiplied by price to imply revenue. There is no revenue or GMV field. To validate a single product in depth once you have a shortlist, call analyze_product - product_scout ranks a field of candidates, analyze_product interrogates one. Not for generic video search (use search_videos), creator analysis (use analyze_account), or any guaranteed-sales claim. Cost: 5 credits. Requires the shop_intelligence entitlement.
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": "product_scout"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Order the results: verified_first is the default when omitted, listing verified emerging products first and measured-growth products next, then unverified candidates and established comparisons interleaved so neither dominates, buyer-satisfaction risks last. Also: opportunity (same grouping, needs history), rating (highest rated), sold (most cumulative sold), reviews (most reviewed), discount, price_asc, price_desc, momentum, creator_adoption. An unsupported name is rejected, never replaced. History-backed sorts are refused up front when history is unavailable rather than silently falling back. | |
| limit | No | Max products to return. Default 20, hard cap 20. This is a ceiling, not a target — fewer rows means the provider had fewer matching products, never that results were withheld. | |
| niche | No | Niche or category to search (e.g. 'Beauty & Skincare', 'Fitness & Wellness'). At least one of niche or query is required. | |
| query | No | Free-text product keywords (e.g. 'wireless earbuds'). Widens the search corpus. May be combined with niche. | |
| market | No | 2-letter ISO region code (US, GB, BR, ...) or 'GLOBAL'. Defaults to US. Only regions ScrapeCreators covers for TikTok Shop return usable data. | |
| category | No | Strict category-breadcrumb filter applied to returned rows (case-insensitive substring). Rows whose category is unknown are dropped when this is set. Distinct from niche, which is a search hint rather than a gate. | |
| max_sold | No | Maximum provider-reported cumulative sold count. Strict: unknown is dropped. | |
| min_sold | No | Minimum provider-reported cumulative sold count. This is a lifetime total, not a sales rate. Strict: unknown is dropped. | |
| price_max | No | Maximum price in the market currency. | |
| price_min | No | Minimum price in the market currency. | |
| max_rating | No | Maximum average rating 0-5. Pair with min_rating to isolate a mid-tier band rather than only top-rated listings. Strict: unknown rating is dropped. | |
| min_rating | No | Minimum average rating 0-5. Strict: rows with unknown rating are dropped. | |
| max_reviews | No | Maximum provider-reported review count - the usual way to find products before they are saturated with social proof. Strict: rows whose review count could not be retrieved are dropped rather than assumed to be zero. | |
| min_reviews | No | Minimum provider-reported review count. Review counts are fetched per candidate, so this filter reflects real provider data. Strict: rows whose review count could not be retrieved are dropped rather than assumed to be zero. | |
| max_discount | No | Maximum discount percentage 0-100. Strict: unknown is dropped. | |
| min_discount | No | Minimum discount percentage 0-100 off the listed original price. Strict: unknown is dropped. | |
| min_momentum | No | Minimum momentum component 0-100. Momentum needs stored history; when the history layer has not seen these products yet the request is refused up front with executed:false rather than charged and returned empty. | |
| max_saturation | No | Maximum saturation component 0-100. Saturation needs video-to-product linkage that the current pipeline does not extract, so this is accepted for forward compatibility and reported as unsupported rather than silently applied. | |
| max_competition | No | Maximum competition tolerated, 0-100, expressed intuitively (lower = less competition accepted). | |
| opportunity_stage | No | Comma-separated stages to keep: emerging, promising, crowded, mature, cooling, insufficient_data. Use 'emerging,promising' for the usual 'find breakout products' request. An empty result reports verification_summary.by_status so you can tell a weak category from a restrictive filter; when nothing in the scan could be classified, the empty result is not charged. | |
| min_creator_adoption | No | Minimum creator-adoption component 0-100 (distinct creators per day with confirmed showcase links). Needs stored history; cold-start products report insufficient_data for this component. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| niche | No | ||
| query | No | ||
| region | No | ||
| success | Yes | ||
| executed | No | Present and false when the request needed stored history that is unavailable. Nothing was charged; drop the history-backed filter or sort and retry. | |
| provenance | No | ||
| generated_at | No | ISO timestamp | |
| opportunities | No | ||
| query_context | No | The filters actually applied, echoed back. | |
| source_coverage | No | What the engine managed to read: shop search, product hydration, history depth, counts. | |
| credits_remaining | No | ||
| recommended_chain | No | Suggested next calls, chosen from what this result actually contained. SUGGESTIONS ONLY - present them and let the user pick. Do not call them automatically; each one costs the user credits. | |
| degradation_reasons | No | Why coverage was partial, when it was. Surface these rather than presenting a degraded result as complete. | |
| verification_summary | No | Scan-level verdict. outcome is VERIFIED_OPPORTUNITIES or NO_VERIFIED_OPPORTUNITIES; by_status counts every classified product before stage filters and the limit; explanation says whether the category or the filters were the limit. Lead with this when outcome is NO_VERIFIED_OPPORTUNITIES. | |
| skipped_intelligence_filters | No | Filters that could not be enforced for this request. |