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

> Save who your events are for: the standing ICP for the workspace, or who belongs at one collab.

> [!WARNING]
>
> Writes to your heyBTW workspace. With `confirm: true` it saves the target spec for one scope, replacing that scope's block and keeping the prior version. Without `confirm` it saves nothing. It sends nothing.

> [!NOTE]
>
> This tool is evolving. This page describes what the connector serves today and will be revised as the tool changes.

A target spec says who belongs at your events: titles, seniority, kinds of companies, a city, and exclusions. Save it once for the workspace, and per collab when one event differs. Every invite sprint then starts from it.

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

## When to use it

* "Our events are for VP and above in RevOps and Marketing at 50 to 500 person SaaS companies."
* "For the LA dinner, only people within 50 miles, and no current customers."
* get\_workspace\_overview or get\_event\_details served `target_spec: null` with a next step to save one.

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `scope` | string | Yes | `workspace` (the standing ICP) or `collab` (one event, overriding the workspace per key). |
| `channel_id` | string | With `scope: collab` | A collab from [list\_events](https://heybtw.com/docs/tools/list-events.md). Only your own, non-demo collabs. |
| `target_spec` | object | Yes | The block, below. |
| `confirm` | boolean | No | Default false: preview only. |
| `client_request_id` | string | With `confirm: true` | A fresh hyphenated UUID. |
| `contract_version` | string | No | Omit for v1. |

The `target_spec` block takes `describe` (free text), `personas` (a list of {`titles`, `seniority`, `functions`}), `companies` ({`industries`, `size_bands`, `regions`, `tech`, `funding_stage`}) and `exclusions` ({`customers`, `competitors`, `partner_employees`}). At collab scope only: `geography` ({`city`, `radius_miles`}, default the collab's city and 50 miles), `target_account_sources`, `net_new_goal` and `exclusions.invited_no_show_min`.

* `seniority`: `c_suite`, `vp`, `director` or `manager`, as a floor (`director` means directors and above). A single string is read as a one-item list.
* `regions`: North America, LATAM, EMEA, APAC, ANZ, Middle East, Africa or Global, where a company is headquartered.
* `size_bands`: `"min-max"` or `"min+"`, for example `"50-500"`.
* `geography` is where the people must be, never a company headquarters.

## Workflow

**1. Ask the user who they want**

Do not derive a spec from the roster or the CRM.

**2. Preview**

Call without `confirm`. The response shows the resolved spec, which keys change and every item left out with its allowed values.

**3. Confirm**

After the user agrees, call again with the same spec, `confirm: true` and a fresh `client_request_id`. On a transport error, retry with the same id: a committed save is replayed, never repeated.

## Response

Neither a preview nor a save was captured for this page. The shape below is from the tool's code and contract.

| Field | Meaning |
| - | - |
| `outcome` | `preview`, `saved`, or `not_saved` when nothing valid was sent. |
| `scope`, `channel_id` | What was written or would be. |
| `changes` | The keys the save changes. |
| `rejected` | Items left out, each with the allowed values. |
| `target_spec` | The resolved spec, with `from` (`collab`, `workspace` or `default`) per key, a paste-ready `search_brief`, and `suggested_sources` (each `via: your_tools` or `via: heybtw`). |
| `target_spec_gap`, `target_spec_next` | Why a spec is missing and the next step. |
| `version`, `idempotent_replay` | On a save: version\_id, set\_at, supersedes\_version\_id, previous\_set\_at. |

## Rules the agent must follow

* Preview first. Save only after the user agrees.
* The spec is membership criteria only. heyBTW grades, tiers and ranks no one from it and runs no search.
* Take `search_brief` to the user's own tools. `suggested_sources` are suggestions, not steps.
* No spec is shared with a partner.

## Errors and gaps

This validation error is real, captured today from a call with no parameters.

```json theme={null}
{
  "tool": "save_target_spec",
  "status": "error",
  "error": {
    "code": "invalid_parameter",
    "message": "A tool parameter is invalid",
    "what_failed": "A tool parameter (`scope`) is required but was not provided.",
    "what_to_check": "The `scope` argument of this call.",
    "what_to_do": "Provide `scope` as one of `workspace` or `collab`, and retry.",
    "retryable": false,
    "remediation": null
  }
}
```

* `entity_not_found`: a partner's collab, the demo collab or an unknown `channel_id`.
* `insufficient_scope`: the OAuth token lacks `mcp:tools:write`. Nothing is saved.
* An unknown seniority is rejected on its own; the rest still saves.

## Related

* [get\_workspace\_overview](https://heybtw.com/docs/tools/get-workspace-overview.md): shows the saved spec, or the gap.
* [check\_people](https://heybtw.com/docs/tools/check-people.md): `target_spec_match` per person.
* [get\_invite\_recommendations](https://heybtw.com/docs/tools/get-invite-recommendations.md): candidates for 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.