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

# How responses work

> The envelope every heyBTW tool returns, and the vocabulary inside it: facts, carry, next, via, gaps, coverage notes.

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

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

> [!NOTE]
>
> 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`](https://heybtw.com/docs/tools/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.

## Related

* [The rules](https://heybtw.com/docs/mcp/rules.md)
* [Limits and errors](https://heybtw.com/docs/mcp/limits-and-errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.