Polar Analytics

Create a new custom dimension for this workspace. A custom dimension labels rows via when/then/else rules AND can compute derived values with functions (split, concat, regex, date and math operations) in any value block — it is NOT limited to matching discrete values. **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": ValueBlock }, ... ], "else": ValueBlock } 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": ValueBlock, // usually [ "dimension.<table>.<field>" ] "operator": "contains" | "containsCaseSensitive" | "notContains" | "notContainsCaseSensitive" | "startsWith" | "endsWith" | "lower" | "lowerOrEqual" | "greater" | "greaterOrEqual" | "is" | "isAfter" | "isBefore" | "isEmpty" | "isInList" | "isNot" | "isNotEmpty" | "isNotInList" | "isNotNull" | "isNull", "value": "<string>" // for isInList / isNotInList use a // comma-joined string: "US,CA,MX" } ValueBlock = a prefix-notation expression, serialized as a flat array of strings. Each entry is one of: - "operation.<FN>" — a function call; its parameters are the entries that follow, consumed in declaration order. Nest by placing another "operation.<FN>" where a parameter is expected. - "dimension.<table>.<field>" — a dimension reference ("dimension.*.<field>" matches the field on any table). - any other string — a literal. Numbers are passed as strings ("1"). A plain label is a single-literal ValueBlock: [ "<label>" ]. Available functions (token(params) -> returns): operation.LEFT(value, length) -> string operation.RIGHT(value, length) -> string operation.LOWER(value) -> string operation.UPPER(value) -> string operation.CONCAT(value1, value2) -> string operation.TRIM(value) -> string operation.REPLACE(subject, pattern, replacement) -> string operation.DATEDIFF(date_part, date1, date2) -> integer operation.DATEFORMAT(date, format_string) -> string operation.DATEADD(date_part, amount, date) -> date operation.DATETRUNC(date_part, date) -> date operation.POW(base, exponent) -> number operation.DIV0(dividend, divisor) -> number operation.MOD(dividend, divisor) -> number operation.ABS(expression) -> number operation.FLOOR(expression) -> integer operation.CEIL(expression) -> integer operation.ROUND(expression) -> integer operation.SPLIT_PART(string, delimiter, part number) -> string operation.DATE(datetime) -> date operation.CONVERT_TIMEZONE(string, datetime) -> datetime operation.CURRENT_TIMESTAMP() -> datetime operation.DAY(date) -> integer operation.DAYOFWEEK(date) -> integer operation.DAYNAME(date) -> string operation.WEEK(date) -> integer operation.MONTH(date) -> integer operation.MONTHNAME(date) -> string operation.QUARTER(date) -> integer operation.YEAR(date) -> integer operation.REGEXP(subject, pattern) -> string Note: operation.REGEXP compiles to Snowflake REGEXP_SUBSTR(subject, pattern, 1, 1, 'i', 1) — case-insensitive, first match, extracting capture group 1. The pattern MUST contain a capturing group (parentheses); without one the function returns NULL for every row. Example — "CC#" = first three dash-delimited parts of a SKU (NK-108-01K4-0 -> NK-108-01K4): { "whenThen": [{ "when": [{ "lineOperator": "", "leftValue": ["dimension.shopify_sales_main.sku"], "operator": "isNotEmpty", "value": "" }], "then": ["operation.REGEXP", "dimension.shopify_sales_main.sku", "^([^-]+-[^-]+-[^-]+)"] }], "else": ["Other"] } Nested functions — CONCAT(SPLIT_PART(sku, "-", 1), "-suffix"): ["operation.CONCAT", "operation.SPLIT_PART", "dimension.shopify_sales_main.sku", "-", "1", "-suffix"] IMPORTANT — availability: at least one when-block leftValue must reference a "dimension.<table>.<field>" entry. Dimension dependencies are collected from when-blocks only; a custom dimension without any never surfaces in the breakdown list. Anchor formula-only dimensions with a guard such as WHEN <field> isNotEmpty THEN <formula>. 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 workspace. 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.

Returns a short-lived, credential-free URL to upload ANY file (CSV, PDF, image, JSON, …) and the public link to share once it's uploaded. Use this to send a file the merchant can open. How it works (two steps — never put file contents into this call): 1. Call this tool with the file's name. It returns { upload_url, file_url }. 2. Upload the file's BYTES straight to upload_url with the baked helper: python3 /opt/hermes/polar-upload-file.py <local_path> "<upload_url>" then put file_url in your reply. (file_url is a CDN link the merchant can open; images unfurl inline in Slack.) Why not pass the file to a tool directly: tool arguments travel through the model's output, so a file encoded into a call is truncated and arrives corrupt. This path sends the bytes from disk straight to storage, so any size / type works.

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)

Reads a connector the workspace has already connected directly from its provider API, bypassing Polar's warehouse. Always prefer Polar's warehoused data through generate_report whenever it can answer the question, including when the requested range contains today or the last few hours. Recency alone is not a reason to use this tool. Use this tool at your discretion only when at least one of these is true: - the user explicitly asks for live data, provider-side data, or a direct API read - the answer requires a metric, field, breakdown, or current entity state that the warehouse does not expose but one of the connector's live operations does - the answer materially depends on data newer than the relevant account's warehouse coverage When freshness could change the answer, call get_connector_statuses first. Compare the requested period with the account's data_available_through in its timezone; that field is the warehouse coverage boundary, while last_completed_sync_at is not. Prefer generate_report for the covered period and use this tool only for the necessary uncovered portion. This also applies to a freshly connected account that is still backfilling. A user saying "from Meta" or "from Google" names the source, not necessarily the live API — Polar's warehouse already contains that source's data. If the user explicitly asks for live or API-side figures ("read the API directly", "what does Meta itself report"), honour that for any range within the caps. State when figures came from the provider API rather than Polar's warehouse, and do not silently combine the two when their metric definitions or currencies differ. Warehouse reads are faster, cheaper, historically consistent, and model the metrics shown in Polar; live reads spend the workspace's provider API quota, which its syncs also depend on. Connectors that support live reads: Meta (Facebook Ads) — connector_key "facebook-ads" Google Ads — connector_key "google-ads" Google Analytics 4 — connector_key "google-analytics-four" Amazon Seller Central — connector_key "amazon-selling-partner" Amazon Vendor Central — connector_key "amazon-vendor-central" Amazon Ads — connector_key "amazon-ads" TikTok Ads — connector_key "tiktok-ads" Shopify — connector_key "shopify" Klaviyo — connector_key "klaviyo" Google Sheets — connector_key "google-sheets" Google Search Console — connector_key "google-search-console" Instagram Business — connector_key "instagram-business" Facebook Pages — connector_key "facebook-pages" Microsoft Advertising (Bing Ads) — connector_key "bing-ads" Custom integrations — connector_key "custom" (workspaces that have AI-built custom datasources; datasource_id is REQUIRED, and each custom datasource declares its own operations — describe lists them). Every source listed under custom_connectors in your context IS one of these: Superfiliate, ShopMy, AppLovin and the like are read with connector_key "custom" plus their datasource_id. Never conclude a named custom source lacks live reads without running describe against its datasource — calling without datasource_id lists the workspace's custom datasources by name. Discover a connector's operations before the first read: call this tool with operation "describe" — it returns one row per operation with its summary, exact params object (defaults included) and row fields. Pass params: { operation: "<name>" } to narrow to one operation. Validation errors also name the valid values, so a wrong guess is corrected in one step. Inputs: conversation_id (from get_context), connector_key, operation, params (the operation's own object, as documented by describe), and optionally datasource_id to scope to one connected account — get_connector_statuses lists the datasource_ids for native connectors. Omitted on a native connector, the read covers every connected account at once (up to 5; each row then carries account_label); omitted on connector_key "custom", the call lists the workspace's custom datasources by name instead of reading. Returns { rows, row_count, truncated, notes, fetched_at, cached, account_label }. rows follow the operation's row fields as documented by describe. notes carry provider-side caveats and must be reflected in your answer when they qualify the numbers. When a row carries a currency field, report figures in that currency, not the workspace reporting currency. Credentials are never exposed here: the request carries identifiers only and the read happens server-side.

Generates a deep-link URL into the app. These deep links open visualizations and configuration screens that are designed for end-user consumption. Required inputs: - conversation_id Supported visualizations: - Tables (default, returned by generate_report; best when breakdowns are present) - Line Charts (with date granularity) - Bar Charts (without date granularity) - Pie Charts (without date granularity) Calling generate_report with the same arguments returns the dataset that the link will display. 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 (one of: none, day, week, month, year), - settings (for example attribution model; pass an empty object for non-attribution queries) - 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 (analysis of the user's goal and the rationale for generating this report). Output: JSON object containing the deep link. The deep link is an opaque URL that must be reproduced verbatim.

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. Drills into the rollup returned by get_context.connectors when more detail is needed on why a connector is Warning, Broken or Syncing history. 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. The per-check breakdown (name, status, match rate, in/out-of-tolerance days) is available via 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 non-paused accounts, with the exception that an all-paused connector reports paused. A connector or account in warning, broken, or syncing_history state is a data-quality condition relevant to any numbers derived from it. A paused (deactivated) account always reports paused even when it has unresolved errors underneath — the user paused it on purpose, so it does not belong in a "needs attention"/broken rundown. Its issues[] are still listed so the user knows reconnecting won't help until they fix and unpause it. issues[] is a structured array describing the conditions that drive each account's health: - error: { kind: "error", message }: generic plumbing error surfaced verbatim from the connector. - needs_setup: account is connected but no sub-account is selected; setup is incomplete. - missing_scopes: { kind: "missing_scopes", scopes }: the connector is missing OAuth scopes and needs to be reconnected granting these scopes. - delayed: 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. - drift_summary: { kind: "drift_summary", failed_count, tolerated_count, total_count }: at least one data integrity check has a match rate below the threshold. The data integrity report describes this as "X of Y checks failed". tolerated_count is informational; 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"). For deciding whether a requested period extends beyond Polar's warehoused data, data_available_through is the coverage boundary for that account; interpret it in the account's timezone. last_completed_sync_at is an operational sync timestamp, not a warehouse coverage cutoff, and must not be used as a substitute. For connector health and delay warnings, explicit issues[] entries remain the canonical source. Deep-link pattern (account names are not slugified): /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 plus per-check drill-down) 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.

Prepares the analytics environment for a conversation and returns the workspace context required by every other tool. It returns a combined JSON object with the following elements: conversation_id: Conversation identifier consumed verbatim by the other tools in this session. context: Workspace context { currency, timezone, brand_name } (brand_name defaults to the email of the first registered user when no company name is set: often the brand's domain, sometimes a personal email). account_status: { activation, data, book_call_url, connectors_url, message } describing whether the workspace is activated and whether its data is loaded. activation is one of 'pending_call', 'call_booked', 'activated'. data is one of 'none', 'loading', 'ready'. When activation is not 'activated', booking the setup call at book_call_url is the prerequisite next step and data tools will refuse the request. Otherwise, when data is not 'ready', connecting data sources at connectors_url is the prerequisite. The 'message' field is a ready-to-deliver explanation that pairs with the relevant URL. connectors: Canonical per-connector rollup. Each entry { key, health, connections } where health is one of healthy, syncing_history, warning, broken, paused, pending (worst across non-paused accounts; an all-paused connector reports paused). connections is the per-status breakdown of this connector's accounts and only includes health states with at least one account (absent keys mean zero). Total account count equals the sum of connections values. get_connector_statuses drills into specific connectors and exposes the structured issues[] used to compose remediation prose. A connector in warning, broken, or syncing_history state is a data-quality condition relevant to any numbers derived from it, and its connector page has a user-facing deep link for review. A paused account always reports paused even with unresolved errors underneath: treat it as paused, not as needing action — keep it out of any broken/"needs attention" rundown. polar-pixel appears in this list like any other connector: health syncing_history means it is still warming up, healthy means it has matured. The canonical health currently surfaces only 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. last_completed_sync_at on its own is not a reliable freshness signal; explicit issues[] entries are the canonical source. custom_connectors: Array of { key } for connectors that have queryable data tables but no live monitoring (custom imports, data warehouses, legacy entries). Health is unknown for these. connector_status: DEPRECATED, superseded by 'connectors' and 'custom_connectors'. Kept only for backward compatibility and will be removed in a future MCP version. 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. A polar-pixel legacy entry with is_warmed_up=false signals the pixel needs attention: when installed_at is a date, the pixel is still warming up since installed_at and conversion / attribution numbers are not yet statistically meaningful (the calibration window depends on traffic volume and industry but is typically at least a couple of weeks); when installed_at is null, the pipeline last produced data on polar-pixel 'until' and may not be currently flowing. Deep-link pattern for the Connectors area (use canonical 'connectors' key and accounts[].datasource_id from get_connector_statuses; account names are not slugified): 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 workspace's custom dimensions: the 50 most recently created or updated. Each entry carries { id, label } plus ONE of: - summary: human-readable one-line purpose (set when authored or AI-summarized) - refs: array of underlying dimension field names the formula touches (for example ["billing_country"]); a structural hint when no summary exists (a label like "geo v2 jamie" with refs ["billing_country"] is typically a country grouping). Label, summary and refs together describe whether an existing dimension covers a given concept. The full whenThen formula is not inlined; `get_custom_dimension_details(id)` returns it for a single candidate. The `list_custom_dimensions(q?, offset?, limit?)` tool paginates beyond this initial page and searches by case-insensitive substring on title and summary. views: Views list as an array of { id, title }. labels: Present only when the workspace has enabled metric labels: the full label dictionary as an array of { id, name, category, description, metric_count }. Custom metrics may carry `labels`: workspace-defined tags { name, category, description } that the workspace's team attached on purpose (for example a "Certified" label under a "Governance" category). A label's description is authoritative guidance on when to use the metric: when several metrics could answer a question, prefer the one whose labels and label descriptions match the question, and mention the label when you cite the metric. Use this dictionary to understand what each label on a custom metric (from get_metrics / list_custom_metrics / get_custom_metric_details) means before choosing between metrics. snowflake_database: Present only when the `query_snowflake` tool is available for this workspace: the workspace's own Snowflake database name, already quoted and ready to interpolate into fully-qualified identifiers (there is no session default database, so every table reference needs it). Required input: - initialQuestion (user's initial prompt, stated exactly as received) - version (the MCP client version; current is 4.3) The response may include a 'warning' field describing an outdated client version or other notice intended for the user.