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

# query_event_intelligence

> Cross-event attendance patterns by account or event — attendee-level detail grouped by resolved company.

<Note>
  This page documents the **Python MCP surface** (`mcp.heybtw.com`). It reflects `mcp-server/tools/event_intelligence.py` as of this page's publication — see [Schema stability](/docs/integrations/mcp-tools#schema-stability).
</Note>

<Note>
  **Naming note.** This tool predates the `get_<noun>` naming convention used by the other 7 tools on this surface — it is registered and must be called as `query_event_intelligence`, not `get_event_intelligence`. It is a live, supported tool, not deprecated.
</Note>

## Purpose

`query_event_intelligence` groups event attendance by resolved company and returns, for each company, which events they attended, their contact list at those events, and a simple `is_customer`/`is_prospect` flag. It's a lighter-weight sibling to [`get_cross_event_patterns`](/docs/mcp-tools/get-cross-event-patterns) — no trajectory scoring, but includes contact-level detail directly instead of requiring a follow-up call.

## When to use this

* "What events has Chargebee attended?" or "Show me everyone from stripe.com who's engaged with us."
* You want attendee contacts alongside event history in one call, and don't need trajectory/warm-intro data — for that, use [`get_account_relationship`](/docs/mcp-tools/get-account-relationship) instead.

<Warning>
  The published overview page for this surface has previously described this tool as taking `account_name`, `date_range_days`, and `event_id` parameters. Those do not exist on the live implementation — the actual parameters are `event_name`, `domain`, `limit`, and `include_own_domain`, documented below. This page is the corrected reference; treat any conflicting description elsewhere as stale.
</Warning>

## Parameters

| Name                 | Type    | Required | Default | Description                                                                                                                                                        | Example                        |
| -------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| `event_name`         | string  | No       | `null`  | Filter to attendance at events whose name contains this substring (case-insensitive).                                                                              | `"Robotics Summit"`            |
| `domain`             | string  | No       | `null`  | Filter to a specific company domain (matches enrichment-resolved domain, or raw email domain).                                                                     | `"lighthouserobotics.example"` |
| `limit`              | integer | No       | `10`    | Max **companies** returned (see [Pagination and limits](#pagination-and-limits) for how this interacts with the underlying row fetch). Effective range `[1, 500]`. | `25`                           |
| `include_own_domain` | boolean | No       | `false` | Include the calling workspace's own domain in results.                                                                                                             | `true`                         |

## Default behavior

Called with no parameters, returns up to **10 companies**, grouped from event attendance across the whole workspace with no date restriction — the underlying data is not date-filtered by this tool at all despite `metadata.date_range_applied` appearing in the envelope (it is always `null` here; unlike other tools, there is no `date_from`/`date_to` parameter on this one).

## Sample request

```json theme={null}
{
  "tool": "query_event_intelligence",
  "arguments": { "domain": "lighthouserobotics.example" }
}
```

## Sample response

```json theme={null}
{
  "tool": "query_event_intelligence",
  "query_time_ms": 39.8,
  "result_count": 1,
  "data": [
    {
      "company": "Lighthouse Robotics",
      "domain": "lighthouserobotics.example",
      "events_attended": 2,
      "event_names": ["Automation Roundtable Q1", "Robotics Summit SF 2026"],
      "contacts": [
        {
          "name": "Priya Nair",
          "title": "VP of Product",
          "email": "priya.nair@lighthouserobotics.example"
        },
        {
          "name": "Sam Oduya",
          "title": "Senior Software Engineer",
          "email": "sam.oduya@lighthouserobotics.example"
        }
      ],
      "is_customer": true,
      "is_prospect": false
    }
  ],
  "metadata": {
    "data_sources_queried": ["Channel", "EventSignUp"],
    "date_range_applied": null,
    "filters_applied": { "event_name": null, "domain": "lighthouserobotics.example", "limit": 10 },
    "coverage_note": null
  }
}
```

**Personal-email domain example** (`domain: "gmail.com"`):

```json theme={null}
{
  "tool": "query_event_intelligence",
  "query_time_ms": 1.1,
  "result_count": 0,
  "data": [],
  "metadata": {
    "data_sources_queried": ["Channel", "EventSignUp"],
    "date_range_applied": null,
    "filters_applied": { "event_name": null, "domain": "gmail.com", "limit": 10 },
    "coverage_note": "'gmail.com' is a personal email provider, not a company domain — it cannot identify a single account."
  }
}
```

## Response field reference

### Envelope

| Field                         | Type          | Description                                                                                 |
| ----------------------------- | ------------- | ------------------------------------------------------------------------------------------- |
| `tool`                        | string        | Always `"query_event_intelligence"`.                                                        |
| `result_count`                | integer       | Number of companies in `data` (≤ `limit`).                                                  |
| `data`                        | array         | One object per resolved company.                                                            |
| `metadata.date_range_applied` | `null` always | This tool has no date parameters; do not infer date scoping from this field on other tools. |

### `data[i]`

| Field             | Type             | Description                                                                                                                                                                                             |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `company`         | string           | Resolved company name (enrichment-resolved where available).                                                                                                                                            |
| `domain`          | string \| null   | Resolved company domain. `null` when no enrichment resolution exists and every contact's raw email domain is a personal-email provider.                                                                 |
| `events_attended` | integer          | Distinct events this company's attendees appear at.                                                                                                                                                     |
| `event_names`     | array of strings | Names of those events, unordered.                                                                                                                                                                       |
| `contacts`        | array of objects | Deduplicated by email: `{ name, title, email }`. **No `limit` cap or `_total`/`_shown` pair on this array** — unlike every other tool on this surface, all contacts for a matched company are returned. |
| `is_customer`     | boolean          | `true` if any attendee from this company ever hit `opportunity` or `meetingBooked`.                                                                                                                     |
| `is_prospect`     | boolean          | Always the logical inverse of `is_customer` — not an independent signal.                                                                                                                                |

## Errors

* **`domain` is a personal-email provider** (e.g. `gmail.com`, `outlook.com`). Handled explicitly, does not error — returns `result_count: 0` with `metadata.coverage_note` explaining why (shown in the sample above).
* 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).

## Pagination and limits

No cursor-based pagination. `limit` (default 10) caps the number of **companies** in the response, but the underlying SQL row fetch is `clamp_limit(limit) * 10` (i.e. up to 10x more raw attendance rows than companies requested, capped at the shared server-side 500-row ceiling before the `* 10` multiplier) — this is an internal over-fetch to make sure grouping by company doesn't starve the requested company count, not a caller-facing knob. If you need more than 10 companies, raise `limit` directly; there is no way to fetch "the next 10."

## Related tools

* [`get_cross_event_patterns`](/docs/mcp-tools/get-cross-event-patterns) — the trajectory-scored alternative, without inline contacts.
* [`get_account_relationship`](/docs/mcp-tools/get-account-relationship) — deeper single-account profile including warm intro paths and CRM pipeline, once you've identified a company of interest here.