Saved analyses tools

search_funnels: List the saved funnel analyses in a project, or fetch one by ID.
search_trends: List the saved trend analyses in a project, or fetch one by ID.
search_reports: List the saved report analyses in a project, or fetch one by ID.

search_funnels

Searches the saved funnel analyses in a project, or fetches one by ID. Funnels measure step-by-step customer conversion through event sequences. Omit funnel_id to list all funnels — the response gives you the name, tags, archived flag, initiative assignment, and whether the funnel is parametrized. Pass funnel_id to fetch the analysis body itself: funnel_steps, the customer_filter that decides who enters, the drill_down breakdown, an optional secondary metric, and parameter metadata.

A funnel has no top-level date filter. Both the date scope and the conversion window live under funnel_steps, where duration_filter is the conversion window. Chart and table display settings, such as number formatting and column ordering, are left out of the response to keep an agent's context small.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`funnel_id`	`str`	No	The funnel ID. Omit to list all funnels; provide to fetch one.

Response parameters

The tool returns a FunnelsResponse when funnel_id is omitted, or a FunnelResponse when it's provided.

When funnel_id is omitted, the FunnelsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[FunnelSummary]`	The funnel summaries.
`error`	`str \| null`	Error message if the request failed.

The FunnelSummary object has the following fields:

Field	Type	Description
`id`	`str`	The funnel's unique ID.
`name`	`str`	The funnel's display name.
`archived`	`bool`	Whether the funnel has been archived.
`tags`	`list[str]`	User-defined tags.
`initiative_id`	`str \| null`	The initiative this funnel belongs to, if any.
`created`	`any \| null`	Unix timestamp of when the funnel was created.
`created_by_display_name`	`str \| null`	Display name of the creator.
`edited`	`any \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str \| null`	Display name of the last editor.
`parametrized`	`bool`	Whether the funnel uses dynamic parameters.

When funnel_id is provided, the FunnelResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Funnel \| null`	The full funnel definition.
`error`	`str \| null`	Error message if the request failed.

The Funnel object adds the following fields on top of the summary record:

Field	Type	Description
`funnel_steps`	`any \| null`	The funnel body: each step's `name`, `type`, and event `filter`, the `duration_filter` conversion window, and an optional `date_filter`.
`customer_filter`	`any \| null`	The customer filter restricting which customers enter the funnel.
`drill_down`	`any \| null`	The drill-down configuration: `none`, `customer` for a customer attribute breakdown, or `step` for an event attribute on a step.
`metric`	`any \| null`	An optional secondary metric measured on one funnel step, given as a step index and an event attribute.
`description`	`str \| null`	An optional written description of the funnel.
`version_id`	`str \| null`	The version ID of the current funnel definition.
`parametrized`	`bool`	Whether the funnel uses dynamic parameters. When `true`, inspect `parameters` and `parameter_values`.
`parameters`	`any \| null`	The parameter definitions when `parametrized` is `true`: a list of `{name, source}` entries, including parameters inherited from prerequisite aggregates and expressions.
`parameter_values`	`any \| null`	The persisted runtime values for the parameters, as a map of parameter name to string value.

search_trends

Searches the saved trend analyses in a project, or fetches one by ID. Trend analyses show how a metric changes over time, for example daily event count or weekly revenue. Omit trend_id to list all trends — the response gives you the name, tags, archived flag, initiative assignment, and whether the trend is parametrized. Pass trend_id to fetch the analysis body itself: the event_types series with their filters, the date_filter range, the group_by time granularity, the customer_filter, and parameter metadata.

Chart display settings, such as y-axis configuration, are left out of the response to keep an agent's context small.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`trend_id`	`str`	No	The trend ID. Omit to list all trends; provide to fetch one.

Response parameters

The tool returns a TrendsResponse when trend_id is omitted, or a TrendResponse when it's provided.

When trend_id is omitted, the TrendsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[TrendSummary]`	The trend analysis summaries.
`error`	`str \| null`	Error message if the request failed.

The TrendSummary object has the following fields:

Field	Type	Description
`id`	`str`	The trend's unique ID.
`name`	`str`	The trend's display name.
`archived`	`bool`	Whether the trend has been archived.
`tags`	`list[str]`	User-defined tags.
`initiative_id`	`str \| null`	The initiative this trend belongs to, if any.
`created`	`any \| null`	Unix timestamp of when the trend was created.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`any \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.
`parametrized`	`bool`	Whether the trend uses dynamic parameters.

When trend_id is provided, the TrendResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Trend \| null`	The full trend analysis definition.
`error`	`str \| null`	Error message if the request failed.

The Trend object adds the following fields on top of the summary record:

Field	Type	Description
`event_types`	`any \| null`	The event series plotted over time. Each entry has a `type`, a `display_name`, an `enabled` flag, and a `filter`.
`date_filter`	`any \| null`	The date range for the trend, either a relative duration or an absolute from and to pair.
`group_by`	`str \| null`	The time granularity for the buckets, such as `hours`, `days`, `weeks`, or `months`.
`unique_per_customer`	`bool \| null`	Whether each customer contributes at most once per time bucket.
`customer_filter`	`any \| null`	The customer filter restricting who is included in the trend.
`description`	`str \| null`	An optional written description of the trend.
`version_id`	`str \| null`	The version ID of the current trend definition.
`parametrized`	`bool`	Whether the trend uses dynamic parameters. When `true`, inspect `parameters` and `parameter_values`.
`parameters`	`any \| null`	The parameter definitions when `parametrized` is `true`: a list of `{name, source}` entries, including parameters inherited from prerequisite aggregates and expressions.
`parameter_values`	`any \| null`	The persisted runtime values for the parameters, as a map of parameter name to string value.

search_reports

Searches the saved report analyses in a project, or fetches one by ID. Reports are multi-metric analytics views that combine event data across dimensions. Omit report_id to list all reports — the response gives you the name, tags, archived flag, initiative assignment, and whether the report is parametrized. Pass report_id to fetch the analysis body itself under server: the rows, columns, metrics, customer filter, and event filters. That means you can inspect a report's metrics and filters without spending an analytics call on calculate_report. Chart and table display settings and per-metric UI modifiers are left out to keep an agent's context small.

Check parametrized before you calculate. When it's true, the report needs runtime values for the names listed in parameters, and you supply them through calculate_report(parameter_values=...). The global_filters parameter can't carry parameter values, so a parametrized report calculated without parameter_values falls back to whatever is stored in parameter_values on the report and returns an error naming the missing parameter if nothing is stored.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`report_id`	`str`	No	The report ID. Omit to list all reports; provide to fetch one.

Response parameters

The tool returns a ReportsResponse when report_id is omitted, or a ReportResponse when it's provided.

When report_id is omitted, the ReportsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[ReportSummary]`	The report summaries.
`error`	`str \| null`	Error message if the request failed.

The ReportSummary object has the following fields:

Field	Type	Description
`id`	`str`	The report's unique ID.
`name`	`str`	The report's display name.
`archived`	`bool`	Whether the report has been archived.
`tags`	`list[str]`	User-defined tags.
`initiative_id`	`str \| null`	The initiative this report belongs to, if any.
`created`	`any \| null`	Unix timestamp of when the report was created.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`any \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.
`parametrized`	`bool`	Whether the report uses dynamic parameters.

When report_id is provided, the ReportResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Report \| null`	The full report definition.
`error`	`str \| null`	Error message if the request failed.

The Report object adds the following fields on top of the summary record:

Field	Type	Description
`server`	`any \| null`	The report analysis body: `rows` (dimensions), `columns`, `metrics`, `customer_filter`, and `event_filters` including the date range. Per-metric UI modifiers are omitted.
`parametrized`	`bool`	Whether the report uses dynamic parameters. When `true`, pass `parameter_values` to `calculate_report`.
`parameters`	`any \| null`	The parameter definitions when `parametrized` is `true`: a list of `{name, source}` entries, including parameters inherited from prerequisite aggregates and expressions.
`parameter_values`	`any \| null`	The persisted runtime values for the parameters, as a map of parameter name to string value.