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`

Default behavior

Called with no parameters, returns every partner in the workspace (archived ones excluded by default), sorted by warmth_score descending — 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"],
      "warmth_score": 0.8,
      "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,
      "pipeline_impact": {
        "crm_enriched": true,
        "sourced_revenue": 128400.0,
        "won_revenue": 42000.0,
        "company_count": 19
      }
    }
  ],
  "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, sorted by `warmth_score` descending.
`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.
`warmth_score`	number (0–1)	Composite score: `min(event_count * 0.15, 0.45)` + `0.20` if any MQL + `0.20` if any opportunity + `0.15` if any meeting, capped at `1.0`.
`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 deduplicated contacts per tier: `executive`, `director_plus`, `manager`, `individual_contributor`, `unknown`. Sums to `contacts_total`.
`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.
`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.

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_summary — per-event partner performance (partner_performance), scoped to one event instead of across all events.

Getting Started

Connecting Your Platforms

MCP Tool Reference

Features

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