> ## 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,
"avg_partner_warmth": 0.56
},
"engagement_health": {
"accounts_new": 402,
"accounts_increasing": 118,
"accounts_stable": 251,
"accounts_decreasing": 41,
"top_engaged_account": {
"company": "Lighthouse Robotics",
"domain": "lighthouserobotics.example",
"events_attended": 6
}
},
"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_summary", "description": "Post-event report with attendance, funnel, seniority, and partner performance" },
{ "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": "get_event_attribution", "description": "Pipeline attribution per event with sourced/influenced breakdown" },
{ "tool": "query_event_intelligence", "description": "Cross-event attendance patterns by account or event" },
{ "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": "Find companies attending multiple events", "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, avg_partner_warmth }`. `active_partners` = partners with `total_sourced > 0`. |
| `engagement_health` | object | `{ accounts_new, accounts_increasing, accounts_stable, accounts_decreasing, top_engaged_account }`. Trajectory buckets are computed the same way as [`get_cross_event_patterns`](/docs/mcp-tools/get-cross-event-patterns). `top_engaged_account` is `null` when there is no pattern data, or when a same-row data-integrity check fails server-side (rare; logged, not surfaced as an error). |
| `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`**. |
**`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 8 tools — not filtered by what's actually usable for this workspace. |
| `suggested_first_queries` | array of `{ tool, description, example_params }` | Conditional on `program_metrics` — e.g. only suggests `get_partner_insights` when `partner_count > 0`. |
| `data_limitations` | array of strings | Plain-English gaps, e.g. missing HubSpot, no event platform connected, no enrichment. Always includes `"Invite recommendations: channel_id filter not yet implemented"` (current known gap in `get_invite_recommendations`). |
## 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 8 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 8 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) — full detail behind `engagement_health`.