How responses work

Every heyBTW tool returns the same envelope. Learn it once and every tool reads the same way. The words on this page are the words on the wire. The docs never use synonyms for them.

The envelope

{
  "tool": "list_events",
  "query_time_ms": 590.8,
  "result_count": 4,
  "data": [ { "event_name": "ScaleUp.ai Field Dinner: Austin", "channel_id": "cmvifxsyp000j07l2hmp06n1u", "event_tense": "past" } ],
  "metadata": {
    "coverage_notes": ["Rows are the Python MCP program scope: archived and demo channels are excluded."],
    "contract_version": "v1",
    "ordering": "event_date_desc_then_channel_id",
    "workspace": { "id": "cmh572mmk0003l404yflrnj9u", "display_name": "heyBTW" }
  },
  "status": "partial",
  "gaps": [
    {
      "code": "partial_coverage",
      "message": "Partner events restricted by the host's Sponsor Mode",
      "what_failed": "5 partner event(s) in this workspace are restricted by the host's Sponsor Mode settings and are not available over MCP yet.",
      "what_to_check": "This response's coverage_note.",
      "what_to_do": "Use the heyBTW dashboard's partner view for those events. Retrying will not change the result.",
      "retryable": false,
      "remediation": null
    }
  ]
}

The sample above is trimmed from a real list_events response.

Key	Meaning
`tool`	The tool that answered.
`data`	The result rows. Most tools serve exactly one row, `data[0]`, holding everything. List-shaped tools serve one row per item.
`status`	`ok`, `partial` (served, with gaps) or `error` (nothing served, see `error`).
`gaps`	What is missing and why, one object per gap: `code`, `message`, `what_failed`, `what_to_check`, `what_to_do`, `retryable`.
`metadata.coverage_notes`	Sentences that explain the answer. Some say “tell the user … as written”: relay those word for word.
`metadata.contract_version`	`v1` unless you asked for another. See Contract versions.
`metadata.pagination`	On paged tools: `limit`, `returned`, `has_more`, `next_cursor`.
`crm_context`	On CRM-dependent tools, the first key. Says which route reaches the CRM. See below.

Partial is an answer

status: partial means heyBTW served what it could and named the rest. A gap with retryable: false will not change on retry. Report the answer, then say what is missing using the gap’s own words. Never treat a missing fact as zero.

The facts vocabulary

Newer tools open data[0] with a facts list and close it with carry and next. Read them in that order.

Word	Meaning
`facts`	A list of `{id, sentence, fields, via, basis}`. Read each `sentence` to the user before proposing anything. `fields` holds the numbers, `basis` says where they came from.
gap (inside facts)	`{id, gap: "..."}`: the fact is absent, not zero. Say so.
`carry`	The join to take to the user’s own tool: `{destination, via: "your_tools", join_keys, ask}`. For example, take these emails to the CRM and ask which are customers.
`next`	The one next step, or a gap saying why there is none yet. Some carry `doors`, ordered options.
`via`	Who does it. `heybtw` means heyBTW computed it. `your_tools` means the user’s own connector does it.

Join keys everywhere: a person by email, a company by company_domain.

crm_context

Every tool that depends on a CRM puts crm_context first.

Field	Meaning
`connection_path`	`dashboard` when a CRM is connected inside heyBTW.
`provider`	The CRM connected inside heyBTW, for example `attio` or `hubspot`.
`status`	Whether that connection is working.
`capability`, `capability_served`	What this tool needed from the CRM (`deal_read`, `contact_lookup`, `activity_read`) and whether heyBTW could serve it.
`crm_joined`, `crm_join_key`	Whether heyBTW joined the CRM in this response, and on which keys.
`agent_guidance`	The one rule to follow next.

When capability_served is false, the CRM-derived numbers in that response are null with a gap. Use the CRM connector in your client for those questions, joined on email and company_domain. Never put a number of your own under heyBTW’s name.

On CRM-dependent tools, crm_context appears at the top level and again inside data[0]. They are the same block.

Writes: preview, confirm, replay

Write tools share three conventions.

Preview first. Tools that import or change many records (record_signups, import_people, save_target_spec, activate_list, the partner invite) return a preview and save nothing. The preview carries a preview_token or import_token, valid for 15 minutes. Confirm by token. Never send the rows again.
client_request_id. Every write takes a fresh hyphenated UUID you generate. Retrying with the same id after a timeout replays the first answer (idempotent_replay: true) and never repeats the write. Reusing an id for a different write is refused.
Say what it did. Write responses report what changed per row (row_outcomes, counts) and what heyBTW did not do (no sends, no enrichment, no platform writes).

Event tense and the event clock

Event tools say where an event sits on the calendar, read in the collab’s own time zone. Read these as served. Never compute them from dates.

Field	Values
`event_tense`	`upcoming`, `live` (the event’s day is today), `past`, `unscheduled`
`days_until`, `days_since`	Calendar days to or from the event day
`event_window`	`pre_event` (more than 14 days out), `sprint` (14 to 8 days), `event_week` (last 7 days and the day), `wind_down` (14 days after), `wrapped` (later)

Contract versions

Every tool accepts contract_version. Omit it to get v1, the default. A few reads also serve v2: get_event_details filters, and an opaque event_id on some tools. A version a tool does not serve is refused with invalid_parameter, never silently downgraded. Build on v1 unless a reference page says otherwise.

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

How responses work

The envelope

Partial is an answer

The facts vocabulary

crm_context

Writes: preview, confirm, replay

Event tense and the event clock

Contract versions

​The envelope

​Partial is an answer

​The facts vocabulary

​crm_context

​Writes: preview, confirm, replay

​Event tense and the event clock

​Contract versions

​Related

The envelope

Partial is an answer

The facts vocabulary

crm_context

Writes: preview, confirm, replay

Event tense and the event clock

Contract versions

Related