get_account_relationship

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

Purpose

get_account_relationship answers “tell me everything about this account” for a single company: every event they’ve attended, their contacts with seniority classification, which partners give you a warm intro path to them, an engagement trajectory, and (when HubSpot is connected) pipeline context. It is the primary AE-prep / account-research tool on this surface.

When to use this

“What do we know about Zynga?” or “Give me a profile on stripe.com before my call.”
Before drafting outreach — warm_intro_paths and context_graph_summary.recommended_actions give you a starting angle.
After get_cross_event_patterns surfaces an account worth investigating further.

Parameters

Name	Type	Required	Default	Description	Example
`domain`	string	One of `domain` / `account_name` required	`null`	Company domain. Preferred — more reliable matching than `account_name`.	`"zynga.com"`
`account_name`	string	One of `domain` / `account_name` required	`null`	Company name, used only when `domain` is unknown.	`"Zynga"`
`limit`	integer	No	`50`	Caps the underlying event-history row fetch (see Pagination and limits). Clamped to `[1, 500]`.	`100`

Default behavior

At least one of domain or account_name is required — omitting both does not produce a helpful validation message today (see Errors). Given only domain, the tool returns everything on record for that account: full event history (no separate array cap beyond the limit used at the row level), up to the first 50 deduplicated contacts (contacts_shown/contacts_total tell you if more exist), and all warm intro paths found. Personal-email domains (gmail.com, outlook.com, etc.) are rejected up front — see Errors — because they cannot identify a single company.

Sample request

{
  "tool": "get_account_relationship",
  "arguments": { "domain": "lighthouserobotics.example" }
}

Sample response

{
  "tool": "get_account_relationship",
  "query_time_ms": 61.4,
  "result_count": 1,
  "data": [
    {
      "domain": "lighthouserobotics.example",
      "company": "Lighthouse Robotics",
      "trajectory": "increasing",
      "event_history": [
        {
          "event_name": "Robotics Summit SF 2026",
          "channel_id": "chn_88af1",
          "event_date": "2026-06-18T00:00:00+00:00",
          "role": "partner_sourced",
          "attendee_count": 3,
          "mql": true,
          "opportunity": true
        },
        {
          "event_name": "Automation Roundtable Q1",
          "channel_id": "chn_71c02",
          "event_date": "2026-02-04T00:00:00+00:00",
          "role": "attendee",
          "attendee_count": 1,
          "mql": true,
          "opportunity": false
        }
      ],
      "contacts": [
        {
          "email": "priya.nair@lighthouserobotics.example",
          "name": "Priya Nair",
          "title": "VP of Product",
          "seniority": "director_plus",
          "funnel_status": "opportunity"
        },
        {
          "email": "sam.oduya@lighthouserobotics.example",
          "name": "Sam Oduya",
          "title": "Senior Software Engineer",
          "seniority": "individual_contributor",
          "funnel_status": "mql"
        }
      ],
      "contacts_total": 2,
      "contacts_shown": 2,
      "warm_intro_paths": [
        {
          "partner_name": "Northwind Ventures",
          "event_name": "Robotics Summit SF 2026",
          "intro_basis": "co-attended event",
          "path_count": 3
        }
      ],
      "context_graph_summary": {
        "narrative": "Lighthouse Robotics has attended 2 event(s). 1 senior contact(s) engaged (e.g. director_plus level). Warm intro paths via: Northwind Ventures. $0 pipeline identified (open).",
        "trajectory": "increasing",
        "recommended_actions": [
          "Prioritise for next event invite",
          "Request intro via Northwind Ventures",
          "Check CRM for open opportunities"
        ]
      },
      "agent_guidance": {
        "crm_join_key": "domain",
        "crm_enriched": true,
        "suggested_follow_up": ["Check HubSpot for open opportunities"]
      },
      "pipeline": {
        "company": "Lighthouse Robotics",
        "revenue": 0.0,
        "is_won": false
      }
    }
  ],
  "metadata": {
    "data_sources_queried": ["EventSignUp", "Channel", "EventAttributionOpportunity"],
    "date_range_applied": null,
    "filters_applied": { "domain": "lighthouserobotics.example", "account_name": null, "crm_enriched": true },
    "coverage_note": null
  }
}

Response field reference

Envelope

Field	Type	Description
`tool`	string	Always `"get_account_relationship"`.
`query_time_ms`	number	Server-side execution time in ms.
`result_count`	0 \| 1	`0` when the account has no event attendance on record, or the `domain` given is a personal-email provider.
`data`	array (length 0 or 1)	The account object.
`metadata`	object	See Response format. `coverage_note` explains a `0`-result response.

`data[0]`

Field	Type	Description
`domain`	string	Resolved company domain — prefers enrichment-resolved value over the raw input.
`company`	string	Resolved display name — prefers enrichment over self-reported over `account_name` input, falls back to `"Unknown"`.
`trajectory`	`"new"` \| `"increasing"` \| `"stable"` \| `"decreasing"`	Engagement direction over the account’s event history.
`event_history`	array of objects	One entry per distinct event, newest first. Each: `{ event_name, channel_id, event_date, role, attendee_count, mql, opportunity }`. `role` is `"attendee"`, `"partner"`, or `"partner_sourced"`. `attendee_count` counts this account’s own attendees at that event, not total event attendance.
`contacts`	array of objects	Up to 50 deduplicated contacts: `{ email, name, title, seniority, funnel_status }`. `seniority` ∈ `executive` \| `director_plus` \| `manager` \| `individual_contributor` \| `unknown`. `funnel_status` ∈ `opportunity` \| `meeting_booked` \| `mql` \| `registered`.
`contacts_total`	integer	Total deduplicated contacts found (may exceed 50).
`contacts_shown`	integer	`min(contacts_total, 50)` — how many are actually in the `contacts` array.
`warm_intro_paths`	array of objects	`{ partner_name, event_name, intro_basis, path_count }`. Grouped by (partner, event) pair. Judge a path on `intro_basis` and `path_count` — see the version note below for what else is on the wire.
`context_graph_summary.narrative`	string	Human-readable one-paragraph summary, generated server-side — not an LLM call, template-composed from the fields above.
`context_graph_summary.recommended_actions`	array of strings	Up to 3 suggested next steps, derived server-side from the account’s engagement history and which data is present.
`agent_guidance.crm_join_key`	string	Always `"domain"` — the field to join against your CRM’s own Account/Company record.
`agent_guidance.crm_enriched`	boolean	Mirrors whether HubSpot is connected for this workspace.
`pipeline`	object \| omitted	Present only when CRM is connected AND a matching pipeline record exists. `{ company, revenue, is_won }`. Omitted entirely otherwise — do not assume it is `null`; check for key presence.

The sample above is not a verbatim capture. warm_intro_paths entries carry more on the wire than it shows.Contract v1 is the default — omit contract_version and v1 is what you get — and a v1 intro path additionally carries strength (a float, one of 0.9 / 0.58 / 0.38) and strength_label ("strong" / "medium" / "light"). Contract v2 replaces both with a reasons array carrying the observed facts the tier was derived from. v2 is defined but not advertised, so v1 is what a live call returns today.Both are withdrawn (HEY-1897): strength was an invented float and strength_label a claim-like tier. They are documented nowhere on this page on purpose. Judge a path on intro_basis and path_count, and migrate to reasons when v2 is advertised.

Errors

Missing both domain and account_name. Raised as a registered invalid_parameter error (issue required, action provide) before any lookup runs — an actionable structured error, not the generic sanitized one. Always pass one of the two.
domain is a personal-email provider (e.g. gmail.com). This is handled explicitly and does not error — it returns result_count: 0 with metadata.coverage_note explaining that a personal-email domain cannot identify one company, and suggesting account_name instead.
All other failures funnel through the same generic sanitized error as every tool — see get_workspace_overview — Errors and MCP Tools — Errors and troubleshooting.

Pagination and limits

No cursor-based pagination. limit (default 50, clamped to [1, 500]) bounds the underlying event-attendance row fetch used to build event_history and contacts — it is not a direct cap on the number of events or contacts returned (those are built by grouping/deduplicating the fetched rows). contacts is separately hard-capped to the first 50 after dedup regardless of limit; use contacts_total to know if you’re seeing everything.

get_cross_event_patterns — find candidate accounts before profiling one in depth here.
get_partner_insights — the partner-centric view of the same warm-intro relationships.
get_event_details — the event-centric view; use it to see everyone at an event, not just one account.

Getting Started

Connecting Your Platforms

MCP Tool Reference

Features

Lists

Partner Ecosystem

If You've Been Invited

Concepts

Frequently Asked Questions

get_account_relationship

Purpose

When to use this

Parameters

Default behavior

Sample request

Sample response

Response field reference

Envelope

`data[0]`

Errors

​Purpose

​When to use this

​Parameters

​Default behavior

​Sample request

​Sample response

​Response field reference

​Envelope

​data[0]

​Errors

​Pagination and limits

​Related tools

Purpose

When to use this

Parameters

Default behavior

Sample request

Sample response

Response field reference

Envelope

`data[0]`

Errors

Pagination and limits

Related tools