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

> Which accounts and people to consider inviting to an upcoming event, each with the facts behind it.

> [!NOTE]
>
> Read-only.

Two weeks before an event, the question is who to invite. This tool returns candidate accounts for one target event, each with structured `reasons` and up to 5 of its people. For each person it gives a city-grained location with a distance band, who on the team knows them (`known_by`), and their invite and attendance history.

Follows the [heyBTW MCP rules](https://heybtw.com/docs/mcp/rules.md).

## When to use it

* "Who should we invite to the LA dinner?"
* "Which past attendees are within driving distance of the venue?"
* "Who does someone on our team already know at these accounts?"
* "Who have we invited before who never came?"

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `event_name` | string | One of two | The event's name from [list\_events](https://heybtw.com/docs/tools/list-events.md). Partial and close matches resolve; an ambiguous name returns the candidates with their `channel_id`s. |
| `channel_id` | string | One of two | Takes precedence when both are given. |
| `limit` | integer | No | Default 25, maximum 500 accounts. |
| `location_scope` | string | No | `local`, `regional` or `same_country`. Keeps accounts with at least one person within that band. |
| `include_own_domain` | boolean | No | Default false. True includes your own staff. |
| `filters` | object | No | v2 only. See the warning below. |
| `contract_version` | string | No | Omit for v1. v2 requires the event and accepts `filters`. |

## Response

`crm_context` comes first. `data` holds one row per account, in a fixed order: ABM priority, then past events attended descending, then company name, then domain (`metadata.ordering`). Position is that ordering and nothing more. No numeric rank is returned.

| Field | Meaning |
| - | - |
| `company`, `domain` | The account. Join to the CRM on `domain`. |
| `reasons[]` | Observed facts, each with a `code` and the `basis` it was read from: abm\_priority, prior\_attendance, opportunity\_history, meeting\_history, mql\_history, partner\_relationship. |
| `past_events`, `is_customer` | Past sign-ups at the account, and whether it is a customer. |
| `priority` | v1 only: the ABM list designation, the same value as the abm\_priority reason. |
| `people[]`, `people_total` | Up to 5 people, nearest distance band first. `people_total` counts them all. |
| `people[].location` | City-grained, with `source`, `source_detail`, `as_of`. Null when nothing places the person. |
| `people[].distance_band` | From the event's city: `local` (under 50 miles), `regional` (under 150 miles), `same_country`, `international`. |
| `people[].known_by` | Emails of workspace members who know the person. Route the invite to that sender. |
| `people[].invite_history` | {count, last_at, last_channel, last_outcome}: what the newest invite led to (`registered`, `attended` or `none`). |
| `people[].event_history` | `this_city`, `this_series` (null: series are not recorded yet), `anywhere`. |
| `metadata.scope` | `event_tense` and `days_until` or `days_since`. |
| `metadata.location_anchor`, `metadata.location_scope` | The city bands are measured from, and what a scope kept and excluded. |

Location `source` is one of `manual`, `registration_declared`, `imported_declared`, `enrichment`, `crm`, `event_derived`, highest precedence first. An `event_derived` location is where someone attended, never where they live. A person's location never comes from the company.

This sample is trimmed from a real call today with `location_scope: "regional"` on a ScaleUp.ai fixture collab.

```json theme={null}
{
  "tool": "get_invite_recommendations",
  "data": [
    {
      "company": "Solstice Media Group",
      "domain": "solsticemg.com",
      "reasons": [
        { "code": "prior_attendance", "basis": "EventSignUp attendance history", "events_attended": 3 }
      ],
      "past_events": 3,
      "is_customer": false,
      "priority": null,
      "industry": null,
      "people": [
        {
          "email": "grace.bakshi@solsticemg.com",
          "name": "Grace Bakshi",
          "title": "Head of Growth",
          "location": {
            "source": "imported_declared",
            "city": "Los Angeles",
            "region": "Los Angeles-Long Beach-Anaheim, CA",
            "country": "United States",
            "source_detail": "import (attio), 2026-10-20",
            "as_of": "2026-10-20T20:56:11.117Z",
            "canonicalized": true
          },
          "distance_band": "local",
          "known_by": ["ben@heybtw.com"],
          "invite_history": {
            "count": 1,
            "last_at": "2026-10-10T21:15:00.000Z",
            "last_channel": "personal_email",
            "last_outcome": "none"
          },
          "event_history": {
            "this_city": { "attended_count": 0, "last_at": null },
            "this_series": null,
            "anywhere": { "attended_count": 2 }
          }
        }
      ],
      "people_total": 1
    }
  ],
  "metadata": {
    "scope": { "event_tense": "upcoming", "days_until": 15 },
    "ordering": "abm_priority_then_past_events_desc_then_company_asc_then_domain_asc",
    "location_anchor": {
      "status": "resolved",
      "city": "Los Angeles",
      "region": "Los Angeles-Long Beach-Anaheim, CA",
      "country": "United States"
    },
    "location_attribution": "Geographical data (c) GeoNames, https://www.geonames.org, CC-BY 4.0",
    "location_scope": {
      "within": "regional",
      "evaluated_accounts": 48,
      "in_scope": 5,
      "outside_scope": 43,
      "location_unknown": 0
    }
  },
  "status": "partial"
}
```

## Rules the agent must follow

* These are facts to weigh, not a ranking. Never rank or promote a person on invite count alone.
* Cite the location `source` whenever you state a location, and show `location_attribution` with any band you present.
* Never state miles or a drive time. "Within a two-hour drive" is the `regional` band.
* State the scope and its excluded counts with any list you present from `location_scope`.
* Null is unknown, never zero. Never recompute these facts from get\_event\_details.
* A person surfaces only if they have a sign-up somewhere in the workspace. Accounts already signed up for the target event are excluded.

## Errors and gaps

* An ended event: v1 keeps its rows with a coverage note; v2 returns no candidates and an `event_in_past` gap. Route to follow-up instead.
* `event_calendar_unavailable` gap (retryable): `event_tense` and day counts are null.
* An event with no resolvable city refuses a scoped call with no rows and a gap.
* `scope_truncated` gap: more than 500 candidates, the rest were not scope-evaluated.
* `partial_coverage` (not retryable): partner events restricted by the host's Sponsor Mode. A disclosure, not a failure.

## Related

* [check\_people](https://heybtw.com/docs/tools/check-people.md): the same person facts for a list from elsewhere.
* [save\_list](https://heybtw.com/docs/tools/save-list.md): keep the people the user picks.
* [get\_cross\_event\_patterns](https://heybtw.com/docs/tools/get-cross-event-patterns.md): past engagement, after an event.
* Playbook: [Fill the room in the two weeks before](https://heybtw.com/docs/playbooks/invite-sprint.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.