BeautyIQ: Shade Dupes & Safety

Find cross-brand dupe candidates of a confirmed, unambiguous shade. Takes a ``source_variant_id`` — if you have a shade name instead, call search_products first and use its matched_shade.variant_id. Returns candidates with classification, dupe score and resolved names. Always present the engine's ranked candidates with their classification labels and scores — including honest LOW_CONFIDENCE_MATCH, and the absence of TRUE_DUPE/COLOR_DUPE when that is the case. Never replace or supplement this ranking with your own product suggestions or general knowledge. Defaults to the same product format (e.g. lipstick, not lip pencil). Set same_product_type=false only to explore other formats and label color_alternative as a color alternative, not an interchangeable replacement. Unknown formats cannot pass the strict filter. Explain missing formula/performance data. Prices are dated observations, not live quotes; show currency, date, source and stale/promotional flags. observed_savings_percent is the actual observed saving percentage when both observations are under seven days old and comparable. Older prices are historical; never use them for a budget or a savings claim. price_advantage is a clamped engine component, not an amount of money, a probability, or an exact saving at its limits. Budget currency defaults from the market (IT/DE/FR/ES: EUR, GB: GBP, US: USD). Pass currency as an ISO code when specified by the user. A budget excludes prices in another currency/country; no FX is inferred.

Endocrine Disruption Score for a catalog product. Returns the score band, flagged ingredients, data confidence and the safety disclaimer verbatim. Presence-based screening, not a dose assessment — always relay the disclaimer to the user.

Score a raw INCI ingredient list for a product category (stateless). Use when the product is not in the catalog. Ingredient names that match nothing are reported in unknown_ingredients, never silently dropped. Always relay the disclaimer verbatim.

Search the BeautyIQ catalog for a makeup product or shade. First checks literal catalog shade names, then uses semantic discovery. If requires_clarification is true, ask the user to choose the product, format/line or finish before calling find_dupes. Never select the first ambiguous result automatically. Optional product_type narrows literal lookup (e.g. lipstick vs lip_liner vs nail_polish). Format hints come from catalog names, not verified finish or performance measurements. Different sizes/markets remain distinct choices. Show size when known; never assume that a mini and a full-size product have the same value. Resolves free text — including shade names like "Ruby Woo" — to catalog products. Each result may carry a ``matched_shade`` whose ``variant_id`` is the input for the find_dupes tool. Semantic similarity is NOT identity: before treating a result as the user's product, check that brand AND shade match what they described; otherwise say it was not found and ask for the exact brand/shade. For descriptive queries with no shade name, present the product candidates and ask which shade the user wears — find_dupes needs a specific variant. Relay what the engine returns, including honest no-result cases; never substitute catalog answers with general knowledge.