Ask AI

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

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

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

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

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

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

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

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

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

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

Save a 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.

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

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

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

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

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

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.