Ask AI

ESCAPE HATCH: ask Triple Whale's own AI assistant (Moby) a free-form question, answered by Triple Whale's servers against their full dataset. Use ONLY when no structured tool covers the question — prefer get_connector_data(connector:'triple-whale') / get_marketing_performance / get_spend_reconciliation first: they're faster (Moby takes 20-60 seconds), deterministic, and carry confidence/freshness signals. Good Moby use-cases: TW-specific features we don't sync (cohort LTV projections, TW custom metrics/expressions, creative-level breakdowns), or cross-checking a number against what Triple Whale itself reports. The answer is Triple Whale's OWN computation — present it as 'Triple Whale reports…', not as independently verified.

TRIGGER: Call WITHOUT asking once an applied intervention's check date has passed. Find candidates with get_interventions(dueForCheckIn: true). Attaches the latest RECORDED post-fix snapshot for each tracked metric (a snapshot whose periodStart is on/after the fix's appliedAt) as the 'post' side, computes deltas vs baseline, and flags whether each metric met its expected delta. Google Ads (source 'google-ads', from synced stats) and Triple Whale (source 'tw', live from Triple Whale for the exact window) metrics are measured automatically: the post side runs from the day after the change to yesterday, and a missing or misaligned baseline is recomputed for the 28 days before. Pass campaignId to scope a record's Google Ads metrics to one campaign. Other sources are NOT captured live, so if you haven't recorded post-fix snapshots yet (via record_metric_snapshot), record them first. If NO tracked metric has a post snapshot, a measured verdict (lift_confirmed/regressed/lift_inconclusive/partial) is REFUSED rather than closing with zero measurement — record snapshots then retry, or pass force:true to close on external evidence, or verdict:'abandoned' if you never measured. Sets the intervention's verdict and status='closed'.

Get cart abandonment analytics. Reports: stats (trackedAbandonmentRecords, abandonedCheckouts, recoveredCheckouts, recoveryRate %, abandonedValue, lostRevenue, abandonedAgeDistribution — how long ago the still-unrecovered carts were abandoned: 0-24h, 24-48h, 2-7d, 7-30d, 30d+), top_products (most frequently abandoned products with count, quantity, and total value). IMPORTANT UNIVERSE: figures cover only Shopify's abandoned-checkout records; completed purchases never enter this dataset, so do NOT derive an abandonment rate from these counts or compare them to order totals. Shopify API limitations — the following are never available and will always be null/unknown: abandonedStep (contact/shipping/payment), landingPage, referrer, deviceType, browserFamily. These fields do not exist in Shopify's GraphQL abandonedCheckouts API.

Get Google Analytics (GA4) website traffic and e-commerce data. **DO NOT USE THIS FOR CHECKOUT FUNNEL OR CVR QUESTIONS** — call `get_marketing_performance` instead, which uses Shopify TrafficStat (the canonical session source) and Shopify orders. GA4 over-counts sessions (~2-3× higher than Shopify TrafficStat for many stores due to subdomain/bot inclusion) which produces a CVR roughly half the real Shopify-native rate. Use GA4 for: traffic sources (channels, referrers, AI assistants), device/country/browser splits, landing-page performance, GA4-specific event counts — things TrafficStat doesn't cover. Reports: summary (sessions, activeUsers, newUsers, pageViews, engagedSessions, conversions — with % change vs prior period — DO NOT use these sessions for funnel/CVR), trend (daily breakdown of sessions/users/pageViews — returns `charts` with four ready-to-render line specs: sessions, activeUsers, pageViews, conversions. `charts[].data` is the FULL daily series even when `items` is truncated for token budget), by_channel (sessions, users, revenue and conversions by channel group: Organic Search, Paid Search, Direct, Social, Email, etc. — returns `charts` with a sessions bar; plus a revenue bar when revenue is populated), by_source (sessions broken down by specific REFERRER source/medium — use this for 'AI traffic' / 'ChatGPT / Perplexity / Claude referrals' / 'where is my traffic coming from' / 'what changed in my traffic' questions; includes a rolled-up `aiSourceRollUp` block totalling traffic from known AI assistants, PLUS by default a `comparison` block vs the equal-length prior window: per-source previousSessions/sessionsChangePercent, `newSources` (sources with zero prior sessions), `disappearedSources`, and a `_spamReferrerFlag` when a brand-new referral domain arrives at volume — the purchased-bot-traffic signature that inflates sessions and crashes CVR in both GA4 AND Shopify TrafficStat), by_device (desktop/mobile/tablet split — returns `charts` with a sessions bar), by_country (traffic by country — returns `charts` with a top-15 sessions bar), ecommerce (revenue, transactions, AOV, conversion rate, add-to-cart events and rate — only available if GA4 e-commerce tracking is configured — STILL DO NOT use this CVR as the headline; it's pixel-based), top_products (top products by revenue, units sold, and add-to-cart events from GA4 e-commerce — only available if GA4 e-commerce tracking is configured), top_pages (top pages by total views with sessions, conversions, and revenue per page — use this for 'what are my most visited pages?', 'which landing pages convert best?'), by_campaign (rank UTM campaigns by attributed revenue/orders/sessions — pass medium:'email' to isolate the email program. BEST FOR: 'which email campaigns drove the most revenue?', 'rank campaigns by performance'. Requires links to carry utm_campaign; untagged traffic is not stored. NOTE: opens/clicks/open-rate are email-platform metrics GA4 cannot see — revenue/orders/sessions only). DEFAULT TO RENDERING THE RELEVANT CHART for trend/by_channel/by_device/by_country — open a Claude Artifact or Code Interpreter. Use raw `items` numbers only when the user asks for one specific value.

Anomaly detection across revenue, conversion rate, and refund rate for each of your stores (works for a single store too). Compares the most recent 7-day window against the prior 4 weeks and flags moves outside +/- 1.5 standard deviations or 25% — whichever is stricter. Returns ranked anomalies with store, metric, current vs baseline, severity, and a one-line explanation. High-severity anomalies carry EITHER `drivers`+`driverSummary` (the tag/source/country slice that drove the move) OR `driversNote` (attribution ran, the move is broad-based — sitewide cause, not one channel), plus an `investigate` block: the exact next tool call WITH the anomaly's own window. USE `investigate` VERBATIM — the target tool's default 30-day window will NOT show a one-week move. Use as a session opener: 'anything weird happening?'.

START HERE at the beginning of a session — call it FIRST and SILENTLY (don't announce the call, narrate your plan, or reference your instructions; just open with what it surfaces). One call that orients you before answering: the stores and their currencies, any data sources broken RIGHT NOW (numbers are unreliable until reconnected), open fix-work (interventions due for a verdict / in flight / recently closed), the current focus-plan headline, what each store IS (category / price tier / gift-led — so you frame things correctly), the top recent anomalies (with a `driverSummary` naming what drove a drop, a `driversNote` when the move is broad-based, and an `investigate` next-call to run VERBATIM — it carries the anomaly's own window), and a 'what changed' digest over the last N days (anomalies, fixes closed, fixes now due, new store notes). Lead your first response with anything in brokenConnections, whatChanged, and _tip_actions. Cheap to call and debounced internally; safe to call first on any 'how are things?' / 'what should I look at?' / session-opening question.

Did THAT campaign actually work? Cross-source synthesis tool that measures the real impact of a specific Klaviyo campaign by comparing the post-send window against a DAY-OF-WEEK-ALIGNED baseline (same N days one week earlier). Returns: the campaign metadata, Klaviyo's own attribution claim, the actual Shopify orders/revenue/new-customers in the post-send window, the baseline counterfactual, the lift (window - baseline), and an `attributionAnalysis` reconciling Klaviyo's claim against measured lift. Use this for 'did the SUMMER20 campaign work?' / 'how did the May newsletter perform?' / 'is my abandoned-cart flow actually driving revenue?'. PREFER this over manually calling get_connector_data(connector:'klaviyo') + get_store_summary and trying to compute lift yourself — the day-of-week-aligned baseline is the right counterfactual and the attribution reconciliation explains the gap between Klaviyo's claim and reality. Pass either campaignId (exact Klaviyo internal ID) or campaignName (fuzzy match; returns the most recent match plus a disambiguation block if multiple found). Default windowDays is 7 — increase for high-consideration purchases with longer journeys.

Co-purchase / market-basket analysis. Given an anchor product (productTitle), returns other products frequently bought with it, ranked by lift. Reports: basket (same-order co-purchase — best for bundles, 'frequently bought together' widgets, post-checkout upsells), lifetime (same-customer across all their orders — best for email flows and longer-horizon recommendations; also returns avgDaysToCoBuy for sequencing). Each pair has support, confidence, lift (>3 strong, 1.5–3 moderate, <1.5 weak), and a verdict. Co-occurrences below `minCoOccurrences` are suppressed because lift is unstable on small samples.

Get product collections and their contents, including SEO metadata. Reports: list (all collections with product counts plus seoTitle/seoDescription), products (products in a specific collection with pricing, inventory, SEO, and optional sales data). seoTitle/seoDescription correspond to Shopify's global.title_tag and global.description_tag metafields. Use for 'how many products in the sandals collection?', 'what products are in collection X?', 'which collection products sell best?', or to inspect collection/product SEO tags.

Get a unified dashboard with key metrics from ALL connected data sources in one call. Returns a lean snapshot of revenue, traffic, marketing, email, organic search, UX, support, reviews, subscriptions, and loyalty — only for sources that are connected. Use this for 'Give me an overview' or 'How is the business doing?' then drill into specifics with individual tools. Note: in multi-store mode, the store param filters Shopify data (revenue, orders, products, customers) to that store. Non-Shopify sources (GA4, Klaviyo, Search Console, Gorgias, etc.) are account-level and always return aggregated data regardless of store param. In multi-store workspaces, get_store_comparison gives side-by-side Shopify metrics across all stores (that tool is only present for multi-store keys).

Get data from one connected third-party connector. Pass `connector` to pick which one and `report` to pick the report within it — valid `report` values differ per connector; this is the quick index, call get_help(<topic>) for the full picker + gotchas per connector. • connector:"triple-whale" — marketing attribution (channel mix, PPS, journey events). Reports: summary, attributions, by_channel, product_attribution, channel_by_model, journey, pps. NOTE: the `source` param below is Triple Whale's OWN acquisition-source filter (e.g. "google-ads") for journey/pps reports — unrelated to `connector`. Full report picker, attribution-model guide, known limits: get_help("triple_whale"). • connector:"klaviyo" — email marketing. Reports: campaign_summary, campaigns, top_campaigns, flow_summary, flows, top_flows, list_summary, lists, product_attribution, signup_trends, available_metrics. Detail: get_help("klaviyo"). • connector:"sendy" — self-hosted email (subscriber lists only — no campaign stats, no historical trend, current-state snapshot). Reports: list_summary, lists. Detail: get_help("sendy"). • connector:"gorgias" — customer support. Reports: summary, daily (tickets per day, for lining up with refunds/orders/campaigns), tickets, by_channel, satisfaction, top_tags. Detail: get_help("gorgias"). • connector:"recharge" — subscriptions. Reports: summary, metrics, cancellation_reasons, upcoming_charges, failed_charges. `days` on upcoming_charges is a FORWARD-LOOKING forecast window (default 30). Detail: get_help("recharge"). • connector:"google-search-console" — SEO. Reports: summary, top_queries, top_pages, trends, by_country, by_device, keyword_movers, new_keywords, page_ranking_changes, anomalies, zero_traffic, branded_split, cannibalization. Detail: get_help("search_console"). • connector:"clarity" — UX/session analytics. Reports: summary, ux_issues, by_dimension, trends. Detail: get_help("clarity"). • connector:"youtube" — channel/video analytics + transcripts. Reports: summary, videos, top_videos, video_details (needs videoId), search_transcripts (needs query). `days` on top_videos is a BACKWARD-LOOKING lookback window (default 7) — opposite sense from recharge's `days`. Detail: get_help("youtube"). • connector:"google-ads" — ad performance + live change log. Reports: summary, campaigns, daily, by_campaign_type, by_device, by_network, change_history, search_terms, ads, ad_groups, keywords, impression_share, campaign_settings, shopping_products, conversion_reconciliation. Detail: get_help("google_ads"). • connector:"xero" — accounting (P&L, cash, invoices, bills, expenses, monthly trend). Reports: financials, cash, invoices, bills, expenses, trend. Detail: get_help("xero"). • connector:"ringcentral" — call/message activity. Reports: summary, daily, calls, correlate, voicemails, voicemail_probe, by_agent, account. Detail: get_help("ringcentral"). • connector:"reviewsio" — Reviews.io-specific stats/NPS (distinct from the shared get_reviews aggregate over Yotpo/Reviews.io/Judge.me). Reports: stats, nps_trend, stats_trend, surveys, survey_responses, reply_stats, unanswered. Detail: get_help("reviewsio"). • connector:"smile" — Smile.io loyalty program. Reports: summary, points_activity, top_members, vip_tiers, redemption_patterns, engagement. Detail: get_help("smile"). • connector:"swish" — Swish wishlist analytics. Reports: summary, top_products, demand_trends, metrics. `days` on demand_trends is a BACKWARD-LOOKING lookback window (default 30). Detail: get_help("swish"). • connector:"woocommerce" — WooCommerce store data (alternative to Shopify). Reports: summary, top_products, orders, customers, low_stock. Detail: get_help("woocommerce"). • connector:"meta-ads" — Facebook/Instagram ad performance. Reports: summary, campaigns, daily. Detail: get_help("meta_ads"). • connector:"tiktok-ads" — TikTok ad performance. Reports: summary, campaigns, daily. Detail: get_help("tiktok_ads"). • connector:"shipstation" — shipping/fulfillment analytics. Reports: summary, carrier_breakdown, fulfillment_speed, daily. Detail: get_help("shipstation"). GOTCHA: `days` means OPPOSITE things depending on connector (forward-forecast for recharge, backward-lookback for youtube) — check get_help(connector) before assuming direction. `limit`/`startDate`/`endDate` meaning and defaults also vary slightly per connector (e.g. xero's dates target a specific snapshot period, not a rolling window; ringcentral defaults endDate to today, not yesterday) — see get_help(connector) for specifics.

Get customer behavior and retention insights. All reports are per-store in multi-store mode — use the store param to target a specific store. Reports: new_vs_returning (revenue/orders/AOV split by first-time vs repeat buyers), repeat_metrics (repeat purchase rate, avg days between purchases, BOTH avgLifetimeValue and medianLifetimeValue, lifetimeValueSkewRatio + distribution note — LEAD WITH MEDIAN when describing 'the typical customer', use mean only when distribution is symmetric; if `lifetimeValueDistributionNote` is present the mean is misleading), cohorts (monthly acquisition cohorts — counts and aggregate repeat rate), retention_curve (per-cohort cumulative retention % AND LTV at month 1/3/6/12 — the canonical e-commerce LTV view; cohorts that haven't matured to a milestone show null for that milestone, not a fake-low value), by_category (repeat rate by Shopify product_type — requires product_type to be set, returns 'Uncategorized' if not), cohorts_by_first_purchase (cohorts by first product category), top_customers (ranked by LTV or order count), lapsed_high_value (high-spending customers who haven't ordered recently — per-store, ideal for targeted win-back campaigns; rows carry a Shopify-admin adminUrl (this dataset holds no names/emails by design) and customer tags, trade-frequency accounts are flagged likelyWholesale so they're excluded from consumer win-backs, and customers inactive beyond maxDaysInactive (default 365d) are treated as churned and excluded).

Get customer analytics by dimension. Reports: segments (one-time/returning/VIP/at-risk), top (by spend or orders — includes customerId for each customer), by_country (geographic distribution — country is derived from order shipping address, not customer records; Shopify does not expose customer country without protected data access approval), customer_history (full order history with line items for a specific customer — use customerId from the 'top' report, or rank e.g. rank=1 for top customer, or tag to find by customer tag), tag_segments (size behavioural sub-segments by Shopify tag, signup year, marketing consent, and tag-overlap crosstab — BEST FOR: 'how many non-purchasers carry tag X?', 'break the newsletter list down by signup year', building differentiated nurture tracks. Defaults to the non-purchaser cohort; pass `tags` for the specific tags to count + cross-tabulate, `purchaserFilter` to change cohort). NOTE: For 'how many customers bought product X?' use get_orders(report: 'by_product') instead — it returns unique customer counts per product. This tool does NOT support product-level filtering.

Get daily/period numbers from one of three domains — pass `domain` to pick which, `report` to pick the report within it. `report:"daily"` exists in ALL THREE domains and means a DIFFERENT payload in each — always pass both `domain` and `report` together, never assume "daily" behaves the same across domains. • domain:"funnel" — the daily series WITH sessions/CVR/funnel steps. Reports: daily (default — { period, data, charts, presentation }, each day has revenue, sessions, visitors, cvr, aov, orders, addToCart, reachedCheckout; DEFAULT TO RENDERING THE RELEVANT CHART), traffic_breakdown (Shopify ShopifyQL traffic dimensions for the period — bySource, byDevice, topLandingPages, topReferrers; requires Shopify Plus/Advanced and traffic sync to have run). No default window — pass startDate/endDate explicitly (falls back to a 30-day window if omitted, but don't rely on that). • domain:"revenue" — REVENUE-centric (the only domain with by_channel/by_country/pnl_summary). Reports: daily (default — time-series of revenue + orders with chart specs and event context), by_channel (net sales + order count split by sales channel — requires Shopify Plus/Advanced), by_country (net sales by billing country — requires Shopify Plus/Advanced), pnl_summary (full P&L: gross/net sales, discounts, returns, shipping, taxes, payment processing fees, orders, items — requires Shopify Plus/Advanced; fee coverage can be partial, the response states it). All money values formatted currency strings. Defaults to a 30-day window ending yesterday. • domain:"operational" — the OPERATIONAL daily view (new vs returning customers, fulfillment rate, refunds, discount usage) from a pre-computed DailyStat rollup (updated by the scheduler, not a live query). Reports: daily (each day's revenue, orders, avgOrderValue, itemsSold, newCustomers, returningCustomers, discountUsageRate, fulfillmentRate, refunds), summary (period totals, daily averages, rates). Defaults to a 30-day window ending yesterday (report:"daily") or its own real aggregated window (report:"summary"). Use "funnel" for sessions/CVR/traffic questions, "revenue" for channel/country/P&L breakdowns, "operational" for dashboard KPI tracking.

CALL THIS FIRST to see which data sources are connected and have data. Returns connection status and record counts for: Shopify (always connected), Triple Whale, Klaviyo, Gorgias, Recharge, Google Search Console, Google Analytics, Microsoft Clarity, and YouTube. Use this to understand what data is available before making other queries. If a source shows 'not_connected', those tools will return empty results.

Get discount code analytics. Reports: summary (usage rate, AOV impact), top_codes (best performing codes by revenue/usage), code_details (specific code performance — requires 'code' param), by_product (which discount codes were applied to which products — optionally filter by 'code').

Return the merchant's current weekly plan — the committed 'what to work on now' list. Use as a session opener. The plan stays current until the merchant re-plans (say 'plan my week' / refresh: true) — it does NOT auto-expire, so re-asks return the same plan with each item's LIVE state (a 'tackle' item shows done once its finding is addressed; a 'check' item once its intervention closes). If no plan exists or refresh is requested, returns a synthesis bundle — open findings, interventions due for check-in, the outcomes summary, metric trends, AND the previous plan's unfinished items to carry forward — plus an _instruction to call save_focus blending tackle/check/watch items.

Forecast a metric — answers 'what should I expect?' / 'are we on track this month?' / 'project next month'. Returns a per-store `stores` array (each in its OWN currency — never summed across currencies). Each store has: `currentMonth` (month-to-date actual + projected month-end with low/high band, built from the live daily run-rate), `horizon` (future full months with expected/low/high), `method`, `confidence`, explicit `assumptions`, `historyMonths`, and a ready-to-render `charts[0]` line spec (seriesField='series' splits actual vs forecast). HONESTY: every forecast carries a method (month_to_date_pace / linear_trend / naive_last_month / yoy_seasonal), a confidence level, and an interval — LEAD with the range and the confidence, never present the point estimate as a promise. Current-month projection works immediately from orders; forward months need calendar-month snapshot history and degrade gracefully (low confidence / declines to project when too thin). v1 metrics: revenue, orders.

Discovery tool: list the GA4 property's custom dimensions and custom metrics (with apiName, uiName, description), plus the standard dimension/metric API names available on the property. Call this to find valid field names before building a get_ga4_funnel report or interpreting custom events. LIVE GA4 Admin/Data API call.

Run a real GA4 funnel report — step-by-step conversion through a sequence of events, with optional breakdown and next-action analysis. This is a LIVE call to the GA4 Data API (not synced data), so it can answer 'where do users drop off between viewing a product and purchasing?' with GA4's own funnel engine. Each step is an event name (e.g. page_view, add_to_cart, begin_checkout, purchase) or a full GA4 FilterExpression. Returns funnelTable (completions + completion rate per step), funnelVisualization, and propertyQuota. For the CANONICAL checkout funnel and CVR use get_marketing_performance / get_metrics_comparison instead — this tool is for GA4-event-level funnel shape and custom event sequences.

Fetch the full guidance behind the server instructions, on demand. The eager instructions summarise each area in one or two lines and point here for detail — call this only when you actually need the depth (you usually won't). Topics: routing (the canonical source-of-truth map — which tool owns each metric), signals (how to read _freshness / _confidence / _anomalies / _benchmark / _dataDepth / _recentDayCaveat / _alerts / _storeNotes), conventions (money / dates / timezone / abbreviations), claims (handling numbers the user quotes), analysis (median-vs-mean, hypotheses-not-causation, partial-day, pushback discipline), multistore (per-store vs account-level data, and the propertyId/customerId/siteUrl requirement), writeback (interventions / insights / snapshots / wakeups), triple_whale (Total Impact). You can ALSO pass a METRIC NAME (ltv, order_counts, aov, cvr, cac, repeat_rate, roas, mer, nps, csat, refund_rate — synonyms accepted) for its definition + canonical tool + gotcha, or a TOOL NAME (e.g. "get_analytics", "query_orders") for that tool's worked examples. Omit topic to list the topics, metrics, and tools that have examples.

Get the business improvement checklist (the FINDINGS to act on). If insights exist, returns the current checklist with status. If no insights exist (or refresh is requested), returns a data bundle with all key metrics from connected sources — use this data to generate actionable business recommendations (typically 3–8, as many as the data supports), then call save_insights to store them. You can also call save_insights with a single insight at any time during conversation. Use report: 'thread' (with threadId or insightId) to retrieve a linked sequence of related findings as one story. NOTE: 'did the fix work' / win-rate / outcomes are NOT here — insights are observations. Once a fix ships, set_intervention flips the finding to 'addressed' and the outcome lives on the intervention; call get_interventions(report: 'outcomes') for that. Filter by category, tags, or threadId to narrow the list. Each returned item includes threadId, parentInsightId, and a threadCount so you can spot follow-up chains without an extra call.

List interventions (the actions/fixes that were shipped) and report their measured outcomes. This is the SINGLE source of truth for 'did it work' — insights (findings) never carry a verdict. Use report: 'status' for a one-call picture of 'what fix-work is open' (due for check-in / in flight / recently closed + win rate — best for 'where did we get to?' / session start); report: 'list' (default) for the full rows; report: 'outcomes' for 'fixes that worked vs didn't' (buckets closed interventions by verdict + win rate). Filter by insightId to answer 'how did the fix(es) for this finding turn out?'. Each intervention includes baseline + post snapshots and computed deltas (when closed).

Get inventory analytics. Reports: summary (activeProducts count, totalVariants, outOfStock variant count, lowStock variant count with >0 and ≤10 units, totalUnits, active locations count), low_stock (products needing reorder — threshold defaults to 10 units), out_of_stock (zero-inventory variants), by_location (per-warehouse breakdown with location name, total SKUs tracked, units on hand).

Get marketing performance dashboard — INCLUDING the canonical checkout funnel. ALSO USE THIS for 'checkout funnel' / 'where do customers drop off' / 'how is my funnel performing' questions; do NOT manually stitch a funnel from get_analytics + get_store_summary. Returns: `funnel` (sessions, addToCartRate, checkoutRate, purchaseRate, cvr — sessions sourced from Shopify TrafficStat when available, GA4 fallback otherwise, pixel as last resort), `_pixelFunnel` (Triple Whale pixel-tracked equivalents with step-by-step ratios for drop-off SHAPE analysis), `channels` (revenue/sessions/cvr per channel like Google, Facebook, Email, Direct), ROAS and MER from Triple Whale, and `dailyTrends` per channel. IMPORTANT SOURCE HIERARCHY for `funnel.cvr`: (1) Shopify TrafficStat sessions + Shopify orders (Plus/Advanced — canonical), (2) GA4 sessions + Shopify orders (fallback when TrafficStat empty — slightly inflated due to GA4 pixel undercount), (3) Triple Whale pixel as last resort with explicit `_warning`. Inspect `funnel.source` and `funnel._sourceNote` before quoting CVR. `_pixelFunnel` is for FUNNEL SHAPE analysis only — compare addToCartRate vs checkoutRate vs purchaseRate to find drop-off points. Pixel absolute counts undercount real activity; never report `_pixelFunnel.cvr` as the store's conversion rate. Channels uses Triple Whale attribution when connected. Use for marketing ROI, channel comparison, and funnel-shape diagnosis — but for the actual CVR figure use get_metrics_comparison.

Get Shopify Markets data — geographic market definitions and per-market revenue performance. Reports: markets (list of configured markets with their assigned countries and currencies), performance (revenue, orders, AOV, and revenue share broken down by market for a date range). Use this to understand which geographic markets are configured and how revenue is distributed across them. Note: market data requires the market sync to have run at least once; orders are attributed to markets using Shopify's market field (Plus merchants) or a country-code fallback (all merchants).

BEST FOR COMPARISONS AND THE CANONICAL CONVERSION RATE: Get core e-commerce metrics (Revenue, Sessions, CVR, AOV, Revenue per Session) with period-over-period comparisons. CVR here uses Shopify TrafficStat sessions (Plus/Advanced) — or GA4 sessions as fallback — divided by REAL Shopify orders. This is the right source for 'what's my conversion rate?' / 'how's my CVR trending?' questions. Do NOT use Triple Whale pixel CVR (from get_connector_data(connector:'triple-whale') or get_marketing_performance._pixelFunnel) as a stand-in: pixel undercounts purchases and sessions and produces misleading absolute numbers. Supports WoW (week-over-week), MoM (month-over-month), YoY (year-over-year), and custom period comparisons. Returns { period, metrics, comparison, charts, presentation }. `charts` is an array of grouped-bar specs (one per headline metric, current vs comparison) ready to drop into any plotting library. DEFAULT TO RENDERING THE RELEVANT CHART when the user is comparing periods or asks 'how is X vs Y' — bar charts are the natural fit. Use `comparison.changes` for the % delta caption. Use raw numbers from `metrics` only when the user asks for a single specific value.

Get metrics with MULTIPLE comparisons at once. Perfect for questions like 'Show me revenue WoW and YoY' or 'Compare this week to last week and same week last year'. Returns { period, metrics, comparisons, charts, presentation }. `charts` is an array of grouped-bar specs (one per headline metric) with 3+ bars each (current + each comparison period). DEFAULT TO RENDERING THE RELEVANT CHART for multi-period questions — bars side-by-side communicate the deltas instantly. Pull each comparison's % change from its `changes` object for captions.

Look up a specific order with full line item details (product, variant, SKU, quantity, price, vendor). Use orderName for user-facing IDs like '#1001', or orderId for Shopify numeric IDs. Also supports orderIds (array) to look up multiple orders at once — useful for cross-referencing with Triple Whale attribution data.

Get order analytics by dimension. Reports: by_status (order counts/revenue by financial status), by_country (geographic sales breakdown — supports compare for WoW/MoM/YoY trend, returns top rising/falling countries), by_product (BEST FOR: 'how many customers bought product X?', 'which products have the most unique buyers?', product-level customer counts. Returns uniqueCustomers, orderCount, unitsSold, and revenue per product. Use this whenever the question involves customers AND products together), by_tag (order volume per Shopify order tag with SUDDEN-DROP DETECTION — compares the last 7 days vs the prior weeks and flags tags whose order count fell significantly. BEST FOR: 'did orders with tag X drop?', 'has any marketplace/dropship channel stopped?'. Pass `tag` to focus one tag, or omit to scan all tags; returns a `drops` list plus per-tag current/baseline/change).

Get Shopify product sales analytics — units sold and revenue per product from ShopifyQL. Requires Shopify Plus or Advanced. NOTE: Views, add-to-cart, and purchase funnel counts are no longer available from ShopifyQL (Shopify removed these fields) — use get_marketing_performance for funnel analysis or get_analytics(ecommerce) for GA4-based product funnel data. Reports: summary (total units/revenue), top_products (ranked by revenue or units sold), product_detail (daily units/revenue for a specific product).

Get product catalog with inventory levels, pricing, cost, margins, status, and SEO metadata. Returns: title, vendor, productType, price, cost, margin, marginPercent, totalInventory, seoTitle (Shopify global.title_tag), seoDescription (Shopify global.description_tag), productUrl (full storefront URL — use this directly instead of guessing). Use for questions about products, pricing, profitability, cost price, stock levels, or SEO/meta tags.

CROSS-SOURCE PRODUCT HEALTH SCAN — one call that returns per-product reviews + refunds + sales velocity + inventory + a composite 'needs attention' score (0-100). Use this for 'which products need fixing?' / 'what should I look at?' / 'are there any product issues?' / 'which products are performing badly?'. Saves the LLM from stitching get_top_products + get_refunds + get_reviews + get_inventory manually — synthesis is consistent and the composite score is grounded in the same heuristic each time. Returns each product's underlying signals (refund rate, review rating, review count, stock level, units sold, days since last sale) plus a `flags` array explaining WHY the score is what it is. Sort is by attentionScore descending so the most concerning products come first. Filter with `minAttentionScore` (default 0, set to 30 to see only flagged products). Default analyses the top 50 products by sales over the last 30 days.

Get products with marketing channel attribution showing which channels drive sales for each product. Attribution uses Triple Whale last-click data joined to Shopify order line items — requires Triple Whale to be connected. When Triple Whale is not connected, all orders appear under 'unattributed'. Use for questions like 'Which channels drive sales of product X?' or 'What products does Facebook sell?'

Join Google Search Console queries with Shopify product sales — answers questions that pure SEO or pure sales tools can't. Reports: by_url (given a product URL, return its top driving organic queries plus the matching product's sales/orders/refunds and an implied click-to-purchase rate), unconverting_pages (URLs that received >= minClicks organic clicks but the matching product sold <= maxSales units in the same window — flags 'SEO-visible-but-not-converting' listings), top_pages_with_sales (top organic pages joined with their product sales, ranked by clicks × orderCount so high-throughput pages surface). For unconverting_pages and top_pages_with_sales, only product URLs (matching /products/{handle}) are joined to sales — collection pages and blog posts are not.

Get refund/return analytics. Reports: summary (total refunds, refund rate, % of revenue — supports compare for WoW/MoM/YoY trend), top_products (most refunded products by amount or rate), by_reason (classifies refund notes into buckets: size_fit_too_small, size_fit_too_large, quality_defect, wrong_item, shipping_late_or_lost, color_style_mismatch, comfort, changed_mind, duplicate, out_of_stock — with top affected products and sample verbatim notes per bucket. The out_of_stock bucket is a fulfilment/overselling signal, not a customer preference. Best for diagnosing high refund rates).

Diagnostic tool for 'why did revenue change?' questions. Bundles headline metric deltas, product mix shifts, and pre-generated ranked hypotheses into one call — so you don't have to stitch signals together yourself and risk asserting causation. Each hypothesis includes: what signal supports it, what else would be true if it's correct, and which tool to call next to confirm or rule it out. Use when the merchant asks why revenue went up or down, what's driving performance, or what changed.

Get product review analytics (Yotpo, Reviews.io, or Judge.me). Reports: summary (average rating, distribution), trends (daily volume/score), top_rated (best reviewed products), lowest_rated (worst reviewed), recent (latest reviews), by_product (all reviews for a specific product — requires productId or productTitle), search (keyword search in reviews), timing (days from purchase to review), sales_impact (reviewed vs unreviewed product sales), themes (BEST FOR 'what do customers complain about?' — aggregates review text into themes like sizing/comfort/quality/shipping with complaint counts, negative share, and sample 1-2★ quotes; pass productId/productTitle to drill into one product). Prefer themes over paging raw review text.

Reconcile ad-spend numbers between Triple Whale's pixel attribution and the ad-platform APIs (Google Ads, Meta, TikTok). Same channel, different numbers — pixel typically captures 10-30% of true spend due to ad blockers, consent banners, and iOS ATT. Returns per-channel platform-API spend, TW pixel spend, ratio, severity (match / moderate / severe / critical), trueRoas (TW revenue / platform spend), pixelRoas (from TW), and a recommendation per channel. Use whenever quoting ROAS — pixel ROAS in isolation is reliably wrong on paid channels with bad pixel coverage.

Return all merchant-attached LLM context notes for a store (or all stores if omitted). Notes are authoritative caveats the merchant has added — e.g. 'one B2B customer skews retention', 'Q2 budget freeze, don't suggest more ad spend', 'pre-2026-03 data is partial'. The same notes are auto-injected into every store-scoped tool response as _storeNotes, so calling this directly is only needed when you want a full picture before answering a session-opening question.

Return what the system understands about a store's IDENTITY — primaryCategory, priceTier, audience, positioning, giftLed (is it typically bought as a gift for others?), the revenue-weighted category mix, and price range. System-generated from the catalog + sales (refreshed ~monthly), with any merchant corrections applied on top. Use as a session opener to orient yourself before answering, or when the user asks 'what do you know about my store?'. Treat `_merchantCorrected` fields as authoritative. If the profile is wrong, call update_store_profile. Omit `store` to get every store in the workspace.

Get overall store metrics from Shopify order data ONLY: revenue, orders, average order value, items sold, discounts, unique customers — all for the specified period. Includes percentage changes vs prior period. Also returns all-time totals (orders, products, customers). Use this for high-level store performance questions. For an overview spanning ALL connected sources (traffic, email, support, reviews, etc.) use get_complete_dashboard instead.

Report the health of every connected data source for each of your stores (works for a single store too). For each provider/instance: last successful sync timestamp, record count, freshness flag (stale if > 36h), and key-field nullability rates (e.g. % of customers without firstOrderAt populated). Use this to diagnose 'why is metric X showing 0?' or to confirm data is current before reporting numbers.

List the merchant's active targets with LIVE actual-vs-target pacing, recomputed from ground truth on every call (never stored). Each target returns a `pacing` block: status (ahead / on_track / at_risk / behind / too_early / not_paceable), actualToDate, projected month-end with its interval, progressPercent, gapToTarget, currentDailyPace vs requiredDailyRunRate, and days elapsed/remaining. Live month-pacing is available for monthly revenue/orders targets scoped to a store; other targets return the goal and defer to get_yoy_monthly / query_metric_snapshots. HONESTY: the status band is derived from the forecast's low/high interval — 'behind' means behind the optimistic end — and below 25% of the period elapsed it returns 'too_early' rather than a noisy verdict. Filter with metric / period / store.

Merged, date-ordered timeline of everything that happened to the business: interventions (changes the merchant applied, and when their verdict landed) plus store-context notes (campaign launches, migrations, budget freezes, data quirks the merchant recorded). Use this to line dated events up against a metric movement — 'revenue dipped on the 12th, what changed around then?' — instead of calling get_interventions and get_store_notes separately and stitching them yourself. Returns events sorted most-recent-first, each with a date, kind, store, and detail. Includes expired/closed items within the window so historical context isn't lost.

Get top selling products ranked by revenue or quantity. Set level to 'variant' to break down by variant (size, colour, etc.) — includes SKU, discount, and profit margin when cost data is available. Set level to 'category' for a revenue / COGS / gross-profit / margin-% rollup by product TYPE (e.g. 'Sewing Machines vs Fabric') — the structured answer to category-P&L / margin-by-category questions (margin is computed only over cost-configured units, with a costCoveragePercent per category). Optionally filter variants by productTitle. Supports compare for WoW/MoM/YoY trend — returns top 5 rising/falling/new products with the comparison.

Get sales-velocity analytics from one of two angles — pass `angle` to pick which, `report` to pick the report within it. • angle:"inventory" — the INVENTORY-management angle: how fast stock is moving and what to reorder. Reports: summary (sell-through rate, turnover, health status), by_product (products sorted by sales velocity), restock (reorder quantity recommendations from velocity, lead time, and safety stock — pass leadTimeDays/safetyStockDays; the reason to pick this angle). Use when the question is "what should I reorder and how much?". • angle:"product" — the PRODUCT angle: how individual products are selling over time. Reports: summary (totalUnitsSold, revenue, productsTracked, inventoryHealth counts), by_product (per-product velocity, stock, reorder urgency), trend (daily time series for one product — requires productId), stagnant (active products with zero or near-zero sales — dead stock/zombie listings; pass maxOrders to widen from zero-sales to near-zero). Use for a single product's trend or stagnant/dead-stock questions. Both angles share `report:"summary"`/`"by_product"` (different content per angle) and the `sortBy`/`filter` params on by_product. `days` defaults to 30 in both angles (note: angle:"product", report:"summary" ignores `days` entirely — it's always a fixed trailing-30-day aggregate).

Retrieve a single wakeup by ID. Use this inside a Claude routine prompt: the routine fires, calls `get_wakeup({ id: 'abc-123' })`, gets the full context and benchmarks, then runs the analysis. Also auto-marks the wakeup as triggered if the trigger date has passed.

Retrieve scheduled wakeups for a store. Call at the start of sessions where the merchant might have pending wakeups due — especially if today's date is at or past a previously scheduled triggerDate. Returns both pending (not yet fired) and recently triggered (fired in the last 14 days, waiting for analysis). When triggered wakeups are present, LEAD with them: 'I have a scheduled check that fired today — [name]. Here's what I was tracking...' then run the analysis comparing current data against the saved benchmarks.

Get weekly revenue, orders, and items sold as a time series. Data is aggregated live from the Shopify Order table. Returns { rows, charts, presentation }. `rows` is the table — each row: weekOf, revenue (formatted), orders, itemsSold. `charts` is an array of three ready-to-render chart specs (revenue, orders, items — separate charts because units differ) in long/tidy format with metadata. DEFAULT TO RENDERING THE CHART when the user asks about trends, weekly patterns, seasonality, or uses 'show me' / 'how is' / 'pattern' phrasing. Fall back to numbers from `rows` only when the user asks for a single specific week.

Month-by-month year-over-year comparison for a single metric. SINGLE-CALL ANSWER for 'how is revenue this year vs last year by month?' / 'show me 2026 vs 2025 monthly trends'. Returns { metric, currentYear, compareYear, rows, totals, charts, presentation, seeAlso }. `rows` is one entry per month with current/compare/change. `charts[0]` is a ready-to-render grouped-bar spec (seriesField='year') — drop straight into a chart library. `totals` gives the year-to-date sum + YoY %. Reads pre-aggregated calendar-month snapshots so it's clean and quick. DEFAULT TO RENDERING THE CHART for any 'X this year vs last year by month' question.

Query recorded metric snapshots as a time series. Use to answer 'show me all CVR snapshots for UK over the last 6 months', 'how has ROAS evolved by month?', etc. Returns canonical snapshot data (matches the dashboard and monthly digest exactly) plus a `charts` array of ready-to-render line chart specs (one per metric; multi-series when the query spans multiple stores or segments). DEFAULT TO RENDERING THE CHART when the LLM is asked to show a metric over time — these are the SAME numbers the merchant sees on /dashboard/metrics. Call with no args (or just `list: true`) to get the full registry of canonical metric keys.

List individual orders matching filters: date range, financial status, customerId, min/max order total, order tags — sortable by date or total. Returns one row per order with name, status, fulfillment, orderTotal (formatted), items count, country, tags, and date. Use for 'show me recent orders', 'orders over $500', 'this customer's pending orders', 'orders tagged wholesale'. DISAMBIGUATION: for AGGREGATE order analytics (counts/revenue by status, country, or product) use get_orders; to look up ONE known order by its #name or ID with line items, use get_order.

Record one or more structured metric snapshots for time-series analysis. Use this whenever you cite a metric in an insight, weekly digest, or benchmark — instead of (or in addition to) burying it in prose. Each snapshot is queryable later via query_metric_snapshots, e.g. 'show CVR for UK over the last 6 months'. Always pass canonical metric keys from the registry (call query_metric_snapshots with no args to list them, or see the error hint when you pass an unknown key). Provide both a current value and, ideally, a baseline value so trajectories can be plotted. When a snapshot was produced by a specific tool call, include sourceParams (the tool name + the exact args you used) so the value can be reproduced later without guesswork. IDEMPOTENCY: re-recording the same logical measurement does NOT append a duplicate. The identity tuple is (metric, periodStart, periodEnd, store, segment, source, periodKind, periodLength) — periodKind and periodLength are part of the identity so 'April 2026 calendar+month' and 'rolling+month' don't collide. The existing row is updated: latest value wins, and metadata fields (sourceParams, baseline, confidence, confidenceReason, notes) merge — newer non-empty replaces, missing preserves the prior. INSIGHT LINKAGE is many-to-many and PURELY ADDITIVE here — both insightId (single) and insightIds (array) UNION with any existing links and never remove. The same snapshot can serve as evidence for parent + child + 30-day-check simultaneously. To remove a link, use update_insight(insightId, unlinkSnapshotIds: [...]).

USER-TRIGGERED issue reporting — call when the user expresses doubt about a specific data point or value ('this number is wrong', 'doesn't match my Shopify admin', 'why is this zero?', 'something's off here'). Capture their concern as a structured report BEFORE speculating about causes. After saving, briefly acknowledge ('I've logged that for the team to review') and then offer to help debug if relevant.

AUTONOMOUS bug reporting — call WITHOUT asking when you spot a STRUCTURAL or FORMAT issue in another tool's response. ONLY for issues you can identify mechanically (precision, types, schema). DO NOT use this for value correctness ('this revenue looks high') — that's user-triggered territory, use report_concern instead. Examples that DO qualify: a numeric field with 15 decimal places, _currency says EUR but values look like USD, response field is null where the description implies a value, the shape doesn't match the tool description. The platform dedupes by (toolName, category, description), so reporting the same issue across many tool calls is fine — counter increments, no spam. After reporting, continue answering the user's original question normally; do not mention the report.

Retire a store note that is OUT OF DATE or WRONG, so it stops reaching every AI session on this workspace (yours and teammates'). Retiring is reversible: the note is kept with who/when/why and the merchant can restore it from the dashboard. ONLY call this when the user says a note is no longer true or wrong, or when they agree to replace several notes with one consolidated note you've just saved. NEVER retire a note on your own judgement, and never because it seems irrelevant to the current question — it may matter to a teammate's work. Confirm to the user what you retired.

Persist the week's committed plan generated from the get_focus data bundle. The plan blends THREE streams: 'tackle' (new open findings to act on, link insightId), 'check' (interventions due for their verdict, link interventionId), and 'watch' (a metric/anomaly to keep an eye on, set metric). Each item needs title, rationale (why now, citing data), action, expectedImpact, effort, priority. Item completion is DERIVED — a 'tackle' is done when its finding becomes addressed, a 'check' when its intervention closes — so always link insightId/interventionId when the item maps to one. Carry forward any unfinished items from the previous plan (get_focus returns them with their live state). The plan stays current until the merchant re-plans ('plan my week') — calling save_focus supersedes the previous plan by default.

TRIGGER: Whenever you surface a problem or opportunity from the data, OFFER to save it as an insight and confirm before writing — don't auto-save. Make the offer concrete and inline: 'Want me to save this as an insight to track?'. Findings vary in significance; the user decides what belongs on the checklist. Insights are OBSERVATIONS (findings to act on) — when a fix is actually SHIPPED, that's a separate thing: call set_intervention (it auto-flips the linked insight to 'addressed' and owns the before/after verdict). Don't model 'fix applied' or '30-day check' as insights. Call this AFTER generating recommendations from get_insights data, OR mid-conversation when the user confirms. Can save any number of insights. To replace the existing checklist (instead of appending), set replace: true. To update a single existing insight, use update_insight with the insight's id instead. parentInsightId/threadId group related FINDINGS as one story (finding → re-finding → superseded). RESPONSE: returns `insights: [{insightId, title, category, priority, status, threadId, parentInsightId}]` in the same order as the input — use those insightIds directly in subsequent record_metric_snapshot / set_intervention(linkedInsightIds) / update_insight calls (no round-trip through get_insights needed).

Save a store-context note that future sessions — the user's AND their teammates' — should know. Notes are the workspace's SHARED memory: teammates' AI sessions read the same data but never see this chat, so anything not saved here stays with this one conversation. Call it when (1) the user reveals business context the data alone wouldn't show (e.g. 'one B2B customer is a reseller', 'Q2 budget is fixed', 'migrated platforms in March'); (2) the user AGREES a reporting definition or rule with you during analysis (e.g. 'turnover = Shopify Total sales after discounts and returns, incl. VAT and delivery', 'units exclude orders discounted 75%+ — those are exchanges/samples') — category reporting_convention; (3) the user CORRECTS how you read a number (e.g. 'DE per-unit value is down because slow lines are discounted on Avocado'). Use store:'all' when it applies to every store. Confirm once saved: 'I've noted that for future sessions and for anyone else on the workspace'. Notes are flagged AI-suggested so the merchant can review/delete them. Do NOT save your OWN conclusions or verdicts ('ads are performing well', 'CVR is healthy') — they go stale and mislead teammates; conclusions are recomputed from data. No speculation, transient session state, or things already obvious from the data.

Store a merchant's GOAL for a metric over a calendar period ('we need £80k this month'). TRIGGER: whenever the user states a target/goal/budget for a metric. This saves the merchant's own target in our DB (NOT a write-back to any connected tool). Pacing (are we on track?) is computed later on read by get_targets — never stored. Money metrics (revenue, aov, ltv, …) MUST be scoped to one store via `store` because the workspace can run multiple currencies; pass targetValue in MAJOR units (80000 for £80k). Non-money metrics (orders, cvr, refund_rate, …) may be workspace-wide (omit store). Setting a target for a slot that already has one supersedes the old target (history is kept). After saving, tell the user in one line what you logged.

Create or update a scheduled wakeup. **Create mode** (no `id`): schedule a future analysis with context and a metric snapshot. Call when the merchant asks to check back later, OR proactively before a retail event or trend worth monitoring. At save time pull the relevant metrics and write `context` as instructions for your future self. Returns `{ id }` — save that id to link the Claude routine. **Update mode** (with `id`): patch an existing wakeup — use this to link a Claude routine ID after creating it: `save_wakeup({ id: 'abc', routineId: 'trig_...' })`. The two systems work together: your wakeup holds the benchmarks and context; the Claude routine fires the session; the routine prompt includes the wakeup id so it calls `get_wakeup(id)` to retrieve everything it needs.

TRIGGER: Call WITHOUT asking whenever the user applies or ships a fix. 'Fix' covers any shipped change — SEO/copy/ads/UX/ops, AND code/schema/connector changes. Distinct from save_insights (which captures observations) — this is for tracking actions: 'I changed X, hypothesised Y, will measure at dates [a,b,c]'. Auto-captures the most recent matching snapshots as baseline (for each {store, metric} in trackedMetrics), so you don't have to manually record baselines first. Use complete_intervention later to capture the post-fix snapshots and compute deltas. INPUT-MINIMAL EXAMPLE: set_intervention({store: 'acme-store-us', type: 'technical_seo', description: 'Applied hreflang fix to product pages', trackedMetrics: ['organic_clicks', 'organic_ctr'], checkDates: ['2026-06-07','2026-07-07','2026-08-07']}). For code/connector fixes use type: 'connector_fix' or similar. Pass linkedInsightIds when this intervention closes the loop on existing insights. After saving, tell the user in one line what you logged.

Set the manual state of a single item in the current focus plan: 'in_progress' (started), 'dropped' (decided not to do it this week), or 'planned' (clear the overlay). NOTE: you can NOT set an item to 'done' here — completion is DERIVED from the linked finding becoming addressed or the intervention closing. To complete a 'tackle' item, ship the fix and call set_intervention (which addresses the finding); to complete a 'check' item, call complete_intervention. Get itemIds from get_focus.

Update an insight (a FINDING) — set its status, or edit its content. Allowed status: open / addressed / superseded / dismissed. Note: you normally don't set 'addressed' by hand — that happens automatically when set_intervention links this finding to a shipped fix. An insight carries NO fix verdict; 'did it work' lives on the linked intervention (see get_interventions). Use this to dismiss/supersede a finding, edit its text/tags, or attach evidence snapshots.

TRIGGER: Call WITHOUT asking when an existing intervention's details need correcting — a check date that should move, a note to add, a hypothesis to sharpen, or a threshold watch to attach. Interventions could previously only be created and closed, so a wrong check date stayed wrong and surfaced as due on the wrong day; closing and re-creating is NOT a workaround, because it discards the captured baseline snapshots and the applied date. NOTES APPEND by default with a date stamp, since corrections accumulate — pass notesMode:'replace' only to deliberately overwrite. Verdict and status are not editable here: closing goes through complete_intervention so post-fix snapshots and deltas are captured with it. EXAMPLE: update_intervention({interventionId: '63f81dc3-...', removeCheckDates: ['2026-09-22'], addCheckDates: ['2026-09-25'], notes: 'Moved the check to the 25th — the 22nd fell before the campaign had 14 days of runtime.'}).

Correct a store's profile when the USER tells you it's wrong (e.g. 'we're actually a premium brand', 'people DO buy our products as gifts at Christmas', 'we're skincare not cosmetics'). Corrections are authoritative: they override the system's guess immediately AND survive the monthly auto-regeneration. ONLY call this from something the user stated about their own store — never from your own inference. `giftLed` especially matters: it controls whether retail gift-holidays are treated as relevant for this store. Confirm to the user once saved.