get_account_relationship

Read-only.

The marketer’s question is “what is our history with this company?” Reach for this tool before a meeting, an intro ask or an invite decision about one account. Follows the heyBTW MCP rules.

This page documents the v1 response, the one served by default. The tool is evolving and this page will be revised.

When to use it

“What’s our history with Beacon Hill Software?”
“Who from Beacon Hill has come to our events, and did they check in?”
“Is there a partner who can intro us to them?”
“Before my call, how engaged is this account?”

Parameters

Parameter	Type	Required	Notes
`domain`	string	One of `domain` or `account_name`	Preferred, for example `beaconhillsw.com`.
`account_name`	string	See above	Fallback when you have no domain.
`limit`	integer	No	Signup history rows read. Default 50, maximum 500.
`contract_version`	string	No	Omit for v1. Only v1 is advertised.

Archived and demo collabs are excluded, as in list_events; a restored collab’s records return.

Response

data[0]:

Field	Meaning
`domain`, `company`	The account.
`trajectory`	The account’s engagement direction across events.
`event_history[]`	Per event: `event_name`, `channel_id`, `event_date`, `role`, `attendee_count` (sign-ups), `mql`, `opportunity`.
`contacts[]`	Collapsed to each contact’s most recent event: `email`, `name`, `title`, `seniority`, `funnel_status`, `attendance_status`, `source`, `company_domain`, `event_date`, `channel_id`, `partner_source`.
`contacts_total`, `contacts_shown`	Disclose a cut.
`warm_intro_paths[]`	Partners with a path into the account, each with `reasons` (`code` and `basis`: co_attendance, then opportunity_history, meeting_history, mql_history when observed).
`context_graph_summary`	`narrative`, `trajectory`, `recommended_actions` (fixed rules over roster facts, nothing weighted).
`agent_guidance`	`crm_joined`, `crm_join_key` (`domain`), `suggested_follow_up`. `crm_enriched` is deprecated: read `crm_joined`.
`pipeline`	Present when a CRM is connected inside heyBTW: revenue, sourced, influenced, won, opportunity and closed-lost counts.

Contact source is event_attendance (on an event roster) or crm_deal_contact (named on an attributed CRM deal without attending; email, title and funnel_status are null, never fabricated). attendance_status keeps the layers apart: APPROVED is registered, only CHECKED_IN is attended. A real response for a ScaleUp.ai fixture account, trimmed to two events, two contacts and one coverage note:

{
  "tool": "get_account_relationship",
  "data": [
    {
      "domain": "beaconhillsw.com",
      "company": "Beacon Hill Software",
      "trajectory": "stable",
      "event_history": [
        {
          "event_name": "ScaleUp.ai x Partners: SF Tech Week Open House",
          "channel_id": "cmvifxnzh000907l2zptjqszl",
          "event_date": "2026-11-10T01:30:00",
          "role": "attendee",
          "attendee_count": 1,
          "mql": false,
          "opportunity": false
        },
        {
          "event_name": "ScaleUp.ai Field Dinner: Austin",
          "channel_id": "cmvifxsyp000j07l2hmp06n1u",
          "event_date": "2026-09-27T23:30:00",
          "role": "attendee",
          "attendee_count": 2,
          "mql": false,
          "opportunity": false
        }
      ],
      "contacts": [
        {
          "email": "hollis.quigley@beaconhillsw.com",
          "name": "Hollis Quigley",
          "title": "Head of Growth",
          "seniority": "executive",
          "funnel_status": "registered",
          "attendance_status": "APPROVED",
          "source": "event_attendance",
          "company_domain": "beaconhillsw.com",
          "event_date": "2026-11-10T01:30:00",
          "channel_id": "cmvifxnzh000907l2zptjqszl",
          "partner_source": null
        },
        {
          "email": "rosa.rasmussen@beaconhillsw.com",
          "name": "Rosa Rasmussen",
          "title": "Head of Sales Development",
          "seniority": "executive",
          "funnel_status": "registered",
          "attendance_status": "CHECKED_IN",
          "source": "event_attendance",
          "company_domain": "beaconhillsw.com",
          "event_date": "2026-09-27T23:30:00",
          "channel_id": "cmvifxsyp000j07l2hmp06n1u",
          "partner_source": null
        }
      ],
      "contacts_total": 5,
      "contacts_shown": 5,
      "warm_intro_paths": [],
      "context_graph_summary": {
        "narrative": "Beacon Hill Software has attended 3 event(s). 5 senior contact(s) engaged (e.g. Head of Growth level). $86,000 pipeline identified (won).",
        "trajectory": "stable",
        "recommended_actions": []
      },
      "agent_guidance": {
        "crm_enriched": true,
        "suggested_follow_up": ["Check the connected CRM for open opportunities"],
        "crm_joined": true,
        "crm_join_key": "domain"
      },
      "pipeline": {
        "company": "beaconhillsw.com",
        "revenue": 86000,
        "sourced_revenue": 86000,
        "influenced_revenue": 0,
        "won_revenue": 86000,
        "opportunity_count": 1,
        "is_won": true,
        "closed_lost_revenue": 0,
        "closed_lost_count": 0
      }
    }
  ],
  "metadata": {
    "coverage_notes": [
      "partner_source is the partner that canonical attribution credits for the sign-up, read from the account-scoped attribution projection. That projection covers sign-ups whose email is at the account's domain (on a lookup by account_name, sign-ups whose company is that name) and the account's CRM deal contacts. A null partner_source does not mean no partner brought the contact: either no partner is credited for that sign-up, or the sign-up is outside that projection, for example a personal address matched to this account by enrichment."
    ],
    "contract_version": "v1"
  },
  "status": "partial",
  "gaps": [
    { "code": "partial_coverage", "message": "Partner events restricted by the host's Sponsor Mode", "retryable": false }
  ]
}

Rules the agent must follow

attendee_count counts sign-ups, never attendance. Only CHECKED_IN is attended.
A null partner_source does not mean no partner brought the contact. Relay the coverage note as written.
When more history exists than limit reads, warm path reasons and recommended_actions are null (unknown, not empty) and a scope_truncated gap names the lever.
For owners, open deals and activity, use the user’s own CRM connector first, joined on company_domain. Say pipeline is heyBTW’s only when crm_joined is true.
Never weight or rank contacts. Serve the facts with their basis.

Errors and gaps

Code	When	What to do
`scope_truncated` (not retryable)	History cut at `limit`.	Raise `limit` up to 500.
`partial_coverage` (not retryable)	Workspace-wide disclosure, such as partner events restricted by the host’s Sponsor Mode.	A disclosure, not a failure.
`invalid_parameter`	Neither `domain` nor `account_name`.	Provide one.
`rate_limit_exceeded`, `internal_error`		Honor Retry-After; retry once on internal_error.

No cursor is emitted: narrow the query rather than paging.

get_cross_event_patterns: patterns across many accounts.
get_partner_overlaps: which partners share this account.
get_event_attribution: event-level revenue.
Playbook: What each system knows.

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_account_relationship

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