get_abm_plan

Read-only.

The marketer’s question is “who are we going after for this event, who owns each account, and how many seats are left?” Reach for this tool whenever the user asks who is Wishlist or Target, who is covered or uncovered, or the seats to goal for a collab. Never rebuild the plan from chat history or ask the user to paste the ABM table. Follows the heyBTW MCP rules.

When to use it

“How many seats are left for the SF open house?”
“Which Target accounts have no owner yet?”
“Who on the partner side covers Beacon Hill?”
“How far down the outreach ladder are we on Wishlist accounts?”

Parameters

Parameter	Type	Required	Notes
`channel_id`	string	One of `channel_id` or `event_name`	From list_events.
`event_name`	string	See above	An ambiguous name returns no plan and lists the candidates.
`cursor`	string	No	`metadata.pagination.next_cursor` for the SAME collab. Expires after 15 minutes.
`contract_version`	string	No	Omit for v1. Only v1 is advertised.

No limit: a page holds up to 100 accounts, in the List’s own order.

Response

data[0], read through the same read the ABM board uses, so every value is the board’s:

Field	Meaning
`collab`	`channel_id` and `event_name`.
`working_from`	`list_id` and `list_name` of the List the plan works from, or null when it has none.
`seats_to_goal`	The board’s Seats-to-Goal ledger (below).
`outreach_ladder`	The collab’s outreach marks, in order.
`accounts[]`	One page of the working List.
`account_total`	The List’s members.
`agent_guidance`	`scope_boundaries` and `working_list`.

seats_to_goal:

Field	Meaning
`rsvp_target`	The event’s RSVP target.
`account_count`	Accounts on the plan.
`invited`, `registered`, `attended`	Counts of the contacts tracked on the plan. Registered and attended are separate layers.
`whitespace`	The board’s whitespace count, served as the board computes it.
`by_owner[]`	The same counts per owner you may see. An account with several owners counts under each.

Each account: company_name (or null), company_domain, priority (YOUR workspace’s own label, such as Wishlist, Target or General, or null), covered_by (owners you may see: kind you, workspace or unmanaged_partner with company name and domain, or person with contact.contact_email and contact.contact_name for a partner’s CSM or AM), owner_count (every owner, including ones not named to you), outreach (contacts per outreach mark), outreach_unmarked, source (added, matched or via_partner) and contributed_by. A real response for the SF open house fixture, trimmed to the notes that matter. This collab’s ABM board has no working List yet, so there are no accounts, but seats_to_goal still carries the RSVP target:

{
  "tool": "get_abm_plan",
  "result_count": 1,
  "data": [
    {
      "collab": {
        "channel_id": "cmvifxnzh000907l2zptjqszl",
        "event_name": "ScaleUp.ai x Partners: SF Tech Week Open House"
      },
      "working_from": null,
      "seats_to_goal": {
        "rsvp_target": 150,
        "account_count": 0,
        "invited": 0,
        "registered": 0,
        "attended": 0,
        "whitespace": 0,
        "by_owner": []
      },
      "outreach_ladder": [],
      "accounts": [],
      "account_total": 0,
      "agent_guidance": {
        "scope_boundaries": [
          "Overlap facts and counts between this plan and a partner's accounts belong to get_partner_overlaps. This tool never reports them.",
          "Follow-up tasks committed on this collab belong to get_due_tasks.",
          "Invites are sent only through activate_list, with its preview and confirmation steps. This tool sends nothing."
        ],
        "working_list": "Pass working_from.list_id to get_lists to read the working List's members, or to activate_list to send it."
      }
    }
  ],
  "metadata": {
    "coverage_notes": [
      "seats_to_goal is the Seats-to-Goal ledger the ABM board shows: the event's RSVP target and the registered and attended counts of the contacts tracked on the plan. by_owner lists the owners your workspace may see, and an account with several owners counts under each of them.",
      "This collab's ABM surface works from no List yet, so the plan has no accounts. seats_to_goal still shows the event's RSVP target."
    ],
    "contract_version": "v1",
    "pagination": { "limit": 100, "returned": 0, "has_more": false, "next_cursor": null }
  },
  "gaps": [
    { "code": "partial_coverage", "message": "Partner events restricted by the host's Sponsor Mode", "retryable": false }
  ],
  "status": "partial"
}

Rules the agent must follow

priority is the user’s own label, not heyBTW’s judgment. This tool ranks and recommends nothing.
A row names no contact to invite: who to invite is the covering owner’s decision.
It reports no overlap and no other partner’s priority. For overlap use get_partner_overlaps.
Read seats_to_goal as served. Never compute seats left from other counts.
Pages are offset-derived: an account added or removed while you page can repeat or skip. De-duplicate on company_domain.

Errors and gaps

Code	When	What to do
`invalid_parameter`	Neither `channel_id` nor `event_name`, a malformed id, or a cursor not issued for this call.	Fix it.
`entity_not_found`	No collab this workspace hosts or partners on with active consent.	Check list_events.
`query_timeout`	A dynamic working List could not be evaluated in time.	Retry later.
`upstream_crm_error`	The CRM did not answer for a working List whose criteria need it.	Retry later.
`rate_limit_exceeded`, `internal_error`		Honor Retry-After; retry once on internal_error.

A failed read is always an error, never an empty plan.

get_lists: the working List’s members.
activate_list: send the working List, with preview and confirmation.
get_partner_overlaps: overlap facts.
Playbook: Invite sprint.

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