Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

fix(mcp): clarify saved funnel query contract (#124479)

posthog[bot]86b889dacc8a
diff --git a/frontend/src/queries/schema.json b/frontend/src/queries/schema.json
index 7c3eb5d53944..0c1d1895d30f 100644
--- a/frontend/src/queries/schema.json
+++ b/frontend/src/queries/schema.json
@@ -3321,7 +3321,7 @@
"properties": {
"math": {
"$ref": "#/definitions/AssistantFunnelsMath",
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time."
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time."
},
"optionalInFunnel": {
"default": false,
@@ -3350,7 +3350,7 @@
},
"math": {
"$ref": "#/definitions/AssistantFunnelsMath",
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time."
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time."
},
"name": {
"description": "Action name from the plan.",
@@ -3478,7 +3478,7 @@
},
"math": {
"$ref": "#/definitions/AssistantFunnelsMath",
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time."
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time."
},
"optionalInFunnel": {
"default": false,
@@ -3623,7 +3623,7 @@
"type": "object"
},
"AssistantFunnelsMath": {
- "enum": ["first_time_for_user", "first_time_for_user_with_filters"],
+ "enum": ["total", "first_time_for_user", "first_time_for_user_with_filters"],
"type": "string"
},
"AssistantFunnelsNode": {
diff --git a/frontend/src/queries/schema/schema-assistant-queries.ts b/frontend/src/queries/schema/schema-assistant-queries.ts
index bd51de891947..ca7a5a7bade3 100644
--- a/frontend/src/queries/schema/schema-assistant-queries.ts
+++ b/frontend/src/queries/schema/schema-assistant-queries.ts
@@ -707,11 +707,14 @@ export interface AssistantTrendsQuery extends AssistantInsightsQueryBase {
compareFilter?: CompareFilter
}
-export type AssistantFunnelsMath = FunnelMathType.FirstTimeForUser | FunnelMathType.FirstTimeForUserWithFilters
+export type AssistantFunnelsMath =
+ | FunnelMathType.AnyMatch
+ | FunnelMathType.FirstTimeForUser
+ | FunnelMathType.FirstTimeForUserWithFilters
export interface AssistantFunnelNodeShared {
/**
- * Optional math aggregation type for the series. Only specify this math type if the user wants one of these.
+ * Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one.
* `first_time_for_user` - counts the number of users who have completed the event for the first time ever.
* `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.
*/
diff --git a/posthog/schema.py b/posthog/schema.py
index 93f34619f0c0..bbdeb67a2170 100644
--- a/posthog/schema.py
+++ b/posthog/schema.py
@@ -10657,11 +10657,12 @@ class AssistantFunnelNodeShared(BaseModel):
math: AssistantFunnelsMath | None = Field(
default=None,
description=(
- "Optional math aggregation type for the series. Only specify this math type"
- " if the user wants one of these. `first_time_for_user` - counts the number"
- " of users who have completed the event for the first time ever."
- " `first_time_for_user_with_filters` - counts the number of users who have"
- " completed the event with specified filters for the first time."
+ "Optional math aggregation type for the series. `total` is the default"
+ " stored on saved funnels and can be preserved when rerunning one."
+ " `first_time_for_user` - counts the number of users who have completed the"
+ " event for the first time ever. `first_time_for_user_with_filters` -"
+ " counts the number of users who have completed the event with specified"
+ " filters for the first time."
),
)
optionalInFunnel: bool | None = Field(
@@ -10708,11 +10709,12 @@ class AssistantFunnelsActionsNode(BaseModel):
math: AssistantFunnelsMath | None = Field(
default=None,
description=(
- "Optional math aggregation type for the series. Only specify this math type"
- " if the user wants one of these. `first_time_for_user` - counts the number"
- " of users who have completed the event for the first time ever."
- " `first_time_for_user_with_filters` - counts the number of users who have"
- " completed the event with specified filters for the first time."
+ "Optional math aggregation type for the series. `total` is the default"
+ " stored on saved funnels and can be preserved when rerunning one."
+ " `first_time_for_user` - counts the number of users who have completed the"
+ " event for the first time ever. `first_time_for_user_with_filters` -"
+ " counts the number of users who have completed the event with specified"
+ " filters for the first time."
),
)
name: str = Field(..., description="Action name from the plan.")
@@ -10765,11 +10767,12 @@ class AssistantFunnelsEventsNode(BaseModel):
math: AssistantFunnelsMath | None = Field(
default=None,
description=(
- "Optional math aggregation type for the series. Only specify this math type"
- " if the user wants one of these. `first_time_for_user` - counts the number"
- " of users who have completed the event for the first time ever."
- " `first_time_for_user_with_filters` - counts the number of users who have"
- " completed the event with specified filters for the first time."
+ "Optional math aggregation type for the series. `total` is the default"
+ " stored on saved funnels and can be preserved when rerunning one."
+ " `first_time_for_user` - counts the number of users who have completed the"
+ " event for the first time ever. `first_time_for_user_with_filters` -"
+ " counts the number of users who have completed the event with specified"
+ " filters for the first time."
),
)
optionalInFunnel: bool | None = Field(
diff --git a/posthog/schema_enums.py b/posthog/schema_enums.py
index 2c3865152a8c..b703a8eac0d7 100644
--- a/posthog/schema_enums.py
+++ b/posthog/schema_enums.py
@@ -358,6 +358,7 @@ class FunnelAggregateByHogQL(Enum):
class AssistantFunnelsMath(StrEnum):
+ TOTAL = "total"
FIRST_TIME_FOR_USER = "first_time_for_user"
FIRST_TIME_FOR_USER_WITH_FILTERS = "first_time_for_user_with_filters"
diff --git a/products/signals/skills/signals-scout-product-analytics/references/funnel-maturity.md b/products/signals/skills/signals-scout-product-analytics/references/funnel-maturity.md
index 1be686c9afa8..2b996ec890cf 100644
--- a/products/signals/skills/signals-scout-product-analytics/references/funnel-maturity.md
+++ b/products/signals/skills/signals-scout-product-analytics/references/funnel-maturity.md
@@ -18,7 +18,7 @@ Trends mode groups entrants by entrant period, and counts each entrant's convers
- Copy the saved funnel's `series`, `funnelOrderType`, `funnelWindowInterval`, `funnelWindowIntervalUnit` and filters into the query. Do not change the measured flow.
- Set `funnelsFilter.funnelVizType: trends` and `interval: week` (use `day` only for a daily cadence).
- Set a `dateRange` that ends now. Start it at the beginning of an entrant period that is at least one conversion interval, the buffer and N+2 entrant periods before now. Then the latest mature point and N mature baseline points remain after you drop the immature points, and the first point is a full period.
-- Pass `output_format: "json"`. The default optimized output shows only rates and no entrant counts.
+- With the exec dispatcher, run `call --json query-funnel <json_input>`. Put `--json` before the tool name; do not add `output_format` to the JSON input. The default optimized output shows only rates and no entrant counts.
- Each result holds `days`, `data` (conversion %), `reached_from_step_count` (entrants) and `reached_to_step_count`, with matching indexes.
- Each point is one entrant period. Score only the points whose entrant period ended at least one conversion interval, plus the buffer, before now. Use the older mature points as the baseline.
- With `interval: day`, compare a point only to baseline points on the same weekday.
@@ -48,5 +48,5 @@ A saved ordered funnel `Signup → project created → first event`, with a 14-d
- The cutoff is Wed 24 minus 6 hours. The newest mature week is Mon 1 – Sun 7, because Sun 7 + 14 days ends on Sun 21. The week Mon 8 – Sun 14 matures only after Sun 28.
- With N = 4 baseline weeks, start the `dateRange` on a Monday at least 14 days, 6 hours and 6 weeks before now, and end it now.
-- Run the prefix funnel `Signup → project created` and the full funnel in trends mode with `output_format: "json"`.
+- Run the prefix funnel `Signup → project created` and the full funnel in trends mode with `call --json query-funnel <json_input>`.
- Read the points for weeks that start Mon 1 and earlier. Drop the points for Mon 8, Mon 15 and Mon 22, which look low only because their entrants are still converting.
diff --git a/services/mcp/definitions/prompts/query-funnel.md b/services/mcp/definitions/prompts/query-funnel.md
index 787f124f74e8..fea168cfe6d1 100644
--- a/services/mcp/definitions/prompts/query-funnel.md
+++ b/services/mcp/definitions/prompts/query-funnel.md
@@ -4,6 +4,25 @@ Use 'read-data-schema' to discover available events, actions, and properties for
IMPORTANT: Funnels REQUIRE AT LEAST TWO series (events or actions).
+Start with the smallest valid request and add only fields the question needs:
+
+```json
+{
+ "kind": "FunnelsQuery",
+ "series": [
+ { "kind": "EventsNode", "event": "sign up" },
+ { "kind": "EventsNode", "event": "purchase" }
+ ],
+ "dateRange": { "date_from": "-30d" }
+}
+```
+
+`series` is required. Each event step requires `kind: "EventsNode"` and `event`; each action step requires `kind: "ActionsNode"`, a numeric `id`, and `name`.
+
+When adapting a saved funnel from `insight-get`, copy its `query.source` fields rather than sending an insight ID or wrapping them in `query`. Preserve its steps, filters, order, conversion window, and `math: "total"` values so the measurement stays the same. Change only the fields needed for the requested comparison.
+
+If a saved query fails validation, remove only the presentation-only field named by the error or inspect `schema query-funnel <field>`. Do not remove a step or measurement filter to make the request pass. Use `insight-query` instead when the saved insight should run unchanged.
+
The funnel insights have the following features:
- Various visualization types (steps, time-to-convert, historical trends).
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index a4e0682abc5f..a9cbaae345b0 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -11777,7 +11777,7 @@
"system_prompt_hint": "Error issue filtering and aggregation (error-tracking category)"
},
"query-funnel": {
- "description": "Run a funnel query to analyze conversion rates through a sequence of steps. Funnel insights help understand user behavior as users navigate through a product. A funnel consists of a sequence of at least two events or actions, where some users progress to the next step while others drop off. Funnels use percentages as the primary aggregation type.\n\nUse 'read-data-schema' to discover available events, actions, and properties for filters and breakdowns.\n\nIMPORTANT: Funnels REQUIRE AT LEAST TWO series (events or actions).\n\nThe funnel insights have the following features:\n\n- Various visualization types (steps, time-to-convert, historical trends).\n- Filter data and apply exclusion steps (events only, not actions).\n- Break down data using a single property.\n- Specify conversion windows (default 14 days), step order (strict/ordered/unordered), and attribution settings.\n- Aggregate by users, sessions, or specific group types.\n- Track first-time conversions with special math aggregations.\n\nExamples of use cases include:\n\n- Conversion rates between steps.\n- Drop off steps (which step loses most users).\n- Steps with the highest friction and time to convert.\n- If product changes are improving their funnel over time.\n- Average/median/histogram of time to convert.\n- Conversion trends over time (using trends visualization type).\n- First-time user conversions (using first_time_for_user math).\n\nCRITICAL: Be minimalist. Only include filters, breakdowns, and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.\n\n# Data narrowing\n\n## Property filters\n\nUse property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.\n\nIMPORTANT: Do not check if a property is set unless the user explicitly asks for it.\n\nWhen using a property filter, you should:\n\n- **Prioritize properties directly related to the context or objective of the user's query.** Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like `paidCustomer` or `icp_score`.\n- **Ensure that you find both the property group and name.** Property groups should be one of the following: event, person, session, group.\n- After selecting a property, **validate that the property value accurately reflects the intended criteria**.\n- **Find the suitable operator for type** (e.g., `contains`, `is set`).\n- If the operator requires a value, use the `read-data-schema` tool to find the property values.\n- You set logical operators to combine multiple properties of a single series: AND or OR.\n\nInfer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.\n\nSupported operators for the String type are:\n\n- equals (exact)\n- doesn't equal (is_not)\n- contains (icontains)\n- doesn't contain (not_icontains)\n- matches regex (regex)\n- doesn't match regex (not_regex)\n- is set\n- is not set\n\nSupported operators for the Numeric type are:\n\n- equals (exact)\n- doesn't equal (is_not)\n- greater than (gt)\n- less than (lt)\n- is set\n- is not set\n\nSupported operators for the DateTime type are:\n\n- equals (is_date_exact)\n- doesn't equal (is_not for existence check)\n- before (is_date_before)\n- after (is_date_after)\n- is set\n- is not set\n\nSupported operators for the Boolean type are:\n\n- equals\n- doesn't equal\n- is set\n- is not set\n\nAll operators take a single value except for `equals` and `doesn't equal` which can take one or more values (as an array).\n\n## Time period\n\nYou should not filter events by time using property filters. Instead, use the `dateRange` field. If the question doesn't mention time, use last 30 days as a default time period.\n\n### Date boundaries\n\nA `date_to` with no time is an inclusive calendar day.\nGive a full timestamp instead to end the window at an exact instant.\nBoth forms below cover all of August and nothing in September.\n\n- `{ \"date_from\": \"2026-08-01\", \"date_to\": \"2026-08-31\" }`\n- `{ \"date_from\": \"2026-08-01T00:00:00Z\", \"date_to\": \"2026-09-01T00:00:00Z\" }`\n\n# Funnel guidelines\n\n## Exclusion steps\n\nUsers may want to use exclusion events to filter out conversions in which a particular event occurred between specific steps. These events should not be included in the main sequence. You should include start and end indexes (0-based) for each exclusion where the minimum `funnelFromStep` is 0 (first step) and the maximum `funnelToStep` is the number of steps minus one. Exclusion events cannot be actions, only events.\n\nIMPORTANT: Exclusion steps filter out conversions where the exclusion event occurred BETWEEN the specified steps. This does NOT exclude users who completed the event before the funnel started or after it ended.\n\nFor example, there is a sequence with three steps: sign up (step 0), finish onboarding (step 1), purchase (step 2). If the user wants to exclude all conversions in which users navigated away between sign up and finishing onboarding, the exclusion step will be `$pageleave` with `funnelFromStep: 0` and `funnelToStep: 1`.\n\n## Breakdown\n\nA breakdown is used to segment data by a single property value. They divide all defined funnel series into multiple subseries based on the values of the property. Include a breakdown **only when it is essential to directly answer the user's question**. You should not add a breakdown if the question can be addressed without additional segmentation.\n\nWhen using breakdowns, you should:\n\n- **Identify the property group** and name for a breakdown.\n- **Provide the property name** for a breakdown.\n- **Validate that the property value accurately reflects the intended criteria**.\n\nExamples of using a breakdown:\n\n- page views to sign up funnel by country: you need to find a property such as `$geoip_country_code` and set it as a breakdown.\n- conversion rate of users who have completed onboarding after signing up by an organization: you need to find a property such as `organization name` and set it as a breakdown.\n\n## Combining multiple events into a single step (`GroupNode`)\n\n**Use a `GroupNode`** when the user wants a single funnel step to match any of several events — e.g. \"Pageview OR Pageleave counts as one step\", or \"the user signed up via any of these channels\". Different filters per event are fine — put them on the inner nodes. Use separate steps instead when the user wants the events to occur in sequence. Only `OR` is supported.\n\nFunnel math (`first_time_for_user` etc.), `optionalInFunnel`, and step-wide property filters are not supported on a grouped step — filters must live on the inner nodes, and any math / optional handling must use a regular non-grouped step.\n\n**Where things live:**\n\n- On the group: only `name` (display label).\n- On each inner node: `event` (or action `id`), `properties`, `name` — all respected normally; per-node `properties` apply only to that node.\n\n### Example — funnel with a grouped step\n\nA 3-step funnel where the middle step matches either `$pageview` on Safari or `$pageleave` on Chrome:\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"sign up\" },\n {\n \"kind\": \"GroupNode\",\n \"operator\": \"OR\",\n \"name\": \"Pageview on Safari, Pageleave on Chrome\",\n \"nodes\": [\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageview\",\n \"name\": \"Pageview\",\n \"properties\": [{ \"key\": \"$browser\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Safari\"] }]\n },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageleave\",\n \"name\": \"Pageleave\",\n \"properties\": [{ \"key\": \"$browser\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Chrome\"] }]\n }\n ]\n },\n { \"kind\": \"EventsNode\", \"event\": \"purchase\" }\n ],\n \"dateRange\": { \"date_from\": \"-30d\" }\n}\n```\n\n# Examples\n\n## Conversion from first event ingested to insight saved for organizations over 6 months\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"first team event ingested\" },\n { \"kind\": \"EventsNode\", \"event\": \"insight saved\" }\n ],\n \"dateRange\": { \"date_from\": \"-6m\" },\n \"interval\": \"month\",\n \"aggregation_group_type_index\": 0,\n \"funnelsFilter\": {\n \"funnelOrderType\": \"ordered\",\n \"funnelVizType\": \"trends\",\n \"funnelWindowInterval\": 14,\n \"funnelWindowIntervalUnit\": \"day\"\n },\n \"filterTestAccounts\": true\n}\n```\n\n## Signup page CTA click rate within one hour, excluding page leaves, broken down by OS\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageview\",\n \"properties\": [{ \"key\": \"$current_url\", \"type\": \"event\", \"value\": \"signup\", \"operator\": \"icontains\" }]\n },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"click subscribe button\",\n \"properties\": [{ \"key\": \"$current_url\", \"type\": \"event\", \"value\": \"signup\", \"operator\": \"icontains\" }]\n }\n ],\n \"dateRange\": { \"date_from\": \"-180d\" },\n \"interval\": \"week\",\n \"funnelsFilter\": {\n \"funnelWindowInterval\": 1,\n \"funnelWindowIntervalUnit\": \"hour\",\n \"funnelOrderType\": \"ordered\",\n \"exclusions\": [{ \"kind\": \"EventsNode\", \"event\": \"$pageleave\", \"funnelFromStep\": 0, \"funnelToStep\": 1 }]\n },\n \"breakdownFilter\": { \"breakdown_type\": \"event\", \"breakdown\": \"$os\" },\n \"filterTestAccounts\": true\n}\n```\n\n## Credit card purchase rate from viewing a product with strict ordering (no events in between)\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"view product\" },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"purchase\",\n \"properties\": [{ \"key\": \"paymentMethod\", \"type\": \"event\", \"value\": \"credit_card\", \"operator\": \"exact\" }]\n }\n ],\n \"dateRange\": { \"date_from\": \"-30d\" },\n \"funnelsFilter\": {\n \"funnelOrderType\": \"strict\",\n \"funnelWindowInterval\": 14,\n \"funnelWindowIntervalUnit\": \"day\"\n },\n \"filterTestAccounts\": true\n}\n```\n\n## View product to buy button to purchase, using actions and events\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"ActionsNode\", \"id\": 8882, \"name\": \"view product\" },\n { \"kind\": \"EventsNode\", \"event\": \"click buy button\" },\n {\n \"kind\": \"ActionsNode\",\n \"id\": 573,\n \"name\": \"purchase\",\n \"properties\": [\n { \"key\": \"shipping_method\", \"value\": \"express_delivery\", \"operator\": \"icontains\", \"type\": \"event\" }\n ]\n }\n ],\n \"funnelsFilter\": { \"funnelVizType\": \"steps\" },\n \"filterTestAccounts\": true\n}\n```\n\n# Reminders\n\n- You MUST ALWAYS use AT LEAST TWO series (events or actions) in the funnel.\n- Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.\n- Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.\n- The default funnel step order is `ordered` (events in sequence but with other events allowed in between). Use `strict` when events should happen consecutively with no events in between. Use `unordered` when order doesn't matter.\n- Exclusion events in funnels only exclude conversions where the event happened between the specified steps, not before or after the funnel.",
+ "description": "Run a funnel query to analyze conversion rates through a sequence of steps. Funnel insights help understand user behavior as users navigate through a product. A funnel consists of a sequence of at least two events or actions, where some users progress to the next step while others drop off. Funnels use percentages as the primary aggregation type.\n\nUse 'read-data-schema' to discover available events, actions, and properties for filters and breakdowns.\n\nIMPORTANT: Funnels REQUIRE AT LEAST TWO series (events or actions).\n\nStart with the smallest valid request and add only fields the question needs:\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"sign up\" },\n { \"kind\": \"EventsNode\", \"event\": \"purchase\" }\n ],\n \"dateRange\": { \"date_from\": \"-30d\" }\n}\n```\n\n`series` is required. Each event step requires `kind: \"EventsNode\"` and `event`; each action step requires `kind: \"ActionsNode\"`, a numeric `id`, and `name`.\n\nWhen adapting a saved funnel from `insight-get`, copy its `query.source` fields rather than sending an insight ID or wrapping them in `query`. Preserve its steps, filters, order, conversion window, and `math: \"total\"` values so the measurement stays the same. Change only the fields needed for the requested comparison.\n\nIf a saved query fails validation, remove only the presentation-only field named by the error or inspect `schema query-funnel <field>`. Do not remove a step or measurement filter to make the request pass. Use `insight-query` instead when the saved insight should run unchanged.\n\nThe funnel insights have the following features:\n\n- Various visualization types (steps, time-to-convert, historical trends).\n- Filter data and apply exclusion steps (events only, not actions).\n- Break down data using a single property.\n- Specify conversion windows (default 14 days), step order (strict/ordered/unordered), and attribution settings.\n- Aggregate by users, sessions, or specific group types.\n- Track first-time conversions with special math aggregations.\n\nExamples of use cases include:\n\n- Conversion rates between steps.\n- Drop off steps (which step loses most users).\n- Steps with the highest friction and time to convert.\n- If product changes are improving their funnel over time.\n- Average/median/histogram of time to convert.\n- Conversion trends over time (using trends visualization type).\n- First-time user conversions (using first_time_for_user math).\n\nCRITICAL: Be minimalist. Only include filters, breakdowns, and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.\n\n# Data narrowing\n\n## Property filters\n\nUse property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.\n\nIMPORTANT: Do not check if a property is set unless the user explicitly asks for it.\n\nWhen using a property filter, you should:\n\n- **Prioritize properties directly related to the context or objective of the user's query.** Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like `paidCustomer` or `icp_score`.\n- **Ensure that you find both the property group and name.** Property groups should be one of the following: event, person, session, group.\n- After selecting a property, **validate that the property value accurately reflects the intended criteria**.\n- **Find the suitable operator for type** (e.g., `contains`, `is set`).\n- If the operator requires a value, use the `read-data-schema` tool to find the property values.\n- You set logical operators to combine multiple properties of a single series: AND or OR.\n\nInfer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.\n\nSupported operators for the String type are:\n\n- equals (exact)\n- doesn't equal (is_not)\n- contains (icontains)\n- doesn't contain (not_icontains)\n- matches regex (regex)\n- doesn't match regex (not_regex)\n- is set\n- is not set\n\nSupported operators for the Numeric type are:\n\n- equals (exact)\n- doesn't equal (is_not)\n- greater than (gt)\n- less than (lt)\n- is set\n- is not set\n\nSupported operators for the DateTime type are:\n\n- equals (is_date_exact)\n- doesn't equal (is_not for existence check)\n- before (is_date_before)\n- after (is_date_after)\n- is set\n- is not set\n\nSupported operators for the Boolean type are:\n\n- equals\n- doesn't equal\n- is set\n- is not set\n\nAll operators take a single value except for `equals` and `doesn't equal` which can take one or more values (as an array).\n\n## Time period\n\nYou should not filter events by time using property filters. Instead, use the `dateRange` field. If the question doesn't mention time, use last 30 days as a default time period.\n\n### Date boundaries\n\nA `date_to` with no time is an inclusive calendar day.\nGive a full timestamp instead to end the window at an exact instant.\nBoth forms below cover all of August and nothing in September.\n\n- `{ \"date_from\": \"2026-08-01\", \"date_to\": \"2026-08-31\" }`\n- `{ \"date_from\": \"2026-08-01T00:00:00Z\", \"date_to\": \"2026-09-01T00:00:00Z\" }`\n\n# Funnel guidelines\n\n## Exclusion steps\n\nUsers may want to use exclusion events to filter out conversions in which a particular event occurred between specific steps. These events should not be included in the main sequence. You should include start and end indexes (0-based) for each exclusion where the minimum `funnelFromStep` is 0 (first step) and the maximum `funnelToStep` is the number of steps minus one. Exclusion events cannot be actions, only events.\n\nIMPORTANT: Exclusion steps filter out conversions where the exclusion event occurred BETWEEN the specified steps. This does NOT exclude users who completed the event before the funnel started or after it ended.\n\nFor example, there is a sequence with three steps: sign up (step 0), finish onboarding (step 1), purchase (step 2). If the user wants to exclude all conversions in which users navigated away between sign up and finishing onboarding, the exclusion step will be `$pageleave` with `funnelFromStep: 0` and `funnelToStep: 1`.\n\n## Breakdown\n\nA breakdown is used to segment data by a single property value. They divide all defined funnel series into multiple subseries based on the values of the property. Include a breakdown **only when it is essential to directly answer the user's question**. You should not add a breakdown if the question can be addressed without additional segmentation.\n\nWhen using breakdowns, you should:\n\n- **Identify the property group** and name for a breakdown.\n- **Provide the property name** for a breakdown.\n- **Validate that the property value accurately reflects the intended criteria**.\n\nExamples of using a breakdown:\n\n- page views to sign up funnel by country: you need to find a property such as `$geoip_country_code` and set it as a breakdown.\n- conversion rate of users who have completed onboarding after signing up by an organization: you need to find a property such as `organization name` and set it as a breakdown.\n\n## Combining multiple events into a single step (`GroupNode`)\n\n**Use a `GroupNode`** when the user wants a single funnel step to match any of several events — e.g. \"Pageview OR Pageleave counts as one step\", or \"the user signed up via any of these channels\". Different filters per event are fine — put them on the inner nodes. Use separate steps instead when the user wants the events to occur in sequence. Only `OR` is supported.\n\nFunnel math (`first_time_for_user` etc.), `optionalInFunnel`, and step-wide property filters are not supported on a grouped step — filters must live on the inner nodes, and any math / optional handling must use a regular non-grouped step.\n\n**Where things live:**\n\n- On the group: only `name` (display label).\n- On each inner node: `event` (or action `id`), `properties`, `name` — all respected normally; per-node `properties` apply only to that node.\n\n### Example — funnel with a grouped step\n\nA 3-step funnel where the middle step matches either `$pageview` on Safari or `$pageleave` on Chrome:\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"sign up\" },\n {\n \"kind\": \"GroupNode\",\n \"operator\": \"OR\",\n \"name\": \"Pageview on Safari, Pageleave on Chrome\",\n \"nodes\": [\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageview\",\n \"name\": \"Pageview\",\n \"properties\": [{ \"key\": \"$browser\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Safari\"] }]\n },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageleave\",\n \"name\": \"Pageleave\",\n \"properties\": [{ \"key\": \"$browser\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Chrome\"] }]\n }\n ]\n },\n { \"kind\": \"EventsNode\", \"event\": \"purchase\" }\n ],\n \"dateRange\": { \"date_from\": \"-30d\" }\n}\n```\n\n# Examples\n\n## Conversion from first event ingested to insight saved for organizations over 6 months\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"first team event ingested\" },\n { \"kind\": \"EventsNode\", \"event\": \"insight saved\" }\n ],\n \"dateRange\": { \"date_from\": \"-6m\" },\n \"interval\": \"month\",\n \"aggregation_group_type_index\": 0,\n \"funnelsFilter\": {\n \"funnelOrderType\": \"ordered\",\n \"funnelVizType\": \"trends\",\n \"funnelWindowInterval\": 14,\n \"funnelWindowIntervalUnit\": \"day\"\n },\n \"filterTestAccounts\": true\n}\n```\n\n## Signup page CTA click rate within one hour, excluding page leaves, broken down by OS\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageview\",\n \"properties\": [{ \"key\": \"$current_url\", \"type\": \"event\", \"value\": \"signup\", \"operator\": \"icontains\" }]\n },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"click subscribe button\",\n \"properties\": [{ \"key\": \"$current_url\", \"type\": \"event\", \"value\": \"signup\", \"operator\": \"icontains\" }]\n }\n ],\n \"dateRange\": { \"date_from\": \"-180d\" },\n \"interval\": \"week\",\n \"funnelsFilter\": {\n \"funnelWindowInterval\": 1,\n \"funnelWindowIntervalUnit\": \"hour\",\n \"funnelOrderType\": \"ordered\",\n \"exclusions\": [{ \"kind\": \"EventsNode\", \"event\": \"$pageleave\", \"funnelFromStep\": 0, \"funnelToStep\": 1 }]\n },\n \"breakdownFilter\": { \"breakdown_type\": \"event\", \"breakdown\": \"$os\" },\n \"filterTestAccounts\": true\n}\n```\n\n## Credit card purchase rate from viewing a product with strict ordering (no events in between)\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"view product\" },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"purchase\",\n \"properties\": [{ \"key\": \"paymentMethod\", \"type\": \"event\", \"value\": \"credit_card\", \"operator\": \"exact\" }]\n }\n ],\n \"dateRange\": { \"date_from\": \"-30d\" },\n \"funnelsFilter\": {\n \"funnelOrderType\": \"strict\",\n \"funnelWindowInterval\": 14,\n \"funnelWindowIntervalUnit\": \"day\"\n },\n \"filterTestAccounts\": true\n}\n```\n\n## View product to buy button to purchase, using actions and events\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"ActionsNode\", \"id\": 8882, \"name\": \"view product\" },\n { \"kind\": \"EventsNode\", \"event\": \"click buy button\" },\n {\n \"kind\": \"ActionsNode\",\n \"id\": 573,\n \"name\": \"purchase\",\n \"properties\": [\n { \"key\": \"shipping_method\", \"value\": \"express_delivery\", \"operator\": \"icontains\", \"type\": \"event\" }\n ]\n }\n ],\n \"funnelsFilter\": { \"funnelVizType\": \"steps\" },\n \"filterTestAccounts\": true\n}\n```\n\n# Reminders\n\n- You MUST ALWAYS use AT LEAST TWO series (events or actions) in the funnel.\n- Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.\n- Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.\n- The default funnel step order is `ordered` (events in sequence but with other events allowed in between). Use `strict` when events should happen consecutively with no events in between. Use `unordered` when order doesn't matter.\n- Exclusion events in funnels only exclude conversions where the event happened between the specified steps, not before or after the funnel.",
"category": "Query wrappers",
"feature": "insights",
"summary": "Run a funnel query",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index e23bd84eedc2..4443d5b4c031 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -12464,7 +12464,7 @@
"system_prompt_hint": "Error issue filtering and aggregation (error-tracking category)"
},
"query-funnel": {
- "description": "Run a funnel query to analyze conversion rates through a sequence of steps. Funnel insights help understand user behavior as users navigate through a product. A funnel consists of a sequence of at least two events or actions, where some users progress to the next step while others drop off. Funnels use percentages as the primary aggregation type.\n\nUse 'read-data-schema' to discover available events, actions, and properties for filters and breakdowns.\n\nIMPORTANT: Funnels REQUIRE AT LEAST TWO series (events or actions).\n\nThe funnel insights have the following features:\n\n- Various visualization types (steps, time-to-convert, historical trends).\n- Filter data and apply exclusion steps (events only, not actions).\n- Break down data using a single property.\n- Specify conversion windows (default 14 days), step order (strict/ordered/unordered), and attribution settings.\n- Aggregate by users, sessions, or specific group types.\n- Track first-time conversions with special math aggregations.\n\nExamples of use cases include:\n\n- Conversion rates between steps.\n- Drop off steps (which step loses most users).\n- Steps with the highest friction and time to convert.\n- If product changes are improving their funnel over time.\n- Average/median/histogram of time to convert.\n- Conversion trends over time (using trends visualization type).\n- First-time user conversions (using first_time_for_user math).\n\nCRITICAL: Be minimalist. Only include filters, breakdowns, and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.\n\n# Data narrowing\n\n## Property filters\n\nUse property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.\n\nIMPORTANT: Do not check if a property is set unless the user explicitly asks for it.\n\nWhen using a property filter, you should:\n\n- **Prioritize properties directly related to the context or objective of the user's query.** Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like `paidCustomer` or `icp_score`.\n- **Ensure that you find both the property group and name.** Property groups should be one of the following: event, person, session, group.\n- After selecting a property, **validate that the property value accurately reflects the intended criteria**.\n- **Find the suitable operator for type** (e.g., `contains`, `is set`).\n- If the operator requires a value, use the `read-data-schema` tool to find the property values.\n- You set logical operators to combine multiple properties of a single series: AND or OR.\n\nInfer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.\n\nSupported operators for the String type are:\n\n- equals (exact)\n- doesn't equal (is_not)\n- contains (icontains)\n- doesn't contain (not_icontains)\n- matches regex (regex)\n- doesn't match regex (not_regex)\n- is set\n- is not set\n\nSupported operators for the Numeric type are:\n\n- equals (exact)\n- doesn't equal (is_not)\n- greater than (gt)\n- less than (lt)\n- is set\n- is not set\n\nSupported operators for the DateTime type are:\n\n- equals (is_date_exact)\n- doesn't equal (is_not for existence check)\n- before (is_date_before)\n- after (is_date_after)\n- is set\n- is not set\n\nSupported operators for the Boolean type are:\n\n- equals\n- doesn't equal\n- is set\n- is not set\n\nAll operators take a single value except for `equals` and `doesn't equal` which can take one or more values (as an array).\n\n## Time period\n\nYou should not filter events by time using property filters. Instead, use the `dateRange` field. If the question doesn't mention time, use last 30 days as a default time period.\n\n### Date boundaries\n\nA `date_to` with no time is an inclusive calendar day.\nGive a full timestamp instead to end the window at an exact instant.\nBoth forms below cover all of August and nothing in September.\n\n- `{ \"date_from\": \"2026-08-01\", \"date_to\": \"2026-08-31\" }`\n- `{ \"date_from\": \"2026-08-01T00:00:00Z\", \"date_to\": \"2026-09-01T00:00:00Z\" }`\n\n# Funnel guidelines\n\n## Exclusion steps\n\nUsers may want to use exclusion events to filter out conversions in which a particular event occurred between specific steps. These events should not be included in the main sequence. You should include start and end indexes (0-based) for each exclusion where the minimum `funnelFromStep` is 0 (first step) and the maximum `funnelToStep` is the number of steps minus one. Exclusion events cannot be actions, only events.\n\nIMPORTANT: Exclusion steps filter out conversions where the exclusion event occurred BETWEEN the specified steps. This does NOT exclude users who completed the event before the funnel started or after it ended.\n\nFor example, there is a sequence with three steps: sign up (step 0), finish onboarding (step 1), purchase (step 2). If the user wants to exclude all conversions in which users navigated away between sign up and finishing onboarding, the exclusion step will be `$pageleave` with `funnelFromStep: 0` and `funnelToStep: 1`.\n\n## Breakdown\n\nA breakdown is used to segment data by a single property value. They divide all defined funnel series into multiple subseries based on the values of the property. Include a breakdown **only when it is essential to directly answer the user's question**. You should not add a breakdown if the question can be addressed without additional segmentation.\n\nWhen using breakdowns, you should:\n\n- **Identify the property group** and name for a breakdown.\n- **Provide the property name** for a breakdown.\n- **Validate that the property value accurately reflects the intended criteria**.\n\nExamples of using a breakdown:\n\n- page views to sign up funnel by country: you need to find a property such as `$geoip_country_code` and set it as a breakdown.\n- conversion rate of users who have completed onboarding after signing up by an organization: you need to find a property such as `organization name` and set it as a breakdown.\n\n## Combining multiple events into a single step (`GroupNode`)\n\n**Use a `GroupNode`** when the user wants a single funnel step to match any of several events — e.g. \"Pageview OR Pageleave counts as one step\", or \"the user signed up via any of these channels\". Different filters per event are fine — put them on the inner nodes. Use separate steps instead when the user wants the events to occur in sequence. Only `OR` is supported.\n\nFunnel math (`first_time_for_user` etc.), `optionalInFunnel`, and step-wide property filters are not supported on a grouped step — filters must live on the inner nodes, and any math / optional handling must use a regular non-grouped step.\n\n**Where things live:**\n\n- On the group: only `name` (display label).\n- On each inner node: `event` (or action `id`), `properties`, `name` — all respected normally; per-node `properties` apply only to that node.\n\n### Example — funnel with a grouped step\n\nA 3-step funnel where the middle step matches either `$pageview` on Safari or `$pageleave` on Chrome:\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"sign up\" },\n {\n \"kind\": \"GroupNode\",\n \"operator\": \"OR\",\n \"name\": \"Pageview on Safari, Pageleave on Chrome\",\n \"nodes\": [\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageview\",\n \"name\": \"Pageview\",\n \"properties\": [{ \"key\": \"$browser\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Safari\"] }]\n },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageleave\",\n \"name\": \"Pageleave\",\n \"properties\": [{ \"key\": \"$browser\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Chrome\"] }]\n }\n ]\n },\n { \"kind\": \"EventsNode\", \"event\": \"purchase\" }\n ],\n \"dateRange\": { \"date_from\": \"-30d\" }\n}\n```\n\n# Examples\n\n## Conversion from first event ingested to insight saved for organizations over 6 months\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"first team event ingested\" },\n { \"kind\": \"EventsNode\", \"event\": \"insight saved\" }\n ],\n \"dateRange\": { \"date_from\": \"-6m\" },\n \"interval\": \"month\",\n \"aggregation_group_type_index\": 0,\n \"funnelsFilter\": {\n \"funnelOrderType\": \"ordered\",\n \"funnelVizType\": \"trends\",\n \"funnelWindowInterval\": 14,\n \"funnelWindowIntervalUnit\": \"day\"\n },\n \"filterTestAccounts\": true\n}\n```\n\n## Signup page CTA click rate within one hour, excluding page leaves, broken down by OS\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageview\",\n \"properties\": [{ \"key\": \"$current_url\", \"type\": \"event\", \"value\": \"signup\", \"operator\": \"icontains\" }]\n },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"click subscribe button\",\n \"properties\": [{ \"key\": \"$current_url\", \"type\": \"event\", \"value\": \"signup\", \"operator\": \"icontains\" }]\n }\n ],\n \"dateRange\": { \"date_from\": \"-180d\" },\n \"interval\": \"week\",\n \"funnelsFilter\": {\n \"funnelWindowInterval\": 1,\n \"funnelWindowIntervalUnit\": \"hour\",\n \"funnelOrderType\": \"ordered\",\n \"exclusions\": [{ \"kind\": \"EventsNode\", \"event\": \"$pageleave\", \"funnelFromStep\": 0, \"funnelToStep\": 1 }]\n },\n \"breakdownFilter\": { \"breakdown_type\": \"event\", \"breakdown\": \"$os\" },\n \"filterTestAccounts\": true\n}\n```\n\n## Credit card purchase rate from viewing a product with strict ordering (no events in between)\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"view product\" },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"purchase\",\n \"properties\": [{ \"key\": \"paymentMethod\", \"type\": \"event\", \"value\": \"credit_card\", \"operator\": \"exact\" }]\n }\n ],\n \"dateRange\": { \"date_from\": \"-30d\" },\n \"funnelsFilter\": {\n \"funnelOrderType\": \"strict\",\n \"funnelWindowInterval\": 14,\n \"funnelWindowIntervalUnit\": \"day\"\n },\n \"filterTestAccounts\": true\n}\n```\n\n## View product to buy button to purchase, using actions and events\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"ActionsNode\", \"id\": 8882, \"name\": \"view product\" },\n { \"kind\": \"EventsNode\", \"event\": \"click buy button\" },\n {\n \"kind\": \"ActionsNode\",\n \"id\": 573,\n \"name\": \"purchase\",\n \"properties\": [\n { \"key\": \"shipping_method\", \"value\": \"express_delivery\", \"operator\": \"icontains\", \"type\": \"event\" }\n ]\n }\n ],\n \"funnelsFilter\": { \"funnelVizType\": \"steps\" },\n \"filterTestAccounts\": true\n}\n```\n\n# Reminders\n\n- You MUST ALWAYS use AT LEAST TWO series (events or actions) in the funnel.\n- Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.\n- Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.\n- The default funnel step order is `ordered` (events in sequence but with other events allowed in between). Use `strict` when events should happen consecutively with no events in between. Use `unordered` when order doesn't matter.\n- Exclusion events in funnels only exclude conversions where the event happened between the specified steps, not before or after the funnel.",
+ "description": "Run a funnel query to analyze conversion rates through a sequence of steps. Funnel insights help understand user behavior as users navigate through a product. A funnel consists of a sequence of at least two events or actions, where some users progress to the next step while others drop off. Funnels use percentages as the primary aggregation type.\n\nUse 'read-data-schema' to discover available events, actions, and properties for filters and breakdowns.\n\nIMPORTANT: Funnels REQUIRE AT LEAST TWO series (events or actions).\n\nStart with the smallest valid request and add only fields the question needs:\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"sign up\" },\n { \"kind\": \"EventsNode\", \"event\": \"purchase\" }\n ],\n \"dateRange\": { \"date_from\": \"-30d\" }\n}\n```\n\n`series` is required. Each event step requires `kind: \"EventsNode\"` and `event`; each action step requires `kind: \"ActionsNode\"`, a numeric `id`, and `name`.\n\nWhen adapting a saved funnel from `insight-get`, copy its `query.source` fields rather than sending an insight ID or wrapping them in `query`. Preserve its steps, filters, order, conversion window, and `math: \"total\"` values so the measurement stays the same. Change only the fields needed for the requested comparison.\n\nIf a saved query fails validation, remove only the presentation-only field named by the error or inspect `schema query-funnel <field>`. Do not remove a step or measurement filter to make the request pass. Use `insight-query` instead when the saved insight should run unchanged.\n\nThe funnel insights have the following features:\n\n- Various visualization types (steps, time-to-convert, historical trends).\n- Filter data and apply exclusion steps (events only, not actions).\n- Break down data using a single property.\n- Specify conversion windows (default 14 days), step order (strict/ordered/unordered), and attribution settings.\n- Aggregate by users, sessions, or specific group types.\n- Track first-time conversions with special math aggregations.\n\nExamples of use cases include:\n\n- Conversion rates between steps.\n- Drop off steps (which step loses most users).\n- Steps with the highest friction and time to convert.\n- If product changes are improving their funnel over time.\n- Average/median/histogram of time to convert.\n- Conversion trends over time (using trends visualization type).\n- First-time user conversions (using first_time_for_user math).\n\nCRITICAL: Be minimalist. Only include filters, breakdowns, and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.\n\n# Data narrowing\n\n## Property filters\n\nUse property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.\n\nIMPORTANT: Do not check if a property is set unless the user explicitly asks for it.\n\nWhen using a property filter, you should:\n\n- **Prioritize properties directly related to the context or objective of the user's query.** Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like `paidCustomer` or `icp_score`.\n- **Ensure that you find both the property group and name.** Property groups should be one of the following: event, person, session, group.\n- After selecting a property, **validate that the property value accurately reflects the intended criteria**.\n- **Find the suitable operator for type** (e.g., `contains`, `is set`).\n- If the operator requires a value, use the `read-data-schema` tool to find the property values.\n- You set logical operators to combine multiple properties of a single series: AND or OR.\n\nInfer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.\n\nSupported operators for the String type are:\n\n- equals (exact)\n- doesn't equal (is_not)\n- contains (icontains)\n- doesn't contain (not_icontains)\n- matches regex (regex)\n- doesn't match regex (not_regex)\n- is set\n- is not set\n\nSupported operators for the Numeric type are:\n\n- equals (exact)\n- doesn't equal (is_not)\n- greater than (gt)\n- less than (lt)\n- is set\n- is not set\n\nSupported operators for the DateTime type are:\n\n- equals (is_date_exact)\n- doesn't equal (is_not for existence check)\n- before (is_date_before)\n- after (is_date_after)\n- is set\n- is not set\n\nSupported operators for the Boolean type are:\n\n- equals\n- doesn't equal\n- is set\n- is not set\n\nAll operators take a single value except for `equals` and `doesn't equal` which can take one or more values (as an array).\n\n## Time period\n\nYou should not filter events by time using property filters. Instead, use the `dateRange` field. If the question doesn't mention time, use last 30 days as a default time period.\n\n### Date boundaries\n\nA `date_to` with no time is an inclusive calendar day.\nGive a full timestamp instead to end the window at an exact instant.\nBoth forms below cover all of August and nothing in September.\n\n- `{ \"date_from\": \"2026-08-01\", \"date_to\": \"2026-08-31\" }`\n- `{ \"date_from\": \"2026-08-01T00:00:00Z\", \"date_to\": \"2026-09-01T00:00:00Z\" }`\n\n# Funnel guidelines\n\n## Exclusion steps\n\nUsers may want to use exclusion events to filter out conversions in which a particular event occurred between specific steps. These events should not be included in the main sequence. You should include start and end indexes (0-based) for each exclusion where the minimum `funnelFromStep` is 0 (first step) and the maximum `funnelToStep` is the number of steps minus one. Exclusion events cannot be actions, only events.\n\nIMPORTANT: Exclusion steps filter out conversions where the exclusion event occurred BETWEEN the specified steps. This does NOT exclude users who completed the event before the funnel started or after it ended.\n\nFor example, there is a sequence with three steps: sign up (step 0), finish onboarding (step 1), purchase (step 2). If the user wants to exclude all conversions in which users navigated away between sign up and finishing onboarding, the exclusion step will be `$pageleave` with `funnelFromStep: 0` and `funnelToStep: 1`.\n\n## Breakdown\n\nA breakdown is used to segment data by a single property value. They divide all defined funnel series into multiple subseries based on the values of the property. Include a breakdown **only when it is essential to directly answer the user's question**. You should not add a breakdown if the question can be addressed without additional segmentation.\n\nWhen using breakdowns, you should:\n\n- **Identify the property group** and name for a breakdown.\n- **Provide the property name** for a breakdown.\n- **Validate that the property value accurately reflects the intended criteria**.\n\nExamples of using a breakdown:\n\n- page views to sign up funnel by country: you need to find a property such as `$geoip_country_code` and set it as a breakdown.\n- conversion rate of users who have completed onboarding after signing up by an organization: you need to find a property such as `organization name` and set it as a breakdown.\n\n## Combining multiple events into a single step (`GroupNode`)\n\n**Use a `GroupNode`** when the user wants a single funnel step to match any of several events — e.g. \"Pageview OR Pageleave counts as one step\", or \"the user signed up via any of these channels\". Different filters per event are fine — put them on the inner nodes. Use separate steps instead when the user wants the events to occur in sequence. Only `OR` is supported.\n\nFunnel math (`first_time_for_user` etc.), `optionalInFunnel`, and step-wide property filters are not supported on a grouped step — filters must live on the inner nodes, and any math / optional handling must use a regular non-grouped step.\n\n**Where things live:**\n\n- On the group: only `name` (display label).\n- On each inner node: `event` (or action `id`), `properties`, `name` — all respected normally; per-node `properties` apply only to that node.\n\n### Example — funnel with a grouped step\n\nA 3-step funnel where the middle step matches either `$pageview` on Safari or `$pageleave` on Chrome:\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"sign up\" },\n {\n \"kind\": \"GroupNode\",\n \"operator\": \"OR\",\n \"name\": \"Pageview on Safari, Pageleave on Chrome\",\n \"nodes\": [\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageview\",\n \"name\": \"Pageview\",\n \"properties\": [{ \"key\": \"$browser\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Safari\"] }]\n },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageleave\",\n \"name\": \"Pageleave\",\n \"properties\": [{ \"key\": \"$browser\", \"operator\": \"exact\", \"type\": \"event\", \"value\": [\"Chrome\"] }]\n }\n ]\n },\n { \"kind\": \"EventsNode\", \"event\": \"purchase\" }\n ],\n \"dateRange\": { \"date_from\": \"-30d\" }\n}\n```\n\n# Examples\n\n## Conversion from first event ingested to insight saved for organizations over 6 months\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"first team event ingested\" },\n { \"kind\": \"EventsNode\", \"event\": \"insight saved\" }\n ],\n \"dateRange\": { \"date_from\": \"-6m\" },\n \"interval\": \"month\",\n \"aggregation_group_type_index\": 0,\n \"funnelsFilter\": {\n \"funnelOrderType\": \"ordered\",\n \"funnelVizType\": \"trends\",\n \"funnelWindowInterval\": 14,\n \"funnelWindowIntervalUnit\": \"day\"\n },\n \"filterTestAccounts\": true\n}\n```\n\n## Signup page CTA click rate within one hour, excluding page leaves, broken down by OS\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n {\n \"kind\": \"EventsNode\",\n \"event\": \"$pageview\",\n \"properties\": [{ \"key\": \"$current_url\", \"type\": \"event\", \"value\": \"signup\", \"operator\": \"icontains\" }]\n },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"click subscribe button\",\n \"properties\": [{ \"key\": \"$current_url\", \"type\": \"event\", \"value\": \"signup\", \"operator\": \"icontains\" }]\n }\n ],\n \"dateRange\": { \"date_from\": \"-180d\" },\n \"interval\": \"week\",\n \"funnelsFilter\": {\n \"funnelWindowInterval\": 1,\n \"funnelWindowIntervalUnit\": \"hour\",\n \"funnelOrderType\": \"ordered\",\n \"exclusions\": [{ \"kind\": \"EventsNode\", \"event\": \"$pageleave\", \"funnelFromStep\": 0, \"funnelToStep\": 1 }]\n },\n \"breakdownFilter\": { \"breakdown_type\": \"event\", \"breakdown\": \"$os\" },\n \"filterTestAccounts\": true\n}\n```\n\n## Credit card purchase rate from viewing a product with strict ordering (no events in between)\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"EventsNode\", \"event\": \"view product\" },\n {\n \"kind\": \"EventsNode\",\n \"event\": \"purchase\",\n \"properties\": [{ \"key\": \"paymentMethod\", \"type\": \"event\", \"value\": \"credit_card\", \"operator\": \"exact\" }]\n }\n ],\n \"dateRange\": { \"date_from\": \"-30d\" },\n \"funnelsFilter\": {\n \"funnelOrderType\": \"strict\",\n \"funnelWindowInterval\": 14,\n \"funnelWindowIntervalUnit\": \"day\"\n },\n \"filterTestAccounts\": true\n}\n```\n\n## View product to buy button to purchase, using actions and events\n\n```json\n{\n \"kind\": \"FunnelsQuery\",\n \"series\": [\n { \"kind\": \"ActionsNode\", \"id\": 8882, \"name\": \"view product\" },\n { \"kind\": \"EventsNode\", \"event\": \"click buy button\" },\n {\n \"kind\": \"ActionsNode\",\n \"id\": 573,\n \"name\": \"purchase\",\n \"properties\": [\n { \"key\": \"shipping_method\", \"value\": \"express_delivery\", \"operator\": \"icontains\", \"type\": \"event\" }\n ]\n }\n ],\n \"funnelsFilter\": { \"funnelVizType\": \"steps\" },\n \"filterTestAccounts\": true\n}\n```\n\n# Reminders\n\n- You MUST ALWAYS use AT LEAST TWO series (events or actions) in the funnel.\n- Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.\n- Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.\n- The default funnel step order is `ordered` (events in sequence but with other events allowed in between). Use `strict` when events should happen consecutively with no events in between. Use `unordered` when order doesn't matter.\n- Exclusion events in funnels only exclude conversions where the event happened between the specified steps, not before or after the funnel.",
"category": "Query wrappers",
"feature": "insights",
"summary": "Run a funnel query",
diff --git a/services/mcp/src/tools/generated/query-wrappers.ts b/services/mcp/src/tools/generated/query-wrappers.ts
index 00b66f8b0cfc..9608d4489d5c 100644
--- a/services/mcp/src/tools/generated/query-wrappers.ts
+++ b/services/mcp/src/tools/generated/query-wrappers.ts
@@ -872,14 +872,14 @@ const AssistantFunnelsFilter = z.object({
.optional(),
})
-const AssistantFunnelsMath = z.enum(['first_time_for_user', 'first_time_for_user_with_filters'])
+const AssistantFunnelsMath = z.enum(['total', 'first_time_for_user', 'first_time_for_user_with_filters'])
const AssistantFunnelsEventsNode = z.object({
custom_name: z.string().describe('Optional custom name for the event if it is needed to be renamed.').optional(),
event: z.string().describe('Name of the event.'),
kind: z.literal('EventsNode').default('EventsNode'),
math: AssistantFunnelsMath.describe(
- 'Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.'
+ 'Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.'
).optional(),
optionalInFunnel: z.coerce
.boolean()
@@ -896,7 +896,7 @@ const AssistantFunnelsActionsNode = z.object({
id: z.coerce.number().describe('Action ID from the plan.'),
kind: z.literal('ActionsNode').default('ActionsNode'),
math: AssistantFunnelsMath.describe(
- 'Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.'
+ 'Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.'
).optional(),
name: z.string().describe('Action name from the plan.'),
optionalInFunnel: z.coerce
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/query-funnel-actors.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/query-funnel-actors.json
index 56540a969d90..a053bf099bf6 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/query-funnel-actors.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/query-funnel-actors.json
@@ -1290,8 +1290,8 @@
"type": "string"
},
"math": {
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
- "enum": ["first_time_for_user", "first_time_for_user_with_filters"],
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
+ "enum": ["total", "first_time_for_user", "first_time_for_user_with_filters"],
"type": "string"
},
"optionalInFunnel": {
@@ -1850,8 +1850,8 @@
"type": "string"
},
"math": {
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
- "enum": ["first_time_for_user", "first_time_for_user_with_filters"],
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
+ "enum": ["total", "first_time_for_user", "first_time_for_user_with_filters"],
"type": "string"
},
"name": {
@@ -2436,8 +2436,9 @@
"type": "string"
},
"math": {
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
"enum": [
+ "total",
"first_time_for_user",
"first_time_for_user_with_filters"
],
@@ -3098,8 +3099,9 @@
"type": "string"
},
"math": {
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
"enum": [
+ "total",
"first_time_for_user",
"first_time_for_user_with_filters"
],
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/query-funnel.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/query-funnel.json
index 98d782fedecf..08573ef57997 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/query-funnel.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/query-funnel.json
@@ -1241,8 +1241,8 @@
"type": "string"
},
"math": {
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
- "enum": ["first_time_for_user", "first_time_for_user_with_filters"],
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
+ "enum": ["total", "first_time_for_user", "first_time_for_user_with_filters"],
"type": "string"
},
"optionalInFunnel": {
@@ -1781,8 +1781,8 @@
"type": "string"
},
"math": {
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
- "enum": ["first_time_for_user", "first_time_for_user_with_filters"],
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
+ "enum": ["total", "first_time_for_user", "first_time_for_user_with_filters"],
"type": "string"
},
"name": {
@@ -2347,8 +2347,12 @@
"type": "string"
},
"math": {
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
- "enum": ["first_time_for_user", "first_time_for_user_with_filters"],
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
+ "enum": [
+ "total",
+ "first_time_for_user",
+ "first_time_for_user_with_filters"
+ ],
"type": "string"
},
"optionalInFunnel": {
@@ -2981,8 +2985,12 @@
"type": "string"
},
"math": {
- "description": "Optional math aggregation type for the series. Only specify this math type if the user wants one of these. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
- "enum": ["first_time_for_user", "first_time_for_user_with_filters"],
+ "description": "Optional math aggregation type for the series. `total` is the default stored on saved funnels and can be preserved when rerunning one. `first_time_for_user` - counts the number of users who have completed the event for the first time ever. `first_time_for_user_with_filters` - counts the number of users who have completed the event with specified filters for the first time.",
+ "enum": [
+ "total",
+ "first_time_for_user",
+ "first_time_for_user_with_filters"
+ ],
"type": "string"
},
"name": {
diff --git a/services/mcp/tests/unit/query-wrappers-generated.test.ts b/services/mcp/tests/unit/query-wrappers-generated.test.ts
index 784128381739..621d352fe5df 100644
--- a/services/mcp/tests/unit/query-wrappers-generated.test.ts
+++ b/services/mcp/tests/unit/query-wrappers-generated.test.ts
@@ -1,7 +1,8 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
import { z } from 'zod'
import { GENERATED_TOOLS } from '@/tools/generated/query-wrappers'
+import type { Context } from '@/tools/types'
const behavioralFilter = {
type: 'behavioral',
@@ -45,6 +46,53 @@ describe('generated query wrappers', () => {
expect(tool.schema.safeParse({ ...query, properties: [behavioralFilter] }).success).toBe(true)
})
+ it('runs a saved funnel with total math once and keeps raw entrant counts', async () => {
+ const results = [
+ {
+ days: ['2026-10-05'],
+ data: [42],
+ reached_from_step_count: [100],
+ reached_to_step_count: [42],
+ },
+ ]
+ const runQuery = vi.fn().mockResolvedValue({ results, formatted_results: '42% conversion' })
+ const context = {
+ api: {
+ query: vi.fn().mockReturnValue({ runQuery }),
+ getProjectBaseUrl: vi.fn().mockReturnValue('http://localhost:8010/project/1'),
+ },
+ stateManager: {
+ getProjectId: vi.fn().mockResolvedValue('1'),
+ getCachedOrFetchProject: vi.fn().mockResolvedValue({ test_account_filters_default_checked: false }),
+ },
+ } as unknown as Context
+ const tool = GENERATED_TOOLS['query-funnel']!()
+ const params = tool.schema.parse({
+ kind: 'FunnelsQuery',
+ series: [
+ { kind: 'EventsNode', event: 'sign up', math: 'total' },
+ { kind: 'EventsNode', event: 'purchase', math: 'total' },
+ ],
+ dateRange: { date_from: '-8w' },
+ interval: 'week',
+ funnelsFilter: { funnelVizType: 'trends' },
+ output_format: 'json',
+ })
+ const result = await tool.handler(context, params)
+
+ expect(runQuery).toHaveBeenCalledTimes(1)
+ expect(runQuery).toHaveBeenCalledWith({
+ query: expect.objectContaining({
+ kind: 'FunnelsQuery',
+ series: [
+ expect.objectContaining({ event: 'sign up', math: 'total' }),
+ expect.objectContaining({ event: 'purchase', math: 'total' }),
+ ],
+ }),
+ })
+ expect(result).toMatchObject({ results })
+ })
+
it('rejects unsupported behavioral count operators', () => {
const tool = GENERATED_TOOLS['query-trends']!()