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

`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`. `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` — 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: "<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 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 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).

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 — full detail behind engagement_health.

Getting Started

Connecting Your Platforms

MCP Tool Reference

Features

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