Detrics

Checks the status of an in-progress OAuth connection flow by the polling job id returned by connect_platform. Returns whether the user has completed authorization or the flow is still pending.

check_connection_status

Initiate OAuth connection flow for a new datasource. Returns a URL that the user must open in their browser to authorize access. Safe to use for an already-connected platform: if the user authorizes with the same platform account, the existing connection is updated in place (tokens and account list refreshed) — no duplicate connection is created.

connect_platform

Get details of a specific AI Context by ID. Returns the context name and all platform data sources with their account IDs.

get_context

Reads Data Warehouse state: destinations, transfers, table groups, tables, runs, audit log, shares, folders, tags, presets, platform defaults and BigQuery schema previews. Use it to inspect or diagnose the workspace's BigQuery warehouse. The entity parameter selects what to read. With id (any warehouse UUID) it returns that record, resolved polymorphically for the entity — a transfer id under entity "transfer_run" returns that transfer's runs, a run id returns the run's detail with chunks (failed first). Without id it returns a paginated listing (default 20 per page, max 100) with sort_by / sort_order overrides plus total and has_more. entity "overview" returns destination statuses, transfer counts and recent failures. entity "transfer" with id returns full detail with bundled destination/table-group summaries, per-table sync settings, live sync progress, last runs and recent audit entries. entity "schema_preview" requires platform_api and metrics (optional dimensions and time_aggregation) and returns the BigQuery column schema that field selection produces — data previews come from query_marketing_data with the same fields. entity "preset" and entity "platform_defaults" require platform_api.

get_warehouse

Returns the AI Contexts in the current workspace. An AI Context is a named collection of platform accounts used to scope queries — a context_id can be passed to query_marketing_data in place of connection_id and account_ids. The default response is a summary per context ({ context_id, name, platforms with accounts_count }); include_account_ids=true adds each platform's account_ids with id and display_name. Filters: name_contains (case-insensitive substring on the context name) and platform_api (only contexts including that platform). If the workspace has no contexts, the response falls back to a connections summary.

list_contexts

Returns the accounts available for a platform_api in the current workspace, deduplicated across connections. Each row includes platform_account_id, display_name, platform_api and status. platform_account_id is the external platform's own identifier (Facebook ad account number, Google Ads customer ID, Shopify store domain) and is the value query_marketing_data takes in account_ids.

list_accounts

Returns the platforms connected in the current workspace. Use it to see which data sources are available or to obtain a connection_id. The default mode is a per-platform summary with connection_count, unique_accounts_count and active_connection_count; setting platform_api or mode "connections" returns one row per connection with its connection_id. In connections mode, rows without a status field are active — only non-active connections carry an explicit status. The same external account can appear under multiple connections when several teammates connect it independently; unique_accounts_count is the deduplicated total.

list_connections

Returns the available metrics and dimensions for a platform_api, with metadata (tooltips, categories, compatibility rules). Use it to discover the valid field names for a platform before querying — names differ per platform and per workspace. Platforms with large catalogs return a category index ("mode":"index" with categories, most_used and field_counts) instead of the full list; search, category or include_all narrow or expand a follow-up call, and limit caps results per list (default 50). Passing connection_id adds the workspace's custom fields to the standard ones; on ad/analytics platforms (facebook-ads, google-analytics-4, klaviyo, appsflyer) account-scoped custom fields also require account_ids. CRM platforms (hubspot, salesforce) have per-object-type fields: a call with only platform_api returns the available_entities list, and a call with entity plus connection_id returns that entity's standard and custom fields (custom properties, e.g. HubSpot deal properties, only appear at that point).

list_fields

Creates and manages BigQuery destinations — the customer's GCP project and dataset where synced data lands. The action parameter selects the operation. setup_mode, gcp_project_id, dataset_name, dataset_location and timezone are permanent after creation; only the display name and image storage can change later. setup_mode "standard" (default): Detrics is granted BigQuery User at project level and creates the dataset itself. "least_privilege": the customer pre-creates the dataset and grants BigQuery Job User at project scope plus BigQuery Data Editor at dataset scope. The create response includes the IAM grant instructions and, by default, the result of an immediate connection test (test_after_create: false skips it). test_connection reports per-stage results: BigQuery Connectivity, Project Access, Dataset Permissions, Table Permissions, Job Permissions. send_setup_instructions emails the IAM steps to a recipient. delete requires confirm: true and never touches BigQuery data.

manage_warehouse_destination

Creates and manages warehouse table groups (per-platform collections of table schemas) and tables (field selections that become BigQuery tables). The action parameter selects the operation. A table group holds many tables for one platform and is a reusable schema — it syncs nothing on its own; transfers (manage_warehouse_transfer) bind it to destinations and accounts, and each transfer independently enables/disables the group's tables and can override their filters, so one group serves multiple transfers. create_group_from_preset instantiates a curated group and tables from a preset_key (presets come from get_warehouse entity "preset"). Custom table creation validates metrics and dimensions against the platform's field catalog (list_fields) and rejects unknown names with did-you-mean suggestions; custom/dynamic fields (GA4 custom events, HubSpot properties) validate once discovered via list_fields with connection_id. Data previews come from query_marketing_data with the same fields — there is no preview action here. Fields flagged ephemeralUrl (e.g. facebook-ads ad_image_url) are re-hosted into the destination's image bucket when image storage is configured: the sync rewrites the column to a durable URL keyed on the field's ephemeralUrlEntityField (e.g. ad_id), which must also be selected in the table — re-hosting is silently skipped without it. Destinations without image storage keep the raw expiring URL. update_table on a table feeding active transfers returns a schema-impact report on the first call without saving — each change carries a what_happens string with its physical BigQuery consequence (column added and filled forward, table archived and rebuilt, resync needed) — and a second call with confirm: true applies it; blocking_conflicts (e.g. moving off daily aggregation while a transfer syncs incrementally) are rejected outright. Removing a field still referenced by filters is rejected on platforms without dimensionless filtering; platforms that support it (e.g. GA4) allow the removal and the filter keeps working. rename_table is blocked once the table has synced (the BigQuery table name derives from it; copy_table plus delete_table achieve a rename). Max 500 columns per table. Dimension filter operators: contains, equals, not_equals, not_contains, regex_contains, regex_contains_exact, regex_not_contains_exact; filters may reference dimensions not selected in the table on platforms that support dimensionless filtering. delete_table and delete_group require confirm: true.

manage_warehouse_table