ANSWER FIRST for any 'how is everything doing' / 'what should I look at' / 'give me a status' question across the user's whole workspace. Returns fleet totals (visitors, events, % vs prior period), status breakdown (live/active/quiet/no_events), a prioritized 'needs attention' list (sites without events, sites that suddenly went quiet, big down-movers), top movers (by absolute % change, volume-gated to ignore tiny-volume noise), and AI-traffic leaders. Default range last_7_days. Lead the response with fleet_totals, then needs_attention if non-empty, then top_movers. Don't repeat the raw numbers — paraphrase them.

Rank sites by signed % visitor change vs the prior period. Use for 'which sites are growing/declining', 'biggest movers', 'what's trending'. direction='up' returns growers only, 'down' returns decliners only, 'both' (default) returns the biggest movers regardless of direction. Volume-gated: sites with under 20 visitors in either period are excluded (their % deltas are noise — count is in excluded_low_volume).

Find sites that look abandoned: classified as 'never_installed' (site exists but has never fired an event — most likely the tracker isn't installed) or 'went_silent' (used to get traffic, last seen N+ days ago). Default quiet_days=7. Use for 'which sites are dead', 'what should I delete', 'what needs investigating'. Returned in priority order: never_installed first (most actionable: just install the tracker), then longest-silent.

Find unusually high or low traffic days across sites using per-site z-score. For each site, computes the mean and stddev of daily visitors over the range, then flags any day where |z| ≥ threshold (default 2.5, ~1-in-100). Use for 'anything weird?', 'spikes this week', 'show me unusual traffic'. Pass site_id to scope to one site, otherwise scans the whole fleet. Returns most-recent anomalies first. Sites under 20 visitors total are skipped (not enough signal).

ANSWER FIRST for any 'why did traffic [spike/drop/change]' question on a specific site. Pulls overview + deltas, the top 5 page gainers and losers vs prior period, the top 5 referrer gainers and losers, anomaly-day callouts (z-score ≥ 2), and the daily series so you can name the actual day things broke. Use the gainers/losers lists to attribute the change — if one page or referrer dominates the delta, call it out by name. Don't paste the raw arrays at the user; paraphrase: 'traffic dropped 22% — almost entirely driven by /pricing losing 1,400 visitors after Reddit traffic dried up on Wednesday.'

ANSWER FIRST for any 'add analytics' / 'install analytics' / 'set up analytics' / 'add tracking to my app' request — this is the one-call install workflow that bundles site creation + framework-specific snippet + paste-target file path + post-install next steps. Strongly preferred over chaining create_site → get_install_snippet → etc., because the LLM doesn't have to plan orchestration. Pass domain (the user's site), framework if known (next/react/vite/remix/astro/nuxt/sveltekit/html — detect by reading their package.json + config files: next.config.* → next, nuxt.config.* → nuxt, svelte.config.* → sveltekit, astro.config.* → astro, @remix-run/* dep → remix, vite.config.* → vite, otherwise react or html), and event_hint if the user mentioned a specific event to track (e.g. 'track signups' → event_hint='signup'). Returns: the install snippet, the EXACT file to edit (paste_target.file), an example custom-event snippet (if event_hint passed), and a machine-readable next_actions array. Workflow for the agent: (1) edit paste_target.file to insert snippet.code, (2) mention privacy_policy.reminder, (3) ask if they want the badge, (4) call verify_install once they deploy, (5) offer event tracking if they mentioned conversions.

ANSWER FIRST for 'what sites do I have in Gizmo?', 'list my sites', 'show me my projects', 'which domains am I tracking?'. Returns every site in the workspace with id, domain, createdAt, and current ignored status. Optional tag filter narrows to one group. Use the returned site.id when calling get_site_traffic, get_install_snippet, verify_install, etc. Cheap call — no events touched.

Register a domain in Gizmo and return the install snippet. For first-time install asks ('add analytics', 'install Gizmo', 'set up tracking'), prefer setup_analytics_for_site — it bundles this call + the paste target + next-step suggestions in one response. Use create_site directly when the user only wants the site row created (e.g. 'add foo.com to my Gizmo workspace without installing yet') or when integrating from another tool that's already orchestrating its own install flow. Pass the framework matching the user's project (next/react/vite/remix/astro/nuxt/sveltekit/html). Returns site row + install snippet + privacy_policy reminder + optional badge.

Re-fetch the framework-specific install snippet for an existing site. Use this when the snippet was printed earlier but never installed, when the user switched frameworks, or when they ask 'where's the gizmo install snippet for foo.com?', 'how do I install Gizmo on this project?', 'show me the tracking code'. Supports: next, react, vite, remix, astro, nuxt, sveltekit, html. Same install-vs-print rule as create_site: if the user asked to install / add / set up, EDIT the file the snippet.instructions field names rather than printing the snippet.

ANSWER FIRST for any 'is it working?', 'did the install work?', 'is Gizmo tracking my site?', 'verify analytics setup', 'check if it's installed' question — typically asked right after create_site / get_install_snippet. Fetches the site's homepage and scans for the tracker script. Returns one of: {installed: true} (script tag found, with the publicKey we issued), {installed: false, reason} (page loaded but no tag — usually means the snippet wasn't placed or the build wasn't deployed yet), or {error} (fetch blocked / timed out / Cloudflare challenge — common on sites behind strict bot defense; doesn't necessarily mean it's broken). Tell the user the result honestly: 'Confirmed working' if installed; 'Couldn't find the script — did you deploy?' if no_tag; 'Couldn't reach the site (Cloudflare / bot block) — but if events are landing in the dashboard you're fine' on error.

Return the official "Powered by Gizmo" footer badge as a single anchor tag. Call this when the user asks to add a badge, link back, or thank Gizmo. INSTALL RULES: place the badge inline inside the user's existing footer next to their copyright line (e.g. "© 2026 acme. Powered by Gizmo."). Do NOT wrap the snippet in a card, box, or extra styling — it intentionally inherits font-size and color from the surrounding text so it matches the user's design. Do NOT separate the badge onto its own row above/below the footer; it belongs ON the copyright line. The snippet is one tag with inline styles; edit the user's footer component / template directly to insert it. The badge href includes ?ref=badge so Gizmo can attribute traffic back.

Return the JavaScript snippet for firing a custom event from the user's site code (e.g. window.gizmo("signup", {plan:"pro"})). Call this when the user says 'track signups', 'fire an event when someone clicks X', 'add custom event for Y', 'how do I track Z' — anything that means instrumenting a custom event in their codebase. The tracker script must already be installed (create_site or get_install_snippet handles that). After this call returns, EDIT the user's code to insert the snippet at the right code path — a click handler, a form-submit success branch, a router-change effect, etc. — based on what they're tracking. Don't just print the snippet; place it. Pass properties for any dimensions you want to break down later (plan, sku, variant, etc.); the dashboard can then roll up event counts by property via breakdown_by_property. Event name and property keys must be 1–64 chars, letters/digits/underscore (event name also allows dot and dash).

ANSWER FIRST for 'tag this site as X', 'organize my sites', 'group sites by client/project/type'. Attaches one or more free-form tags to a site (creates the tag if new). Use to organize a fleet — e.g. tag every client project with the client name, tag side projects 'personal', tag staging environments 'staging'. Pair with filter_sites_by_tag to drill into one group.

ANSWER FIRST for 'show me my [tag] sites', 'list sites tagged X', 'which sites are tagged Y?'. Returns every site in the workspace that has the given tag. Pairs with add_site_tags for fleet organization. Identical to list_sites({tag: ...}) — exposed as a separate tool because the verb 'filter' triggers naturally when users phrase the ask that way.

Create a conversion goal for a site. type='path' matches sessions that visit a path-prefix; type='event' matches sessions that fire a named custom event. Use this when the user says 'track signups as a goal', 'add a goal for /thank-you', etc. Goals show up on the site dashboard with conversion count + rate.

ANSWER FIRST for 'what's my conversion rate?', 'how many signups this week?', 'show me my goals', 'are my conversions up or down?'. Lists every goal defined for a site with conversion count + rate over the date range. Pair with create_goal first if the user hasn't defined any goals yet.

Remove a conversion goal by id. Use when the user says 'delete the X goal', 'remove that conversion goal', 'I don't track that anymore'. Destructive — confirm the user means it before calling; the historical conversion data attached to the goal disappears with it.

Create a multi-step funnel for a site. Steps run in order — a session 'reaches' step N if it matched all of steps 0..N within the same session (30-min idle gap). Use this when the user says 'track the pricing → signup funnel' or describes a sequence. type='path' matches a path-prefix; type='event' matches a named custom event. Min 2 steps, max 10.

ANSWER FIRST for 'where are users dropping off?', 'show me the funnel', 'how's my signup flow doing?', 'what's my conversion funnel?'. Lists every funnel defined for a site with per-step reached counts + drop-off rate between steps. Surface the biggest drop as the headline — that's usually where the opportunity is. Pair with create_funnel first if the user hasn't defined any funnels yet.

Remove a funnel by id. Use when the user says 'delete the X funnel', 'remove that flow', 'I'm not tracking that anymore'. Destructive — confirm before calling.

Aggregate metrics across all sites in the workspace (visitors, pageviews, sessions, bounce rate, top sites). Supports filters and custom date ranges.

Optional dimension filters. Each filter is {dim, op, value}. Available dims: page, entry_page, exit_page, referrer, hostname, channel, ai_source, utm_source, utm_medium, utm_campaign, country, region, city, language, device, browser, screen, event_name, or prop:. Available ops: is, is_not, contains, not_contains. Filters AND together. Example: [{dim:'country', op:'is', value:'US'}, {dim:'device', op:'is_not', value:'mobile'}].

Optional date range. Either {preset:'last_7_days'} (also: today, yesterday, last_14_days, last_30_days, last_90_days, last_year, month_to_date, last_month, all_time) OR {from:'2026-05-01', to:'2026-05-15'} for a custom range (ISO 8601 dates or timestamps). Defaults vary by tool.

Traffic metrics for a single site (overview + top pages + top referrers). Supports filters and custom date ranges.

Optional dimension filters. Each filter is {dim, op, value}. Available dims: page, entry_page, exit_page, referrer, hostname, channel, ai_source, utm_source, utm_medium, utm_campaign, country, region, city, language, device, browser, screen, event_name, or prop:. Available ops: is, is_not, contains, not_contains. Filters AND together. Example: [{dim:'country', op:'is', value:'US'}, {dim:'device', op:'is_not', value:'mobile'}].

Optional date range. Either {preset:'last_7_days'} (also: today, yesterday, last_14_days, last_30_days, last_90_days, last_year, month_to_date, last_month, all_time) OR {from:'2026-05-01', to:'2026-05-15'} for a custom range (ISO 8601 dates or timestamps). Defaults vary by tool.

Top page paths by event count. Supports filters (e.g. country=US) so you can answer "top pages from Germany." Pass site_id to scope to one site.

Optional dimension filters. Each filter is {dim, op, value}. Available dims: page, entry_page, exit_page, referrer, hostname, channel, ai_source, utm_source, utm_medium, utm_campaign, country, region, city, language, device, browser, screen, event_name, or prop:. Available ops: is, is_not, contains, not_contains. Filters AND together. Example: [{dim:'country', op:'is', value:'US'}, {dim:'device', op:'is_not', value:'mobile'}].

Optional date range. Either {preset:'last_7_days'} (also: today, yesterday, last_14_days, last_30_days, last_90_days, last_year, month_to_date, last_month, all_time) OR {from:'2026-05-01', to:'2026-05-15'} for a custom range (ISO 8601 dates or timestamps). Defaults vary by tool.

Top referrer hostnames by event count. Supports filters (e.g. device=mobile) so you can answer "top referrers from mobile users." Pass site_id to scope to one site.

Optional dimension filters. Each filter is {dim, op, value}. Available dims: page, entry_page, exit_page, referrer, hostname, channel, ai_source, utm_source, utm_medium, utm_campaign, country, region, city, language, device, browser, screen, event_name, or prop:. Available ops: is, is_not, contains, not_contains. Filters AND together. Example: [{dim:'country', op:'is', value:'US'}, {dim:'device', op:'is_not', value:'mobile'}].

Optional date range. Either {preset:'last_7_days'} (also: today, yesterday, last_14_days, last_30_days, last_90_days, last_year, month_to_date, last_month, all_time) OR {from:'2026-05-01', to:'2026-05-15'} for a custom range (ISO 8601 dates or timestamps). Defaults vary by tool.

Top-N for any column-backed dimension: page, referrer, country, region, city, browser, device, language, screen, channel, ai_source, hostname. Use this for "top countries / browsers / devices / channels / AI sources / cities / etc." — anything in the dashboard's breakdown tabs. For custom event properties (UTM rollups, plan splits, anything you ship in event JSON), use breakdown_by_property instead. Filters and custom date ranges supported.

Optional dimension filters. Each filter is {dim, op, value}. Available dims: page, entry_page, exit_page, referrer, hostname, channel, ai_source, utm_source, utm_medium, utm_campaign, country, region, city, language, device, browser, screen, event_name, or prop:. Available ops: is, is_not, contains, not_contains. Filters AND together. Example: [{dim:'country', op:'is', value:'US'}, {dim:'device', op:'is_not', value:'mobile'}].

Optional date range. Either {preset:'last_7_days'} (also: today, yesterday, last_14_days, last_30_days, last_90_days, last_year, month_to_date, last_month, all_time) OR {from:'2026-05-01', to:'2026-05-15'} for a custom range (ISO 8601 dates or timestamps). Defaults vary by tool.

Query raw events. Default returns the latest 100; max 1000 per call. For large analyses, paginate by date_range. Filters supported.

Optional dimension filters. Each filter is {dim, op, value}. Available dims: page, entry_page, exit_page, referrer, hostname, channel, ai_source, utm_source, utm_medium, utm_campaign, country, region, city, language, device, browser, screen, event_name, or prop:. Available ops: is, is_not, contains, not_contains. Filters AND together. Example: [{dim:'country', op:'is', value:'US'}, {dim:'device', op:'is_not', value:'mobile'}].

Optional date range. Either {preset:'last_7_days'} (also: today, yesterday, last_14_days, last_30_days, last_90_days, last_year, month_to_date, last_month, all_time) OR {from:'2026-05-01', to:'2026-05-15'} for a custom range (ISO 8601 dates or timestamps). Defaults vary by tool.

Time-bucketed visitors / pageviews / events for a date range. Returns one row per bucket. Bucket auto-resolves to hour for windows ≤ 48h, day otherwise — pass bucket to override. Optional site_id scopes to a single site. Filters supported.

Optional dimension filters. Each filter is {dim, op, value}. Available dims: page, entry_page, exit_page, referrer, hostname, channel, ai_source, utm_source, utm_medium, utm_campaign, country, region, city, language, device, browser, screen, event_name, or prop:. Available ops: is, is_not, contains, not_contains. Filters AND together. Example: [{dim:'country', op:'is', value:'US'}, {dim:'device', op:'is_not', value:'mobile'}].

Optional date range. Either {preset:'last_7_days'} (also: today, yesterday, last_14_days, last_30_days, last_90_days, last_year, month_to_date, last_month, all_time) OR {from:'2026-05-01', to:'2026-05-15'} for a custom range (ISO 8601 dates or timestamps). Defaults vary by tool.

ANSWER FIRST for 'how many [X] signups by plan?', 'split [event] by [property]', 'pro vs free signups', 'sales by SKU', 'newsletter signups by source' — anything that means grouping a CUSTOM event property the user previously instrumented with get_event_tracking_snippet. Property name must match [A-Za-z0-9_.-]{1,64}. For built-in dimensions (country, browser, device, channel, AI source, city, etc.) use get_breakdown instead. Returns top values for the property with visitor counts.

Optional date range. Either {preset:'last_7_days'} (also: today, yesterday, last_14_days, last_30_days, last_90_days, last_year, month_to_date, last_month, all_time) OR {from:'2026-05-01', to:'2026-05-15'} for a custom range (ISO 8601 dates or timestamps). Defaults vary by tool.