get_partner_overlaps

Read-only.

The marketer’s question is “which accounts do we share with our partners, and which targets does no partner touch?” Reach for this tool for account mapping and for placing an account in an account-mapping play. Follows the heyBTW MCP rules.

When to use it

“Which of our targets does Brightpath also work with?”
“Show me accounts shared by two or more partners.”
“Which declared targets does no partner touch?”
“Run the warm-intros play for the open house.”

Parameters

All optional.

Parameter	Type	Notes
`partner_domains`	list	1 to 50 partner domains. Omit for the whole ecosystem.
`scope`	object	`{"kind": "global"}` (default), `{"kind": "event", "event_id": <channel_id>}` or `{"kind": "conference", "conference_id": <channel_id>}`.
`evidence_class`	list	`managed`, `attributed`, `inferred`. Default managed and attributed; inferred counts toward `partner_count` only when listed.
`min_confidence`	string	`HIGH`, `MEDIUM` or `LOW` (default).
`partner_role`, `my_role`	list	`customer`, `prospect`, `partner`, `neutral`.
`min_partner_count`	integer
`all_partners`	boolean	Only accounts every named partner touches.
`exclusive_to_partner`	string	Accounts only that partner touches.
`uncovered_targets_only`	boolean	Declared targets no named partner touches.
`target_list_id`	string	Judge `in_target` and uncovered targets against exactly that List.
`play`	string	One name from `playCatalog`. It sets `my_role`, `partner_role` and `evidence_class` itself, so pass none of them with it, and it cannot run with `uncovered_targets_only`.
`limit`	integer	Default 50, from 1 to 100.
`cursor`	string	`next_cursor`, with the SAME other arguments.
`contract_version`	string	Omit for v1. Only v1 is advertised.

Response

data[0] (note the camelCase keys, served as written):

Field	Meaning
`rows[]`	`company_domain`, `company_name`, `partner_count`, `in_target`, `my_role` with `my_role_provenance`, `touches[]` (`partner_domain`, `role`, `evidence_class`, `confidence`, `source_list_id`), `observed` (`joint_events_attended`, `event_ids`, `last_touch`, `attendee_seniority_max`), `basis[]`. Ordered by partner_count, then joint events, then company_domain.
`setCounts`	`shared_by_all`, `shared_by_2_plus`, `exclusive` per partner, `uncovered_targets`, `accounts_evaluated`.
`coverage`	`target_universe_source` and `target_universe_size`.
`playCatalog[]`	Every play with the `my_role`, `partner_role` and `evidence_class` it sets.
`agentGuidance`	Guidance written for every heyBTW MCP surface (see the warning below).
`pagination`	`limit`, `returned`, `has_more`, `next_cursor`.

setCounts reflects the full matched set before min_confidence, partner_role and my_role narrow the returned rows. my_role narrows after the page is read, so a page can hold fewer rows than returned: follow next_cursor until has_more is false.

Plays

`play`	`my_role`	`partner_role`	`evidence_class`
`warm-intros`	prospect	customer	managed
`mutual-customers`	customer	customer	managed
`shared-prospects`	prospect	prospect	managed
`make-intros`	customer	prospect	managed

A real response from the heyBTW workspace scoped to the SF open house fixture, trimmed to two plays. The fixture partners have no managed or attributed account evidence yet, so no rows come back while 251 declared targets are uncovered:

{
  "tool": "get_partner_overlaps",
  "result_count": 0,
  "data": [
    {
      "rows": [],
      "setCounts": {
        "shared_by_all": 0,
        "shared_by_2_plus": 0,
        "exclusive": {},
        "uncovered_targets": 251,
        "accounts_evaluated": 0
      },
      "coverage": { "target_universe_source": "workspaceTargets", "target_universe_size": 251 },
      "pagination": { "limit": 2, "returned": 0, "has_more": false, "next_cursor": null },
      "toolVersion": "2.0",
      "playCatalog": [
        { "name": "warm-intros", "label": "Warm intros", "my_role": ["prospect"], "partner_role": ["customer"], "evidence_class": ["managed"] },
        { "name": "mutual-customers", "label": "Mutual customers", "my_role": ["customer"], "partner_role": ["customer"], "evidence_class": ["managed"] }
      ]
    }
  ],
  "metadata": {
    "filters_applied": {
      "scope": { "event_id": "cmvifxnzh000907l2zptjqszl", "kind": "event" },
      "evidence_class": ["managed", "attributed", "inferred"],
      "limit": 2
    },
    "contract_version": "v1",
    "tool_version": "2.0"
  },
  "status": "ok",
  "gaps": []
}

Rules the agent must follow

partner_count, exclusivity and in_target are set facts. Nothing is ranked or rated: apply the user’s own CRM and ICP to prioritize.
my_role is maintained in heyBTW from Lists (provenance manual), not CRM-verified. Cross-check in the user’s CRM where it matters.
Join on company_domain (lowercase, without www) against the user’s CRM.
Follow next_cursor until has_more is false before stating a total from rows.
A failed read is always an error, never an empty set. An empty rows with status: "ok" is a real answer.

Errors and gaps

Code	When	What to do
`invalid_parameter`	An argument outside the rules, a play not in `playCatalog`, or a play passed with role, evidence or uncovered filters.	Fix the arguments.
`entity_not_found`	No collab with that `channel_id`.	Check list_events.
`rate_limit_exceeded`	30 requests per 5 s per workspace.	Honor Retry-After.
`internal_error`		Retry once.

get_account_relationship: one account in depth.
get_partner_insights: one partner’s rollup.
get_abm_plan: the collab’s target accounts and who covers them.
Playbook: Invite sprint.

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_overlaps

When to use it

Parameters

Response

Plays

Rules the agent must follow

Errors and gaps

​When to use it

​Parameters

​Response

​Plays

​Rules the agent must follow

​Errors and gaps

​Related

When to use it

Parameters

Response

Plays

Rules the agent must follow

Errors and gaps

Related