Available Tools

The Atribu MCP server exposes 17 tools. Every tool returns a structured response with a data object and a meta object containing request metadata, data freshness, and attribution context.

Shared parameters

Most tools accept these common parameters:

Available attribution models: last_touch, first_touch, split_50_50, linear, position_based, time_decay, last_non_direct, custom_weighted, engagement_weighted

Discovery tools

whoami

Identity, usage, and effective settings for the current MCP token. Returns scopes, units used vs cap, your workspaces, and (when scope is unambiguous) active workspace settings (pii_mode, mcp_writeback_enabled, your role) and the active profile's currency. Always call once per session — it tells you upfront whether PII unmask or write-back will work, so the AI tool can guide the user correctly without trial-and-error calls.

Cost: 0 units

Returns: { token, usage, user, workspaces[], active_workspace, active_profile, server_version }. active_workspace and active_profile are null when scope is ambiguous.

list_workspaces

List all workspaces you have access to. Use the returned id values as workspace_id in subsequent calls.

Cost: 0 units

Returns: Array of { id, name } objects.

list_profiles

List all profiles within a workspace. Use the returned id values as profile_id in subsequent calls.

Cost: 0 units

Returns: Array of { id, name, domain } objects.

Performance tools

get_performance_summary

Headline KPIs for a date window plus the equivalent prior period. Returns three buckets: cash (real revenue, drives ROAS), pipeline (CRM deal counts + raw value_amount sum — NOT revenue), and leads (top of funnel).

Cost: 1 unit

Returns:

{
  "spend": { "amount": 1032.42 },
  "cash": {
    "attributed_revenue": { "amount": 4000 },
    "attributed_conversions": 6,
    "total_conversions": 17,
    "collected": { "amount": 9749 },
    "roas": { "value": 3.87, "formatted": "3.87x" }
  },
  "pipeline": {
    "appointments_booked": 38,
    "closed_won": 0,
    "crm_value_amount_sum": {
      "attributed": { "amount": 76600 },
      "total": { "amount": 79600 }
    },
    "note": "Counts are concrete events. crm_value_amount_sum is the raw sum of whatever the agency entered in their CRM's deal value field — NOT revenue. Never present as a revenue claim without confirming the CRM convention."
  },
  "leads": { "count": 409, "note": "Top of funnel events with no revenue." },
  "traffic": { "visitors": 1550, "pageviews": 2386, "bounce_rate_percent": 87.3 }
}

compare_periods

Compare two arbitrary date windows side by side. Useful for year-over-year, pre/post campaign launch, or seasonal comparisons.

Cost: 1 unit

Returns: Same structure as get_performance_summary with current and previous objects representing the two windows.

Campaign tools

top_campaigns

Top campaigns ranked by attributed revenue within a date window.

Cost: 1 unit

Returns: Array of campaigns with name, platform_id, spend, revenue, roas, conversions, clicks, impressions.

top_ad_sets

Top ad sets ranked by attributed cash revenue. Sits between top_campaigns (broader) and top_creatives (narrower) — answers "which audience/placement is delivering?" before drilling into individual creatives.

Cost: 1 unit

Requires: Meta Ads connection

Returns: Array of ad sets with ad_set_name, campaign_name (parent), spend, attributed_revenue, roas, attributed_conversions, cac, ctr_percent, impressions, clicks, avg_engagement_score.

top_creatives

Top individual ads ranked by ROAS, with creative details (thumbnail URLs, headlines, body text).

Cost: 1 unit

Requires: Meta Ads connection

Returns: Array of ads with name, spend, revenue, roas, ctr, thumbnail_url, headline, body.

explain_campaign

Deep dive into a single campaign: headline metrics, daily trend, and constituent ads.

Cost: 2 units

The campaign_id can be a UUID (internal ID), a Meta platform_id, or a campaign name. The tool resolves it automatically.

Returns:

{
  "summary": {
    "name": "Summer Sale - Retargeting",
    "platform_id": "23851234567890",
    "spend": 1200.00,
    "revenue": 5400.00,
    "roas": 4.50,
    "conversions": 28,
    "clicks": 1840,
    "impressions": 42000
  },
  "daily_trend": [
    { "date": "2026-04-01", "spend": 180, "revenue": 720, "clicks": 260 }
  ],
  "ads": [
    { "name": "Video - Testimonial", "spend": 600, "revenue": 3200, "roas": 5.33 }
  ]
}

Customer tools

explain_customer_journey

Full event timeline for a single customer: ad clicks, page views, form fills, conversions, and payments.

Cost: 2 units

Returns: Customer info (name, masked email/phone) plus an array of timeline events ordered chronologically.

Analysis tools

compare_attribution_models

Run the same date window through multiple attribution models to see how credit distribution shifts.

Cost: 5 units

Returns: One result set per model, each with the same campaign-level metrics. Compare to understand which channels are undervalued by single-touch models.

creative_fatigue_check

Detect ads showing fatigue signals: declining CTR, rising CPM, or audience saturation compared to the prior equal-length window.

Cost: 2 units

Requires: Meta Ads connection

Returns: Array of ads with current vs prior period metrics and fatigue indicators.

find_anomalies

Flag unusual daily spikes or drops in spend, revenue, or traffic using z-score analysis (median + MAD).

Cost: 2 units

Returns: Array of anomalous days with the metric name, observed value, expected range, and z-score magnitude.

get_funnel

Goal-driven conversion funnel for the date window. Walks the canonical lead-gen progression lead_created → appointment_booked → showed → qualified → closed_won with per-stage counts, stage-to-stage conversion rates, and drop-off counts. Also returns negative-outcome buckets (disqualified, no_show, closed_lost).

Cost: 1 unit

scope=pipeline_only restricts to events linked to a CRM pipeline (deals in a stage). scope=contact_only restricts to events without one (lead-only / form fills).

Returns:

{
  "scope": "all",
  "window": { "start": "2026-04-01", "end": "2026-04-30" },
  "main_chain": [
    { "key": "lead_created", "label": "Leads", "count": 409, "conversion_rate_from_previous_pct": null, "drop_off_from_previous_count": 0 },
    { "key": "appointment_booked", "label": "Booked", "count": 38, "conversion_rate_from_previous_pct": 9.29, "drop_off_from_previous_count": 371 },
    { "key": "showed", "label": "Showed", "count": 24, "conversion_rate_from_previous_pct": 63.16, "drop_off_from_previous_count": 14 },
    { "key": "qualified", "label": "Qualified", "count": 12, "conversion_rate_from_previous_pct": 50.00, "drop_off_from_previous_count": 12 },
    { "key": "closed_won", "label": "Closed Won", "count": 0, "conversion_rate_from_previous_pct": 0, "drop_off_from_previous_count": 12 }
  ],
  "drop_off_outcomes": [
    { "key": "disqualified", "label": "Disqualified", "count": 7 },
    { "key": "no_show", "label": "No Show", "count": 5 },
    { "key": "closed_lost", "label": "Closed Lost", "count": 3 }
  ],
  "totals": {
    "all_events": 498,
    "leads": 409,
    "closed_won": 0,
    "lead_to_closed_won_rate_pct": 0
  }
}

get_tracking_breakdown

Top values per traffic-dimension (channel, country, page, browser, device, OS, referrer, campaign, etc.) ranked by visitors. Returns up to 6 dimensions in one call.

Available dimensions: channel, referrer, campaign, page, entry_page, exit_page, country, region, city, device, browser, os

Cost: 1 unit

Returns:

{
  "breakdowns": {
    "channel": [
      { "dimension_value_key": "paid_social", "label": "Paid Social", "visitors": 820, "visits": 1120, "pageviews": 2400, "bounce_rate_pct": 62.4, "conversions": 14, "conversion_rate_pct": 1.71, "cash_revenue": { "amount": 3200 } }
    ],
    "country": [
      { "dimension_value_key": "US", "label": "United States", "visitors": 540, "visits": 720, "pageviews": 1820, "bounce_rate_pct": 58.1, "conversions": 12, "conversion_rate_pct": 2.22, "cash_revenue": { "amount": 2800 } }
    ]
  },
  "window": { "start": "2026-04-01", "end": "2026-04-30" },
  "dimensions_requested": ["channel", "country"],
  "limit_per_dimension": 10
}

list_conversions

Paginated list of conversions for a date window, ordered by conversion_time DESC. Each row carries the customer (masked PII by default), first-touch channel, time-to-complete, revenue, plus the customer's lifetime totals.

Cost: 1 unit

goal filters by event_type (e.g. payment_received, lead_created, appointment_booked, closed_won). Pass all to include every conversion type. Use next_cursor from the response for the next page.

For a SINGLE customer's full event timeline, use explain_customer_journey instead.

list_visitors

Paginated visitor roster (identified + anonymous) for a date window, ordered by last_seen_at DESC. Each row carries last-seen timestamp, session count, total cash revenue, channel/source from the latest session, and device/geo.

Cost: 1 unit

is_identified=true means the visitor has a customer_profile_id (matched via identify() or a server-side event). False means anonymous-only. total_revenue is cash only (revenue_type='cash') and reflects the customer's lifetime sum.

get_attribution_quality

Diagnostic — how trustworthy is attribution data for this date window? Returns the share of conversion-related events with full UTMs (best), with fbclid only (Meta click but no UTMs), and with no tracking at all (worst).

Cost: 1 unit

Returns:

{
  "window": { "start": "2026-04-01", "end": "2026-04-30" },
  "totals": {
    "total_events": 409,
    "with_full_utms": 248,
    "with_fbclid_only": 102,
    "with_no_tracking": 59
  },
  "percentages": {
    "full_utms_pct": 60.6,
    "fbclid_only_pct": 24.9,
    "no_tracking_pct": 14.4,
    "attributable_coverage_pct": 85.5
  }
}

get_engagement_summary

Site-wide engagement quality for the date window: scroll depth, time on page, rage clicks, dead clicks, form completion, video completion, JS errors, and Core Web Vitals (LCP/FCP/CLS/INP/TTFB). Optional breakdown by page (top N most-engaged) or day (timeline).

Cost: 1 unit

Returns: summary.attention (scroll depth, time on page), summary.frustration (rage/dead clicks, JS errors), summary.forms (submitted/abandoned + completion rate), summary.video (plays/completions + completion rate), summary.web_vitals (avg LCP/FCP/CLS/INP/TTFB + LCP good/poor pct). With breakdown_by='page' adds pages[]. With breakdown_by='day' adds daily[].

whatsapp_attribution_summary

Revenue and conversions attributed to WhatsApp touchpoints (Click-to-WhatsApp ads or WhatsApp-sourced traffic).

Cost: 2 units

Requires: WhatsApp integration

Returns: Conversation counts, conversion counts, revenue attributed to WhatsApp touchpoints.

Write-back tool

send_meta_conversions

Push attributed conversions to Meta Conversions API (CAPI) for ad delivery optimization. This tool has a three-step safety flow: preview, dry-run, confirm.

See the dedicated Write-Back guide for the full flow, safety rails, and examples.

Cost: 10 units

Requires: mcp:write scope, Meta Ads connection, workspace write-back enabled, workspace admin role.

Response envelope

Every tool returns a consistent envelope:

{
  "data": { },
  "meta": {
    "request_id": "01968a3b-...",
    "workspace_id": "...",
    "profile_id": "...",
    "window_start": "2026-04-01",
    "window_end": "2026-04-14",
    "attribution_model": "last_touch",
    "currency": "USD",
    "data_as_of": "2026-04-14T18:30:00Z",
    "freshness_by_provider": {
      "meta": "2026-04-14T18:30:00Z",
      "ghl": "2026-04-14T17:00:00Z"
    },
    "data_freshness_warning": null,
    "record_count": 12,
    "pii_level_applied": "masked"
  }
}

Related