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 scores companies as invite candidates for a specific event (identified by channel_id), combining ABM priority tier, past event attendance, and historical conversion signals (opportunity/MQL/meeting) into a single score with a plain-English reasoning string.

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 (region, vertical, budget), this tool takes only channel_id today — there is no region, vertical, partners, or budget/ROI parameter on the live implementation. If your use case needs those filters, they are not available yet; do not construct calls assuming they exist.

Parameters

Name	Type	Required	Default	Description	Example
`channel_id`	string	Yes (functionally — see below)	`""`	The target event’s channel id. Candidates already signed up for this event are excluded.	`"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`

channel_id has a default of "" at the function signature level (so a call omitting it does not raise a Python-level type error), but an empty string will not match any real channel — treat it as required in practice.

Default behavior

Given only channel_id, returns up to 25 candidates sorted by score descending, 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 “everyone scored low.”

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",
      "score": 0.85,
      "reasoning": "ABM top priority target; attended 3 past events (highly engaged); has generated opportunities; previously MQL'd",
      "past_events": 3,
      "is_customer": true,
      "priority": "TOP_PRIORITY",
      "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, sorted by `score` descending.
`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.
`score`	number (0–1, 2 decimal places)	See scoring breakdown below.
`reasoning`	string	Semicolon-joined list of the specific factors that contributed to `score`; `"General prospect"` when no factor applied (score near 0).
`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.
`priority`	string \| null	ABM priority tier if the company is on an ABM list (e.g. `"TOP_PRIORITY"`, `"INVITE"`), else `null`.
`industry`	string \| null	Industry, when known.

Scoring breakdown (additive, capped at 1.0, rounded to 2 decimals):

Factor	Weight
ABM priority = `TOP_PRIORITY`	+0.35
ABM priority = `INVITE`	+0.20
≥3 past events attended	+0.25
1–2 past events attended	+0.15
Has ever generated an opportunity	+0.15
Has ever been an MQL	+0.10
Has ever booked a meeting	+0.10
Has any partner relationship on record	+0.05

Errors

Same generic-sanitized-error behavior as every tool on this surface — see get_workspace_overview — Errors. An unresolvable or omitted channel_id does not raise a distinct “channel not found” error — it simply produces result_count: 0 (nothing to score against).

Pagination and limits

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

get_event_summary — see who’s already registered for the target event before deciding who else to invite.
get_cross_event_patterns — a broader, unscored 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

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