save_target_spec

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.

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.

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. 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 ), companies () and exclusions (). At collab scope only: geography (, 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

Ask the user who they want

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

Preview

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

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.

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

get_workspace_overview: shows the saved spec, or the gap.
check_people: target_spec_match per person.
get_invite_recommendations: candidates for 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

save_target_spec

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