get_invite_recommendations

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

Purpose

get_invite_recommendations ranks companies as invite candidates for a specific event (identified by channel_id), drawing on ABM list membership, past event attendance, and historical conversion signals (opportunity/MQL/meeting). Each candidate carries a plain-English reasoning string naming the factors that surfaced it.

When to use this

“Who should we invite to our upcoming event?” once the event exists in heyBTW as a channel.
Building or refreshing an invite list from ABM + attendance history rather than starting from a blank spreadsheet.

Despite the name suggesting event-attribute targeting, this tool targets one event and nothing else. There is no region, vertical, partners, or budget/ROI parameter, and no account-tier filter. Name the event, then filter or segment the returned candidates in your agent.

Parameters

Name	Type	Required	Default	Description	Example
`event_name`	string	One of the two	`""`	The human-readable event name. Case-insensitive; partial and close matches resolve. An ambiguous name returns the matching candidates with their `channel_id`s instead of data, so you can re-call with a specific one.	`"Fintech Dinner Berlin"`
`channel_id`	string	One of the two	`""`	The target event’s channel id. The programmatic override for pipelines that already resolved an id; takes precedence when both are given.	`"chn_88af1"`
`limit`	integer	No	`25`	Max candidates returned. Clamped to `[1, 500]`.	`50`
`include_own_domain`	boolean	No	`false`	Include the workspace’s own domain in results.	`true`

Name the event either way. event_name is the human-facing resolver; channel_id is the programmatic one. Both default to "" at the function signature level, so a call omitting both does not raise a Python-level type error, but it cannot identify a target event and will not produce recommendations.

Default behavior

Given one event identifier, returns up to 25 candidates, strongest candidate first, excluding companies already signed up for that event and excluding the workspace’s own domain. metadata.coverage_note always states the “excludes already-signed-up” exclusion so an agent doesn’t misread a short list as “nobody qualified.” An event_name that resolves to nothing yields no recommendations and says so in metadata — it never falls back to a workspace-wide list. An ambiguous one returns the candidate events with their channel_ids under an ambiguous_event_name coverage note; re-call with the channel_id you want.

Sample request

{
  "tool": "get_invite_recommendations",
  "arguments": { "channel_id": "chn_9a112", "limit": 25 }
}

Sample response

{
  "tool": "get_invite_recommendations",
  "query_time_ms": 47.3,
  "result_count": 1,
  "data": [
    {
      "company": "Lighthouse Robotics",
      "domain": "lighthouserobotics.example",
      "reasoning": "Attended 3 past events (highly engaged); has generated opportunities; previously MQL'd",
      "past_events": 3,
      "is_customer": true,
      "industry": "Robotics & Automation"
    }
  ],
  "metadata": {
    "data_sources_queried": ["Channel", "EventSignUp", "ABMCompany"],
    "date_range_applied": null,
    "filters_applied": { "channel_id": "chn_9a112", "limit": 25 },
    "coverage_note": "Excludes companies already signed up for target event"
  }
}

Response field reference

Envelope

Field	Type	Description
`tool`	string	Always `"get_invite_recommendations"`.
`result_count`	integer	Number of candidates returned.
`data`	array	One object per candidate, strongest candidate first.
`metadata.coverage_note`	string	Always `"Excludes companies already signed up for target event"`.

`data[i]`

Field	Type	Description
`company`	string	Candidate company name.
`domain`	string \| null	Candidate domain.
`reasoning`	string	Semicolon-joined list of the specific factors that surfaced this candidate; `"General prospect"` when no factor applied.
`past_events`	integer	Count of this company’s prior event attendance in the workspace.
`is_customer`	boolean	`true` if this company has ever generated an opportunity or booked a meeting.
`industry`	string \| null	Industry, when known.

The sample above is not a verbatim capture. A live response carries more fields than it shows, and you should not build on them.Contract v1 is the default — omit contract_version and v1 is what you get — and a v1 candidate additionally carries a numeric score. Contract v2 replaces score and reasoning with a structured reasons array. v2 is defined but not advertised, so v1 is what a live call returns today.score is withdrawn (HEY-1764, HEY-1897): it was a composite of invented weights. It is documented nowhere on this page on purpose — publishing it would teach an agent to depend on a number heyBTW has decided not to keep, and the removal is already implemented in v2.priority (values such as "TOP_PRIORITY", "INVITE") is a separate case: it is still emitted in both v1 and v2. It is omitted here on HEY-2067 tier-vocabulary grounds, not because it has left the wire. Do not read its absence from this page as absence from the response.What to build on: the order of data, and the fields documented in the table above. Rank on position, not on a scalar.

Errors

channel_id is malformed. Raised as a registered invalid_parameter error before any lookup runs.
channel_id names a channel that does not exist, or is outside your workspace. Raised as a registered entity_not_found error (HEY-1906). It does not silently produce an empty list — a target event that resolves to nothing is an error, never a fabricated recommendation list.
event_name resolves to nothing. Not an error. Returns no recommendations with a metadata coverage note naming what failed to resolve.
event_name is ambiguous. Not an error. Returns the matching events with their channel_ids under an ambiguous_event_name coverage note.
Everything else funnels through the same generic sanitized error as every tool on this surface — see get_workspace_overview — Errors.

Pagination and limits

No cursor-based pagination. limit (default 25, clamped to [1, 500]) caps candidates returned after ranking — there is no offset/cursor to page past it.

get_event_details — see who’s already registered for the target event before deciding who else to invite.
get_cross_event_patterns — a broader view of accounts with repeat engagement, useful when you don’t yet have a target channel_id.

Getting Started

Connecting Your Platforms

MCP Tool Reference

Features

Lists

Partner Ecosystem

If You've Been Invited

Concepts

Frequently Asked Questions

get_invite_recommendations

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