get_program_report

Read-only.

It answers “how is the event program doing?” in one response, ready for a chart or a summary. It owns no number: each block is another tool’s output, named in sources. Follows the heyBTW MCP rules.

When to use it

“Give me a quarterly summary of our event program.”
“Chart our funnel from MQL to closed won.”
“Which events drove the most pipeline this year?”
“Make me a slide on event ROI.”

Parameters

Parameter	Type	Required	Notes
`time_range`	string	No	`last_30_days`, `this_quarter`, `last_quarter`, `ytd` or `program_total` (default). Any other value is `invalid_parameter`.
`contract_version`	string	No	Omit for `v1`.

time_range is the only narrowing parameter. It windows the funnel and the event rows the way the dashboard tab does; program_summary, velocity_comparison and coverage are program-wide and never windowed.

Response

Field	Meaning
`time_range`, `window`	The range asked for and the instants applied.
`funnel`	The dashboard’s own funnel `steps`, each with `label`, `source`, `field`, `count`, `count_source`, `canonical_stage`, `complete`. Plus `computed_at`, `freshness`, `complete` and `incomplete_reasons`.
`events`	`get_event_attribution`’s per-event rows without the deal breakdown. Upcoming events carry `event_tense` and `registered_account_pipeline`.
`program_summary`	`cost_per_meeting`, program-wide, verbatim from `get_event_attribution`.
`velocity_comparison`	Event-touched vs. non-touched deals, verbatim from `get_event_attribution`.
`coverage`	`get_data_health` verbatim.
`sources`	The canonical tool behind each block.

The sample below is trimmed from a real program_total call (fixture data; one event row of four shown).

{
  "tool": "get_program_report",
  "data": [
    {
      "time_range": "program_total",
      "window": { "date_from": null, "date_to": null, "authority": "bridge" },
      "funnel": {
        "computed_at": "2026-11-03T19:36:48.062Z",
        "freshness": { "age_seconds": 0, "stale": false, "window_seconds": 300 },
        "complete": true,
        "incomplete_reasons": [],
        "steps": [
          { "id": "mqls", "label": "MQLs", "source": "attio_deal_stage", "field": "Lead", "count": 25, "count_source": "per_step", "canonical_stage": "mql", "complete": true },
          { "id": "meetings_booked", "label": "Meetings Booked", "source": "attio_deal_stage", "field": "Meeting Booked", "count": 22, "count_source": "per_step", "canonical_stage": "meeting_booked", "complete": true },
          { "id": "opportunities", "label": "Opportunities", "source": "attio_deal_stage", "field": "Opportunity", "count": 17, "count_source": "per_step", "canonical_stage": "opportunity", "complete": true },
          { "id": "closed_won", "label": "Closed Won", "source": "attio_deal_stage", "count": 5, "count_source": "per_step", "canonical_stage": "closed_won", "complete": true }
        ]
      },
      "events": [
        {
          "event_name": "ScaleUp.ai x Partners: NYC Tech Week Open House",
          "channel_id": "cmvifxuom000o07l2hioks7wf",
          "event_date": "2026-05-05T22:00:00",
          "total_signups": 46,
          "mql_count": null,
          "crm_joined": true,
          "crm_join_key": null,
          "pipeline": { "total_revenue": 536000, "sourced_revenue": 536000, "influenced_revenue": 0, "won_revenue": 140000, "company_count": 6 }
        }
      ],
      "event_count": 4,
      "program_summary": {
        "cost_per_meeting": { "total_invested_usd": 6000, "paid_event_count": 1, "meetings_from_paid_events": 0, "cost_per_meeting_usd": null }
      },
      "velocity_comparison": {
        "event_touched_avg_days_to_close": null,
        "non_touched_avg_days_to_close": null,
        "event_touched_win_rate": 0.167,
        "non_touched_win_rate": 0.214,
        "win_rate_lift_pp": -4.8,
        "event_touched_count": 12,
        "non_touched_count": 14
      },
      "sources": {
        "events": "get_event_attribution per-event rows (rollup fields)",
        "program_summary": "get_event_attribution program_summary, verbatim",
        "coverage": "get_data_health, verbatim"
      }
    }
  ],
  "metadata": { "contract_version": "v1" },
  "status": "partial"
}

The coverage block is omitted from the sample; it is the get_data_health row. On this workspace every funnel step is a CRM deal stage, which counts every deal at that stage whatever the window, so the per-event funnel counts are null.

Rules the agent must follow

Report each number as its source tool would. Never compute a rate, a ratio or a composite from these blocks, and never rank events by a score.
A step with complete: false is a lower bound. Say so, with funnel.incomplete_reasons.
A stale funnel reads as of computed_at. Say when it was computed.
Upcoming events show 0 attributed. Their registered_account_pipeline is never attribution and never goes into a total.
A negative lift in velocity_comparison is a fact to relay as served, not a verdict on the program.
Read crm_context first. When heyBTW does not read deals, the CRM-derived counts are null with one gap; use the user’s own CRM connector for those questions.

Errors and gaps

Code	What it means	What to do
`invalid_parameter`	A `time_range` outside the five values.	Pick one of the five.
`partial_coverage` (funnel or attribution)	Forwarded verbatim from `get_event_attribution` and `get_data_health`. `retryable: false`.	Relay them. A remedy naming `time_range` applies to the funnel and event rows only.
`stale_data`	The funnel is older than 300 seconds. `retryable: true`.	Report it as of `computed_at`, or retry.
`scope_truncated`	More than 500 events in the window.	Use a narrower `time_range`.
`internal_error`	Failure on heyBTW’s side.	Retry once.

get_event_attribution: the deal breakdown behind each row.
get_data_health: the coverage block on its own.
get_workspace_overview: the funnel totals with integration status.
Playbook: Did anyone follow up, and what did the event do for pipeline.

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

get_program_report

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