get_workspace_context

The session-start tool. Call this once before any analytics question so the agent knows the user’s timezone, currency, configured custom event labels, connected ad accounts, and default attribution model / window. Replaces the legacy “data instructions” prompt-stuffing pattern with a single, cacheable, ~1 KB call.

When to use

At the start of every chat session before any analytics question.
Whenever the user references a custom event by name (“deals”, “lead magnet”) and you need the slot map.
To check the default attribution model before running query_ad_metrics.

For per-question lookups about a specific entity, use search_workspace. For tracking-health diagnostics, use get_space_health.

Parameters

Parameter	Type	Required	Description
`format`	string	No	`json` (default), `csv`, or `yaml`. Single-object payload — CSV flattens to key/value rows.

Output shape

{
  "space":   { "id": 123, "name": "Acme Marketing" },
  "team":    { "id": 7, "name": "Acme Inc." },
  "timezone": "America/New_York",
  "currency": "USD",
  "ad_accounts": [
    { "source": "facebook_ads", "id": "act_1234567890", "name": "Acme Meta", "currency": "USD", "status": "active", "last_synced_at": "2026-05-15T14:08:00Z" },
    { "source": "google_ads",   "id": "111-222-3333",   "name": "Acme Google", "currency": "USD", "status": "active", "last_synced_at": "2026-05-15T13:55:00Z" }
  ],
  "custom_event_labels": {
    "custom_event_2": "Deal Created",
    "custom_event_5": "Lead Magnet"
  },
  "default_attribution_model":  "last_touch",
  "default_attribution_window": 30,
  "ai_credit_balance": 14200,
  "business": {
    "summary": "Acme sells project-management software to agencies. Visitors start a free trial from the pricing page. Trials convert to paid plans in the app.",
    "type": "saas",
    "website": "https://acme.com",
    "platform": "Next.js",
    "lead_destination": "HubSpot",
    "uses_native_lead_forms": false,
    "ad_platforms": ["facebook", "google"]
  }
}

ai_credit_balance reflects the team’s ai_credits column (shared across every space on the team). default_attribution_model / default_attribution_window surface Cometly’s product defaults — they aren’t currently persisted per-space. business is null until setup step 1 (“About your business”) has been saved for the space. summary is up to three sentences on what the company sells, to whom, and how a customer converts on the site; it is drafted automatically from the website and can be edited in Setup → step 1. type is one of ecommerce, saas, lead_gen, services, or other. lead_destination is where leads or sales are recorded (for example HubSpot or Shopify checkout), uses_native_lead_forms covers Meta, LinkedIn, and TikTok native lead forms, and ad_platforms lists the platform keys the user says they run.

Caveats

The ai_credit_balance field reflects the team-level balance at request time. Don’t recommend analyze_report (or other credit-charging tools) when the balance is at zero.
last_synced_at is best-effort — different ad platforms expose different timestamp columns. Use get_space_health for the canonical freshness check.

Get Started

Connecting Clients

Tools

Resources

Prompts

When to use

Parameters

Output shape

Caveats

​When to use

​Parameters

​Output shape

​Caveats

When to use

Parameters

Output shape

Caveats