Polar Analytics

Create a new custom dimension for this tenant. A custom dimension is a rule-based (when/then/else) label derived from existing dimensions. **Prefer reusing an existing custom dimension.** Before calling this tool, inspect the `custom_dimensions` field returned by `get_context` and, if needed, fetch details via `get_custom_dimension_details`. Only create a new one if no existing dimension matches the user's intent semantically. ===== json payload shape (CustomDimension) ===== { "whenThen": [ { "when": [ WhenBlock, ... ], "then": [ "<label>" ] // array of bare strings }, ... ], "else": [ "<fallback label>" ] // array of bare strings } WhenBlock = { "lineOperator": "" | "and" | "or", // Trailing connector — joins this block to the NEXT one. // Last block always "". For multi-block whens, the first // and middle blocks carry "and"/"or"; only the final one is "". "leftValue": [ "dimension.<table>.<field>" ], // array, one entry "operator": "is" | "isNot" | "isInList" | "isNotInList" | "contains" | "notContains" | "containsCaseSensitive" | "notContainsCaseSensitive" | "startsWith" | "endsWith" | "lower" | "lowerOrEqual" | "greater" | "greaterOrEqual" | "isBefore" | "isAfter" | "isNull" | "isNotNull" | "isEmpty" | "isNotEmpty", "value": "<string>" // for isInList / isNotInList use a // comma-joined string: "US,CA,MX" } Required inputs: - conversation_id - title (short, human-readable name) - json (per the shape above) On success returns { id, title, editUrl }. The chat UI surfaces the editUrl as an "Open dimension editor" button on the tool-call card — do NOT repeat it as a markdown link in your visible response. Just tell the user the dimension was created and briefly describe what it groups.

Create a new custom metric for this tenant. A custom metric is a formula built from a sequence of `elements` (existing metric refs, operators, values). **Prefer reusing an existing metric.** Call `get_metrics` first with `custom-metrics` included to see what already exists; only create if no existing metric matches the user's intent semantically. Aggregation note: the formula is evaluated per-row then SUMmed at the outer query level (ratio-of-SUM for simple arithmetic). For division on same-source metrics the aggregation becomes SUM-of-ratio, which can surprise the user on multi-day granularity. ===== metricData payload shape ===== Required: title, elements, formatting. description is optional. elements: array of typed-object nodes. Every element is an OBJECT, never a bare string. Valid shapes: - Metric reference: { "type": "metric", "value": "<table>.raw.<key>" // e.g. shopify_sales_main.raw.gross_sales | "<table>.computed.<key>" | "custom_<N>", "filters": [] // optional; omit or [] // when no filters apply } - Arithmetic operator: { "type": "operator", "value": "+" | "-" | "*" | "/" | "(" | ")" | "x" } - Literal value (numeric constant inside the formula): { "type": "value", "value": "<number-as-string>" } // e.g. "2" - Line break (visual only, rare): { "type": "linebreak", "value": "" } Filters on a metric element (optional). Each filter is one of: - OR element: { "dimension": "<dimKey>", "operator": "IS" | "ISNOT" | "CONTAINS" | "NOTCONTAINS", "values": ["a","b"] } - AND group: an array of the OR elements above Empty array or omitted field = "no filter on this metric ref". formatting: REQUIRED object, one of four discriminated shapes: - { "type": "number", "numberType": "integer" | "decimal", "prefix"?: string, "suffix"?: string, "metricRepresentation"?: "higher_is_better" | "lower_is_better" } - { "type": "percent", "metricRepresentation"?: "higher_is_better" | "lower_is_better" } - { "type": "currency", "currency"?: string, // 3-letter ISO "metricRepresentation"?: "higher_is_better" | "lower_is_better" } - { "type": "timedelta", "metricRepresentation"?: "higher_is_better" | "lower_is_better" } Required inputs: - conversation_id - metricData (per shape above) On success returns { id, title, editUrl }. The chat UI surfaces the editUrl as an "Open metric editor" button on the tool-call card — do NOT repeat it as a markdown link in your visible response. Just tell the user the metric was created and briefly describe what it computes.

Delete an existing custom dimension. Deletion is permanent (hard delete); only the MCP audit log retains the payload for recovery. CRITICAL (non-self-created items): If you did NOT create this dimension in the current conversation, BEFORE calling this tool you MUST: 1. Call `get_custom_dimension_usages` to see what depends on it. If non-empty, tell the user in plain English what would be orphaned (names + types, not just counts) and stop — deletion is blocked anyway, so don't try. 2. If the usages list is empty, tell the user the dimension's name (and id, for reference) and ask whether to proceed with deletion. 3. Once the user gives a clear affirmation ("yes", "go ahead", "delete it", etc.), call this tool. You do NOT need the user to repeat the id. For items you created in the CURRENT conversation: delete freely when asked. The server also runs an in-use check; if any references exist it returns a `blockedBy` list. Relay that list to the user and stop — do not cascade or work around the block. Required inputs: - conversation_id - id (the custom_<N> id)

Delete an existing custom metric. Deletion is permanent (hard delete); only the MCP audit log retains the payload for recovery. CRITICAL (non-self-created items): If you did NOT create this metric in the current conversation, BEFORE calling this tool you MUST: 1. Call `get_custom_metric_usages` to see what depends on it. If non-empty, tell the user in plain English what would be orphaned (names + types, not just counts) and stop — deletion is blocked anyway, so don't try. 2. If the usages list is empty, tell the user the metric's name (and id, for reference) and ask whether to proceed with deletion. 3. Once the user gives a clear affirmation ("yes", "go ahead", "delete it", etc.), call this tool. You do NOT need the user to repeat the id. For items you created in the CURRENT conversation: delete freely when asked. The server also runs an in-use check; if any references exist it returns a `blockedBy` list. Relay that list to the user and stop — do not cascade or work around the block. Required inputs: - conversation_id - id (the custom_<N> id)

Generate a deep-link into the app in the form of a URL. These deep links contain visualizations and/or configuration screens that are pretty and user-friendly. Required inputs: - conversation_id Supported visualizations: - Tables (default, returned by generate_report, looks best with breakdowns present), - Line Charts (With date granularity) - Bar Charts (Without date granularity) - Pie Charts (Without date granularity) Tip: You can use generate_report to check what the result will be (only true if you use exactly the same arguments). Required inputs: - metrics (comma-separated keys exactly as received from the `metrics` field of the `get_context` tool), - dimensions (comma-separated keys exactly as received from the `breakdowns` field in list_dimensions), - dateRangeFrom/dateRangeTo (YYYY-MM-DD), - granularity (none|day|week|month|year), - settings (e.g. attribution model - pass empty object if non-attribution query) - ordering (comma-separated key-value pairs of key and direction) - rules (JSON string like {"country":[{"value":["US"],"operator":"IS"}]}), - metricRules (JSON string like {"shopify_sales_main.raw.total_orders":[{"operator":"GREATER","value":["0"]}]}), - views (comma-separated ids exactly as received from the `view` field of `list_dimensions`), - reflexion (your analysis of the user's goal and why you are generating this report). Output: JSON object containing the deep link. Always use the exact deep link, it only works if printed exactly.

Generate a comprehensive analytics report. Required inputs: - conversation_id, - metrics (comma-separated keys exactly as received from the `metrics` field of the `get_context` tool), - dimensions (comma-separated keys exactly as received from the `breakdowns` field in list_dimensions), - dateRangeFrom/dateRangeTo (YYYY-MM-DD), - ordering (comma-separated key-value pairs of key and direction) - granularity (none|day|week|month|year), - settings (e.g. attribution model - pass empty object if non-attribution query) - rules (JSON string like {"country":[{"value":["US"],"operator":"IS"}]}), - metricRules (JSON string like {"shopify_sales_main.raw.total_orders":[{"operator":"GREATER","value":["0"]}]}), - views (comma-separated ids exactly as received from the `view` field of `list_dimensions`), - limit (optional, integer): Max rows to return (default 1000). ALWAYS set an explicit limit appropriate to the query — for browsing/listing choose a single integer between 10 and 25, for analysis use only as many rows as needed. Fetching too many rows wastes context. The full dataset is always available via the returned deep link. - comparisonPeriod (optional): Compare against a previous period. Values: previousPeriod (same duration before current range), previousYear, previousMonth, or range (requires comparisonDateRangeFrom/To). - comparisonDateRangeFrom/comparisonDateRangeTo (optional, YYYY-MM-DD): Custom comparison date range, only used when comparisonPeriod is "range". Output: JSON report table data, totals data and a deep link to display the same table (with totals) in-app. When comparison is requested, also returns compareTableData, compareTotalData, and comparisonDateRange. Only include attribution_model in settings when generating reports that involve marketing channel attribution or cross-channel analysis. For Shopify metrics (sales, orders, product data, customer segments), pass an empty settings object if you do not know the attribution model. Totals data: returns a row of totals for every metric in the metrics list. Always use these provided totals; do not recompute sums yourself unless you really need to. For grouped/segmented reports (e.g., “top 5 cities”), sum the returned rows and verify they never exceed the corresponding server totals; if there’s a mismatch, prefer the server totals and call it out as a reconciliation note. For ungrouped reports, display the returned totals directly. When presenting percentages or shares, compute them as row_value / total_value (not from independently summed rows) If a total is missing for a metric, state that totals are unavailable and avoid inferring them. When the data is useful, include the exact deep link so the customer can explore further on their own in-app. Use the 👉 emoji to make it very clear that it's a link. Use generate_app_report_link to generate other links or visualizations as needed. If you got the report from an element in the `get_dashboard_details` tool, use those deep links. This shouldn't prevent you from generating an artifact with other content if needed, the goal is for the user to link to the Polar report if they want to validate the data or explore further. After responding, ask user for a 1-10 rating, then call rate_report. Gating: this tool refuses with `{ error: true, reason: "needs_activation" | "needs_connectors", message, book_call_url, connectors_url }` when `account_status` from `get_context` indicates the tenant is not yet activated or has no loaded connector data. Don't retry on the same tenant in the same conversation — deliver the message verbatim or paraphrase, point the user at the URL, and stop.

Detailed per-account connector health from /api/datasources/statuses. Use this to drill into the rollup returned by get_context.connectors when the user asks why a connector is Warning/Broken/Syncing history, or to compose remediation prose. Each entry is { key, health, connections, accounts[] }. connections is the per-status breakdown of this connector's accounts (sparse — absent keys mean zero). accounts[] carries { datasource_id, account_name, health, issues, last_completed_sync_at, data_available_through, timezone, data_integrity }. data_integrity is a rollup of the account's data integrity checks: { ok, failed, total } counts, or null when no check signal is available. "ok" includes both exact matches and within-tolerance results — both pass from the user's perspective. For the per-check breakdown (name, status, match rate, in/out-of-tolerance days), call get_data_integrity_report({ datasource_id }). health is one of: healthy | syncing_history | warning | broken | paused | pending. The connector-level health is the worst across its accounts (except all-paused → paused). issues[] is a structured array. Compose the prose yourself from the kind: - error: { kind: "error", message } — generic plumbing error surfaced verbatim from the connector - needs_setup: account is connected but no sub-account is selected; user should finish setup - missing_scopes: { kind: "missing_scopes", scopes } — the connector is missing OAuth scopes; user should reconnect granting these scopes - delayed: no sync today past the morning threshold in the connector's timezone; surface to the user. Hourly-refresh staleness is not flagged until the team calibrates a per-pipeline threshold. - drift_summary: { kind: "drift_summary", failed_count, tolerated_count, total_count } — at least one data integrity check failed (its match rate is below the threshold). Tell the user "X of Y checks failed" (the wording the data integrity report uses) and link to the report. tolerated_count is informational only; those days are within tolerance and the user sees them as "OK". - drift_verified: { kind: "drift_verified", tolerated_count, total_count } — every data integrity check passed (some may be within tolerance, which the user sees as "OK"); surface as positive reassurance, do not flag as a problem Never speculate about lag from last_completed_sync_at alone — only act on explicit issues[] entries. Deep-link pattern (do NOT slugify account names): /connectors/<connector-key> — connector page /connectors/<connector-key>/<datasource_id> — specific account row, where datasource_id is the UUID from accounts[].datasource_id /connectors/<connector-key>/<datasource_id>/data-integrity — data integrity report (full pass/fail breakdown + drill-down per check) Example: /connectors/facebook-ads/8f3a1c0e-44d6-4d8a-9f8b-7c2a1e5d9a40 Required input: conversation_id (from get_context). Optional: connectorKeys to narrow the response to a subset of connectors from get_context.connectors.

Run this tool once at the beginning of each conversation to prepare the analytics environment. It returns a combined JSON object with five elements: conversation_id: Conversation ID context: Workspace context { currency, timezone, brand_name (if none is set, it defaults to the email of the first registered user, often the brand’s domain, sometimes a personal email) }; account_status: { activation: 'pending_call' | 'call_booked' | 'activated', data: 'none' | 'loading' | 'ready', book_call_url, connectors_url, message } describing whether the tenant is activated and whether their data is loaded. If activation is not 'activated', tell the user to book the setup call at book_call_url before doing anything else — booking is the highest-priority next step and data tools will refuse until activation completes. Otherwise, if data is not 'ready', tell the user to connect data sources at connectors_url. The 'message' field is a ready-to-deliver explanation; surface it verbatim or paraphrase, but always include the relevant URL. When account_status.message is non-empty, deliver it before any analytics work; connectors: Canonical per-connector rollup. Each entry { key, health, connections } where health is one of healthy | syncing_history | warning | broken | paused | pending (worst across accounts; all-paused → paused). connections is the per-status breakdown of this connector's accounts — only includes health states with at least one account, absent keys mean zero. Total account count = sum of connections values. When any connector is warning, broken, or syncing_history, mention it to the user and offer the deep link. Call get_connector_statuses to drill into specific connectors and compose remediation prose from the structured issues[]. polar-pixel appears in this list like any other connector — health syncing_history means it is still warming up; healthy means it has matured. Note: the canonical health currently only surfaces daily delay signals (no sync today past the morning threshold in the connector's timezone). Hourly-refresh staleness is not flagged until the team calibrates a per-pipeline threshold. Do not speculate about lag from last_completed_sync_at alone; act only on explicit issues[]. custom_connectors: Array of { key } for connectors that have queryable data tables but no live monitoring (custom imports, data warehouses, legacy entries). Treat their health as unknown — never claim they are healthy or broken. connector_status: DEPRECATED — superseded by 'connectors' and 'custom_connectors'. Kept only for backward compatibility and will be removed in a future MCP version. Prefer 'connectors' for health and 'get_connector_statuses' for detail. Legacy shape: array of { name, status, until } where status is 'historical' (data not ready), 'incremental' (data ready up to 'until'), or 'paused' (data exists but syncing is paused — reports use data up to 'until'). Customers can manage connectors at https://app.polaranalytics.com/connectors. If a polar-pixel legacy entry has is_warmed_up=false, the pixel needs attention. Open your final answer with a bold data-quality warning before any numbers. If installed_at is a date, say the pixel is still warming up (give installed_at as the install date) and conversion / attribution numbers aren't statistically meaningful yet — suggest letting it accumulate for at least a couple of weeks before drawing conclusions, with the actual time depending on traffic volume and industry. If installed_at is null, say the pipeline last produced data on polar-pixel 'until' and may not be currently flowing — numbers may be stale. Deep-link pattern for the Connectors area (use canonical 'connectors' key and accounts[].datasource_id from get_connector_statuses; never slugify account names): https://app.polaranalytics.com/connectors/<connector-key> for a connector page, https://app.polaranalytics.com/connectors/<connector-key>/<datasource_id> for an account row. Example: https://app.polaranalytics.com/connectors/facebook-ads/8f3a1c0e-44d6-4d8a-9f8b-7c2a1e5d9a40. custom_dimensions: Initial page of the tenant's custom dimensions — the 50 most recently created/updated. Each entry carries { id, label } plus ONE of: - summary: human-readable one-line purpose (preferred when authored or AI-summarized) - refs: array of underlying dimension field names the formula touches (e.g. ["billing_country"]). Use as a structural hint when no summary exists — a clumsy label like "geo v2 jamie" with refs ["billing_country"] is very likely a country grouping. Match on label + summary + refs together when judging whether an existing dimension already covers the user's intent. Before calling `create_custom_dimension`, scan this list and reuse whenever one matches. The full whenThen formula is NOT inlined; call `get_custom_dimension_details(id)` to fetch it for any candidate worth inspecting. For older or oddly-named dimensions beyond this initial page, call `list_custom_dimensions(q?, offset?, limit?)` — paginated + searchable by case-insensitive substring on title and summary. If the user references a dimension by name and you don't see it here, search via list_custom_dimensions before creating a duplicate. views: Views list as an array of { id, title }. Always call this tool first before proceeding with any other analytics requests. Required input: - initialQuestion (user's initial prompt, stated exactly as received) - version (Always pass 3.8) If a warning is included in the response, you must display it prominently.

Used to discover what filtering a custom dimension does. Note: When the user is only looking to use the custom dimension and it's clear which custom dimension they're referring to, looking up its details is superflous. Required inputs: - conversation_id - id (the id of a custom dimension, exactly as obtained from the `custom_dimensions` field of `get_context`) Returns the custom dimension with its definition (rules and connector filters).

List every tenant-owned object that currently depends on a given custom dimension — reports, custom metrics, and KI sections. MUST be called before any `update_custom_dimension` or `delete_custom_dimension` attempt on a dimension that was NOT created in the current conversation. Use the result to tell the user in plain English what the change would affect (e.g. "This dimension is used by 3 reports and 1 KI section — these are the names…") before asking for confirmation. Returns { usages: [{ id, title, type: "report" | "custom_metric" | "ki_section" }] }. An empty list means nothing currently depends on it. Required inputs: - conversation_id - id (the custom_<N> id of the dimension)