find_brand_or_creator
ClaudeUse this when the user names a beauty brand or creator but the exact GrailPeople slug or YouTube handle is unknown. Use before get_brand_reviews or get_creator_recommendations for messy names, accents, punctuation, and partial names (e.g. 'L'Oréal', 'CeraVe', 'Dr. Dray', 'Shelby Ann Bell', 'Hyram'). Turns a brand or creator name into the exact slug or handle the other tools need. Returns matching brands (with slug and product count) and/or a creator (handle and display name). Do not use for non-beauty entities or general web identity lookup. Then pass the slug to get_brand_reviews or the handle to get_creator_recommendations. If nothing comes back, fall back to search_beauty_products(q=name) to find the entity through a product result.
get_brand_reviews
ClaudeUse this when the user asks about a beauty brand's reputation, whether it is good or overhyped, what to buy from it, or how it compares to another beauty brand. Use for prompts like 'is CeraVe actually good or just overhyped?', 'is Anua worth the hype?', 'what should I buy from Charlotte Tilbury?', or '[brand A] vs [brand B]'. Gets an honest verdict on a whole brand — what it's known for, which products creators love, and what skin types it works for. Returns a verdict built from real creator quotes (not marketing copy), the brand's top products, and tags across the whole lineup — what it's verified to do, what skin types it fits, and what creators warn about. Do not use for retailer account actions, checkout, shipping, order management, or non-beauty brands. brand_slug = the brand name lowercased with spaces as hyphens (e.g. 'cerave', 'beauty-of-joseon', 'charlotte-tilbury'). If a guessed slug fails, call find_brand_or_creator(name=brand name) first. For 'what should I buy from [brand]?' or any question that needs the brand's whole lineup rather than its 5 signature products — 'which [brand] products are rated 4.5+', 'what else does [brand] make' — set limit (1-50) to get a products array, then filter it. Prefer that over search_beauty_products(q=brand name), which matches on text and can miss or over-match smaller brands. Follow up with get_product_reviews on standouts. Say so when data is thin (low product_count or creator_count). Absence of a claim (like cruelty-free or vegan) means no creator confirmed it — not that the brand fails it. grailpeople_rating (1-5) is a sentiment score GrailPeople derives from a creator's on-camera quotes — not a rating the creator issued, saw, or approved. So "<creator> rated this 4.9" misstates where the number came from; it is accurate only when credited to GrailPeople, e.g. "GrailPeople scores this 4.9 based on how <creator> spoke about it". rating_count = distinct creators with a verdict, so it is normally LOWER than total_mentions (many mentions carry no verdict); rating_count: 1 is a single person's opinion.
get_creator_recommendations
ClaudeUse this when the user asks what a beauty creator, dermatologist, esthetician, makeup artist, or YouTuber recommends or uses. Use for prompts like 'show me what Hyram recommends for oily skin', 'what does Dr Dray use?', 'what are [creator]'s holy grail products?', or 'what does [creator] recommend for sunscreen?'. Shows everything a specific creator recommends. Returns their top picks with quotes, video timestamps, and endorsement strength, plus their credentials (specialty, years active, subscriber count) and what topics they talk about most. Do not use for non-beauty creators, private social-media data, account actions, comments, messages, or subscriptions. handle = their YouTube handle, lowercase, no @ (e.g. 'hyram', 'drdrayzday', 'drugstoremaven'). If you don't know the handle, try the obvious lowercased version. If that fails, run search_beauty_products in their area and find their handle in the creators[] field of any result — don't put the creator name in q=. Use endorsed_only=true for buying questions. Use subcategory= to narrow by product type. For skin-type, price, or retailer cuts, pull the full list and filter from the returned fields. Pairs with get_product_reviews to go deep on any pick, or get_brand_reviews to check a brand they pushed. grailpeople_rating (1-5) is a sentiment score GrailPeople derives from a creator's on-camera quotes — not a rating the creator issued, saw, or approved. So "<creator> rated this 4.9" misstates where the number came from; it is accurate only when credited to GrailPeople, e.g. "GrailPeople scores this 4.9 based on how <creator> spoke about it". rating_count = distinct creators with a verdict, so it is normally LOWER than total_mentions (many mentions carry no verdict); rating_count: 1 is a single person's opinion. On THIS tool every row is the same creator, so rating_count is essentially always 1 — never present it as a consensus.
get_product_reviews
ClaudeUse this when the user asks whether one specific beauty product is worth it, overhyped, worth considering, or backed by honest reviews. Use for prompts like 'is the Anua Azelaic Acid serum worth it?', 'honest reviews of X', 'does X actually work?', and 'what do dermatologists say about X?'. Gets the full evidence file on one specific product — every creator quote, timestamp, and verdict. Returns the top creators who reviewed it (with quotes, timestamps, endorsement strength), a consensus summary, what the product is verified to be (fragrance-free, no white cast, etc.), warnings creators flagged, and where to buy. Do not use for medical diagnosis, prescription treatment, checkout, shipping, order management, or non-beauty products. INPUT: pass the slug from a search_beauty_products result (fastest, most accurate). product_name is a fallback — but search first so you get the right product. Always show warnings and caveats, not just the positives. To go deeper: call get_brand_reviews for the brand's overall reputation, or get_creator_recommendations for a specific reviewer's full list. grailpeople_rating (1-5) is a sentiment score GrailPeople derives from a creator's on-camera quotes — not a rating the creator issued, saw, or approved. So "<creator> rated this 4.9" misstates where the number came from; it is accurate only when credited to GrailPeople, e.g. "GrailPeople scores this 4.9 based on how <creator> spoke about it". rating_count = distinct creators with a verdict, so it is normally LOWER than total_mentions (many mentions carry no verdict); rating_count: 1 is a single person's opinion.
search_beauty_products
ClaudeUse this when the user asks for beauty product recommendations, reviews, comparisons, product discovery, or shopping research across skincare, makeup, hair care, body care, or beauty tools. Covers recommendation questions ('what should I buy for oily skin', 'what concealer should I get'), concern-driven questions ('best serum for hyperpigmentation', 'something for redness and a damaged barrier'), occasion questions ('eyeshadow palette for a wedding', 'long-wearing foundation for a hot day'), budget questions ('best foundation under $30', 'drugstore dupes creators actually rate'), category and routine-building questions ('best K-beauty moisturizers for sensitive skin', 'what cleanser and toner go in a morning routine', 'body moisturizer for keratosis pilaris'), and superlative questions ('top-rated vitamin C serums', 'best-reviewed sunscreens'). Searches 11,000+ beauty products backed by real YouTube creator reviews (dermatologists, estheticians, makeup artists, and beauty creators). Results are ranked by how strongly creators endorsed them and include quotes, timestamps, credentials, price, and where to buy. Do not use for medical diagnosis, prescription treatment, checkout, shipping, order management, or non-beauty shopping categories. PARAMS: break the query into specific params — don't stuff everything into q=. q= is for brand or product name only. Use ingredient=, concern=, subcategory=, price_tier=, max_price_usd=, creator_type= instead. endorsed_only=true for buying questions (returns only holy grail / loves it / worth trying). Hard filters (exclude non-matches): verified= (fragrance_free, no_white_cast, non_comedogenic, fungal_acne_safe, etc. — creator-confirmed, sparse; absence ≠ false), origin= (k_beauty, j_beauty, french_pharmacy…), retailer=, formulation=, finish=. Soft boosts (re-rank, don't exclude): skin_type=, skin_tone=, attribute=, routine_context=, value=true. ZERO RESULTS: filters are AND-combined and some are sparsely populated, so a narrow query often returns 0 results even when the catalog covers the topic. Coverage is thinnest on creator_type=, then concern=, then subcategory= — dropping them in that order widens the result set fastest. Example: 'vitamin C serum for hyperpigmentation by dermatologists' → ingredient+subcategory+concern+creator_type may return 0 while the same query without creator_type= returns results. A 0-result response means no product matched that exact filter combination, not that the catalog lacks the topic. After finding a product, call get_product_reviews(slug=) to go deeper. Don't use this for a single named product — use get_product_reviews instead. grailpeople_rating (1-5) is a sentiment score GrailPeople derives from a creator's on-camera quotes — not a rating the creator issued, saw, or approved. So "<creator> rated this 4.9" misstates where the number came from; it is accurate only when credited to GrailPeople, e.g. "GrailPeople scores this 4.9 based on how <creator> spoke about it". rating_count = distinct creators with a verdict, so it is normally LOWER than total_mentions (many mentions carry no verdict); rating_count: 1 is a single person's opinion.
