Skip to main content
Glama

hooklayer

by io.github.khan-ashifur
OverviewDiscussionsAdmin

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 confidence band, evidence-cited why_now[], risks[], insufficient_signals[] and history_coverage. The ranking is deterministic and contains no model output - read 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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sortNoOrder the results: momentum, creator_adoption, price_asc, price_desc, reviews, rating, sold, discount, opportunity. History-backed sorts are refused up front when history is unavailable rather than silently falling back.
limitNoMax 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.
nicheNoNiche or category to search (e.g. 'Beauty & Skincare', 'Fitness & Wellness'). At least one of niche or query is required.
queryNoFree-text product keywords (e.g. 'wireless earbuds'). Widens the search corpus. May be combined with niche.
marketNo2-letter ISO region code (US, GB, BR, ...) or 'GLOBAL'. Defaults to US. Only regions ScrapeCreators covers for TikTok Shop return usable data.
categoryNoStrict 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_soldNoMaximum provider-reported cumulative sold count. Strict: unknown is dropped.
min_soldNoMinimum provider-reported cumulative sold count. This is a lifetime total, not a sales rate. Strict: unknown is dropped.
price_maxNoMaximum price in the market currency.
price_minNoMinimum price in the market currency.
max_ratingNoMaximum 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_ratingNoMinimum average rating 0-5. Strict: rows with unknown rating are dropped.
max_reviewsNoMaximum 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_reviewsNoMinimum 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_discountNoMaximum discount percentage 0-100. Strict: unknown is dropped.
min_discountNoMinimum discount percentage 0-100 off the listed original price. Strict: unknown is dropped.
min_momentumNoMinimum 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_saturationNoMaximum 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_competitionNoMaximum competition tolerated, 0-100, expressed intuitively (lower = less competition accepted).
opportunity_stageNoComma-separated stages to keep: emerging, promising, crowded, mature, cooling. Use 'emerging,promising' for the usual 'find breakout products' request.
min_creator_adoptionNoMinimum 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

TableJSON Schema
NameRequiredDescriptionDefault
nicheNo
queryNo
regionNo
successYes
executedNoPresent and false when the request needed stored history that is unavailable. Nothing was charged; drop the history-backed filter or sort and retry.
provenanceNo
generated_atNoISO timestamp
opportunitiesNo
query_contextNoThe filters actually applied, echoed back.
source_coverageNoWhat the engine managed to read: shop search, product hydration, history depth, counts.
credits_remainingNo
recommended_chainNoSuggested 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_reasonsNoWhy coverage was partial, when it was. Surface these rather than presenting a degraded result as complete.
skipped_intelligence_filtersNoFilters that could not be enforced for this request.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / limit / description
      Previous value: -"Max products to return. Default 10, hard cap 20."New value: +"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."
  2. Added

TDQS

A4.6/5.0
Behavior5/5

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

With annotations limited to readOnly/openWorld/idempotent/destructive hints, the description carries the real behavioral load: deterministic 9-component engine with no model output, cost of 5 credits, shop_intelligence entitlement requirement, null-means-unknown semantics for provider_reported.*, absence of any revenue/GMV field, and the instruction never to present the score alone.

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 purpose, then example questions, return semantics, sibling routing, and cost. Dense and information-rich, but several clauses (revenue/GMV caveats, provider_reported explanation) are somewhat repetitive relative to their operational value.

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 21-parameter open-world ranking tool with an output schema, the description supplies everything an agent needs: what it ranks, the component/status/confidence model, how to interpret why_now/risks, and how to route to analyze_product. Nothing material is missing despite the output schema already covering return shape.

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 schema already documents all 21 parameters in detail (including strict-filter and cold-start behaviors). The description adds engine-level context but no additional parameter syntax or format meaning beyond what the schema provides, so the baseline of 3 applies.

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?

States a specific verb+resource ('Find and rank current TikTok Shop / social-commerce product opportunities') with a clear differentiator ('using evidence rather than opinion'). It explicitly distinguishes itself from siblings by naming analyze_product, search_videos, and analyze_account and describing what each does instead.

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?

Provides concrete example questions that select this tool, gives the explicit handoff rule ('once you have a shortlist, call analyze_product'), and names when NOT to use it (generic video search, creator analysis, guaranteed-sales claims). Alternatives and conditions are fully spelled out.

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

All hooklayer toolsInspect
Try in Browser
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources