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

# get_data_health

> Which of this workspace's numbers are not yet measured, and what closes each gap.

> [!NOTE]
>
> Read-only.

It answers "can I trust this number?" Call it before reporting a \$0, a missing revenue figure or a partner count, so the user hears what heyBTW has not measured instead of a zero. Follows the [heyBTW MCP rules](https://heybtw.com/docs/mcp/rules.md).

## When to use it

* "Why does this event show no pipeline?"
* "How many of our sign-ups can't be matched to a company?"
* "Which events have attribution and which don't?"
* "Is our partner-sourced count complete?"
* "Before I send this report, what's missing?"

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `contract_version` | string | No | Omit for `v1`. |

No other parameter. The response is one row, never dropped.

## Response

`data[0]` itemizes coverage facts. It computes nothing of its own: each fact is another tool's, and `fact_sources` names the source of each. It carries no composite, grade or tier.

| Field | Meaning |
| - | - |
| `facts` | Opens the row. `unresolved_people` says in one `sentence` how many sign-up records have no resolvable company, with counts in `fields`, `via: heybtw` and a `basis`. |
| `next` | When the count is above zero, `next.doors` names two ways to close the gap, in order: add company and title from the user's own tools and bring the rows back through [`record_signups`](https://heybtw.com/docs/tools/record-signups) or [`import_people`](https://heybtw.com/docs/tools/import-people), then enrich in heyBTW from the dashboard Enrichment page (`path`). |
| `attribution_coverage` | `events_with_canonical_attribution` and `events_without_canonical_attribution`, both named with `channel_id`. The same lists [`get_event_attribution`](https://heybtw.com/docs/tools/get-event-attribution) names. |
| `unmatched_partner_source` | `signup_count`: sign-ups whose partner source matches no active partner. |
| `enrichment_coverage` | Sign-up records with and without a resolvable company. Counted per record (one per person per event), not per person. |
| `unmeasured_facts` | Facts heyBTW does not measure yet. Today: `provider_sync_freshness`, with its own gap. |
| `fact_sources` | The resolver behind each fact. |
| `upstream_coverage_notes` | Notes forwarded from the source tools, each with its `source_tool`. |

The sample below is trimmed from a real response on the heyBTW workspace. Every sign-up there has a company, so `facts` says so and no `next` is served. The fact's `basis` sentence is left out of the sample; it says the count is over sign-up records, one per person per event, not distinct people.

```json theme={null}
{
  "tool": "get_data_health",
  "result_count": 1,
  "data": [
    {
      "facts": [
        {
          "id": "unresolved_people",
          "sentence": "Every sign-up on this workspace has a company.",
          "fields": {
            "signup_records_without_resolvable_company": 0,
            "signup_records_total": 154
          },
          "via": "heybtw"
        }
      ],
      "attribution_coverage": {
        "source_tool": "get_event_attribution",
        "event_count": 4,
        "events_with_canonical_attribution": [
          { "event_name": "ScaleUp.ai Field Dinner: Austin", "channel_id": "cmvifxsyp000j07l2hmp06n1u" },
          { "event_name": "ScaleUp.ai x Partners: NYC Tech Week Open House", "channel_id": "cmvifxuom000o07l2hioks7wf" }
        ],
        "events_without_canonical_attribution": [],
        "events_with_invalid_canonical_projection": []
      },
      "unmatched_partner_source": { "source_tool": "get_event_attribution", "signup_count": 0 },
      "enrichment_coverage": {
        "signup_records_with_resolvable_company": 154,
        "signup_records_without_resolvable_company": 0,
        "signup_records_total": 154
      },
      "unmeasured_facts": ["provider_sync_freshness"]
    }
  ],
  "metadata": { "contract_version": "v1" },
  "status": "partial",
  "gaps": [
    {
      "code": "partial_coverage",
      "message": "Data-health fact not measured: provider_sync_freshness",
      "what_to_do": "Treat provider_sync_freshness as unknown, never as fresh or stale. Retrying will not change this result.",
      "retryable": false
    },
    {
      "code": "partial_coverage",
      "message": "Canonical attribution coverage is incomplete for this response",
      "what_failed": "Canonical attribution data is missing for 2 of 4 events that have not happened yet, so nothing is attributed to them until their event day - their sourced, influenced and won figures are 0 until then, and registered_account_pipeline is the open pipeline of the accounts registered for them, which is not attribution: ScaleUp.ai x Marlowe Cloud: LA Revenue Leaders Dinner, ScaleUp.ai x Partners: SF Tech Week Open House.",
      "retryable": false
    }
  ]
}
```

## Rules the agent must follow

* When `unresolved_people` is above zero, relay its `sentence` and offer both `next.doors` in their order before any CRM join. The join misses those people.
* Treat `provider_sync_freshness` as unknown. Never call a sync fresh or stale.
* An event with no canonical attribution has unknown revenue, not \$0. Name it from `attribution_coverage`.
* An upcoming event shows 0 attributed until its event day. That is the rule, not missing data. Its `registered_account_pipeline` (from `get_event_attribution`) is never attribution.
* Counts here are sign-up records. Do not report them as distinct people.

## Errors and gaps

| Code | What it means | What to do |
| - | - | - |
| `partial_coverage` (unmeasured fact) | A fact with no live source, such as `provider_sync_freshness`. `retryable: false`. | Say it is not measured. |
| `partial_coverage` (attribution) | Forwarded verbatim from `get_event_attribution`, for example events that have not happened yet. | Relay it; scope revenue questions to covered events. |
| `partial_coverage` (Sponsor Mode) | Partner events restricted by the host's Sponsor Mode are not counted. | Point to the dashboard's partner view. |
| `scope_truncated` | More than 500 events, or a list too long for the response. | Say the lists are capped. |
| `internal_error` | Failure on heyBTW's side. | Retry once. |

## Related

* [`get_event_attribution`](https://heybtw.com/docs/tools/get-event-attribution): the source of the attribution facts.
* [`get_program_report`](https://heybtw.com/docs/tools/get-program-report): serves this row verbatim as its `coverage` block.
* [`record_signups`](https://heybtw.com/docs/tools/record-signups) and [`import_people`](https://heybtw.com/docs/tools/import-people): the first door for unresolved people.
* Playbook: [Did anyone follow up, and what did the event do for pipeline](https://heybtw.com/docs/playbooks/follow-up-and-roi.md).


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