get_workspace_overview

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.

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

{
  "tool": "get_workspace_overview",
  "arguments": {}
}

Sample response

{
  "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.

`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` — 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 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: "<string>" }

. 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 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 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 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).

get_event_attribution — the canonical source for attribution_summary’s numbers, with per-event granularity.
get_partner_insights — full detail behind partner_program.
get_cross_event_patterns — the one place account trajectories are classified. This tool no longer computes them; see the engagement_health warning above.

Getting Started

Connecting Your Platforms

MCP Tool Reference

Features

Lists

Partner Ecosystem

If You've Been Invited

Concepts

Frequently Asked Questions

get_workspace_overview

Purpose

When to use this

Parameters

Default behavior

Sample request

Sample response

Response field reference

Envelope

`data[0]`

`data[0].configuration`

`data[0].program_metrics`

`data[0].agent_guidance`

Errors

​Purpose

​When to use this

​Parameters

​Default behavior

​Sample request

​Sample response

​Response field reference

​Envelope

​data[0]

​data[0].configuration

​data[0].program_metrics

​data[0].agent_guidance

​Errors

​Pagination and limits

​Related tools

Purpose

When to use this

Parameters

Default behavior

Sample request

Sample response

Response field reference

Envelope

`data[0]`

`data[0].configuration`

`data[0].program_metrics`

`data[0].agent_guidance`

Errors

Pagination and limits

Related tools