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

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

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

## 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_id`s under an `ambiguous_event_name` coverage note; re-call with the `channel_id` you want.

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

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

## 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_id`s 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](/docs/mcp-tools/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.

## Related tools

* [`get_event_details`](/docs/mcp-tools/get-event-details) — 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 view of accounts with repeat engagement, useful when you don't yet have a target `channel_id`.