query_event_intelligence

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.

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.

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 — 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 instead.

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.

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

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

Sample response

{
  "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"):

{
  "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.

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

get_cross_event_patterns — the trajectory-scored alternative, without inline contacts.
get_account_relationship — deeper single-account profile including warm intro paths and CRM pipeline, once you’ve identified a company of interest here.

Getting Started

Connecting Your Platforms

MCP Tool Reference

Features

Partner Ecosystem

If You've Been Invited

Concepts

Frequently Asked Questions

query_event_intelligence

Purpose

When to use this

Parameters

Default behavior

Sample request

Sample response

Response field reference

Envelope

`data[i]`

Errors

​Purpose

​When to use this

​Parameters

​Default behavior

​Sample request

​Sample response

​Response field reference

​Envelope

​data[i]

​Errors

​Pagination and limits

​Related tools

Purpose

When to use this

Parameters

Default behavior

Sample request

Sample response

Response field reference

Envelope

`data[i]`

Errors

Pagination and limits

Related tools