check_people

Read-only.

This tool is evolving. This page describes what the connector serves today and will be revised as the tool changes.

You have a list from somewhere else (a prospect file, a CRM export, a spreadsheet). check_people tells you, per email, whether this workspace has seen the person before: events attended, invites recorded, and which teammates know them. Call it before importing or inviting a list. Follows the heyBTW MCP rules.

When to use it

“Who on this list has been to one of our events?”
“Have we invited any of these people before, and did they come?”
“Does anyone on the team know these people?”
“Before I import this list, what do we already have on them?”

Parameters

Parameter	Type	Required	Notes
`people`	list of objects	Yes	1 to 500 entries of . Only `email` is read. Any other key is refused.
`channel_id`	string	No	A collab from list_events. Measures `event_history.this_city` against that event’s city.
`event_name`	string	No	Instead of `channel_id`. An ambiguous name returns no rows and lists the candidates.
`fields`	list of strings	No	Any of `identity`, `event_history`, `invite_history`, `known_by`, `target_spec_match`. Omit for all.
`contract_version`	string	No	Omit for v1, the only advertised version.

Send a longer list in chunks of 500. Do not send the same chunk twice.

Response

crm_context comes first. data[0] holds one row per person sent, in input order.

Field	Meaning
`rows[].row`	The position in the list you sent.
`rows[].identity`	`matched` when the workspace holds an attended event, a recorded invite or an imported contact for the email, else `unmatched`.
`rows[].event_history`	. `this_city` is null without a collab or a resolvable city.
`rows[].invite_history`	: `registered`, `attended` or `none`.
`rows[].known_by`	Emails of workspace members who know the person.
`rows[].target_spec_match`	Null on every row in this version.
`rows[].row_gaps`	For example `invalid_email`. One bad row never fails the call.
`counts`	`matched`, `unmatched`, `seen_before`, `invited_before`, `no_history`, over the served rows.
`carry`	The CRM check to run in your own connector, joined on `email` and `company_domain`.
`target_spec`	Whether a target spec is saved, with the next step when not.

This sample is trimmed from a real call today on fictional fixture people.

{
  "tool": "check_people",
  "data": [
    {
      "rows": [
        {
          "row": 0,
          "email": "luis.castillo@wavecrestgames.com",
          "company_domain": "wavecrestgames.com",
          "identity": "matched",
          "event_history": {
            "attended_count": 1,
            "last_at": "2026-11-19T02:30:00.000Z",
            "last_collab": "ScaleUp.ai x Marlowe Cloud: LA Revenue Leaders Dinner",
            "this_city": null
          },
          "invite_history": {
            "count": 1,
            "last_at": "2026-10-13T16:30:00.000Z",
            "last_channel": "personal_email",
            "last_outcome": "registered"
          },
          "known_by": ["ben@heybtw.com"],
          "target_spec_match": null
        },
        {
          "row": 1,
          "email": null,
          "company_domain": null,
          "row_gaps": ["invalid_email"]
        }
      ],
      "counts": { "matched": 1, "unmatched": 0, "seen_before": 1, "invited_before": 1, "no_history": 0 },
      "rows_served": 2,
      "rows_checked": 2,
      "carry": {
        "destination": "crm",
        "via": "your_tools",
        "join_keys": ["email", "company_domain"],
        "ask": "which of these are customers or have open deals, and who owns them"
      }
    }
  ],
  "status": "ok"
}

Rules the agent must follow

These are facts, never a verdict. Do not suppress, skip, tier or rank anyone from them.
Null or absent is unknown, never zero.
Never report a person with no CRM value as net-new. Run the carry check in the user’s own CRM connector.
Never recompute these facts from get_event_details calls.

Errors and gaps

invalid_parameter: people missing, empty or over 500, an entry with a key this tool does not read, a malformed channel_id, or an unknown name in fields.
entity_not_found: no event with that channel_id or event_name.
A response trimmed to fit says so in a gap and in next_row. Counts cover the served rows only. Narrow with fields.
internal_error: retry once.

import_people: bring the unmatched people in.
get_invite_recommendations: the same person facts, for candidates heyBTW finds.
save_target_spec: save who belongs in the room.
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

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