save_list

Writes to your heyBTW workspace. It creates a List or adds members to one. It never removes a member, never creates a contact and never sends an invite.

Once the user has picked the people they want, save_list keeps them as a List. The List it saves is the one the Lists panel shows and the one activate_list invites. Follows the heyBTW MCP rules.

When to use it

“Save these 12 people as ‘LA dinner invites’.”
“Add the three I just found to my Q4 List.”
“Keep the people I imported from HubSpot as a List.”

Parameters

Pass exactly one of name or list_id.

Parameter	Type	Required	Notes
`name`	string	One of two	Creates a new List with this name.
`list_id`	string	One of two	Adds to an existing static List of people. From get_lists.
`member_emails`	list of strings	Yes	1 to 500 emails of people this workspace already holds.
`client_request_id`	string	Yes	A fresh hyphenated UUID for this save.
`contract_version`	string	No	Omit for v1.

Only people the workspace already holds are saved: an email on one of its event sign-ups, or a person brought in with import_people. To save people from a CRM, call import_people first and pass its member_emails here.

Workflow

Save

Call with name or list_id, member_emails and a fresh client_request_id. There is no preview: a save only adds.

Report what was saved and rejected

Tell the user added_count, already_present_count and each entry in rejected_refs with its reason.

Choose the next door

There are two, and the user chooses:

Send Luma invites: pass the list_id to activate_list with a Luma event. This sends real invites after a preview and the user’s explicit confirmation.
Record invites the user sent themselves: pass the list_id to activate_list with destination_type: "external" and the collab’s target_channel_id. This sends nothing; it records the invites so the funnel counts them.

On a transport error, retry with the same client_request_id. A committed save is replayed (idempotent_replay: true), so a retried create never makes a second List. Reusing an id with different arguments is refused.

Response

A successful save was not captured for this page, because it would create a List in a production workspace. The shape below is from the tool’s code and contract.

Field	Meaning
`outcome`	`created`, or `nothing_saved` when every reference was rejected (no List is created or changed).
`list_id`, `list_name`, `list_status`	The List. Pass `list_id` to activate_list unchanged.
`member_count`	Members on the List after the save.
`added_count`	People added by this call.
`already_present_count`	People already on the List, not added twice.
`duplicate_refs_collapsed`	Emails repeated in this call, saved once.
`rejected_count`, `rejected_refs`	Each rejected email with its `reason`: `invalid_email` or `not_found_in_workspace`. Also disclosed in `gaps`.
`rejected_refs_truncated`	True when not every rejected ref is echoed.
`idempotent_replay`	True when this was a replay of a committed save.

Rules the agent must follow

Never retry a rejected reference against save_list. Import the person first with import_people.
Never simulate a saved List by holding emails across turns. Save it, then read it back with get_lists.
Never choose the external door for the user. Use it only when they say they sent the invites themselves.
A List is not attendance or sign-up.

Errors and gaps

This validation error is real, captured today from a call with no parameters. Validation reports one missing parameter at a time.

{
  "tool": "save_list",
  "status": "error",
  "error": {
    "code": "invalid_parameter",
    "message": "A tool parameter is invalid",
    "what_failed": "A tool parameter (`name` or `list_id`) is required, and this call sends none of them.",
    "what_to_check": "The `name` and `list_id` arguments of this call.",
    "what_to_do": "Provide `name` or `list_id` and retry.",
    "retryable": false,
    "remediation": null
  }
}

invalid_parameter: neither or both of name and list_id, member_emails empty or over 500, or a missing or malformed client_request_id.
insufficient_scope: the OAuth token lacks mcp:tools:write. Nothing is saved.
entitlement_required: the plan lacks MCP write.
A conflict when a client_request_id is reused with different arguments, or the same save is still in flight.

import_people: bring CRM people in first.
get_lists: read the List back.
activate_list: send to Luma, or record invites sent yourself.
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

Workflow

Response

Rules the agent must follow

Errors and gaps

​When to use it

​Parameters

​Workflow

​Response

​Rules the agent must follow

​Errors and gaps

​Related

When to use it

Parameters

Workflow

Response

Rules the agent must follow

Errors and gaps

Related