> ## 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_account_relationship > Full Context Graph profile for one account — event history, contacts, warm intro paths, and CRM pipeline context. 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](/docs/integrations/mcp-tools#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`](/docs/mcp-tools/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](#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](#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](#errors) — because they cannot identify a single company. ## Sample request ```json theme={null} { "tool": "get_account_relationship", "arguments": { "domain": "lighthouserobotics.example" } } ``` ## Sample response ```json theme={null} { "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, "strength": 0.9, "strength_label": "strong" } ], "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](/docs/integrations/mcp-tools#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, strength, strength_label }`. Grouped by (partner, event) pair. `strength` ∈ `0.9` (`"strong"`, an opportunity or meeting resulted), `0.58` (`"medium"`, an MQL or ≥2 shared attendees), `0.38` (`"light"`, otherwise). | | `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 based on `engagement_score` thresholds and data presence. | | `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. | ## Errors * **Missing both `domain` and `account_name`.** The intent is a clear validation error, but current behavior routes this through the generic handler like every other exception — the client sees `RuntimeError: Internal error executing get_account_relationship (error_id=...)`, not an actionable message. 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](/docs/mcp-tools/get-workspace-overview#errors) and [MCP Tools — Errors and troubleshooting](/docs/integrations/mcp-tools). ## 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. ## Related tools * [`get_cross_event_patterns`](/docs/mcp-tools/get-cross-event-patterns) — find candidate accounts before profiling one in depth here. * [`get_partner_insights`](/docs/mcp-tools/get-partner-insights) — the partner-centric view of the same warm-intro relationships. * [`get_event_summary`](/docs/mcp-tools/get-event-summary) — the event-centric view; use it to see everyone at an event, not just one account.