> ## Documentation Index
> Fetch the complete documentation index at: https://heybtw.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# get_partner_overlaps

> Which accounts this workspace shares with one partner, several, or the whole partner ecosystem, as set facts with provenance.

> [!NOTE]
>
> 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](https://heybtw.com/docs/mcp/rules.md).

## 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:

```json theme={null}
{
  "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. |

## Related

* [get\_account\_relationship](https://heybtw.com/docs/tools/get-account-relationship.md): one account in depth.
* [get\_partner\_insights](https://heybtw.com/docs/tools/get-partner-insights.md): one partner's rollup.
* [get\_abm\_plan](https://heybtw.com/docs/tools/get-abm-plan.md): the collab's target accounts and who covers them.
* Playbook: [Invite sprint](https://heybtw.com/docs/playbooks/invite-sprint.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.