get_partner_insights

Read-only.

The marketer’s question is “what did this partner actually drive?” This is the one tool for partner-level revenue. Reach for it for a partner rollup across events; for one event’s view use get_event_attribution. Both read the same canonical resolver, so their partner figures reconcile. Follows the heyBTW MCP rules.

When to use it

“How much pipeline did Brightpath drive this quarter?”
“Which partners brought senior people, not just sign-ups?”
“What’s our account coverage with Ferrocity?”
“Prep the partner QBR numbers.”

Parameters

Parameter	Type	Required	Notes
`partner_domain`	string	No	Substring match, so `acme` can match acme.com and acmecorp.io.
`partner_name`	string	No	Substring match on the partner name.
`time_range`	string	No	`last_30_days`, `this_quarter`, `last_quarter`, `ytd`, `program_total` (default). Anchored to the collab’s event date, not deal creation. An unrecognized value applies no bound.
`include_archived`	boolean	No	Default false. Widens only the partner-record filter; archived and demo collabs stay excluded.
`contract_version`	string	No	Omit for v1. Only v1 is advertised.

Response

crm_context comes first (capability deal_read). Then one row per identity-resolved partner, ordered by sourced revenue descending, then total sourced, then partner name; an unknown value sorts last (metadata.ordering).

Field	Meaning
`partner_name`, `partner_domain`, `partner_identity_key`, `source_partner_ids`	Partners sharing a canonical domain are one row.
`event_count`, `event_names`	Events in the window.
`reasons[]`	Structured facts, each a `code` and its `basis`: `event_participation` (event_count), then opportunity_history, meeting_history, mql_history when observed. Null (not `[]`) when activity rows were truncated.
`sourcing_breakdown`	`total_sourced`, `by_event`.
`funnel_metrics`	`total_signups`, MQL, opportunity and meeting counts and rates.
`seniority_profile`	Counts of the contacts the partner brought, with sample size.
`contacts[]`, `contacts_total`, `contacts_shown`, `contacts_has_more`	A contact sample.
`pipeline_impact`	`sourced_revenue`, `influenced_revenue`, `influenced_new_revenue`, `influenced_expansion_revenue`, `won_revenue`, `company_count`, `opportunity_count`, `crm_joined`, `crm_join_key`.
`account_overlap`	The same numbers the Partner Ecosystem dashboard Coverage cards show: `portfolio_reached`, `penetration`, `co_marketing_events`, `multi_touch`, `never_reached`, `unclassified`, `icp_scoped`, `denominator_mode`, `upcoming`.
`custom_list_overlays[]`	Custom Lists attributed to the partner’s domain. `[]` is normal.
`trends`	`this_quarter_vs_last_quarter.events_cohosted_delta`, for a single matched partner only.

In pipeline_impact, null means unavailable and 0 means measured, none. account_overlap is null when the query is cross-workspace, when the partner spans more than one collab in this workspace, or when the coverage lookup failed soft. None of those means “no data”.

influenced_new_revenue and influenced_expansion_revenue come from the dashboard’s Influence Breakdown panel (“Partner Influenced (New)” and “Partner Influenced (Expansion)”). That taxonomy is independent of Sourced and Influenced: the two classifiers disagree deal by deal. Never present these dollars as a slice of influenced_revenue, never expect them to sum to it, and never add them to the headline. The panel’s other buckets (Direct, Direct Influenced, Partner Sourced) are not served here; say the split is unavailable. The mapping is in agent_guidance.dashboard_vocabulary on get_workspace_overview.

A real response from the ScaleUp.ai fixtures, trimmed to one of four partners:

{
  "tool": "get_partner_insights",
  "result_count": 4,
  "crm_context": {
    "connection_path": "dashboard",
    "provider": "attio",
    "status": "connected",
    "capability": "deal_read",
    "capability_served": true,
    "crm_joined": true,
    "crm_join_key": ["email", "company_domain"]
  },
  "data": [
    {
      "partner_name": "Ferrocity",
      "partner_domain": "ferrocity.ai",
      "partner_identity_key": "domain:ferrocity.ai",
      "source_partner_ids": ["cmvifydub001707l2aimx9q8a"],
      "event_count": 1,
      "event_names": ["ScaleUp.ai x Partners: SF Tech Week Open House"],
      "reasons": [{ "code": "event_participation", "basis": "EventSignUp.partnerSource", "event_count": 1 }],
      "status": "Active",
      "sourcing_breakdown": { "total_sourced": 0, "by_event": [] },
      "funnel_metrics": { "total_signups": 0, "mql_count": 0, "opportunity_count": 0, "meeting_count": 0, "mql_rate": 0.0, "opportunity_rate": 0.0, "meeting_rate": 0.0 },
      "contacts": [],
      "contacts_total": 0,
      "pipeline_impact": {
        "sourced_revenue": 0,
        "influenced_revenue": 0,
        "influenced_new_revenue": 0,
        "influenced_expansion_revenue": 0,
        "won_revenue": 0,
        "company_count": 0,
        "opportunity_count": 0,
        "crm_joined": true,
        "crm_join_key": "company_domain"
      },
      "account_overlap": {
        "portfolio_reached": { "reached": 0, "total": 0 },
        "penetration": { "pct": 0, "trendPct": null },
        "co_marketing_events": 0,
        "multi_touch": 0,
        "never_reached": 0,
        "unclassified": 0,
        "icp_scoped": 0,
        "denominator_mode": "raw",
        "upcoming": 0
      },
      "custom_list_overlays": [],
      "trends": null
    }
  ],
  "metadata": {
    "contract_version": "v1",
    "ordering": "sourced_revenue_desc_then_total_sourced_desc_then_partner_name_asc"
  },
  "status": "partial",
  "gaps": [
    { "code": "partial_coverage", "message": "Partner events restricted by the host's Sponsor Mode", "retryable": false }
  ]
}

pipeline_impact.crm_enriched is also emitted; it is deprecated and will be removed on 2026-11-16. Read crm_joined.

Rules the agent must follow

Partner revenue comes from this tool only. Never compute a partner figure yourself.
Say a revenue figure is heyBTW’s only when pipeline_impact.crm_joined is true.
Null is unknown, never zero. A null reasons or account_overlap is withheld, not empty.
No rank or engagement composite is served. Ordering is by sourced revenue only.
Quote dashboard words from dashboard_vocabulary so the user can find the figure on screen.

Errors and gaps

Code	When	What to do
`canonical_attribution_unavailable` (retryable)	The canonical resolver was unreachable. Revenue fields degrade to null.	Retry; never fill in a number.
`partial_coverage` (not retryable)	Canonical data missing for named records, or workspace-wide disclosures.	Relay as written.
`scope_truncated` (not retryable)	Partner activity rows capped at 500.	Narrow with `partner_name`, `partner_domain` or `time_range`.
`rate_limit_exceeded`, `internal_error`		Honor Retry-After; retry once on internal_error.

get_event_attribution: event-scoped revenue and partners.
get_partner_overlaps: accounts shared with partners.
get_workspace_overview: crm_context and dashboard_vocabulary.
Playbook: Follow-up and ROI.

Get started

How heyBTW MCP works

Playbooks

Tools: orientation

Tools: events and rosters

Tools: people and invites

Tools: after the event

Tools: accounts and partners

Tools: pipeline

get_partner_insights

When to use it

Parameters

Response

Rules the agent must follow

Errors and gaps

​When to use it

​Parameters

​Response

​Rules the agent must follow

​Errors and gaps

​Related

When to use it

Parameters

Response

Rules the agent must follow

Errors and gaps

Related