get_partner_insights

This page documents the Python MCP surface (mcp.heybtw.com). It reflects mcp-server/tools/partner_insights.py as of this page’s publication — see Schema stability.

Purpose

get_partner_insights returns one entry per partner with a full sourcing and funnel breakdown: how many signups/MQLs/opportunities/meetings they’ve driven, per-event detail, a seniority profile of the contacts they’ve brought, and (when HubSpot is connected) pipeline revenue impact.

When to use this

“Which partners have a relationship with a target account we could leverage for a warm intro?” — pair with get_account_relationship for a specific account, or scan all partners here first.
“Which partner should we lean on more — who’s actually converting, not just attending?”
Building a partner performance leaderboard or QBR deck.

Parameters

Name	Type	Required	Default	Description	Example
`partner_name`	string	No	`null`	Filter to partners whose name contains this substring (case-insensitive).	`"Northwind"`
`partner_domain`	string	No	`null`	Filter to partners whose domain contains this substring.	`"northwind"`
`include_archived`	boolean	No	`false`	Include archived/inactive partner relationships.	`true`
`time_range`	string	No	`"program_total"`	One of `last_30_days`, `this_quarter`, `last_quarter`, `ytd`, `program_total`. Scopes `event_count`, `event_names`, `pipeline_impact`, `sourcing_breakdown`, and `funnel_metrics` to the window. `program_total` (or any unrecognized value) applies no bound.	`"this_quarter"`

time_range windows are anchored to the event’s date, not to deal-creation date. This tool answers “what did this partner’s events produce in this window”, not “what deals were created in this window” — a different question a CRM-facing tool would answer. Bounds are computed in UTC and carry an explicit offset on the wire, so parsing is unambiguous; the quarter and year boundaries themselves are anchored to UTC-now, so a workspace far from UTC can see a boundary land up to roughly 12 hours off its local one.

Default behavior

Called with no parameters, returns every partner in the workspace (archived ones excluded by default), strongest relationship first — no result cap, no pagination. Every partner entry is included even if they have zero sourced signups (total_sourced: 0); filter client-side on sourcing_breakdown.total_sourced > 0 if you only want active partners.

Sample request

{
  "tool": "get_partner_insights",
  "arguments": {}
}

Sample response

{
  "tool": "get_partner_insights",
  "query_time_ms": 73.9,
  "result_count": 1,
  "data": [
    {
      "partner_name": "Northwind Ventures",
      "partner_domain": "northwindventures.example",
      "event_count": 3,
      "event_names": ["Robotics Summit SF 2026", "Automation Roundtable Q1", "Founders Dinner NYC"],
      "status": "active",
      "sourcing_breakdown": {
        "total_sourced": 46,
        "by_event": [
          { "event_name": "Robotics Summit SF 2026", "channel_id": "chn_88af1", "sourced": 22, "mql": 6, "opportunity": 2 },
          { "event_name": "Automation Roundtable Q1", "channel_id": "chn_71c02", "sourced": 14, "mql": 3, "opportunity": 1 },
          { "event_name": "Founders Dinner NYC", "channel_id": "chn_5b901", "sourced": 10, "mql": 2, "opportunity": 0 }
        ]
      },
      "funnel_metrics": {
        "total_signups": 46,
        "mql_count": 11,
        "opportunity_count": 3,
        "meeting_count": 5,
        "mql_rate": 0.2391,
        "opportunity_rate": 0.0652,
        "meeting_rate": 0.1087
      },
      "seniority_profile": {
        "executive": 2,
        "director_plus": 9,
        "manager": 14,
        "individual_contributor": 18,
        "unknown": 3
      },
      "contacts": [
        {
          "email": "priya.nair@lighthouserobotics.example",
          "name": "Priya Nair",
          "title": "VP of Product",
          "company": "Lighthouse Robotics",
          "seniority": "director_plus",
          "funnel_status": "opportunity"
        }
      ],
      "contacts_total": 46,
      "contacts_shown": 46,
      "contacts_has_more": false,
      "seniority_profile_sample_size": 46,
      "seniority_profile_is_sampled": false,
      "pipeline_impact": {
        "crm_enriched": true,
        "sourced_revenue": 128400.0,
        "won_revenue": 42000.0,
        "company_count": 19
      },
      "account_overlap": {
        "portfolio_reached": 34,
        "penetration": 0.28,
        "co_marketing_events": 3,
        "multi_touch": 11,
        "never_reached": 87,
        "unclassified": 4,
        "icp_scoped": true,
        "denominator_mode": "icp",
        "upcoming": 2
      },
      "custom_list_overlays": [],
      "trends": null
    }
  ],
  "metadata": {
    "data_sources_queried": ["Partner", "Channel", "EventSignUp", "EventAttributionOpportunity"],
    "date_range_applied": null,
    "filters_applied": { "partner_name": null, "partner_domain": null, "include_archived": false, "crm_enriched": true },
    "coverage_note": null
  }
}

Response field reference

Envelope

Field	Type	Description
`tool`	string	Always `"get_partner_insights"`.
`query_time_ms`	number	Server-side execution time in ms.
`result_count`	integer	Number of partners in `data`.
`data`	array	One object per partner, strongest relationship first.
`metadata`	object	`coverage_note` is `"Connect HubSpot CRM to unlock pipeline attribution"` when CRM is not connected, else `null`.

`data[i]`

Field	Type	Description
`partner_name`	string	Partner display name.
`partner_domain`	string \| null	Partner domain, when set.
`event_count`	integer	Distinct events this partner has been associated with.
`event_names`	array of strings	Names of those events.
`status`	string \| null	Partner relationship status (e.g. `"active"`), from the `Partner` record.
`sourcing_breakdown.total_sourced`	integer	Total signups attributed to this partner across all events.
`sourcing_breakdown.by_event`	array of objects	Per-event `{ event_name, channel_id, sourced, mql, opportunity }`.
`funnel_metrics`	object	`{ total_signups, mql_count, opportunity_count, meeting_count, mql_rate, opportunity_rate, meeting_rate }`. Rates are `0.0` when `total_signups` is `0`.
`seniority_profile`	object	Count of contacts per tier: `executive`, `director_plus`, `manager`, `individual_contributor`, `unknown`. Built from the returned `contacts` array, so it sums to `contacts_shown`, not `contacts_total`. When more contacts exist than were returned, this is a sample — see the two flags below before computing a percentage.
`seniority_profile_sample_size`	integer	How many contacts the profile was built from. Equals `contacts_shown`.
`seniority_profile_is_sampled`	boolean	`true` when contacts were truncated and the profile therefore describes a subset. Do not present a sampled profile as the partner’s full seniority mix.
`contacts`	array of objects	Up to 50 deduplicated contacts: `{ email, name, title, company, seniority, funnel_status }`.
`contacts_total` / `contacts_shown`	integer	Same convention as `get_account_relationship` — `contacts_shown` is capped at 50.
`contacts_has_more`	boolean	`true` when `contacts_total` exceeds `contacts_shown`.
`pipeline_impact`	object	`{ crm_enriched: false }` only, when CRM is not connected. When connected: `{ crm_enriched: true, sourced_revenue, won_revenue, company_count }` — dollar amounts summed across every opportunity this partner sourced, `company_count` is distinct companies.
`account_overlap`	object \| `null`	`{ portfolio_reached, penetration, co_marketing_events, multi_touch, never_reached, unclassified, icp_scoped, denominator_mode, upcoming }`. The same canonical coverage values the Partner Ecosystem Dashboard’s Coverage cards use — never recomputed here. `null` for a global/admin call, when the partner spans more than one collab channel (a known gap), or when the internal lookup failed soft. `null` means “not computed”, never “no overlap” — do not report it as zero.
`custom_list_overlays`	array	One entry per Custom List attributed to this partner. `[]` (not `null`) when there is none. `total_members` on an entry is the service-maintained account count, not a fresh count taken at call time.
`trends`	object \| `null`	Trend detail for this partner. `null` unless the call is scoped to a single `partner_domain` — it is not computed for a whole-workspace listing. Ask for one partner if you need it.

The sample above is not a verbatim capture. A live response carries one more field per partner than it shows.Contract v1 is the default — omit contract_version and v1 is what you get — and a v1 partner additionally carries warmth_score, a composite between event_names and status. It is the only field the sample omits; everything else above is shown as emitted. Contract v2 drops warmth_score and adds an intro_paths array of ranked, source-backed paths. v2 is defined but not advertised, so v1 is what a live call returns today.warmth_score is withdrawn (HEY-1897) because it was an unbacked composite, and it is documented nowhere on this page on purpose. Rank on order, and compare partners on sourcing_breakdown and funnel_metrics.

Errors

Same generic-sanitized-error behavior as every tool on this surface — see get_workspace_overview — Errors. This tool has no parameter-validation failure modes of its own; every parameter is optional and any string value is a valid (possibly zero-match) filter.

Pagination and limits

No caller-facing limit parameter and no cursor pagination — every matching partner is returned in one call. Internally, the underlying rows are capped at 500 before aggregation (a fixed server-side safety limit, not adjustable); a workspace would need over 500 partner-event-partnership rows to hit it, well beyond any workspace observed today. contacts per partner is separately capped at 50 (see contacts_shown/contacts_total above).

get_account_relationship — the account-centric view of the same warm-intro data.
get_workspace_overview — program_metrics.partner_program is a workspace-wide rollup of this tool’s data.
get_event_details — per-event partner performance (partner_performance), scoped to one event instead of across all events.

Getting Started

Connecting Your Platforms

MCP Tool Reference

Features

Lists

Partner Ecosystem

If You've Been Invited

Concepts

Frequently Asked Questions

get_partner_insights

Purpose

When to use this

Parameters

Default behavior

Sample request

Sample response

Response field reference

Envelope

`data[i]`

Errors

​Purpose

​When to use this

​Parameters

​Default behavior

​Sample request

​Sample response

​Response field reference

​Envelope

​data[i]

​Errors

​Pagination and limits

​Related tools

Purpose

When to use this

Parameters

Default behavior

Sample request

Sample response

Response field reference

Envelope

`data[i]`

Errors

Pagination and limits

Related tools