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

> Scored invite candidates for an upcoming event, with human-readable reasoning per account.

<Note>
  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](/docs/integrations/mcp-tools#schema-stability).
</Note>

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

<Warning>
  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.
</Warning>

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

```json theme={null}
{
  "tool": "get_invite_recommendations",
  "arguments": { "channel_id": "chn_9a112", "limit": 25 }
}
```

## Sample response

```json theme={null}
{
  "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](/docs/mcp-tools/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.

## Related tools

* [`get_event_summary`](/docs/mcp-tools/get-event-summary) — see who's already registered for the target event before deciding who else to invite.
* [`get_cross_event_patterns`](/docs/mcp-tools/get-cross-event-patterns) — a broader, unscored view of accounts with repeat engagement, useful when you don't yet have a target `channel_id`.