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

> What this workspace has connected, what its program adds up to, and which tools to call next.

> [!NOTE]
>
> 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](https://heybtw.com/docs/mcp/rules.md).

## 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`](https://heybtw.com/docs/tools/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).

```json theme={null}
{
  "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`](https://heybtw.com/docs/tools/get-program-report) for every step.
* Partner Influenced dollars from [`get_partner_insights`](https://heybtw.com/docs/tools/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. |

## Related

* [`list_events`](https://heybtw.com/docs/tools/list-events): the event directory behind `event_count`.
* [`get_data_health`](https://heybtw.com/docs/tools/get-data-health): which numbers are not yet measured.
* [`get_program_report`](https://heybtw.com/docs/tools/get-program-report): the full funnel and per-event rollup.
* Playbook: [Connect heyBTW next to your CRM and event platform](https://heybtw.com/docs/playbooks/connect-crm-and-event-platform.md).


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