> ## 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
> Program health and agent capability discovery — call this first to orient yourself before querying specific data.
This page documents the **Python MCP surface** (`mcp.heybtw.com`, Claude Desktop and other MCP clients). It reflects the tool exactly as implemented in `mcp-server/tools/workspace_overview.py` as of this page's publication — see [Schema stability](/docs/integrations/mcp-tools#schema-stability).
## Purpose
`get_workspace_overview` returns a single-object snapshot of the calling workspace: its identity and plan, which integrations are connected, headline program metrics (signups, MQLs, pipeline), and agent guidance (which other tools are worth calling next, given what's actually configured).
## When to use this
* The first call in any new agent session against a workspace you haven't queried before.
* "What can I ask about this workspace?" or "Is HubSpot connected here?"
* Before recommending a specific tool to the end user — `agent_guidance.data_limitations` tells you which tools will return degraded or empty data.
## Parameters
| Name | Type | Required | Default | Description | Example |
| ----------- | ---------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------- | -------------- |
| `date_from` | string (ISO 8601 date or datetime) | No | `null` | Restrict `program_metrics` to signups/events on or after this date. When omitted, metrics are all-time. | `"2026-01-01"` |
## Default behavior
Called with no parameters, this tool returns **all-time** program metrics (`program_metrics.period` is `"all_time"`) for the calling workspace — no result cap, no pagination, a single object (`result_count: 1`). `configuration.integrations` reflects live connection state at call time; it is not cached.
## Sample request
```json theme={null}
{
"tool": "get_workspace_overview",
"arguments": {}
}
```
## Sample response
```json theme={null}
{
"tool": "get_workspace_overview",
"query_time_ms": 84.2,
"result_count": 1,
"data": [
{
"workspace_id": "ws_9f2a1c",
"workspace_name": "Acme Events Co",
"domain": "acmeevents.example",
"industry": "Marketing Technology",
"workspace": {
"name": "Acme Events Co",
"domain": "acmeevents.example",
"plan": "growth",
"created_date": "2025-03-11T00:00:00+00:00"
},
"configuration": {
"integrations": {
"hubspot_crm": true,
"luma_events": true,
"splash_events": false,
"zuddl_events": false,
"enrichment": {
"provider": "fullenrich",
"connected": true,
"credits_remaining": 4200
}
},
"capabilities": {
"pipeline_attribution": true,
"partner_sourcing": true,
"seniority_classification": true,
"invite_recommendations": true,
"event_cost_tracking": true,
"enrichment": true
},
"data_availability": {
"event_count": 14,
"partner_count": 6,
"total_signups": 2310,
"has_attribution_data": true
}
},
"program_metrics": {
"period": "all_time",
"period_start": null,
"period_end": "2026-07-25T18:04:11+00:00",
"event_count": 14,
"total_signups": 2310,
"total_mql": 318,
"total_opportunity": 87,
"total_meetings": 142,
"partner_sourced_count": 640,
"unique_companies": 812,
"mql_rate": 0.1377,
"partner_sourced_pct": 0.2771,
"last_event_date": "2026-06-18T00:00:00+00:00",
"first_event_date": "2025-04-02T00:00:00+00:00",
"partner_program": {
"total_partners": 6,
"active_partners": 5,
"partner_sourced_pct": 0.2771
},
"trends": {
"attendance_trend": "increasing",
"mql_trend": "stable",
"partner_count_trend": "increasing"
},
"attribution_summary": {
"crm_connected": true,
"total_sourced_pipeline": 412500.0,
"total_influenced_pipeline": 891200.0,
"total_closed_won": 156000.0,
"total_opportunities": 87,
"program_conversion_rate": 0.1377,
"avg_cost_per_meeting": null,
"avg_cost_per_mql": null
}
},
"agent_guidance": {
"available_tools": [
{ "tool": "get_event_details", "description": "Event logistics, roster, attendance mix, seniority, and partner performance - before or after it runs" },
{ "tool": "get_account_relationship", "description": "Full Context Graph profile for any account by domain" },
{ "tool": "get_partner_insights", "description": "Partner performance, warmth scores, and sourcing breakdown" },
{ "tool": "get_cross_event_patterns", "description": "Multi-event engagement trajectories by company" },
{ "tool": "activate_list", "description": "WRITE - send a saved List's invites to its linked Luma event. Requires action=preview first and explicit human confirmation before action=confirm" },
{ "tool": "get_event_attribution", "description": "Pipeline attribution per event with sourced/influenced breakdown" },
{ "tool": "query_event_intelligence", "description": "DEPRECATED, being retired — cross-event attendance patterns by account or event. Use get_cross_event_patterns, get_account_relationship, or get_event_details instead" },
{ "tool": "get_invite_recommendations", "description": "Scored invite recommendations for a target event" },
{ "tool": "get_workspace_overview", "description": "Program health, integration status, and agent orientation" }
],
"suggested_first_queries": [
{ "tool": "get_event_attribution", "description": "Get attribution summary across all events", "example_params": {} },
{ "tool": "get_cross_event_patterns", "description": "Account engagement trajectories (new/increasing/stable/decreasing) per company, each anchored to the events behind it", "example_params": { "min_events": 2 } },
{ "tool": "get_partner_insights", "description": "Understand partner sourcing performance", "example_params": {} }
],
"data_limitations": [
"Invite recommendations: channel_id filter not yet implemented"
]
}
}
],
"metadata": {
"data_sources_queried": ["Workspace", "Channel", "EventSignUp", "Partner", "HubSpotConfig"],
"date_range_applied": null,
"filters_applied": { "workspace_id": "ws_9f2a1c", "date_from": null },
"coverage_note": null
}
}
```
## Response field reference
### Envelope
| Field | Type | Description |
| --------------- | ---------------- | --------------------------------------------------------------- |
| `tool` | string | Always `"get_workspace_overview"`. |
| `query_time_ms` | number | Server-side execution time in milliseconds. |
| `result_count` | integer | Always `1` on success — this tool returns exactly one object. |
| `data` | array (length 1) | The workspace overview object. |
| `metadata` | object | See [Response format](/docs/integrations/mcp-tools#response-format). |
### `data[0]`
| Field | Type | Description |
| ----------------- | -------------- | ----------------------------------------------------------------------- |
| `workspace_id` | string | The calling workspace's id, resolved from the API key. |
| `workspace_name` | string | Workspace display name. Duplicated at `workspace.name`. |
| `domain` | string \| null | Workspace's own domain, when set. |
| `industry` | string \| null | Workspace industry, when set. |
| `workspace` | object | `{ name, domain, plan, created_date }`. `plan` is `"unknown"` if unset. |
| `configuration` | object | See below. |
| `program_metrics` | object | See below. |
| `agent_guidance` | object | See below. |
### `data[0].configuration`
| Field | Type | Description |
| ----------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
| `integrations.hubspot_crm` | boolean | HubSpot connected and active. |
| `integrations.luma_events` \| `.splash_events` \| `.zuddl_events` | boolean | Event platform connection status per provider. |
| `integrations.enrichment.provider` | `"fullenrich"` \| `null` | `null` when no enrichment credits are configured. |
| `integrations.enrichment.connected` | boolean | `true` when `credits_remaining > 0`. |
| `integrations.enrichment.credits_remaining` | integer \| null | `null` when not connected. |
| `capabilities.*` | boolean | Feature flags derived from `integrations` — e.g. `pipeline_attribution` mirrors `hubspot_crm`. |
| `data_availability.event_count` \| `.partner_count` \| `.total_signups` | integer | Raw counts. |
| `data_availability.has_attribution_data` | boolean | Mirrors `hubspot_crm`. |
### `data[0].program_metrics`
| Field | Type | Description |
| -------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `period` | `"all_time"` \| `"custom"` \| `"last_N_days"` | Derived from whether `date_from` was supplied. |
| `period_start` | string (ISO 8601) \| null | Echoes `date_from`. |
| `period_end` | string (ISO 8601) | Always "now" at call time. |
| `event_count` | integer | Events in the period. |
| `total_signups` | integer | Total signups in the period. |
| `total_mql` | integer | Total MQLs in the period. |
| `total_opportunity` | integer | Total opportunities in the period. |
| `total_meetings` | integer | Total meetings booked in the period. |
| `partner_sourced_count` | integer | Signups attributable to a partner. |
| `unique_companies` | integer | Distinct companies represented. |
| `mql_rate` | number (0–1) | `total_mql / total_signups`, `0.0` if no signups. |
| `partner_sourced_pct` | number (0–1) | `partner_sourced_count / total_signups`. |
| `last_event_date` / `first_event_date` | string (ISO 8601) \| null | Bounds of the workspace's event history. |
| `partner_program` | object | `{ total_partners, active_partners, partner_sourced_pct }`. `active_partners` = partners with `total_sourced > 0`. On contract v1 (the default) this object carries a fourth key, `avg_partner_warmth`, which is withdrawn (HEY-1897) and deliberately undocumented — see the version note below. |
| `trends` | object | `{ attendance_trend, mql_trend, partner_count_trend }`, each `"increasing"` \| `"stable"` \| `"decreasing"` \| `"new"` \| `"insufficient_data"`. Requires ≥3 events in the period; otherwise every field is `"insufficient_data"`. |
| `attribution_summary` | object | See below. Sourced from the same canonical attribution resolver as [`get_event_attribution`](/docs/mcp-tools/get-event-attribution) — always workspace-wide/all-time, **independent of `date_from`**. |
**The sample above is not a verbatim capture: `partner_program` carries one
more key on the wire.**
Contract v1 is the default — omit `contract_version` and v1 is what you get —
and v1's `partner_program` additionally carries `avg_partner_warmth`, the
mean of an unbacked composite. Contract v2 omits it, leaving three observable
facts. v2 is defined but **not advertised**, so v1 is what a live call
returns today.
It is withdrawn (HEY-1897) and documented nowhere on this page on purpose.
Do not build on it; the remaining keys are all independently observable.
**`engagement_health` is a different case: it is gone outright, at every
contract version.** HEY-1913 removed the block outright — `accounts_new`,
`accounts_increasing`, `accounts_stable`, `accounts_decreasing`, and
`top_engaged_account` — rather than deprecating it: its counts were bare
scalars an agent could not re-derive, and a second path computing
trajectories diverged from the anchored one (it reported 20 accounts where
`get_cross_event_patterns` reported 83 on the same workspace).
This tool no longer classifies account trajectories at all.
[`get_cross_event_patterns`](/docs/mcp-tools/get-cross-event-patterns) is the one
trajectory surface, and each of its rows carries the `events[]`,
`first_seen`, `last_seen`, and `total_events` behind its classification. That
is why this tool's `suggested_first_queries` now routes there
unconditionally.
Earlier versions of this page documented `engagement_health` as live. If you
built a parser against it, it has been receiving nothing since that removal.
**`program_metrics.attribution_summary`** — when `configuration.integrations.hubspot_crm` is `false`, this shrinks to `{ crm_connected: false, total_sourced_pipeline: null, total_influenced_pipeline: null, total_closed_won: null, recommendation: "" }`. When CRM is connected but the attribution service is unreachable, every dollar field is `null` and `coverage_note` explains why (the fuller shape shown in the sample omits `coverage_note` because it succeeded). `avg_cost_per_meeting` and `avg_cost_per_mql` are always `null` today — cost data is not yet wired into this rollup (see [`get_event_attribution`](/docs/mcp-tools/get-event-attribution) for the one place program-level cost-per-meeting IS live, under `program_summary`).
### `data[0].agent_guidance`
| Field | Type | Description |
| ------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `available_tools` | array of `{ tool, description }` | Static list of all nine tools — eight read tools plus the `activate_list` write tool — **not** filtered by what's actually usable for this workspace, and not filtered by what the caller is entitled to call. One entry (`activate_list`) is a write tool: read its description before acting on it. |
| `suggested_first_queries` | array of `{ tool, description, example_params }` | Mostly conditional on `program_metrics` — e.g. `get_partner_insights` only when `partner_count > 0`. One entry is **unconditional**: `get_cross_event_patterns` ships on every response as the routing answer for account-trajectory questions, replacing the removed `engagement_health` rollup. |
| `data_limitations` | array of strings | Plain-English gaps, e.g. missing HubSpot, no event platform connected, no enrichment. |
**Two `available_tools` descriptions are stale on the wire.** The catalog is
a static list compiled into the server, and it still describes
`get_invite_recommendations` as returning "scored" recommendations and
`get_partner_insights` as carrying "warmth scores". Both scalars are being
removed from the contract (HEY-1764, HEY-1897); see those tools' reference
pages, which are authoritative over this catalog string. The sample above
transcribes the descriptions as actually emitted rather than quietly
correcting them, so what you see here matches what you will receive.
**`data_limitations` unconditionally includes `"Invite recommendations:
channel_id filter not yet implemented"`,** on every response, and that string
is inaccurate. `channel_id` on
[`get_invite_recommendations`](/docs/mcp-tools/get-invite-recommendations) is one
of the two ways to name the target event — the other is `event_name` — and
both are implemented. It is not a missing optional filter. Do not report it
to a user as a missing feature or a degraded capability. Correcting the
string itself is a change to the MCP server, not to this page.
## Errors
This tool raises no tool-specific structured errors today. Any failure (workspace not found, unexpected exception) is caught by the server's generic handler and surfaces to the client as:
```
RuntimeError: Internal error executing get_workspace_overview (error_id=<12-char hex>).
```
The `error_id` is logged server-side with the real exception — useful when filing a support request, but the client never sees which specific condition failed. This is current behavior across all nine tools; see [MCP Tools — Errors and troubleshooting](/docs/integrations/mcp-tools) for the transport-level errors (401, 429, 503) that can occur before a tool call is even attempted.
## Pagination and limits
Not applicable — this tool always returns exactly one object. There is no `limit` parameter and no cursor-based pagination on any of the eight read tools today (see [Schema stability](/docs/integrations/mcp-tools#schema-stability)).
## Related tools
* [`get_event_attribution`](/docs/mcp-tools/get-event-attribution) — the canonical source for `attribution_summary`'s numbers, with per-event granularity.
* [`get_partner_insights`](/docs/mcp-tools/get-partner-insights) — full detail behind `partner_program`.
* [`get_cross_event_patterns`](/docs/mcp-tools/get-cross-event-patterns) — the one place account trajectories are classified. This tool no longer computes them; see the `engagement_health` warning above.