Ask AI MCP — MCP Radar

ask_moby

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.

Esquema de entrada

{'type': 'object', 'required': ['question'], 'properties': {'store': {'type': 'string', 'description': "For multi-store accounts: which store's TW instance to ask (matches the instance's store assignment). Omit for single-instance accounts."}, 'question': {'type': 'string', 'description': "The question, in natural language, as you would ask Triple Whale's UI assistant. Include the time window explicitly (e.g. 'in the last 30 days')."}}}

complete_intervention

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. It does NOT capture live from source — 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'.

Esquema de entrada

{'type': 'object', 'required': ['interventionId', 'verdict'], 'properties': {'force': {'type': 'boolean', 'description': "Close even when no post-fix snapshot exists for any tracked metric (verdict then rests on your external evidence, with no computed delta). Default false — without it, a measured verdict is refused so you don't get a closed intervention with zero measurement attached."}, 'notes': {'type': 'string', 'description': "Optional note about what was observed, e.g. 'US clicks recovered but DE flatlined — partial win'."}, 'verdict': {'enum': ['lift_confirmed', 'lift_inconclusive', 'regressed', 'partial', 'abandoned'], 'type': 'string', 'description': 'Your verdict. The system also computes per-metric outcomes — your verdict is the overall judgment.'}, 'interventionId': {'type': 'string', 'description': 'The intervention to close.'}}}

get_abandoned_checkouts

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.

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'limit': {'type': 'integer', 'description': 'For top_products: number of products (default: 10)'}, 'report': {'enum': ['stats', 'top_products'], 'type': 'string', 'description': 'Report type'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}}}

get_analytics

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.

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'limit': {'type': 'integer', 'description': 'For by_country, top_products, and by_campaign: number of results (default: 20; by_campaign default 50)'}, 'medium': {'type': 'string', 'description': "For by_campaign: filter to a UTM medium, e.g. 'email' to isolate the email program. Omit to include all tagged campaigns."}, 'report': {'enum': ['summary', 'trend', 'by_channel', 'by_source', 'by_device', 'by_country', 'ecommerce', 'top_products', 'top_pages', 'by_campaign'], 'type': 'string', 'description': "Report type. Use 'by_source' for AI / ChatGPT / Perplexity / Claude / referrer-level traffic questions and 'what changed in my traffic sources'. Use 'top_pages' for most-visited pages or landing page conversion questions. Use 'by_campaign' (with medium:'email') to rank email/UTM campaigns by revenue."}, 'sortBy': {'enum': ['revenue', 'units', 'sessions', 'orders'], 'type': 'string', 'description': 'For top_products: revenue or units. For by_campaign: revenue (default), sessions, or orders.'}, 'compare': {'type': 'boolean', 'description': 'For by_source: attach the prior-window comparison (per-source deltas, newSources, disappearedSources, spam-referrer flag). Defaults to true; pass false to skip.'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Overrides periodType. Defaults to a 30-day window ending yesterday.'}, 'periodType': {'enum': ['last7days', 'last30days', 'last90days', 'last365days'], 'type': 'string', 'description': 'Shorthand time window (default: last30days). Expanded to startDate/endDate automatically. Ignored if startDate is provided explicitly.'}, 'propertyId': {'type': 'string', 'description': "Filter to a specific GA4 property. Works on ALL reports. Use the exact propertyId from the summary response (e.g. 'properties/375762433'). Omit to get aggregated data across all properties. Always use this when the user asks about a specific store's traffic."}}}

get_anomalies

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?'.

Esquema de entrada

{'type': 'object', 'properties': {'lookbackWeeks': {'type': 'integer', 'description': 'How many prior weeks to use as baseline (default 4).'}}}

get_briefing

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.

Esquema de entrada

{'type': 'object', 'properties': {'sinceDays': {'type': 'integer', 'description': "Window for the 'what changed' digest (default 7, max 90). A true 'since your last visit' view is coming; for now this is a rolling window."}}}

get_campaign_impact

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.

Esquema de entrada

{'type': 'object', 'properties': {'store': {'type': 'string', 'description': 'Filter to a specific store domain. Omit to query all connected stores.'}, 'campaignId': {'type': 'string', 'description': 'Klaviyo internal campaign ID (exact match). Use this when you already know it; otherwise use campaignName.'}, 'windowDays': {'type': 'integer', 'description': "Post-send measurement window in days (default 7). Klaviyo's attribution uses 5 days for campaigns; 7 captures the bulk of impact for most consumer goods. Increase for high-AOV considered purchases (machines, furniture) where buying journeys extend over weeks."}, 'campaignName': {'type': 'string', 'description': 'Fuzzy match on campaign name (case-insensitive substring). Returns the most recent match; surfaces a disambiguation block if multiple found.'}}}

get_cart_affinity

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.

Esquema de entrada

{'type': 'object', 'required': ['report', 'productTitle'], 'properties': {'limit': {'type': 'integer', 'description': 'Number of co-products to return (default: 10, max: 25).'}, 'report': {'enum': ['basket', 'lifetime'], 'type': 'string', 'description': 'basket = same-order co-purchase; lifetime = same-customer across orders.'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': "Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday. For lifetime: bounds anchor acquisition; candidate purchases are looked up across the customer's full history."}, 'productTitle': {'type': 'string', 'description': 'Anchor product title (case-insensitive substring match). Required.'}, 'minCoOccurrences': {'type': 'integer', 'description': 'Suppress pairs with fewer than this many co-occurrences (default: 3). Raise to 5–10 for high-volume stores; lower to 2 for low-volume stores or specific anchor products.'}}}

get_collections

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.

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'limit': {'type': 'integer', 'description': 'Number of results (default: 50)'}, 'report': {'enum': ['list', 'products'], 'type': 'string', 'description': 'Report type'}, 'endDate': {'type': 'string', 'description': 'For products: include sales data to this date (YYYY-MM-DD)'}, 'startDate': {'type': 'string', 'description': 'For products: include sales data from this date (YYYY-MM-DD)'}, 'collectionId': {'type': 'string', 'description': 'For products: Shopify collection ID'}, 'collectionTitle': {'type': 'string', 'description': 'For products: search by collection title (partial match)'}}}

get_complete_dashboard

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).

Esquema de entrada

{'type': 'object', 'properties': {'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}}}

get_connector_data

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, 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, 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.

Esquema de entrada

{'type': 'object', 'required': ['connector', 'report'], 'properties': {'days': {'type': 'integer', 'description': 'For recharge upcoming_charges: FORWARD forecast window (default 30). For youtube top_videos and swish demand_trends: BACKWARD lookback window (default 7 / 30 respectively). Opposite directions between recharge and the lookback connectors — see get_help(connector).'}, 'view': {'type': 'string', 'description': 'For triple-whale journey/pps: breakdown view (by_type/by_source/by_country/by_device/funnel for journey; by_source/by_answer/response_rate/recent for pps).'}, 'limit': {'type': 'integer', 'description': "Number of results. Applies to: klaviyo, sendy, gorgias (tickets), recharge (cancellation_reasons), google-search-console, youtube, ringcentral (calls), reviewsio, triple-whale (attributions), smile (top_members), swish (top_products), woocommerce, google-ads (search_terms — terms per account, default 200, max 1000; campaigns with segment:'day' — campaigns expanded, default 10, max 20)."}, 'model': {'enum': ['Triple Attribution', 'Linear Paid', 'Linear All', 'Last Click', 'First Click'], 'type': 'string', 'description': "For triple-whale channel_by_model: which attribution model to read. Defaults to 'Triple Attribution'."}, 'query': {'type': 'string', 'description': 'For youtube search_transcripts: search query (required).'}, 'store': {'type': 'string', 'description': "For google-search-console: Shopify store key (e.g. 'acme-store-us') to auto-resolve the assigned property."}, 'metric': {'type': 'string', 'description': 'For klaviyo top_campaigns/top_flows: ranking metric (revenue, openRate, clickRate).'}, 'report': {'type': 'string', 'description': 'Report type — valid values depend on `connector`. See the tool description for the per-connector list, or get_help(connector) for full detail.'}, 'search': {'type': 'string', 'description': 'For gorgias tickets: case-insensitive keyword search across ticket subject and message body.'}, 'sortBy': {'type': 'string', 'description': "For google-search-console top_queries/top_pages: 'clicks' or 'impressions'. For smile top_members: 'pointsBalance', 'totalEarned', or 'totalSpent'."}, 'source': {'type': 'string', 'description': 'For triple-whale journey: filter to one acquisition source (google-ads, facebook-ads, organic, klaviyo, Direct). NOT the `connector` selector above.'}, 'status': {'type': 'string', 'description': "For klaviyo (campaigns/flows/top_flows — top_flows includes paused and archived flows unless you pass status:'live') / gorgias (tickets) / woocommerce (orders) / google-ads (campaign_settings — e.g. 'ENABLED' to drop long-paused campaigns): filter by status."}, '_offset': {'type': 'integer', 'description': 'For gorgias tickets: pagination offset (default: 0).'}, 'channel': {'type': 'string', 'description': 'For gorgias tickets: filter by channel. For triple-whale attributions/by_channel/product_attribution: filter by marketing channel.'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Meaning/default varies slightly per connector — see get_help(connector).'}, 'groupBy': {'enum': ['channel', 'campaign'], 'type': 'string', 'description': 'For triple-whale channel_by_model: aggregation level.'}, 'orderBy': {'enum': ['publishedAt', 'viewCount', 'likeCount'], 'type': 'string', 'description': 'For youtube videos: sort field.'}, 'segment': {'enum': ['day'], 'type': 'string', 'description': "For google-ads campaigns: 'day' nests a per-day series inside each campaign, so a per-campaign daily view is ONE call instead of one per day. Tightens the campaign cap (see `limit`, default 10, max 20) since campaigns x days multiplies quickly."}, 'siteUrl': {'type': 'string', 'description': "For google-search-console: exact siteUrl from a connectedSites entry, e.g. 'sc-domain:example-store.com'."}, 'videoId': {'type': 'string', 'description': 'For youtube video_details: YouTube video ID (required).'}, 'category': {'enum': ['revenue', 'ads', 'customers', 'pixel', 'email'], 'type': 'string', 'description': 'For triple-whale summary: filter to a specific metric category.'}, 'interval': {'enum': ['day', 'week', 'month'], 'type': 'string', 'description': 'For klaviyo signup_trends: time interval.'}, 'maxScore': {'type': 'integer', 'description': 'For reviewsio unanswered: only show reviews with this rating or lower.'}, 'surveyId': {'type': 'string', 'description': 'For reviewsio survey_responses: filter to specific survey.'}, 'connector': {'enum': ['triple-whale', 'klaviyo', 'sendy', 'gorgias', 'recharge', 'google-search-console', 'clarity', 'youtube', 'reviewsio', 'google-ads', 'xero', 'ringcentral', 'smile', 'swish', 'woocommerce', 'meta-ads', 'tiktok-ads', 'shipstation'], 'type': 'string', 'description': 'Which third-party connector to query. Only connectors this shop has connected are valid — tools/list narrows this enum per shop; call get_data_sources if unsure.'}, 'dimension': {'enum': ['browser', 'device', 'os', 'country', 'source'], 'type': 'string', 'description': 'For clarity by_dimension: dimension to break down by (required).'}, 'direction': {'enum': ['all', 'improved', 'declined'], 'type': 'string', 'description': 'For google-search-console keyword_movers/page_ranking_changes: filter by ranking direction.'}, 'eventType': {'type': 'string', 'description': 'For triple-whale journey: filter to one event type (added_to_cart, signed_up, conversion, subscription, post_purchase_survey_submitted).'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Meaning/default varies slightly per connector — see get_help(connector).'}, 'brandTerms': {'type': 'string', 'description': 'For google-search-console branded_split: comma-separated brand terms (auto-detected if omitted).'}, 'campaignId': {'type': 'string', 'description': "For google-ads: restrict to one campaign. On campaign_settings it fetches just that campaign and expands its negative keyword text (one campaign is a bounded payload); on search_terms it filters the terms server-side, so the top-N and the spend-coverage figure are that campaign's rather than the whole account's."}, 'customerId': {'type': 'string', 'description': "For google-ads: customer ID to filter by (multi-account). Call with report='summary' first to see connected accounts."}, 'periodType': {'enum': ['last7days', 'last30days', 'last90days', 'last365days'], 'type': 'string', 'description': 'For triple-whale: shorthand ROLLING time window, anchored to today (default last30days). For a specific calendar range instead (e.g. a past month), omit this and pass startDate/endDate — summary then fetches that exact range live from Triple Whale rather than reading the rolling-window cache.'}, 'granularity': {'type': 'string', 'description': "For triple-whale by_channel: 'total' (default), 'daily', or 'by_store'. For smile points_activity: 'day', 'week', or 'month'."}, 'minImpressions': {'type': 'integer', 'description': 'For google-search-console cannibalization: minimum impressions (default 10).'}, 'expandNegatives': {'type': 'boolean', 'description': "For google-ads campaign_settings: include negative keyword TEXT as well as counts. Off by default because one campaign's negatives can fill the whole response; implied when campaignId is set."}, 'attributionModel': {'enum': ['fullLastClick', 'fullFirstClick', 'lastPlatformClick', 'linear', 'linearAll'], 'type': 'string', 'description': 'For triple-whale attributions/by_channel/product_attribution: which per-order attribution model to use.'}, 'newCustomersOnly': {'type': 'boolean', 'description': 'For triple-whale channel_by_model: restrict to new-customer orders only.'}}}

get_customer_insights

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).

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'limit': {'type': 'integer', 'description': 'For top_customers and lapsed_high_value: number of results (default: 20)'}, 'months': {'type': 'integer', 'description': 'For cohorts and retention_curve: number of months to look back for acquisition (default: 6 for cohorts, 12 for retention_curve)'}, 'report': {'enum': ['new_vs_returning', 'repeat_metrics', 'cohorts', 'retention_curve', 'by_category', 'cohorts_by_first_purchase', 'top_customers', 'lapsed_high_value'], 'type': 'string', 'description': 'Report type'}, 'sortBy': {'enum': ['totalSpent', 'orders'], 'type': 'string', 'description': 'For top_customers: sort by totalSpent or orders (default: totalSpent)'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD)'}, 'minSpent': {'type': 'number', 'description': 'For lapsed_high_value: minimum lifetime spend in major units, e.g. 500 for £500 (default: 500)'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD)'}, 'daysInactive': {'type': 'integer', 'description': 'For lapsed_high_value: days since last order to count as lapsed (default: 90)'}, 'maxDaysInactive': {'type': 'integer', 'description': 'For lapsed_high_value: upper bound on inactivity — customers whose last order is older than this are treated as churned, not lapsed, and excluded (default: 365). Raise to see the long tail.'}}}

get_customers

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.

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'tag': {'type': 'string', 'description': 'For customer_history: find customer by tag'}, 'rank': {'type': 'integer', 'description': 'For customer_history: look up customer by rank in top customers list (e.g. 1 = top spender)'}, 'tags': {'type': 'array', 'items': {'type': 'string'}, 'description': 'For tag_segments: tags to count explicitly and cross-tabulate (matched case-insensitively; always included even below minTagVolume).'}, 'limit': {'type': 'integer', 'description': 'Number of results (default: 10)'}, 'report': {'enum': ['segments', 'top', 'by_country', 'customer_history', 'tag_segments'], 'type': 'string', 'description': 'Report type'}, 'sortBy': {'type': 'string', 'description': 'For top: totalSpent or orders (default: totalSpent)'}, 'customerId': {'type': 'string', 'description': "For customer_history: Shopify customer ID (from the 'top' report's customerId field)"}, 'minTagVolume': {'type': 'integer', 'description': 'For tag_segments: also surface any other (non-requested) tag with at least this many customers in scope (default 200).'}, 'purchaserFilter': {'enum': ['non_purchasers', 'buyers', 'all'], 'type': 'string', 'description': 'For tag_segments: which cohort to segment (default non_purchasers = ordersCount 0).'}}}

get_daily_metrics

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.

Esquema de entrada

{'type': 'object', 'required': ['domain'], 'properties': {'limit': {'type': 'integer', 'description': 'For domain:"operational", report:"daily": number of days to return (default: 30).'}, 'domain': {'enum': ['funnel', 'revenue', 'operational'], 'type': 'string', 'description': 'Which daily-metrics domain to query. See the tool description for the report list and defaults per domain.'}, 'report': {'type': 'string', 'description': 'Report type — valid values depend on `domain` (see tool description). Defaults to "daily" in every domain if omitted, but "daily" means a different payload per domain.'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day) when omitted.'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Default window (if omitted) varies by domain — see tool description; domain:"funnel" has no real default, always pass this explicitly.'}}}

get_data_sources

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.

Esquema de entrada

{'type': 'object', 'properties': {}}

get_discounts

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').

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'code': {'type': 'string', 'description': 'For code_details: required. For by_product: optional filter by specific discount code.'}, 'limit': {'type': 'integer', 'description': 'For top_codes/by_product: number of results (default: 10/20)'}, 'report': {'enum': ['summary', 'top_codes', 'code_details', 'by_product'], 'type': 'string', 'description': 'Report type'}, 'sortBy': {'enum': ['revenue', 'usage', 'discount'], 'type': 'string', 'description': 'For top_codes: sort field'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD)'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD)'}}}

get_focus

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.

Esquema de entrada

{'type': 'object', 'properties': {'top': {'type': 'integer', 'description': 'Target number of focus items (default 5, max 10). Affects the instruction sent to the model when refresh is needed.'}, 'refresh': {'type': 'boolean', 'description': "Re-plan from current data ('plan my week'). Supersedes the current plan and returns a fresh synthesis bundle. Default: false (returns the current plan)."}}}

get_forecast

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.

Esquema de entrada

{'type': 'object', 'properties': {'store': {'type': 'string', 'description': "Sub-store key (e.g. 'acme-store-us'). Omit to forecast every store in the workspace (each in its own currency)."}, 'metric': {'enum': ['revenue', 'orders'], 'type': 'string', 'description': "Metric to forecast. Defaults to 'revenue'."}, 'horizon': {'type': 'integer', 'description': 'Number of future FULL months to project after the current one (1-3). Defaults to 1.'}}}

get_ga4_dimensions

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.

Esquema de entrada

{'type': 'object', 'properties': {'propertyId': {'type': 'string', 'description': "Filter to a specific GA4 property (e.g. 'properties/375762433'). Omit to use the configured property."}}}

get_ga4_funnel

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.

Esquema de entrada

{'type': 'object', 'required': ['steps'], 'properties': {'steps': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': 'string', 'description': 'Display name for the step'}, 'event': {'type': 'string', 'description': "GA4 event name to filter on (e.g. 'add_to_cart'). Use get_ga4_dimensions to discover custom events."}, 'filterExpression': {'type': 'object', 'description': 'Advanced: a full GA4 FunnelFilterExpression instead of a simple event.'}}}, 'description': 'Ordered funnel steps. Each: { name, event } for a simple event filter, or { name, filterExpression } for a full GA4 FunnelFilterExpression.'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (GA4 data is T-1).'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}, 'propertyId': {'type': 'string', 'description': "Filter to a specific GA4 property (e.g. 'properties/375762433'). Omit to use the configured property."}, 'breakdownDimension': {'type': 'string', 'description': "Optional dimension to segment the funnel by (e.g. 'deviceCategory', 'country')."}, 'nextActionDimension': {'type': 'string', 'description': "Optional dimension to analyse what users do after each step (e.g. 'eventName', 'pagePath')."}}}

get_help

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.

Esquema de entrada

{'type': 'object', 'properties': {'topic': {'type': 'string', 'description': "A guide topic (routing, signals, conventions, claims, analysis, multistore, writeback, triple_whale), a metric name (ltv, order_counts, aov, cvr, cac, repeat_rate, roas, mer, nps, csat, refund_rate), OR a tool name for its worked examples. Omit to list what's available."}}}

get_insights

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.

Esquema de entrada

{'type': 'object', 'properties': {'tags': {'type': 'array', 'items': {'type': 'string'}, 'description': "Filter to insights that contain ANY of these tags (OR semantics). E.g. ['seo'] or ['paid']."}, 'report': {'enum': ['checklist', 'thread'], 'type': 'string', 'description': "Default: 'checklist'. 'thread' retrieves a linked sequence of related findings as one story — requires threadId or insightId. (For fix outcomes / win-rate, use get_interventions(report: 'outcomes').)"}, 'status': {'description': "Filter by status. Pass a single value (e.g. 'open') or an array (e.g. ['open','addressed']) for OR semantics. Allowed values: open, addressed, superseded, dismissed."}, 'refresh': {'type': 'boolean', 'description': 'Set to true to generate fresh insights even if existing ones are present. Default: false — returns existing checklist.'}, 'category': {'enum': ['revenue', 'marketing', 'operations', 'customers', 'seo'], 'type': 'string', 'description': 'Filter to a single category.'}, 'threadId': {'type': 'string', 'description': 'Filter to a single thread (works on checklist and thread reports). Used to view a story end-to-end without category/tag filtering.'}, 'insightId': {'type': 'string', 'description': "For report: 'thread' — resolve the threadId from this insight and return the full thread (alternative to passing threadId directly)."}, 'includeCompleted': {'type': 'boolean', 'description': 'Default true. Set to false to return only active (open) insights.'}}}

get_interventions

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).

Esquema de entrada

{'type': 'object', 'properties': {'type': {'type': 'string', 'description': 'Filter by category (technical_seo, paid_optimization, etc.).'}, 'limit': {'type': 'integer', 'description': 'Max results (default 30).'}, 'since': {'type': 'string', 'description': 'Only interventions appliedAt >= this date (YYYY-MM-DD).'}, 'store': {'type': 'string', 'description': 'Filter by store key.'}, 'report': {'enum': ['status', 'list', 'outcomes'], 'type': 'string', 'description': "Default 'list'. 'status' = consolidated open-work view (dueForCheckIn + inFlight + recentlyClosed + winRate) in one call, ideal for orienting at the start of a session. 'outcomes' buckets closed interventions by verdict (lift_confirmed vs regressed vs lift_inconclusive vs partial), reports a win rate, and lists those still under review."}, 'status': {'enum': ['applied', 'under_review', 'closed', 'abandoned'], 'type': 'string', 'description': 'Filter by lifecycle status.'}, 'verdict': {'enum': ['lift_confirmed', 'lift_inconclusive', 'regressed', 'partial', 'abandoned'], 'type': 'string', 'description': 'Filter by closing verdict (only for closed interventions).'}, 'insightId': {'type': 'string', 'description': 'Only interventions that link back to this insight (via linkedInsightIds) — i.e. the fixes prompted by a specific finding.'}, 'dueForCheckIn': {'type': 'boolean', 'description': "If true, only return interventions whose next checkDate has passed and status is still 'applied'/'under_review'."}}}

get_inventory

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).

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'limit': {'type': 'integer', 'description': 'Number of products (default: 20)'}, 'report': {'enum': ['summary', 'low_stock', 'out_of_stock', 'by_location'], 'type': 'string', 'description': 'Report type'}, 'threshold': {'type': 'integer', 'description': 'For low_stock: stock level threshold (default: 10)'}}}

get_marketing_performance

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.

Esquema de entrada

{'type': 'object', 'properties': {'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}}}

get_markets

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).

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'report': {'enum': ['markets', 'performance'], 'type': 'string', 'description': 'Report type: markets (configured markets and countries) or performance (revenue by market)'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}}}

get_metrics_comparison

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.

Esquema de entrada

{'type': 'object', 'required': ['startDate', 'endDate'], 'properties': {'endDate': {'type': 'string', 'description': 'End date of current period (YYYY-MM-DD)'}, 'startDate': {'type': 'string', 'description': 'Start date of current period (YYYY-MM-DD)'}, 'comparison': {'enum': ['wow', 'mom', 'yoy', 'previous'], 'type': 'string', 'description': 'Comparison type: wow (week-over-week), mom (month-over-month), yoy (year-over-year), previous (equivalent previous period)'}, 'compareLabel': {'type': 'string', 'description': "Label for custom comparison period (e.g., 'Last Year Black Friday Sale')"}, 'compareEndDate': {'type': 'string', 'description': 'For custom comparison: end date of comparison period (YYYY-MM-DD)'}, 'compareStartDate': {'type': 'string', 'description': 'For custom comparison: start date of comparison period (YYYY-MM-DD)'}}}

get_metrics_multi_compare

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.

Esquema de entrada

{'type': 'object', 'required': ['startDate', 'endDate'], 'properties': {'endDate': {'type': 'string', 'description': 'End date of current period (YYYY-MM-DD)'}, 'startDate': {'type': 'string', 'description': 'Start date of current period (YYYY-MM-DD)'}, 'comparisons': {'type': 'array', 'items': {'enum': ['wow', 'mom', 'yoy', 'previous'], 'type': 'string'}, 'description': "List of comparison types to include (default: ['wow', 'yoy'])"}, 'customComparisons': {'type': 'array', 'items': {'type': 'object', 'properties': {'label': {'type': 'string'}, 'endDate': {'type': 'string'}, 'startDate': {'type': 'string'}}}, 'description': "Custom comparison periods (e.g., last year's sale period)"}}}

get_order

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.

Esquema de entrada

{'type': 'object', 'properties': {'orderId': {'type': 'string', 'description': "Shopify numeric order ID e.g. '5559266041988'"}, 'orderIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Array of Shopify numeric order IDs for batch lookup (max 50)'}, 'orderName': {'type': 'string', 'description': "Order name e.g. '#1001' or '1001'"}}}

get_orders

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).

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'tag': {'type': 'string', 'description': 'For by_tag: focus a single order tag (case-insensitive). Omit to scan every tag and surface the ones dropping.'}, 'limit': {'type': 'integer', 'description': 'For by_country: number of countries (default: 10). For by_tag: max tags returned (default: 20).'}, 'report': {'enum': ['by_status', 'by_country', 'by_product', 'by_tag'], 'type': 'string', 'description': 'Report type'}, 'sortBy': {'enum': ['revenue', 'customers', 'units'], 'type': 'string', 'description': 'For by_product: sort field (default: revenue)'}, 'compare': {'enum': ['wow', 'mom', 'yoy', 'previous'], 'type': 'string', 'description': 'For by_country: attach a `comparison` block with rising/falling countries vs the WoW/MoM/YoY/previous-period window.'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD)'}, 'lagDays': {'type': 'integer', 'description': 'For by_tag: end the windows this many days back so the current week is complete days (default 1). Raise it if a marketplace app applies its order tag with a delay.'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD)'}, 'lookbackWeeks': {'type': 'integer', 'description': 'For by_tag: number of prior weekly windows to use as the baseline (default 4, range 2-12).'}}}

get_product_analytics

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).

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'limit': {'type': 'integer', 'description': 'Number of results (default: 20)'}, 'report': {'enum': ['summary', 'top_products', 'product_detail'], 'type': 'string', 'description': 'Report type'}, 'sortBy': {'enum': ['views', 'purchases', 'revenue'], 'type': 'string', 'description': 'For top_products: sort field (default: revenue)'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'productId': {'type': 'string', 'description': 'For product_detail: Shopify product ID'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}}}

get_product_catalog

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.

Esquema de entrada

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'description': 'Number of products (default: 20)'}, 'store': {'type': 'string', 'description': 'Filter to a specific store domain. Omit to query all connected stores.'}}}

get_product_health

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.

Esquema de entrada

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'description': 'Max products to analyse, ordered by recent revenue (default: 50, max: 100).'}, 'store': {'type': 'string', 'description': 'Filter to a specific store domain. Omit to query all connected stores.'}, 'endDate': {'type': 'string', 'description': 'End of sales window (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': 'Start of sales window (YYYY-MM-DD). Defaults to 30 days ago.'}, 'minAttentionScore': {'type': 'integer', 'description': 'Filter to products with attentionScore >= this value (default: 0 = all). Set to 30 to see only products with a flagged signal.'}}}

get_products_by_channel

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?'

Esquema de entrada

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'description': 'Number of products to return (default: 10, max 100).'}, '_offset': {'type': 'integer', 'description': "Pagination offset. If a response's _pagination.hasMore is true, call again with _offset to page through the full set."}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}}}

get_query_to_url

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.

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'url': {'type': 'string', 'description': 'For by_url: the exact URL as it appears in Search Console (https:// included, with or without trailing slash to match how GSC indexed it).'}, 'limit': {'type': 'integer', 'description': 'Number of results (by_url: top queries to return; unconverting_pages / top_pages_with_sales: max URLs returned). Default 20.'}, 'report': {'enum': ['by_url', 'unconverting_pages', 'top_pages_with_sales'], 'type': 'string', 'description': 'Report type'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'maxSales': {'type': 'integer', 'description': "For unconverting_pages: maximum units sold for the matched product in the same window (default 2). 0 means 'pages with zero sales only'."}, 'minClicks': {'type': 'integer', 'description': 'For unconverting_pages: minimum organic clicks for a URL to be considered (default 50). Lower for low-traffic stores; raise to focus on bigger problems.'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}}}

get_refunds

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).

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'limit': {'type': 'integer', 'description': 'For top_products and by_reason: number of results (default: 10)'}, 'report': {'enum': ['summary', 'top_products', 'by_reason'], 'type': 'string', 'description': 'Report type'}, 'sortBy': {'enum': ['amount', 'rate'], 'type': 'string', 'description': 'For top_products: sort field (default: amount)'}, 'compare': {'enum': ['wow', 'mom', 'yoy', 'previous'], 'type': 'string', 'description': 'For summary: attach a `comparison` block showing the same metrics for the WoW/MoM/YoY/previous-period window with percentage changes.'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}}}

get_revenue_drivers

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.

Esquema de entrada

{'type': 'object', 'properties': {'store': {'type': 'string', 'description': 'Filter to a specific store domain.'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday.'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window.'}, 'comparison': {'enum': ['previous', 'wow', 'mom', 'yoy'], 'type': 'string', 'description': 'Comparison window. Default: previous (equivalent prior period).'}}}

get_reviews

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.

Esquema de entrada

{'type': 'object', 'required': ['report'], 'properties': {'sku': {'type': 'string', 'description': 'For search: filter to specific product SKU'}, 'limit': {'type': 'integer', 'description': 'Number of results'}, 'report': {'enum': ['summary', 'trends', 'top_rated', 'lowest_rated', 'recent', 'by_product', 'search', 'timing', 'sales_impact', 'themes'], 'type': 'string', 'description': 'Report type'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD)'}, 'keyword': {'type': 'string', 'description': 'For search: keyword to find in review content'}, 'maxScore': {'type': 'integer', 'description': 'For recent/search: maximum star rating (1-5)'}, 'minScore': {'type': 'integer', 'description': 'For recent/search: minimum star rating (1-5)'}, 'provider': {'enum': ['yotpo', 'reviewsio', 'judge-me'], 'type': 'string', 'description': 'Review provider (auto-detected if omitted)'}, 'productId': {'type': 'string', 'description': 'For by_product/themes: Shopify product ID (numeric or GID) to scope to one product'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD)'}, 'minReviews': {'type': 'integer', 'description': 'For top_rated/lowest_rated: minimum review count (default: 3)'}, 'productTitle': {'type': 'string', 'description': 'For by_product/themes: product title (partial match, case-insensitive)'}}}

get_spend_reconciliation

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.

Esquema de entrada

{'type': 'object', 'properties': {'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}}}

get_store_notes

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.

Esquema de entrada

{'type': 'object', 'properties': {'store': {'type': 'string', 'description': 'Optional. Filter to a specific store. Omit to get notes for all stores the caller has access to.'}}}

get_store_profile

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.

Esquema de entrada

{'type': 'object', 'properties': {'store': {'type': 'string', 'description': 'Optional. Specific store (short or full domain). Omit for all stores in the workspace.'}}}

get_store_summary

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.

Esquema de entrada

{'type': 'object', 'properties': {'endDate': {'type': 'string', 'description': 'End date in ISO format (YYYY-MM-DD). Defaults to yesterday (last fully-closed day — today is excluded by default to avoid partial-day totals; pass an explicit endDate to include today).'}, 'startDate': {'type': 'string', 'description': 'Start date in ISO format (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}}}

get_sync_health

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.

Esquema de entrada

{'type': 'object', 'properties': {}}

get_targets

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.

Esquema de entrada

{'type': 'object', 'properties': {'store': {'type': 'string', 'description': 'Only targets scoped to this sub-store key.'}, 'metric': {'type': 'string', 'description': 'Only targets for this metric.'}, 'period': {'enum': ['month', 'quarter', 'year'], 'type': 'string', 'description': 'Only targets for this period type.'}}}

get_timeline

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.

Esquema de entrada

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'description': 'Max events to return (default 50, max 200).'}, 'store': {'type': 'string', 'description': 'Optional. Filter to a specific store (short or full domain). Omit for all stores the caller can see.'}, 'endDate': {'type': 'string', 'description': 'Window end (YYYY-MM-DD). Defaults to today.'}, 'startDate': {'type': 'string', 'description': 'Window start (YYYY-MM-DD). Defaults to 90 days before endDate.'}}}

get_top_products

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.

Esquema de entrada

{'type': 'object', 'properties': {'level': {'enum': ['product', 'variant', 'category'], 'type': 'string', 'description': 'Grouping level: product (default), variant (by size/colour/SKU), or category (revenue/COGS/gross-profit/margin by product type)'}, 'limit': {'type': 'integer', 'description': 'Number of results (default: 10)'}, 'metric': {'type': 'string', 'description': 'Sort by: revenue or quantity (default: revenue)'}, 'compare': {'enum': ['wow', 'mom', 'yoy', 'previous'], 'type': 'string', 'description': 'Attach a `comparison` block with the top rising/falling/new products vs the WoW/MoM/YoY/previous-period window.'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD)'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD)'}, 'productTitle': {'type': 'string', 'description': 'For variant level: filter to variants of a specific product (partial match)'}}}

get_velocity

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).

Esquema de entrada

{'type': 'object', 'required': ['angle', 'report'], 'properties': {'days': {'type': 'integer', 'description': 'Days for velocity calculation (default: 30 in both angles). Ignored by angle:"product", report:"summary" — that report is always a fixed trailing-30-day aggregate.'}, 'angle': {'enum': ['inventory', 'product'], 'type': 'string', 'description': 'Which velocity angle to query. See the tool description for the report list and defaults per angle.'}, 'limit': {'type': 'integer', 'description': 'For by_product: number of products (default: 20).'}, 'filter': {'enum': ['all', 'atRisk', 'overstocked', 'outOfStock'], 'type': 'string', 'description': 'For by_product: filter.'}, 'report': {'type': 'string', 'description': 'Report type — valid values depend on `angle` (see tool description): inventory has summary/by_product/restock; product has summary/by_product/trend/stagnant.'}, 'sortBy': {'enum': ['velocity', 'daysOfStock', 'risk'], 'type': 'string', 'description': 'For by_product: sort field.'}, 'maxOrders': {'type': 'integer', 'description': 'For angle:"product", report:"stagnant": max orders to count as stagnant (default: 0 = zero sales only, use 1-2 for near-zero).'}, 'productId': {'type': 'string', 'description': 'For angle:"product", report:"trend": Shopify product ID (required).'}, 'variantId': {'type': 'string', 'description': 'For angle:"product", report:"trend": Shopify variant ID (optional).'}, 'leadTimeDays': {'type': 'integer', 'description': 'For angle:"inventory", report:"restock": lead time in days (default: 14).'}, 'safetyStockDays': {'type': 'integer', 'description': 'For angle:"inventory", report:"restock": safety buffer days (default: 7).'}}}

get_wakeup

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.

Esquema de entrada

{'type': 'object', 'required': ['id'], 'properties': {'id': {'type': 'string', 'description': 'The wakeup UUID returned by save_wakeup.'}}}

get_wakeups

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.

Esquema de entrada

{'type': 'object', 'properties': {'store': {'type': 'string', 'description': 'Store domain (short or full). Omit to return wakeups for all stores in the workspace.'}, 'status': {'enum': ['pending', 'triggered', 'all'], 'type': 'string', 'description': "Filter by status. Default: 'all' — returns both pending and recently triggered (last 14 days)."}}}

get_weekly_trends

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.

Esquema de entrada

{'type': 'object', 'properties': {'weeks': {'type': 'integer', 'description': 'Number of weeks (default: 12)'}}}

get_yoy_monthly

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.

Esquema de entrada

{'type': 'object', 'required': ['metric'], 'properties': {'store': {'type': 'string', 'description': "Filter by sub-store key (e.g. 'acme-store-us'). Omit to sum across all stores in the workspace."}, 'metric': {'type': 'string', 'description': "Metric key (e.g. 'revenue', 'orders', 'aov', 'cvr', 'sessions', 'tickets_total'). Must be one that has been captured as a calendar-month snapshot."}, 'source': {'type': 'string', 'description': "Filter by source ('shopify', 'tw', 'ga4', 'google-ads', 'search-console', 'gorgias', 'shipstation'). Omit to sum across sources — usually only useful for metrics that appear in multiple sources (e.g. 'revenue' in both shopify and tw)."}, 'compareYear': {'type': 'integer', 'description': 'Year to compare against. Defaults to currentYear - 1.'}, 'currentYear': {'type': 'integer', 'description': 'Year to use as the current side of the comparison. Defaults to the current calendar year (UTC).'}}}

query_metric_snapshots

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.

Esquema de entrada

{'type': 'object', 'properties': {'list': {'type': 'boolean', 'description': "If true, returns the metric registry (canonical keys, units, descriptions). Use this when you don't know which metrics are available."}, 'limit': {'type': 'integer', 'description': 'Max snapshots to return (default 100, max 500)'}, 'store': {'type': 'string', 'description': "Filter to a specific store/region key. Accepts short form ('acme-store') or full domain ('acme-store.myshopify.com') — both normalize to the short form used in storage."}, 'metric': {'type': 'string', 'description': 'Canonical metric key. Omit to return snapshots across all metrics (filtered by other params).'}, 'source': {'type': 'string', 'description': "Filter by source ('shopify', 'ga4', 'tw', etc.)"}, 'endDate': {'type': 'string', 'description': 'Only include snapshots whose periodStart is <= this date (YYYY-MM-DD)'}, 'segment': {'type': 'string', 'description': 'Filter to a specific segment'}, 'insightId': {'type': 'string', 'description': 'Only snapshots linked to this insight'}, 'startDate': {'type': 'string', 'description': 'Only include snapshots whose periodEnd is >= this date (YYYY-MM-DD)'}, 'confidence': {'description': "Filter by confidence. Pass 'high' / 'medium' / 'low' to match exactly, or 'minHigh' / 'minMedium' to require AT LEAST that level (treats null as 'high'). Useful for benchmarks where you only want trustworthy values."}, 'periodKind': {'enum': ['rolling', 'calendar', 'custom'], 'type': 'string', 'description': "Filter by period anchoring. 'calendar' = discrete buckets only; 'rolling' = trailing windows only. Mixing the two in a single time series silently distorts trends."}, 'periodLength': {'enum': ['day', 'week', 'month', 'quarter', 'year'], 'type': 'string', 'description': 'Filter by bucket size — combine with periodKind to e.g. fetch only calendar-month rows.'}}}

query_orders

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.

Esquema de entrada

{'type': 'object', 'properties': {'tags': {'type': 'array', 'items': {'type': 'string'}, 'description': "Filter to orders carrying these Shopify order tags. Matching is case-insensitive. By default an order matches if it has ANY of the tags (see tagMatch). E.g. ['wholesale'] or ['gift','vip']."}, 'limit': {'type': 'integer', 'description': 'Number of results (default: 20, max: 50)'}, 'offset': {'type': 'integer', 'description': 'Pagination offset'}, 'sortBy': {'enum': ['processedAt', 'totalPrice'], 'type': 'string', 'description': 'Sort field (default: processedAt)'}, 'status': {'enum': ['paid', 'pending', 'refunded', 'partially_refunded'], 'type': 'string', 'description': 'Filter by financial status'}, 'endDate': {'type': 'string', 'description': 'End date (YYYY-MM-DD). Defaults to yesterday.'}, 'maxTotal': {'type': 'number', 'description': 'Maximum order total in dollars'}, 'minTotal': {'type': 'number', 'description': 'Minimum order total in dollars'}, 'tagMatch': {'enum': ['any', 'all'], 'type': 'string', 'description': "How to match multiple tags: 'any' (default, order has at least one) or 'all' (order has every listed tag)."}, 'sortOrder': {'enum': ['asc', 'desc'], 'type': 'string', 'description': 'Sort order (default: desc)'}, 'startDate': {'type': 'string', 'description': 'Start date (YYYY-MM-DD). Defaults to a 30-day window ending yesterday.'}, 'customerId': {'type': 'string', 'description': 'Filter to orders for a specific customer (Shopify customer ID)'}}}

record_metric_snapshot

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: [...]).

Esquema de entrada

{'type': 'object', 'required': ['snapshots'], 'properties': {'snapshots': {'type': 'array', 'items': {'type': 'object', 'required': ['metric', 'value', 'periodStart', 'periodEnd'], 'properties': {'unit': {'enum': ['percent', 'currency', 'count', 'days', 'ratio', 'position'], 'type': 'string', 'description': "Optional override; defaults to the registry unit for the metric. Use 'position' for ranks where 1.0 is best (e.g. avg_position) — distinct from 'count' (a quantity) and 'ratio' (a normalised number)."}, 'notes': {'type': 'string', 'description': "Optional free-text context the registry CAN'T already capture — scope, exclusions, sampling caveats. Good: 'excludes wholesale orders', 'country-filtered to GB only', 'branded + non-branded queries combined'. Don't bother restating things the registry/legend already provides — unit, direction (lower-is-better), or what the metric measures. For trust caveats (sampling/thresholding/window flakiness) prefer setting confidence + confidenceReason; reserve notes for the rest."}, 'store': {'type': 'string', 'description': "Optional sub-store / region key, e.g. 'acme-store-uk' or 'acme-store-uk.myshopify.com'. Either form is accepted and normalized to the short form for storage, so writes and reads always align."}, 'value': {'type': 'number', 'description': "Numeric value in the metric's canonical unit. percent: 0–100, currency: major units (e.g. 1500.50 GBP), count: integer, ratio: e.g. 4.2 for 4.2x ROAS."}, 'metric': {'type': 'string', 'description': "Canonical metric key (e.g. 'cvr', 'aov', 'roas', 'repeat_purchase_rate'). Must match the registry — unknown keys are rejected with a suggestion."}, 'source': {'type': 'string', 'description': "Where the number came from: 'shopify', 'ga4', 'tw', 'klaviyo', 'search-console', etc."}, 'segment': {'type': 'string', 'description': "Optional segment dimension, e.g. 'new', 'returning', 'GB', 'mobile'."}, 'currency': {'type': 'string', 'description': "ISO currency code when unit == 'currency', e.g. 'GBP', 'USD'."}, 'insightId': {'type': 'string', 'description': 'Optional — link this snapshot to an existing insight. ADDITIVE: re-recording with a different insightId adds the link without removing any prior links. The same snapshot can serve as evidence for multiple insights.'}, 'periodEnd': {'type': 'string', 'description': 'Period end (YYYY-MM-DD or ISO timestamp)'}, 'confidence': {'enum': ['high', 'medium', 'low'], 'type': 'string', 'description': "Trust signal for this snapshot. Default: omit (treated as 'high'). Drop to 'medium' or 'low' when a known caveat applies — e.g. EU country-level GA4 data is thresholded/sampled, Triple Whale recent-window data hasn't settled, currency may be mislabelled. Survives aggregation, so 'show me high-confidence CVR snapshots only' becomes a real query."}, 'insightIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Optional — link this snapshot to multiple insights at once. ADDITIVE: this UNIONS with any existing links; it never removes links. To remove a link, use update_insight(insightId, unlinkSnapshotIds: [...]).'}, 'periodKind': {'enum': ['rolling', 'calendar', 'custom'], 'type': 'string', 'description': "How the period is anchored. 'rolling' = trailing window ending at periodEnd (last 30 days, last 7 days, trailing 90d). 'calendar' = a discrete calendar bucket (April 2026, ISO week 18, Q1 2026, YTD). 'custom' = arbitrary range. Pair with periodLength so 'last 30 days' (rolling+month) is distinguishable from 'April 2026' (calendar+month) — otherwise time-series comparisons will silently mix the two."}, 'periodStart': {'type': 'string', 'description': 'Period start (YYYY-MM-DD or ISO timestamp)'}, 'periodLength': {'enum': ['day', 'week', 'month', 'quarter', 'year'], 'type': 'string', 'description': "Size of the period bucket. Omit when periodKind is 'custom' (arbitrary range). Examples: 'last 30 days' = month, 'last 7 days' = week, 'Q1 2026' = quarter, 'YTD' = year (with periodKind: calendar)."}, 'sourceParams': {'type': 'object', 'description': "Optional — the exact tool/report params that produced this value, for reproducibility. E.g. {tool: 'get_connector_data', connector: 'google-search-console', siteUrl: 'https://...', report: 'summary', startDate: '2025-12-01', endDate: '2025-12-31'}. Future-you can copy these straight into a new tool call to verify the number."}, 'baselineValue': {'type': 'number', 'description': 'Optional comparison baseline — typically the prior-period value of the same metric.'}, 'confidenceReason': {'type': 'string', 'description': "Optional one-line caveat explaining a non-high confidence, e.g. 'GA4 country thresholding', 'TW <72h window unstable', 'currency may be GBP mislabel'. Use the SAME phrasing for the same caveat across snapshots so the AI can group them."}, 'baselinePeriodEnd': {'type': 'string', 'description': 'Baseline period end'}, 'baselinePeriodStart': {'type': 'string', 'description': 'Baseline period start'}}}, 'description': 'Array of metric snapshots to record'}}}

report_concern

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.

Esquema de entrada

{'type': 'object', 'required': ['category', 'userQuote', 'description'], 'properties': {'category': {'enum': ['data_mismatch', 'incorrect_calculation', 'missing_data', 'confusing_output', 'slow_response', 'other'], 'type': 'string', 'description': "data_mismatch = user says it doesn't match another source (Shopify admin, GA, etc.). incorrect_calculation = the math looks wrong to them. missing_data = expected data isn't there. confusing_output = the response format is unclear. slow_response = took too long."}, 'severity': {'enum': ['low', 'medium', 'high'], 'type': 'string', 'description': "Inferred from how strongly the user voiced the concern. 'a bit weird' = low; 'this is definitely wrong' = high."}, 'toolName': {'type': 'string', 'description': 'The tool whose response prompted the concern, if known.'}, 'userQuote': {'type': 'string', 'description': "Verbatim what the user said, trimmed. Don't paraphrase."}, 'description': {'type': 'string', 'description': '1–2 sentences framing the concern technically. Include the data point in question.'}, 'expectedValue': {'type': 'string', 'description': "If the user said what they expected (e.g. 'should be around 500'), include it."}, 'responseSnippet': {'type': 'string', 'description': 'Relevant excerpt of the tool response that the user is questioning.'}}}

report_data_issue

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.

Esquema de entrada

{'type': 'object', 'required': ['category', 'description', 'toolName'], 'properties': {'category': {'enum': ['precision', 'type_mismatch', 'inconsistency', 'null_unexpected', 'schema_surprise'], 'type': 'string', 'description': "precision = too many decimals or wrong rounding. type_mismatch = field type doesn't match the tool's description. inconsistency = internal contradictions in one response (e.g. _currency vs values). null_unexpected = null in a field that should always have a value. schema_surprise = response shape doesn't match the tool description."}, 'severity': {'enum': ['low', 'medium', 'high'], 'type': 'string', 'description': 'low = cosmetic (extra decimals), medium = misleading but data still usable, high = data is unusable / breaks downstream logic.'}, 'toolName': {'type': 'string', 'description': "The tool whose response had the issue (e.g. 'get_metrics_comparison')."}, 'description': {'type': 'string', 'description': "1–2 sentences. What's wrong, where, and why it's wrong. Be specific: 'Field cvr returned 4.612345678 (10+ decimals); expected 1–2 decimal precision per the tool description.'"}, 'responseSnippet': {'type': 'string', 'description': 'Optional. The relevant fragment of the response, capped to ~2KB. Include just enough to make the issue reproducible.'}}}

save_focus

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.

Esquema de entrada

{'type': 'object', 'required': ['items'], 'properties': {'items': {'type': 'array', 'items': {'type': 'object', 'required': ['title', 'rationale', 'action', 'priority'], 'properties': {'tags': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Optional — domain/workflow tags.'}, 'type': {'enum': ['tackle', 'check', 'watch'], 'type': 'string', 'description': 'tackle = act on an open finding (link insightId); check = record the verdict on an intervention due for review (link interventionId); watch = monitor a metric/anomaly (set metric). Inferred from which id is present if omitted.'}, 'store': {'type': 'string', 'description': 'Optional — sub-store this applies to.'}, 'title': {'type': 'string', 'description': "Short headline (e.g. 'Fix DE/FR CVR gap')"}, 'action': {'type': 'string', 'description': 'Concrete next step the user should take'}, 'effort': {'type': 'string', 'description': "Effort estimate — 'high'/'medium'/'low' or a short phrase like '1 day eng + copy'"}, 'metric': {'type': 'string', 'description': "Optional — canonical metric key this targets (e.g. 'cvr', 'roas'). Use for 'watch' items."}, 'priority': {'type': 'integer', 'description': 'Rank — 1 is the most important. Items will be sorted by this.'}, 'insightId': {'type': 'string', 'description': "Link the open finding this maps to (type 'tackle'). Completion is derived from the finding becoming addressed."}, 'rationale': {'type': 'string', 'description': "Why now — reference specific numbers and what's behind the ranking"}, 'expectedImpact': {'type': 'string', 'description': "Expected impact — 'high'/'medium'/'low' or a short phrase like '£3-5k/mo if confirmed'"}, 'interventionId': {'type': 'string', 'description': "Link the intervention this maps to (type 'check'). Completion is derived from the intervention closing."}}}, 'description': 'Ordered focus items, top priority first'}, 'context': {'type': 'object', 'description': 'Optional snapshot of inputs used (e.g. {openInsights: 12, lastOutcomesWinRate: 60}). Stored verbatim for auditability.'}, 'replacePrevious': {'type': 'boolean', 'description': 'Default true — supersede the previous plan. Set false to keep history visible.'}}}

save_insights

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).

Esquema de entrada

{'type': 'object', 'required': ['insights'], 'properties': {'replace': {'type': 'boolean', 'description': 'Set to true to replace all active (non-completed) insights. Default: false (appends).'}, 'insights': {'type': 'array', 'items': {'type': 'object', 'required': ['title', 'description', 'action', 'category', 'priority'], 'properties': {'tags': {'type': 'array', 'items': {'type': 'string'}, 'description': "Free-form tags for filtering, e.g. ['seo','paid','fix-applied','30-day-check']. Use lowercase kebab-case and reuse existing tags where possible — these are queryable via get_insights(tags: [...])."}, 'store': {'type': 'string', 'description': "Which store this insight applies to (e.g. 'acme-store-de'). Omit for account-wide insights."}, 'title': {'type': 'string', 'description': "Short title (e.g. 'Reduce cart abandonment rate')"}, 'action': {'type': 'string', 'description': 'Specific action to take to fix/improve this'}, 'status': {'enum': ['open', 'addressed', 'superseded', 'dismissed'], 'type': 'string', 'description': "Workflow state. Default 'open'. Almost always omit (insights start open). 'addressed' = already acted on (normally set automatically when set_intervention links this finding); 'superseded' = replaced by a newer finding; 'dismissed' = not relevant."}, 'category': {'enum': ['revenue', 'marketing', 'operations', 'customers', 'seo'], 'type': 'string', 'description': 'Category'}, 'priority': {'enum': ['high', 'medium', 'low'], 'type': 'string', 'description': 'Priority level'}, 'threadId': {'type': 'string', 'description': 'Optional — explicit thread id to attach this insight to. If omitted but parentInsightId is set, the threadId is inherited from the parent. If both are omitted, the insight stands alone.'}, 'description': {'type': 'string', 'description': 'Why this matters — reference specific data points'}, 'parentInsightId': {'type': 'string', 'description': "Optional — the insightId this is a follow-up to (e.g. the original finding when saving 'fix-applied', or the fix when saving a 30-day check). The new insight inherits the parent's threadId; if the parent doesn't have one yet, a fresh threadId is generated and back-filled onto the parent so the whole story is grouped."}}}, 'description': 'Array of business insights to save (any number)'}}}

save_store_note

Save a new store-context note from something the USER told you that future sessions should know. Only call this when the user reveals business context the data alone wouldn't show (e.g. 'one B2B customer is a reseller', 'Q2 budget is fixed', 'we exclude wholesale orders from retail KPIs', 'migrated platforms in March'). Confirm to the user once saved: 'I've noted that for future sessions'. Notes you save are flagged as AI-suggested so the merchant can review/delete from the dashboard. Do NOT save speculation, transient session state, or things already obvious from the data. Skip if uncertain — the user can add notes manually.

Esquema de entrada

{'type': 'object', 'required': ['store', 'category', 'text'], 'properties': {'text': {'type': 'string', 'description': "Concise framing for future LLM sessions. Include the WHY when relevant. 1–3 sentences. Use the user's verbatim wording where helpful, but you can paraphrase to be unambiguous."}, 'store': {'type': 'string', 'description': "Which store this note applies to (short form 'acme-store-eu' or full 'acme-store-eu.myshopify.com')."}, 'category': {'enum': ['data_quirk', 'business_context', 'strategic_constraint', 'historical_event', 'excluded_segment'], 'type': 'string', 'description': "data_quirk = metrics are misleading; business_context = how to interpret the store's profile; strategic_constraint = don't recommend X; historical_event = pre-date data partial; excluded_segment = filter out Z from analysis."}, 'severity': {'enum': ['info', 'warning'], 'type': 'string', 'description': 'info (default) = apply silently; warning = mention when relevant. Use warning when ignoring the note would mislead the merchant.'}}}

save_target

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.

Esquema de entrada

{'type': 'object', 'required': ['metric', 'targetValue'], 'properties': {'note': {'type': 'string', 'description': "Optional free-text context, e.g. 'stretch goal after the BFCM push'."}, 'store': {'type': 'string', 'description': "Sub-store key (e.g. 'acme-store-us'). REQUIRED for money metrics. Omit for a workspace-wide non-money target."}, 'metric': {'type': 'string', 'description': "Canonical metric key, e.g. 'revenue', 'orders', 'aov', 'cvr', 'refund_rate'. Validated against the metric registry."}, 'period': {'enum': ['month', 'quarter', 'year'], 'type': 'string', 'description': "Calendar period the target is for. Defaults to 'month'. The target attaches to the CURRENT period of this type."}, 'targetValue': {'type': 'number', 'description': 'The goal value in MAJOR currency units for money metrics (80000 = £80k), or the raw value for counts/percentages (1200 orders, 2.5 for 2.5% cvr).'}}}

save_wakeup

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.

Esquema de entrada

{'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Wakeup UUID. Omit to create; provide to update an existing wakeup (e.g. to link a routineId after creating the Claude routine).'}, 'name': {'type': 'string', 'description': 'Short label (≤80 chars). Required on create.'}, 'store': {'type': 'string', 'description': 'Store domain (short or full). Required on create; ignored on update.'}, 'context': {'type': 'string', 'description': 'What to analyse when this fires and why it matters — instructions for your future self. Required on create.'}, 'routineId': {'type': 'string', 'description': 'Claude remote routine ID (trig_...) to link to this wakeup. Set this in an update call after creating the routine.'}, 'benchmarks': {'type': 'object', 'description': "Current metric snapshot for before/after comparison. Be selective — only capture what's relevant to this check."}, 'triggerDate': {'type': 'string', 'description': 'YYYY-MM-DD. Required on create.'}}}

set_intervention

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.

Esquema de entrada

{'type': 'object', 'required': ['type', 'description'], 'properties': {'type': {'enum': ['technical_seo', 'paid_optimization', 'email_optimization', 'content_change', 'pricing_change', 'inventory_change', 'site_speed', 'ux_improvement', 'other'], 'type': 'string', 'description': 'Category of intervention.'}, 'notes': {'type': 'string', 'description': 'Free-text context (excluded scope, caveats, etc.).'}, 'store': {'type': 'string', 'description': "The store/region this fix applies to. Either short ('acme-store-us') or full ('acme-store-us.myshopify.com') — both normalize."}, 'watch': {'type': 'object', 'description': "Optional threshold watch evaluated on every get_briefing, so a breach SURFACES rather than being recomputed by hand each time. Shape: {metric:'orders'|'revenue', windowDays: 1-90, op:'lt'|'lte'|'gt'|'gte', threshold: number, note?: string}, e.g. {metric:'orders', windowDays:3, op:'lt', threshold:55}. Windows cover COMPLETE days only; an unsupported metric is rejected here rather than silently never firing."}, 'appliedAt': {'type': 'string', 'description': "ISO date (YYYY-MM-DD) the fix was ACTUALLY applied, for logging it retroactively (default: now). The baseline auto-lookup only considers snapshots within 60 days BEFORE this date — pass the real date so a retroactive log can still find an older-but-correct baseline instead of one anchored to today. Also anchors the auto-assigned checkDates horizon when checkDates isn't given. Must not be in the future."}, 'checkDates': {'type': 'array', 'items': {'type': 'string'}, 'description': "ISO dates (YYYY-MM-DD) for planned check-ins, e.g. ['2026-06-07','2026-07-07','2026-08-07']. Stored for the dashboard / reminders; not enforced by the system."}, 'hypothesis': {'type': 'string', 'description': "Why you think it'll work (e.g. 'US property losing clicks to UK; hreflang should restore correct routing')."}, 'description': {'type': 'string', 'description': "What was actually changed (e.g. 'Added hreflang tags to all PDPs to fix country-mismatch issue')."}, 'trackedMetrics': {'type': 'array', 'items': {'oneOf': [{'type': 'string'}, {'type': 'object', 'required': ['metric'], 'properties': {'metric': {'type': 'string'}, 'source': {'type': 'string'}, 'segment': {'type': 'string'}}}]}, 'description': "Metrics to track for before/after comparison. Each entry is either a canonical metric key string (e.g. 'organic_clicks') OR an object {metric, segment?, source?} for dimensional pinning. Use the object form when a (metric, store) pair has snapshots across multiple segments or sources — otherwise the auto-baseline lookup is ambiguous and the call rejects with a list of candidates. Examples: ['cvr','aov'] (works when each metric has only one snapshot per store), [{metric:'organic_clicks',segment:'non_branded',source:'search-console'},{metric:'cvr',source:'ga4'}] (explicit dimensions per metric)."}, 'expectedMetrics': {'type': 'object', 'description': "Optional. Per-metric expectation, e.g. {organic_clicks: {deltaPercent: 15, direction: 'up'}}. Used at completion time to flag whether outcomes met expectations."}, 'linkedInsightIds': {'type': 'array', 'items': {'type': 'string'}, 'description': "Insights this intervention is acting on (the original finding(s) that prompted it). Captured for traceability — they're not modified."}}}

update_focus_item

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.

Esquema de entrada

{'type': 'object', 'required': ['itemId', 'state'], 'properties': {'state': {'enum': ['in_progress', 'planned', 'dropped'], 'type': 'string', 'description': 'in_progress = started; dropped = retired for this week (kept for the record, excluded from progress); planned = clear the manual overlay.'}, 'itemId': {'type': 'string', 'description': "The focus item's id (from get_focus items[].id)."}}}

update_insight

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.

Esquema de entrada

{'type': 'object', 'required': ['insightId'], 'properties': {'tags': {'type': 'array', 'items': {'type': 'string'}, 'description': "Replace the insight's tags with this list (e.g. ['seo','fix-applied']). Pass [] to clear all tags."}, 'notes': {'type': 'string', 'description': 'Free-text note about this finding. Stored alongside the insight for future reference.'}, 'title': {'type': 'string', 'description': 'Updated title'}, 'action': {'type': 'string', 'description': 'Updated action step'}, 'delete': {'type': 'boolean', 'description': "Remove this insight entirely — use when the user says it's not relevant or not an issue"}, 'status': {'enum': ['open', 'addressed', 'superseded', 'dismissed'], 'type': 'string', 'description': 'Workflow state. Setting status auto-syncs the legacy completed/dismissed mirror booleans.'}, 'addTags': {'type': 'array', 'items': {'type': 'string'}, 'description': "Append these tags to the existing set without removing others. Useful for adding workflow tags like 'fix-applied' or '30-day-check' without overwriting."}, 'category': {'enum': ['revenue', 'marketing', 'operations', 'customers', 'seo'], 'type': 'string', 'description': 'Updated category'}, 'priority': {'enum': ['high', 'medium', 'low'], 'type': 'string', 'description': 'Updated priority'}, 'threadId': {'type': 'string', 'description': "Set or change this insight's threadId directly. Use empty string to clear."}, 'completed': {'type': 'boolean', 'description': "(Legacy) Mark as completed. Setting true without a status sets status='addressed'; false sets status='open'."}, 'dismissed': {'type': 'boolean', 'description': "(Legacy) Mark as dismissed. Setting this to true without a status sets status='dismissed'."}, 'insightId': {'type': 'string', 'description': 'The insight ID to update'}, 'removeTags': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Remove these tags from the existing set, leaving others intact.'}, 'description': {'type': 'string', 'description': 'Updated description'}, 'linkSnapshotIds': {'type': 'array', 'items': {'type': 'string'}, 'description': "Attach existing metric snapshots (record_metric_snapshot rows) to this insight as supporting evidence for the finding. Pass the snapshotIds (returned from query_metric_snapshots). The snapshots appear in get_insights(report: 'thread') timelines. Use this when snapshots were recorded without insightId — typical when you only learn the insight ID after saving."}, 'parentInsightId': {'type': 'string', 'description': "Link this insight to a predecessor. The threadId is auto-managed: if the parent has one, it's inherited; otherwise a fresh threadId is generated and applied to both. Pass an empty string to detach the parent (and clear threadId if no other thread members reference it)."}, 'unlinkSnapshotIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Detach the given snapshotIds from this insight (sets their insightId to null). Use to correct a wrong link.'}}}

update_intervention

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.'}).

Esquema de entrada

{'type': 'object', 'required': ['interventionId'], 'properties': {'notes': {'type': 'string', 'description': 'Note to record. APPENDED under a date stamp by default, preserving earlier corrections.'}, 'watch': {'type': 'object', 'description': "Attach (or with null, clear) a threshold watch evaluated on every get_briefing, so a breach SURFACES instead of being recomputed by hand. Shape: {metric:'orders'|'revenue', windowDays: 1-90, op:'lt'|'lte'|'gt'|'gte', threshold: number, note?: string}. Example: {metric:'orders', windowDays:3, op:'lt', threshold:55}. Windows cover COMPLETE days only (today is excluded), and a window the order sync does not fully cover reports as indeterminate rather than breached."}, 'notesMode': {'enum': ['append', 'replace'], 'type': 'string', 'description': "Default 'append'. Use 'replace' only when deliberately discarding the existing notes."}, 'checkDates': {'type': 'array', 'items': {'type': 'string'}, 'description': 'REPLACE the whole check-date set with these ISO dates (YYYY-MM-DD). To move a single date, prefer addCheckDates/removeCheckDates so the others cannot be dropped by accident. Cannot be combined with add/remove.'}, 'hypothesis': {'type': 'string', 'description': 'Correct or sharpen why it was expected to work.'}, 'description': {'type': 'string', 'description': 'Correct what was changed.'}, 'addCheckDates': {'type': 'array', 'items': {'type': 'string'}, 'description': 'ISO dates to ADD, leaving the rest in place. Result is deduped and sorted.'}, 'interventionId': {'type': 'string', 'description': 'The intervention to edit. Ids are per-shop — one from another store will not resolve.'}, 'expectedMetrics': {'type': 'object', 'description': "Replace the per-metric expectations, e.g. {orders: {deltaPercent: 10, direction: 'up'}}."}, 'removeCheckDates': {'type': 'array', 'items': {'type': 'string'}, 'description': 'ISO dates to REMOVE, leaving the rest in place. Pair with addCheckDates to move one date.'}}}

update_store_profile

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.

Esquema de entrada

{'type': 'object', 'required': ['store'], 'properties': {'note': {'type': 'string', 'description': 'Free-text authoritative context to remember and feed into future profile regenerations.'}, 'store': {'type': 'string', 'description': 'Which store to correct (short or full domain). Required.'}, 'giftLed': {'type': 'boolean', 'description': 'True if products are typically bought as gifts for others; false for considered/self-purchase goods. Controls retail-calendar gift-event relevance.'}, 'audience': {'type': 'string', 'description': 'Who the customer is.'}, 'priceTier': {'enum': ['value', 'mid', 'premium'], 'type': 'string', 'description': 'Relative price positioning.'}, 'brandTerms': {'type': 'array', 'items': {'type': 'string'}, 'description': "Canonical brand terms (e.g. ['wills vegan','willsveganstore']) used to classify branded vs non-branded queries in get_connector_data(connector:'google-search-console', report:'branded_split'). Pin these when the auto-detected branded% looks wrong or differs between calls — pinned terms make the split deterministic across every caller. Accepts an array or a comma-separated string."}, 'positioning': {'type': 'string', 'description': 'How the store competes (e.g. ethical, budget, specialist).'}, 'primaryCategory': {'type': 'string', 'description': "Coarse category, e.g. 'Footwear', 'Skincare'."}}}

Ask AI

Qué hace este MCP

Herramientas

Cambios recientes en herramientas

Servidores MCP similares

Neonjelly

wildberries-agent-integration

AMZScout Skill + MCP

signals

Shopify Change Intelligence

Decision Intelligence

KDP Niche Research

Eevy