get_invite_recommendations

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.

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

{
  "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.

check_people: the same person facts for a list from elsewhere.
save_list: keep the people the user picks.
get_cross_event_patterns: past engagement, after an event.
Playbook: Fill the room in the two weeks before.

Get started

How heyBTW MCP works

Playbooks

Tools: orientation

Tools: events and rosters

Tools: people and invites

Tools: after the event

Tools: accounts and partners

Tools: pipeline

get_invite_recommendations

When to use it

Parameters

Response

Rules the agent must follow

Errors and gaps

​When to use it

​Parameters

​Response

​Rules the agent must follow

​Errors and gaps

​Related

When to use it

Parameters

Response

Rules the agent must follow

Errors and gaps

Related