Analytics and attribution

This page lists 28 tools. Each tool shows only to members whose role grants its access. The descriptions are the text that the MCP server sends to AI clients.

​

Get analytics metric

Read one dashboard metric for a period, computed as the RoofKit dashboards compute it, so the number matches the widgets. Use it for totals, comparisons, and breakdowns instead of paging leads or records. Returns total, previous_total for the same number of days just before, percent_change, unit, a breakdown when you send dimension, and daily values when you send include_series. Metrics: new_leads = Opportunities created, imports included (the dashboard Leads card). first_conversions = website conversions that created a contact; repeat_conversions = later conversions of a contact. appointments and sales = Opportunities that first entered the Appointment or Won stage. sales_value and quote_value = cents. spend = monthly spend in cents, prorated by day, with the month carry-over. cpl = spend / new_leads, cpa = spend / appointments, cost_per_acquisition = spend / sales (cents). conversion_rate = website sessions that became a lead / visits, in percent. appt_rate and sales_rate = appointments or sales / new_leads, in percent. roas and roi are ratios. Financial metrics need financial access. Arguments

​

List lead sources

List lead sources for a period with the figures of the dashboard Sources table: leads, conversions, calls, SMS, stage counts, prorated spend, CPL, CPA, and the Opportunity figures (created, appointments, won, revenue_cents, roas). lead_count = contacts with a form, call, or SMS conversion in the period, counted for their first-touch source (the dashboard Sources table). conversion_count and form_count = form conversions. conversion_rate = contacts in a conversion stage / lead_count, in percent (not the website conversion_rate metric). stage_counts are keyed by stage id; stages lists the labels. trend and trends = percent change against the same number of days just before. Arguments

​

List campaigns

List marketing campaigns for a period with the same figures as roofkit.lead_sources.list, grouped by campaign. Campaign rows have no spend or Opportunity figures, so their money fields stay null. lead_count = contacts with a form, call, or SMS conversion in the period, counted for their first-touch source (the dashboard Sources table). conversion_count and form_count = form conversions. conversion_rate = contacts in a conversion stage / lead_count, in percent (not the website conversion_rate metric). stage_counts are keyed by stage id; stages lists the labels. trend and trends = percent change against the same number of days just before. Arguments

​

List analytics reports

List the live dashboards the member can open, in the order of the app list: id, name, slug, kind, updated_at, and the in-app url. Read their numbers with roofkit.analytics.metric.get. A manager edits one with the roofkit.analytics.dashboards tools, which need its id and updated_at. Arguments This tool takes no arguments.

​

List analytics spend

List marketing spend per month and per source, as the dashboards read it: a month with no saved amount inherits the latest saved one (spend_carried_from names that month). Amounts are cents. month_totals sums each month. For spend in a date period, call roofkit.analytics.metric.get with metric spend. Save changes with roofkit.analytics.spend.save. Arguments

​

Save marketing spend

Save monthly marketing spend and other costs per source and medium, as the RoofKit Marketing spend table saves them. Confirm the amounts with the user first: a saved month also changes every later month that inherits it. Amounts are whole cents. An amount you leave out stays as it is. null clears the month, so it inherits the latest earlier amount again. Read the source_key and medium_key values with roofkit.analytics.spend.list. A source with no saved spend needs channel_label. Ads connector spend cannot change, but its other costs can. One call saves at most 100 rows within 12 months, and saves all rows or none. Returns the effective spend of the saved sources from the earliest saved month through the current month, in the spend.list row shape. Arguments

​

Record page view

Ingest a page view event. Requires an idempotency key. Arguments

​

Create dashboard

Create a custom dashboard as the member. It is live at once, and every member who can open dashboards sees it (workspace access). Send name, an optional description and default_range (default 30d), and the widgets: presets, widgets, or both. Presets come first. With presets, the rowIndex of each widget counts from the first row below them. A dashboard holds at most 24 widgets. An invalid widget or an unknown metric answers VALIDATION_ERROR with the path of the problem. The plan dashboard limit and the plan widget gates answer FORBIDDEN. Returns the dashboard id, slug, in-app url, updated_at, and the saved widgets with their ids. To share it outside RoofKit, call roofkit.analytics.dashboards.share_link. Requires an idempotency key. Arguments

​

Get dashboard share link

Return the public link of a dashboard, or create one when it has none. Anyone with the URL can view the dashboard and its current figures without signing in, so confirm with the user before you create or share it. The link is the full /share/analytics/<token> URL of the app Share panel, and it stays live until it is revoked. A new link names the member as its creator, so its financial figures follow that member’s financial access. financial_withheld true means the link hides the financial figures. A restricted dashboard, a dashboard whose public links are blocked, and a dashboard with financial data for a member without financial access answer FORBIDDEN. Requires an idempotency key. Arguments

​

Revoke dashboard share link

Revoke the public link of a dashboard. The URL stops working at once for everyone. A later share_link call creates a new URL. A dashboard without a public link answers revoked false. Requires an idempotency key. Arguments

​

Get dashboard

Read one dashboard with its widgets and filters: name, description, kind, default_range, updated_at, the in-app url, the widgets in the app widget draft shape with their ids, and the saved filters. Send its updated_at as expected_updated_at to the edit tools. Read its numbers with roofkit.analytics.metric.get. Arguments

​

Update dashboard

Change the name, description, or default period of a dashboard. The change is live at once for everyone who opens it. Send at least one of name, description, and default_range. An empty description clears it. A newer save answers CONFLICT with the current updated_at. The write records a version that roofkit.analytics.dashboards.versions.restore can undo. Returns the dashboard url and its new updated_at. Requires an idempotency key. Arguments

​

Update dashboard widgets

Remove, edit, and add the widgets of a dashboard in one write. The steps run in this order: remove_widget_ids, update_widgets, add_presets, add_widgets. Read the widget ids and configs with roofkit.analytics.dashboards.get first. Widgets the call does not name stay as they are. New widgets go below the kept ones, and the rowIndex of an added widget counts from the first new row. A dashboard holds at most 24 widgets. An invalid widget or an unknown metric answers VALIDATION_ERROR with its path. The change is live at once for everyone who opens the dashboard and on its public link. A newer save answers CONFLICT with the current updated_at. The write records a version that roofkit.analytics.dashboards.versions.restore can undo. Returns the dashboard url and its new updated_at. Requires an idempotency key. Arguments

​

Set dashboard filters

Replace the saved filters of a dashboard. They apply to every widget, for everyone who opens the dashboard, and on its public link. Each filter has field_key (source, medium, campaign, landing, stage), value, and an optional operator: equals (default) or within_range with value_to. Values of one field match any of them. Filters of different fields must all match. At most 10 filters. An empty list clears them. A filter the dashboard cannot use answers VALIDATION_ERROR with its index. A newer save answers CONFLICT with the current updated_at. The write records a version that roofkit.analytics.dashboards.versions.restore can undo. Returns the dashboard url and its new updated_at. Requires an idempotency key. Arguments

​

Archive dashboard

Archive a dashboard, as Archive dashboard in the app does. It leaves the dashboard list at once for everyone, and its public link stops serving. The widgets, access, and history stay. A manager can bring it back from Settings, Archive in the app. Confirm with the user first. A newer save answers CONFLICT with the current updated_at. The archive records a version. Requires an idempotency key. Arguments

​

List dashboard versions

List the saved versions of one dashboard, newest first. Every write records one: the app, the RoofKit agent, MCP clients, templates, and automations. Each version names its kind (created, edited, restored, archived, unarchived), its source, the member, and for MCP the client. fields and the widget counts say what the change touched. restorable true means the version keeps the dashboard as it was before that change. The history keeps the newest 50 versions. Returns dashboard.updated_at, which roofkit.analytics.dashboards.versions.restore needs. Arguments

​

Restore dashboard version

Restore a dashboard as it was before the change of one version: name, description, icon, default period, filters, and widgets. Access and share links do not change. The change is live at once for everyone who opens the dashboard, and it can replace newer edits, so confirm with the user first. Send expected_updated_at as dashboard.updated_at from roofkit.analytics.dashboards.versions.list. A newer save refuses the call with CONFLICT. Only versions with restorable true can go back. The restore records its own version, so it can be restored away again. Requires an idempotency key. Arguments

​

List analytics objectives

List the campaign objectives: the workspace default CPL, CPA, and ROAS targets, and each campaign that overrides them. effective is the target that applies to a campaign, and its source says workspace_default or campaign. CPL and CPA targets are cents, and ROAS is a ratio. A member without financial access gets null CPL and CPA amounts and restricted: financial. plan_allows_new_objectives is false when the plan lacks custom_kpis or goals. A campaign key is the utm_campaign value with its case, as roofkit.campaigns.list shows it in campaign. A campaign without an override uses the workspace default. Arguments This tool takes no arguments.

​

Set default campaign objectives

Set or clear the workspace default objectives, which every campaign without its own override uses. CPL and CPA targets are whole cents and need financial access. ROAS is a ratio. A new type needs the custom_kpis and goals plan features. Objectives the workspace already holds stay editable and removable on any plan. The change is live on the dashboards and Settings at once. Confirm the targets with the user first. Send expected to refuse the write when someone changed a target since you read it. Arguments

​

Set campaign objectives

Set or clear the objectives of one campaign. They override the workspace default for that campaign only. Clearing an override makes the campaign use the workspace default again. CPL and CPA targets are whole cents and need financial access. ROAS is a ratio. A new type needs the custom_kpis and goals plan features. Objectives the workspace already holds stay editable and removable on any plan. The change is live on the dashboards and Settings at once. Confirm the targets with the user first. expected is required: it is the compare-and-set check against the overrides you read. The first objective of a campaign also adds the campaign to the workspace campaign list. Arguments

​

List attribution keys

List the source, medium, or campaign keys of the Attribution Manager catalog, most leads first, 25 per page. Each row has the canonical key, the raw aliases that resolve to it, and lead_count: the contacts whose first touch carries the key. Campaign rows are per source and medium. Use the keys with roofkit.attribution.keys.remap and roofkit.attribution.keys.merge. Arguments

​

Remap attribution keys

Rename or remap source, medium, or campaign keys: each key in from_keys becomes an alias of to_key, and reports show to_key. Use it to rename a key, or to point a typo at the key it meant. Leads keep their raw UTM values. Reports and Contacts show the new key, and RoofKit rebuilds the stored day summaries in the background. A source or medium change also moves the monthly spend rows onto the new key, and sums them when both keys have spend in a month. A campaign change also moves its objectives onto the new key. aliases replaces the alias list of the keys with the list you send. Leave it out to keep the current aliases. A source remap can also set to_medium_key. The answer has change_id. roofkit.attribution.changes.revert puts every touched row back while no later write changed them. revertible is false for a change too large to keep. Arguments

​

Merge attribution keys

Merge source, medium, or campaign keys into one survivor key. Every merged key becomes an alias of survivor_key, and its leads count under the survivor. Read lead_count with roofkit.attribution.keys.list and confirm the merge with the user first. Leads keep their raw UTM values. Reports and Contacts show the new key, and RoofKit rebuilds the stored day summaries in the background. A source or medium change also moves the monthly spend rows onto the new key, and sums them when both keys have spend in a month. A campaign change also moves its objectives onto the new key. The answer has affected_lead_count, the leads of the merged keys measured before the merge, and survivor_lead_count. The answer has change_id. roofkit.attribution.changes.revert puts every touched row back while no later write changed them. revertible is false for a change too large to keep. Requires an idempotency key. Arguments

​

List attribution changes

List the last 25 key remaps and merges made through MCP, newest first, with change_id, the keys, and whether the change can still be reverted. Arguments This tool takes no arguments.

​

Revert attribution change

Revert one key remap or merge made through MCP. Every alias, spend, objective, and campaign row it touched goes back to its earlier state, live at once. The revert is a compare-and-set: when any of those rows changed after the change, it answers CONFLICT and changes nothing. A campaign the change created stays when leads or objectives now use it. Requires an idempotency key. Arguments

​

List attribution links

List the tracked links of the Attribution Manager Links inventory, newest activity first, with link_id, the UTM values, and conversion_count. Send dismissed true to list dismissed links with their dismissed_at for a restore. Filters match the UTM values without case. Arguments

​

Dismiss attribution link

Dismiss one tracked link: it and every visible link with the same UTM values leave the Links inventory under one dismissed_at stamp. Conversions that arrive while the link is dismissed do not count for it, also after a restore. A dismissed link keeps its stamp. Undo it with roofkit.attribution.links.restore and the dismissed_at of the answer. Requires an idempotency key. Arguments

​

Restore attribution link

Show a dismissed link again: every link of its UTM values that still carries dismissed_at returns to the Links inventory. CONFLICT means no row carries that stamp any more, because a later dismissal, a Builder save, or another restore changed it. Arguments