MCP Tools

This page is the reference for the tools the Attribution MCP server makes available to AI assistants. Each entry says whether your project has the tool, which OAuth scope it uses, what it does, an example of what to ask, its parameters, and what comes back.

Every data tool is read-only — see Scopes. The one exception is logout, which ends your own MCP session.

For how to connect and authenticate, see Attribution MCP Server. For what has changed, see the changelog.

Availability

Each tool carries one of three availability labels:

Stable — tested and offered to customer projects. Every tool on this page is Stable.
Preview — works and has been checked, but not yet enabled for customer projects. Documented separately; ask us if you would like early access to one.
Experimental — untested and not intended for use. These exist and are documented alongside the preview tools so we can polish and open one up when a project needs it; until then, treat them as unavailable.

Stable describes the tool, not your project: not every Stable tool is switched on everywhere.

📘
Which tools does my assistant actually have?
Ask it to run whoami. The answer lists the exact tools the assistant can see on this connection, along with the account, project and scopes it is bound to. If a tool on this page is missing from that list, it is not enabled for your project yet.

Tools are grouped by category: Project, Filters, Events, Reports and Misc. Each tool's entry names the scopes it needs; Scopes defines what each one grants.

Which tool answers what

When you ask…	The assistant uses
"How are my channels performing?", "Where am I losing money?", "Profit by channel"	`get_dashboard_report`
"How does this month compare to last month?", "What changed?"	`get_dashboard_comparison`
"How long until a cohort pays back?", "Are recent cohorts worse than older ones?"	`get_cohort_report`
"Are paid channels bringing in new customers or repeat buyers?"	`get_first_time_purchasers_report`
"What do converting journeys look like?", "Which channels assist?"	`get_paths_report`
"What channels and campaigns do I have set up?"	`get_filter_tree_markdown`
"Which events do we track?", "What is my conversion event called?"	`list_event_names`
"How do the attribution models differ?"	`list_attribution_models`
"What saved views do I have?"	`list_project_views`
"What is this connection?", "Which tools can you see?"	`whoami`

Common report parameters

The report tools read their settings from one of your saved views: attribution type, lookback window, traffic option, cutoff event, revenue group and timezone. Traffic your project excludes from reporting is excluded here too. That keeps the numbers identical to what you see on the dashboard with the same view selected. Only the parameters below can be changed per call. To change anything else, pick a different view.

Parameter	Required	Description
`view_id`	Yes	The saved view ID, from `get_project_context` or `list_project_views`.
`start`, `end`	No	Date range, `YYYY-MM-DD`, both days inclusive, as calendar days in the project timezone. Omit both to use `date_preset`; omit all three to use the view's saved date range.
`date_preset`	No	A named range. Dashboard presets: `yesterday`, `last 7 days`, `last 30 days`, `last month`, `last 3 months`, `last 6 months`, `last year`, `recent days`. Also accepted: `last week`, `this month`, `this quarter`, `last quarter`, `this year`, and any `last N days` or `last N months`.
`conversion_event_name`	No	Overrides the view's conversion event. Case does not matter, but the name must exist in the project; `list_event_names` shows them.
`attribution_model`	No	`linear`, `first_touch`, `last_touch`, `time_decay` or `position_based`. Defaults to the view's model.
`filter_ids`	No	Show only these filters, each with its sub-filters and its parent rows for context. IDs come from `get_filter_tree_markdown`.
`filter_group_ids`	No	Show only these channels, each with all of its sub-filters.

Three things to know:

Scoping slices the rows, not the totals. With filter_ids or filter_group_ids, the per-channel rows are limited to what you asked for, but the Summary totals and the Total row still cover every channel, and the output says so. IDs that do not resolve are called out, and if none resolve the call errors instead of silently running unscoped. Channels and filters you have hidden on a saved view are a dashboard display choice, not a report setting: reports include them, so the rows add up to the Total, and the assistant can scope to a hidden channel by its ID.
Unsupported parameters are refused. If a tool does not support a parameter, the call fails with an error naming it. Nothing is silently ignored.
Reports compute on demand. Most return in seconds; long date ranges on large projects can take up to a few minutes. The output of the dashboard, comparison, cohort and first-time purchasers reports starts with a link to open the same report on your dashboard.

Project

Orientation: what the project is, which saved views exist, and which attribution models are available.

`get_project_context`

Availability: Stable · Scope: project:read, filters:read, account:read

The first call in any conversation. Returns everything the assistant needs to orient itself in one shot: project name and timezone, today's date in that timezone, the project description you wrote in Attribution, the signed-in account and whether it owns the project, every saved view with its ID (the view you last selected in the dashboard is marked as current), that view's full configuration (model, conversion event, attribution type, lookback window, traffic option, date range, revenue group), the revenue group catalog, and the top two levels of your channel tree. This is where the assistant learns your vocabulary, so it can use your channel names and event names instead of guessing.

Try asking: "Connect to my Attribution project and tell me what you can see."

Parameters: none.

What comes back: a structured summary with sections for the project, account, views, current view settings (named, with its ID), revenue groups and channel tree. The revenue group catalog always lists All Revenue (ID -1, every revenue-bearing event counts) and Conversion Event (ID 0, only the conversion event counts) alongside the groups you defined, and the current view's revenue group is shown with its ID so the assistant can refer back to it.

`list_project_views`

Availability: Stable · Scope: project:read

Returns every saved view with its full configuration: conversion event, attribution model, attribution type, lookback window, traffic option, cutoff event, revenue group, date range preset, aggregation period and event property filter. The view ID is the key every report tool takes. The lists of filters and channels a view hides on the dashboard are not included; they only affect what the dashboard displays.

Try asking: "Which saved views do I have, and what conversion event does each one use?"

Parameters: none.

What comes back: the list of views as JSON.

`list_attribution_models`

Availability: Stable · Scope: none

Returns the five attribution models Attribution supports, with their definitions: Linear, First Touch, Last Touch, Time Decay and Position-Based. The assistant uses these definitions verbatim when explaining a model, and the model name when switching a report to a different model.

Try asking: "Explain the difference between time decay and position-based attribution."

Parameters: none.

What comes back: a list of the five models, each with its identifier and a one-sentence definition.

Filters

Your channel tree: the channels (filter groups) and the filters underneath them that classify traffic.

`get_filter_tree_markdown`

Availability: Stable · Scope: filters:read

Returns the top levels of your channel and campaign tree as readable text, with names, IDs, type tags (Integration Channel, Campaign, Ad Set, Search Campaign, Flow, Organic, Affiliate and so on) and integration metadata. This is how the assistant answers "what channels do I have" and how it finds the IDs it needs to scope a report to one channel.

Try asking: "Show me my channel structure. Which channels come from ad integrations?"

Parameters: none.

What comes back: an indented text tree with IDs.

`get_filter_tree`

Availability: Stable · Scope: filters:read

Returns the complete tree as flat JSON with full metadata at every level, however deep the project's tree goes (channel → campaign → ad set → keyword → creative). Each node carries its ID, name, type, depth, parent, sort order, visibility, integration source, item type, any special role (retargeting, virtual, direct, unsegmented) and virtual-filter membership. The assistant reaches for this only when it needs depth or metadata the readable tree does not show.

Try asking: "List every keyword-level filter under our Google Ads channel, including hidden ones."

Parameter	Required	Description
`include_invisible`	No	`true` to include filters and channels hidden on the dashboard. Default `false`.
`oauth_id`	No	Return only the nodes created by one integration.

What comes back: a flat JSON list of nodes.

Events

Discovery for the event names your reports run against, and the properties recorded on them.

`list_event_names`

Availability: Stable · Scope: reports:read

Returns every tracked event name in the project with a flag for whether it carries revenue. The assistant calls it before running a report when you name a business concept ("signups", "deals", "orders") rather than the exact event name, so the report runs on an event that exists.

Try asking: "Which events do we track, and which of them carry revenue?"

Parameter	Required	Description
`start`	No	Only events seen from this date, `YYYY-MM-DD`.
`end`	No	Only events seen up to this date.
`timezone`	No	IANA timezone for the date range.
`with_revenue_only`	No	`true` to return only revenue-bearing events.
`include_event_source`	No	Only events from this source.
`exclude_event_source`	No	Exclude events from this source.

What comes back: a list of event names with a has-revenue marker and source information.

Reports

The formatted reports. Each one runs the same computation as the corresponding dashboard page and returns a readable table with a server-computed Summary block, so the assistant reads results rather than doing arithmetic. All of them take the common report parameters unless noted.

`get_dashboard_report`

Availability: Stable · Scope: reports:read, project:read, filters:read

Your marketing P&L in one table: one row per channel and per sub-filter, with paid and unpaid sources (paid media, organic, direct, affiliate, offline, custom channels) in a single denominator. Columns: Spend, Cost Per Conversion, ROAS, Visits, Conversion Rate, Conversions (fractional multi-touch credit), Revenue Per Conversion, Revenue, and Profit (loss), plus a Total row. Rows are indented to show the channel → filter hierarchy in the same order as the dashboard. This is the workhorse: most "how is X performing", "where am I losing money", "what should I cut or scale" questions are answered by one call.

Try asking: "Get last month's dashboard report. Which channels are profitable, and where are we losing money?"

Parameters: the common report parameters.

What comes back: a Summary block (project totals, top three profit drivers, top three profit drains), then the hierarchical table with a bold Total row. Derived metrics use Attribution's formulas; the assistant is instructed to quote them rather than recompute them.

`get_dashboard_comparison`

Availability: Stable · Scope: reports:read, project:read, filters:read

Two dashboard reports side by side, with the differences computed for you. Period A is the subject and period B the baseline; when you give no baseline, it defaults to the equivalent period immediately before A. Use it for any "versus last month", "month over month" or "what moved" question instead of two separate reports.

Try asking: "Compare this quarter to last quarter. Which channels gained the most profit and which dropped?"

Parameters: view_id, conversion_event_name, attribution_model, filter_ids and filter_group_ids as in the common report parameters (they apply to both periods), plus the two date ranges:

Parameter	Required	Description
`start_a`, `end_a`	No	Period A, `YYYY-MM-DD` inclusive. Omit both to use `date_preset_a`; omit all three to use the view's saved range.
`date_preset_a`	No	Period A as a preset. Same values as `date_preset`.
`start_b`, `end_b`	No	Period B. Omit both, and `date_preset_b`, to use the equivalent period immediately preceding A.
`date_preset_b`	No	Period B as a preset.

The event, model and scoping are shared lenses for both sides. To compare two different events or models, run two dashboard reports.

What comes back: a Summary block with the Total deltas, the three biggest profit gains, the three biggest profit drops and any channels whose profit crossed zero (marked ⚠️), then a table with Spend, Conversions, Revenue and Profit for A and B and their deltas per channel, sorted like the dashboard. A channel present in only one period shows — on the other side. When the baseline profit is exactly zero, the percentage cell reads new instead of a number.

`get_cohort_report`

Availability: Stable · Scope: reports:read, project:read, filters:read

Revenue accumulation by acquisition cohort, for CAC payback and cohort quality questions. One row per cohort of visitors first acquired in a period, with Spend, Revenue to date, ROAS and the age at which the cohort broke even, followed by age columns showing cumulative revenue after 1, 3, 6… periods. Compare cohorts at the same age, not on totals; a — cell means the cohort has not reached that age yet.

Try asking: "Show me monthly acquisition cohorts for the last year. How many months does it take a cohort to pay back its spend, and are recent cohorts paying back faster or slower?"

Parameters: the common report parameters, with two differences:

Parameter	Required	Description
`period`	No	Cohort period: `Day`, `Week`, `Month` or `Quarter`. Defaults to the view's saved aggregation period, then `Month`.
`filter_ids` / `filter_group_ids`	No	Here these choose the acquisition source, like the Source selector on the dashboard's cohort page: only visitors first acquired through these filters or channels form the cohorts. Pass one kind or the other, not both; a virtual filter must be passed alone. Omit both to cohort all traffic.

What comes back: a Summary block (total spend, revenue and ROAS, how many cohorts have paid back, the median payback age, and a newest-versus-prior cohort trend at a common age), then the cohort matrix. Very wide matrices keep only the payback-milestone age columns and say so.

`get_first_time_purchasers_report`

Availability: Stable · Scope: reports:read, project:read, filters:read

Splits results into first-time purchasers (a visitor's first-ever revenue event) and repeat purchasers, per channel and per period. It answers whether paid channels are acquiring new customers or recapturing existing ones: a channel with high spend and a low first-time share is reactivating known buyers, not growing the base.

Try asking: "For last quarter, which channels brought in new customers rather than repeat buyers, and what did a new customer cost on each?"

Parameters: the common report parameters, plus:

Parameter	Required	Description
`aggregate_by_period`	No	`Day`, `Week` or `Month` for the per-period breakdown. Defaults to the view's saved aggregation period, then `Day`. Windows over 61 days use at least `Week`, over 200 days at least `Month`, matching the dashboard; the output notes it.
`paid_only`	No	`true` to include paid channels only.

Attribution type is always backward for this report, and it counts every revenue event rather than the view's conversion event, exactly like the dashboard's First-Time Purchasers page; passing conversion_event_name has no effect here. Because of that it cannot run on a view that filters by an event property; the call is refused up front with an explanation. Scoping with filter_ids / filter_group_ids slices only the per-channel rows.

What comes back: a Summary block (ad spend, first-time and repeat revenue, conversions and revenue per sale, first-time CAC, profit, ROAS, and the first-time share of conversions and revenue), a per-channel table (Spend, First-Time Conversions and Revenue, CAC (New), First-Time ROAS, Repeat Conversions and Revenue, First-Time Share, with a Total row) and a per-period breakdown.

`get_paths_report`

Availability: Stable · Scope: reports:read, project:read (plus filters:read when a path search is used)

Aggregated conversion paths, the dashboard's Common Paths view: the touchpoint sequences that lead to conversions, most frequent first. Use it for "what does the journey look like", "which channels assist versus close", "how many touchpoints before a purchase".

Try asking: "What are the most common paths to purchase this quarter, and how many touchpoints does a typical customer go through?"

Parameters: view_id, start, end, date_preset, conversion_event_name and attribution_model as in the common report parameters (this report does not take filter_ids / filter_group_ids), plus:

Parameter	Required	Description
`labels`	No	Touchpoint granularity: `channels` (default) groups sub-filters into their channel so journeys read like "Google Ads → Email → Direct"; `filters` keeps individual sources for campaign-level patterns.
`combine_recurring`	No	`true` to collapse consecutive repeats of the same touchpoint ("Google Ads → Google Ads → Email" becomes "Google Ads → Email"). Default `false`.
`match_operator`	No	Path search: `contains`, `does_not_contain`, `begins_with` or `ends_with`. Requires exactly one of the two match IDs below.
`match_filter_id`	No	The filter the path search matches on.
`match_filter_group_id`	No	The channel the path search matches on; matches journeys touching any filter in it.
`include_diagram`	No	`true` to append a journey-flow (Sankey) diagram built from the top ten paths, for clients that render Mermaid diagrams. Default `false`.

Conversions here are whole conversions per matched journey, not fractional multi-touch credit, so the totals will not reconcile with the dashboard report's Conversions column. That is expected.

What comes back: a Summary block (total conversions, distinct paths, how much of the total the top patterns cover, the most common path, the top revenue path, and the average touchpoints per conversion), then one row per pattern with Conversions, Share, Revenue, Average Revenue, Average Time to Conversion, Touches and the sequence. The top 50 patterns are listed; the Summary quantifies the remainder.

Misc

Tools that are not about your marketing data: inspecting or ending the connection, and telling Attribution a report looks wrong. All three are always available, whatever else your project has enabled, and none needs a scope.

`logout`

Availability: Stable · Scope: none

Ends the current MCP session: revokes the connection's refresh grant so it cannot obtain new access tokens, and invalidates the current access token immediately. You will need to reconnect and approve access again to use the assistant with Attribution. This is the only tool that is not read-only.

Try asking: "Disconnect from Attribution."

Parameters: none.

What comes back: a confirmation.

`whoami`

Availability: Stable · Scope: none (include_account needs account:read)

Reports what this connection is and what it can do, from the session itself: the AI client's name, the account and project the connection is bound to, the granted scopes, when the access token expires, and the exact list of tools the assistant can currently see, grouped by category. Ask for it when a tool you expect is missing, when a call is denied for scope, or when you want to confirm which project the assistant is looking at. It makes no request to Attribution unless you ask for account details.

Try asking: "Which Attribution project are you connected to, and which tools do you have?"

Parameter	Required	Description
`include_account`	No	`true` to also fetch the signed-in account's name and email. Default `false`.

What comes back: a structured summary with Connection, Tools exposed on this session and Session state sections, plus an Account section when requested.

`log_report_issue`

Availability: Stable · Scope: none

Lets the assistant flag a report that came back empty, all zeros or clearly wrong after it has ruled out the usual causes (a date range outside your data, a guessed event name, a view that excludes the relevant channels). It writes a structured note that Attribution's engineers can find. It is not a support ticket and does not notify anyone directly; for anything urgent, email [email protected].

Try asking: "That report looks wrong to me. Log it for Attribution to check."

Parameter	Required	Description
`report_id`	Yes	The report ID from the report output.
`reason`	Yes	What looks wrong, briefly.
`report_type`	No	The report type, if known.
`params`	No	A summary of the parameters used.

What comes back: a confirmation that the issue was logged.

Tool annotations

Every data tool ships with these MCP annotations, so clients know what to expect:

readOnlyHint: true — safe to auto-permission
destructiveHint: false — no data modification or deletion
idempotentHint: true — calling the same tool with the same arguments returns the same result

The one exception is logout, which manages your session rather than your data. It is annotated readOnlyHint: false, destructiveHint: true (it revokes your session), and idempotentHint: true.

Support

For questions about a specific tool, to request a tool for your project, or to report incorrect tool behavior, email [email protected].