get_workspace_overview

Read-only.

The orientation call. It answers “what is heyBTW connected to, and where does my event program stand?” An agent calls it once at the start of a session, before any other heyBTW tool. Follows the heyBTW MCP rules.

When to use it

“What does heyBTW know about our program?”
“Is our CRM connected? Is Luma connected?”
“How many events, sign-ups and companies do we have so far?”
“What is the event-attributed pipeline number on my dashboard?”
“Where do I start?”

Parameters

Parameter	Type	Required	Notes
`date_from`	string	No	Lower bound for the program counts. `YYYY-MM-DD` (a whole UTC day) or `YYYY-MM-DDTHH:MM[:SS]` with an optional `Z` or `+HH:MM` offset. Omit for all time.
`contract_version`	string	No	Omit for `v1`, the only version this tool advertises. Any other value may be refused with `invalid_parameter`.

There is no limit and no cursor. The response is always one row.

Response

data[0] holds everything, in this order.

Field	Meaning
`crm_context`	First key. Says whether heyBTW reads deals through a CRM connected in heyBTW (`connection_path`, `provider`, `status`, `capability`, `capability_served`, `crm_joined`, `crm_join_key`). `agent_guidance` is the one rule to follow next. Also served at the top level of the response.
`target_spec`	The workspace’s saved membership criteria, or `null`. When `null`, `target_spec_gap` says so in a sentence and `target_spec_next` names the tool that fills it.
`workspace`	Name, domain and created date.
`configuration.integrations.crm`	One provider-neutral CRM block: `connected`, `provider`, `status`, `connection_path`, `capabilities`.
`configuration.integrations.event_platforms`	One block per platform (Luma, Splash, Zuddl): `connected`, `status`, `connect_url`, `requires`, `syncs`.
`configuration.data_availability`	`event_count` (equals the `list_events` count), `total_signups`, `has_attribution_data`.
`program_metrics`	Event, sign-up and company counts; `total_mql`, `total_meetings`, `total_opportunity` from the dashboard funnel; `partner_program`; `attribution_summary`.
`program_metrics.funnel_totals`	Names the funnel step behind each total, its `source`, `window`, `computed_at` and `freshness`.
`agent_guidance`	`crm_paths` and `event_platform_paths` (the routes to a CRM and to event history), `available_tools`, `suggested_first_queries`, `data_limitations`, `dashboard_vocabulary`.

The sample below is trimmed from a real response on the heyBTW workspace (ScaleUp.ai fixture data).

{
  "tool": "get_workspace_overview",
  "result_count": 1,
  "data": [
    {
      "crm_context": {
        "connection_path": "dashboard",
        "provider": "attio",
        "status": "connected",
        "capability": "deal_read",
        "capability_served": true,
        "reason": null,
        "crm_joined": true,
        "crm_join_key": ["email", "company_domain"],
        "agent_guidance": "heyBTW reads deals and pipeline from Attio through the CRM connected in heyBTW, so the CRM values in this response are heyBTW's. For any other CRM lookup, use your client's CRM connector first, joined on email and company_domain."
      },
      "target_spec": null,
      "target_spec_gap": "No target spec is saved for this workspace, so heyBTW does not yet hold which titles, kinds of companies or exclusions define who belongs in your rooms. Save one with save_target_spec (scope workspace).",
      "target_spec_next": {
        "kind": "tool",
        "name": "save_target_spec",
        "reason": "The workspace scope is empty: save the standing ICP once, then add a collab spec per event."
      },
      "configuration": {
        "integrations": {
          "crm": {
            "connected": true,
            "provider": "attio",
            "status": "connected",
            "connection_path": "dashboard",
            "capabilities": ["list_push", "contact_lookup", "deal_read", "activity_read"]
          },
          "event_platforms": {
            "luma": {
              "connected": true,
              "status": "connected",
              "connect_url": "https://heybtw.com/dashboard/workspace/cmh572mmk0003l404yflrnj9u/integrations",
              "requires": "a Luma Plus API key (Luma Plus plan)",
              "syncs": ["events", "guest list", "registration status over time", "check-ins", "registration answers"]
            }
          }
        },
        "data_availability": { "event_count": 4, "total_signups": 154, "has_attribution_data": true }
      },
      "program_metrics": {
        "period": "all_time",
        "event_count": 4,
        "total_signups": 154,
        "total_mql": 25,
        "total_opportunity": 17,
        "total_meetings": 22,
        "funnel_totals": {
          "source": "program_funnel_bridge",
          "window": { "time_period": "all_time", "date_from": null, "date_to": null },
          "computed_at": "2026-11-03T19:36:37.327Z",
          "freshness": { "age_seconds": 0, "stale": false, "window_seconds": 300 }
        },
        "unique_companies": 53,
        "partner_program": { "total_partners": 5, "active_partners": 0, "partner_sourced_pct": 0.0 },
        "attribution_summary": {
          "crm_connected": true,
          "total_event_attributed_pipeline": 1586000,
          "total_sourced_pipeline": 1586000,
          "total_influenced_pipeline": 0,
          "total_closed_won": 140000,
          "total_opportunities": 12
        }
      },
      "agent_guidance": {
        "suggested_first_queries": [
          { "tool": "list_events", "description": "List every event in the program (name, channel_id, start date, upcoming/live/past, roster size)", "example_params": {} }
        ],
        "data_limitations": []
      }
    }
  ],
  "metadata": { "contract_version": "v1" },
  "status": "partial",
  "gaps": [
    {
      "code": "partial_coverage",
      "message": "Partner events restricted by the host's Sponsor Mode",
      "what_to_do": "Use the heyBTW dashboard's partner view for those events. Retrying will not change the result.",
      "retryable": false
    }
  ]
}

Rules the agent must follow

Read crm_context first and follow its agent_guidance. With no CRM connected in heyBTW, check whether the user’s client has a CRM connector and use it for account and deal questions, joined on email and company_domain.
Quote attribution_summary.total_event_attributed_pipeline when the user asks what their events are worth. It is the number on their dashboard. Sourced and influenced are its parts, not the headline.
A funnel total heyBTW could not read is null, never 0, and a gap names it. Say it is unknown.
program_metrics.mql_rate, attribution_summary.program_conversion_rate and trends.mql_trend are always null in v1. Do not compute them. Use the funnel totals, or get_program_report for every step.
Partner Influenced dollars from get_partner_insights are a separate classification. Never present them as a slice of the influenced total.
Call this once per session, not before every question.

Errors and gaps

Code	What it means	What to do
`partial_coverage` (Sponsor Mode)	Some partner events are restricted by the host’s Sponsor Mode and not served over MCP. `retryable: false`.	Report the answer, then say those events are on the dashboard’s partner view. This is a disclosure, not a failure.
`partial_coverage` (degraded read)	One of the three internal reads (attribution, funnel, CRM connection) was refused. The fields it feeds are `null` with a named gap; the rest is served.	Report what was served. Retry later if `retryable` is true.
`invalid_parameter`	A `date_from` outside the accepted grammar, or an unadvertised `contract_version`.	Fix the argument and call again.
`internal_error`	Failure on heyBTW’s side.	Retry once.
`rate_limit_exceeded`	Each overview spends three units of the per-workspace internal budget, so about 20 fit in a minute.	Wait for the `Retry-After` window.

list_events: the event directory behind event_count.
get_data_health: which numbers are not yet measured.
get_program_report: the full funnel and per-event rollup.
Playbook: Connect heyBTW next to your CRM and event platform.

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_workspace_overview

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