Funnel

Read one active Plan convention by id from list_conventions, including its patterns, field mappings, output-field settings and validation rules. Returns not_found for a missing or archived convention. Needs get_account permission. Not available in headless runs.

get_convention

Returns actual values for a dimension field within a date range. scope controls the Data Source boundary: inferred resolves from the dimension, workspace accepts cross-platform dimensions, and data_source enforces one immutable ID. Omitted scope preserves pre-typed compatibility behavior during migration. Deprecated source_id remains accepted but cannot be combined with scope.

get_dimension_values

Loads one export's or view's configuration (any id from list_exports) and returns a ready-to-use query template (dimensions, measures, metrics, date range, currency, filters, scope) for reproducing the exported data with query_data. A currency of `*` means the export converts nothing: pass currency `*` (native) rather than omitting it, which would convert to the workspace default. Check unsupported and unknown_fields: when non-empty the reproduction is approximate. A view stores no dates (the BI tool picks them), so its template has none: ask the user for the range.

get_export

The Flexpoints the workspace's subscription uses, its capacity and what is available, as the subscription's Flexpoints usage page shows them (credits-api `GET /usage/subscription/{subscription}/summary`). Use `available` for how many are left. Needs `get_subscription_usage` on the subscription. A subscription without a Flexpoints plan is `not_enabled`.

get_flexpoint_usage

Flexpoints per connector and destination type across the workspace's subscription, highest first, as the Resources table of the subscription's Flexpoints usage page (credits-api `GET /usage/subscription/{subscription}/resourceSummary`). Paused resources use no Flexpoints, as on the page, and are left out unless `status` asks for them. Needs `get_subscription_detailed_usage` on the subscription.

get_flexpoint_usage_by_connector

The Flexpoints attributed to each workspace of the workspace's subscription, highest first, with the subscription's pool, as the Workspaces tab of its Flexpoints usage page (credits-api `GET /usage/subscription/{subscription}/workspace-summary`). Workspaces share the pool, so only the pool has capacity. Needs `get_subscription_detailed_usage` on the subscription. A subscription without a Flexpoints plan is `not_enabled`.

get_flexpoint_usage_by_workspace

Reads how a portal's dashboards are grouped and ordered for its viewers (portal-service `GET /accounts/{workspace}/portals/{id}/dashboard-sort-config`), with each dashboard's title as the portal shows it. Groups are in display order; the group with `name: null` holds the ungrouped dashboards. Dashboards the portal has that no group lists are appended to it, and ids the portal no longer has are dropped, as the Portals page does. `not_found` when the workspace has no such portal. Needs `get_account`.

get_portal_dashboard_groups

Retrieves workspace context — administrator-authored conventions, business rules, and domain terminology — to improve analysis accuracy and terminology alignment. Call once per workspace after `load_workspace`, before analyzing data. The context is returned as markdown in both content[0].text and the structured workspace_context field so clients with either result-channel behavior can inject it into the model's understanding. Cached per session (5-minute TTL) — repeated calls return instantly. Falls back gracefully if context is unavailable.

get_workspace_context

Read the management state of one exact Data Source UUID from list_data_sources, search_fields category=source or list_deleted_data_sources. Resolves its private Depository key within the authorized workspace; a missing or inaccessible source returns not_found. Never changes the source.

inspect_data_source

Lists the workspace's archived Plan budgets (plan-api `GET /{workspace}/budgets/archive`), sorted by name; `updated_at` is when it was archived or last changed. Use it to find the id prepare_restore_budget takes. Archived budgets have no data source, so get_data has no series for them. Needs `get_account` on the workspace.

list_archived_budgets

List archived Plan conventions in a workspace, sorted by name. These are not active and cannot be fetched with get_convention. Needs get_account permission. Not available in headless runs.

list_archived_conventions

Lists the workspace's configured Plan budgets (plan-api `GET /{workspace}/budgets/v2`; archived budgets excluded), sorted by name. Match the user's wording against name and description, then pass the id to get_data as budget_id. Needs `get_account` on the workspace.

list_budgets

Lists the workspace's client portals with their brand, dashboard count and user count (portal-service `GET /accounts/{workspace}/portals`), newest first, up to 500. Needs `get_account` on the workspace.

list_portals

List curated Funnel template candidates for one connector in the selected workspace without a setup snapshot or an existing source. Use the connector_id from list_connectors or source inspection. This read does not establish whether an existing source may switch to a candidate; Depository validates reconfiguration. No definitions or credentials are returned.

list_connector_templates

List the bounded Funnel connectors available for data source setup in the selected workspace. Pass a returned connector_id to start_data_source_setup or start_data_source_authentication.

list_connectors

List active Plan conventions in a workspace, sorted by name. Returns names, levels, input fields and counts; use get_convention for patterns and output fields. Needs get_account permission. Not available in headless runs.

list_conventions

Lists the workspace's dashboards by title, with their ids (dashboards-service `GET /accounts/{workspace}/dashboards`), up to 1000. Reading the list counts no dashboard view. Needs `get_account` on the workspace.

list_dashboards

List eligible curated Funnel templates for the remote account in an immutable setup snapshot. This does not create or modify a data source.

list_data_source_templates

List active (not deleted) sources in the selected workspace to find the exact public UUID for inspect_data_source and the source management tools. Unlike search_fields, it includes sources excluded from Funnel's data. Pass search (case-insensitive name substring) to find a named source and connector_id to narrow to one connector; page with offset if has_more (offset stops at 9,900; beyond that, narrow with search or connector_id). No private Depository keys or credentials are returned. Identify one source by customer-visible name and connector, then inspect its UUID; if several match, ask the user. Do not change a source from an ambiguous or incomplete result.

list_data_sources

List soft-deleted sources in the selected workspace to discover an exact public UUID for restore_data_source. Uses a workspace-scoped DELETED-state search; no private Depository keys or credentials are returned. Page with offset/limit if has_more; identify one source by customer-visible name and connector, then inspect its UUID. Do not guess or restore a source from an ambiguous or incomplete result.

list_deleted_data_sources

Lists the caller's own connections that can write to a destination type (Connection API `GET /v3/connection`): Google connections that granted the destination's scopes (Sheets for `gsheets`; BigQuery and Cloud Storage for `bigquery`; Cloud Storage for `gcs`), and Snowflake ones (a user with a programmatic access token or a key pair) for `snowflake`. Pass one `id` as the destination's `connection_id` in prepare_create_export. When `connections` is empty, the user must connect an account first: give them `connect_url`, a Funnel page where they sign in (the credentials are entered there, never in chat), then list again once they say they are done. A null `connect_url` means the account must be connected on the new-export page in Funnel (`app_url`). Never changes anything.

list_export_connections

Lists the destinations Funnel data can be exported to, and how each is created: from chat (`create: chat`, with `tool`) or only in Funnel (`create: app`, give the user `app_url`). Whether the workspace's plan allows a destination is checked when it is created. Never changes anything.

list_export_destinations

Lists the data exports configured in a workspace — scheduled pushes of Funnel data to Google Sheets, Excel, BigQuery, Snowflake, S3 and similar destinations — and its views, which a BI tool (Looker Studio, Tableau, Power BI) reads from Funnel (`kind`). Match the user's wording against name and remote_target, then call get_export with the item's id and kind. Only an export (`kind: export`) can be turned on or off or run.

list_exports

List curated Funnel guides when guide_id is omitted. With guide_id=field-rules, read the custom field rule and formula authoring guide. Read-only; mutate_fields may not be available in every environment.

list_guides

Lists the portal brands of the subscription that owns the workspace (portal-service `GET /subscriptions/{subscription}/brands`), by name. Needs `get_account` on the workspace and `get_subscription` on its subscription.

list_brands

Lists the dashboards in one portal of the workspace, by the title the portal shows (portal-service `GET /accounts/{workspace}/portals/{id}/items`), with the portal itself. `not_found` when the workspace has no such portal. Needs `get_account`.

list_portal_dashboards

Lists the users who can open one portal of the workspace (portal-service `GET /accounts/{workspace}/portals/{id}/users`), newest first, up to 1000, with the portal itself. Each user's email, display name and workspace roles come from auth-service's workspace users (`GET /accounts/{workspace}/users`); they are null for a user no longer in the workspace, except that a user id that is an email is its own email. `not_found` when the workspace has no such portal. Needs `get_account`.

list_portal_users

Lists Funnel workspaces accessible to the current user, grouped by subscription. Each subscription represents an organisation in Funnel. Within each subscription, workspaces represent individual advertisers or business units with their own connected ad platforms (Google Ads, Meta, LinkedIn, etc.). A user may have access to workspaces across multiple subscriptions. The returned workspace IDs are used by all other tools. Invoke when the target workspace is unknown, or to discover which workspaces are available for analysis.

list_workspaces

Loads a workspace's available data: ad platforms, dimensions (campaign name, country, ad group, etc.), measures (spend, clicks, impressions), and metrics (CPC, CTR, ROAS, etc.). Returns a summary of connected platforms with field counts, source health status, and which cross-platform metrics are available. Cached per session — repeated calls for the same workspace return instantly. Required once per workspace before querying data or searching for fields. Input: workspace ID from list_workspaces. After loading, call `get_workspace_context` once for this workspace to retrieve administrator-defined conventions, business rules, and domain terminology that improve analysis accuracy and terminology alignment.

load_workspace

Proposes adding dashboards (ids from list_dashboards) to a portal. Each dashboard is read from dashboards-service in the workspace: `dashboards` are those that will be added, under their titles; `already_in_portal` and `not_found` will not be. Returns `unchanged` when none can be added. Changes nothing: returns `change` to show the user and a `proposal` for execute_portal_change. `not_found` when the workspace has no such portal. Needs `get_account` + `edit_portals`. Show the user `change` and ask them to approve it; only then call execute_portal_change with the proposal_id. Nothing is changed until then.

prepare_add_dashboards_to_portal

Proposes archiving an active budget. Archiving deletes its budget data source, so its series leaves get_data and dashboards until it is restored with prepare_restore_budget. Changes nothing: returns `change` to show the user and a `proposal` for execute_budget_change. `not_found` when the workspace has no such active budget. Needs `get_account`, `edit_plan_budgets`, `edit_fields` and `edit_datasources`. Show the user `change` and ask them to approve it; only then call execute_budget_change with the proposal_id. Nothing is changed until then.

prepare_archive_budget

Proposes restoring an archived budget (an id from list_archived_budgets) and its data source. Changes nothing: returns `change` to show the user and a `proposal` for execute_budget_change. `not_found` when the workspace has no such archived budget. Needs `get_account`, `edit_plan_budgets`, `edit_fields` and `edit_datasources`. Show the user `change` and ask them to approve it; only then call execute_budget_change with the proposal_id. Nothing is changed until then.

prepare_restore_budget

Proposes renaming an active budget or changing its description. Only the fields given change; `description: ""` clears it. Targets, dates and breakdowns are edited in Plan, not here. Changes nothing: reads the budget and returns `unchanged` when it already is that way, otherwise `change` to show the user and a `proposal` for execute_budget_change. `not_found` when the workspace has no such active budget. Needs `get_account`, `edit_plan_budgets`, `edit_fields` and `edit_datasources`. Show the user `change` and ask them to approve it; only then call execute_budget_change with the proposal_id. Nothing is changed until then.

prepare_update_budget

Proposes creating a client portal in the workspace, without dashboards; add them with prepare_add_dashboards_to_portal once it exists. A `brand_id` must be one of the subscription's brands (list_brands). Changes nothing: returns `change` to show the user and a `proposal` for execute_portal_change. Needs `get_account` + `edit_portals`. Show the user `change` and ask them to approve it; only then call execute_portal_change with the proposal_id. Nothing is changed until then.

prepare_create_portal

Proposes deleting a portal: its users lose access and its dashboards are untouched. There is no route to restore a portal, so treat it as permanent. Changes nothing: returns `change` to show the user and a `proposal` for execute_portal_change. `not_found` when the workspace has no such portal. Needs `get_account` + `edit_portals`. Show the user `change` and ask them to approve it; only then call execute_portal_change with the proposal_id. Nothing is changed until then.

prepare_delete_portal

Proposes renaming a portal, changing its description, or setting, changing or removing its brand. Only the fields given change; `brand_id: null` and `description: null` clear them. Reads the portal and returns `unchanged` when it already is that way. Changes nothing: returns `change` to show the user and a `proposal` for execute_portal_change. `not_found` when the workspace has no such portal. Needs `get_account` + `edit_portals`. Show the user `change` and ask them to approve it; only then call execute_portal_change with the proposal_id. Nothing is changed until then.

prepare_update_portal

Loads raw, row-level data without aggregation for custom analysis and re-slicing. scope controls the Data Source boundary: inferred resolves from requested fields, workspace accepts cross-platform fields, and data_source enforces one immutable ID. Omitted scope preserves pre-typed compatibility behavior during migration. Deprecated source_id remains accepted but cannot be combined with scope. When provided, the validated scope is applied to the MELD fetch, persisted with the table, and returned in metadata. Field discovery is platform-catalog evidence, not proof that every field is enabled by one exact source configuration.

prepare_data

Propose creating one Funnel data source from a completed setup (connection, remote account and template selected). Changes nothing: the setup is checked again and the exact create is signed. Show the user `change` (connector, connection, remote account, template and name) and ask them to approve it; only then call execute_create_data_source with the proposal_id. `use_connect` means this setup cannot be created here; the user sets it up in Connect.

prepare_create_data_source

Proposes a new enabled, scheduled export of workspace data to a destination, and by default runs it once right after it is created. Changes nothing: returns `change` to show the user and a `proposal` for execute_export_change. `destination.type` picks the destination: `gsheets` (a Google Sheets tab, replaced on every run), `bigquery` (a table in the user's own Google Cloud project) or `snowflake` (a table in the user's own Snowflake account, in an existing database) or `gcs` (gzip CSV files in the user's own Cloud Storage bucket, one per month). A BigQuery or Snowflake table, or a Cloud Storage export's files, is written in monthly parts on the `date` dimension, which it must include, and kept up to date for the export's date range. Fields are checked against the workspace catalog: an unknown id, or one under the wrong role, is `invalid_input`; so is a connection that is not one of the user's (list_export_connections). Runs daily at `schedule.hour`:`schedule.minute` in `schedule.time_zone`, exactly as given. Needs `get_account` + `edit_shares`. Show the user `change` and ask them to approve it; only then call execute_export_change with the proposal_id. Nothing is changed until then.

prepare_create_export

Proposes turning one export's schedule on or off. Changes nothing: reads the export and returns `unchanged` when it already is in that state, otherwise `change` to show the user and a `proposal` for execute_export_change. Needs `get_account` + `edit_shares`. Show the user `change` and ask them to approve it; only then call execute_export_change with the proposal_id. Nothing is changed until then.

prepare_set_export_enabled