Funnel

Returns actual values for a dimension field within a date range — e.g., campaign names, country codes, ad group names, platform names. Useful for previewing what filter values exist before building a query, or for answering "what campaigns ran in Q1?" directly. Inputs: workspace ID, dimension field ID (from search_fields or load_workspace), date range. For platform-specific dimensions on workspaces with multiple accounts on the same platform, a source ID is needed to disambiguate.

get_dimension_values

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 content[0].text and is auto-injected 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

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

Loads raw, row-level data without aggregation — every individual data point as reported by the ad platform. Intended for scenarios where the same data needs to be sliced multiple ways (use query_data mode="aggregate" afterward), or when individual-row inspection is needed. Unlike query_data mode="query" which aggregates at load time (e.g., summing daily spend by campaign), this preserves the raw grain. Returns available ratio metrics that can be computed on the loaded data. Inputs: workspace ID, unique table name, dimensions, measures, date range. Platform-specific dimensions need a source ID. Surfaces a source selection prompt when multiple sources exist for the same platform.

prepare_data

Queries advertising data from connected platforms. Returns tabular results into a named session table for further analysis. **1. Pick a mode:** - query — fetch fresh data by dimensions and measures for a date range - compare_channels — compare metrics across all platforms (cross-platform fields ONLY) - aggregate — re-slice a previously loaded table at different grain (no new fetch) - compute_metric — calculate a ratio (CPC, CTR, ROAS) on a loaded table - restore — reload data evicted from session memory **2. SCOPING RULES (critical — most errors happen here):** - Each field is scoped to cross_platform or a specific platform. - Platform-specific fields require source_id (auto-resolves for single-source platforms). - All-cross-platform queries must omit source_id (returns workspace-wide totals). - All platform-specific fields in a query must belong to the same platform. **3. Required fields per mode:** - query: workspace_id, result_table_name, dimensions (use [] for totals), measures, date_start, date_end - compare_channels: workspace_id, result_table_name, measures, date_start, date_end (optional: metrics for ratio computation) - aggregate: workspace_id, source_table_name - compute_metric: workspace_id, source_table_name, ratio_id - restore: workspace_id, evicted_table_name **4. Source disambiguation:** When multiple sources exist and none is specified, the response returns source_selection_required with available_sources grouped by account. Platform-specific queries accept source_id to resolve. Cross-platform queries accept source_overrides with one source_id per group (a platform may have multiple groups if it has multiple accounts). Dates: YYYY-MM-DD. Percentages as decimals (0.021 = 2.1%). Default limit 500 rows (full result kept server-side; if truncated, re-slice with mode="aggregate" rather than raising limit). **Examples:** Cross-platform totals: {"mode":"query","workspace_id":"<id>","result_table_name":"totals","dimensions":[],"measures":["common-cost","common-impressions"],"date_start":"2025-01-01","date_end":"2025-03-31"} Single-source with platform fields: {"mode":"query","workspace_id":"<id>","result_table_name":"fb_campaigns","dimensions":["facebookads-campaign_name"],"measures":["common-cost","common-clicks"],"source_id":"<source_id>","date_start":"2025-01-01","date_end":"2025-03-31"} Daily breakdown (re-aggregate): {"mode":"aggregate","source_table_name":"fb_campaigns","group_by":["facebookads-campaign_name","date"],"measures":["common-cost"],"date_granularity":"day"}

query_data

Finds available dimensions, measures, and metrics in a workspace. Three modes: **semantic** (preferred) — AI-powered field discovery. Classifies your intent into structural filters (category, platform), narrows the catalog, then selects the most relevant fields by reading their labels and descriptions. Handles synonyms, acronyms, and cross-platform vs platform-specific disambiguation automatically. Ask natural language questions like "how much did I spend on Facebook", "hubspot demo conversions", "cross-platform performance metrics", "pipeline velocity". **browse** — Navigate fields by platform, category (dimension/measure/metric), or group. Use for structured exploration or listing data sources with their IDs. **search** — Keyword text matching. Use only when you know the exact field name or label. Prefer semantic mode for discovery. Use browse to drill into a known group. Use search only for exact lookups.

search_fields

A special tool that returns a trimmed down list of tools given a context. Use this tool only when there are many tools available and you want to get a subset that matches the provided context.