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

# save_list

> Keep a set of people as a heyBTW List: create a named List, or add people to an existing one.

> [!WARNING]
>
> 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](https://heybtw.com/docs/tools/activate-list.md) invites.

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

## 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](https://heybtw.com/docs/tools/get-lists.md). |
| `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](https://heybtw.com/docs/tools/import-people.md). To save people from a CRM, call import\_people first and pass its `member_emails` here.

## Workflow

**1. Save**

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

**2. Report what was saved and rejected**

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

**3. Choose the next door**

There are two, and the user chooses:

* **Send Luma invites**: pass the `list_id` to [activate\_list](https://heybtw.com/docs/tools/activate-list.md) 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.

```json theme={null}
{
  "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.

## Related

* [import\_people](https://heybtw.com/docs/tools/import-people.md): bring CRM people in first.
* [get\_lists](https://heybtw.com/docs/tools/get-lists.md): read the List back.
* [activate\_list](https://heybtw.com/docs/tools/activate-list.md): send to Luma, or record invites sent yourself.
* 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.