> ## Documentation Index
> Fetch the complete documentation index at: https://api.globalwebindex.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Spark MCP v2beta tools — catalogue, call order, and example flow

<Warning>
  **Beta.** `/v2beta/spark-api/mcp` is a preview endpoint, not the final v2 surface.
  An official frozen `/v2` will be published later from this channel — plan for a further
  URL update then. v1 remains available and is not deprecated.
</Warning>

Spark MCP v2beta exposes six tools on one endpoint for every client:

```text theme={null}
POST https://api.globalwebindex.com/v2beta/spark-api/mcp
```

There is no `/openai/mcp` route on this channel. OpenAI clients use the same URL and the same standard tool names.

For request and response schemas with runnable examples, see [API reference](/docs/spark-mcp/v2beta/reference/mcp-tools-v2beta/execute-gwi-mcp-v2beta-tool-calls).

## Call order

On each new analysis, tools run in this order. **Always call `global_filters`, then `generate_insights`.** Insert the other tools only when the conditions below apply.

<Steps>
  <Step title="1. list_datasets — when dataset scope is needed">
    Call if the user names a dataset, if a USA-specific request has no dataset chosen, or if USA vs Core is unclear (ask rather than guess). Use only codes this tool returns; pass them as `dataset_codes` downstream when selected.
  </Step>

  <Step title="2. global_filters — always">
    Resolve location and timeframe before any audience or insight tool. Forward non-empty `location_codes` and `wave_codes` to later tools. Never invent codes.
  </Step>

  <Step title="3. search_audiences — when the user names a saved audience">
    Prefer this when the user refers to an existing My / Shared / GWI audience by title. If nothing matches, fall back to `audience_generation` with that name as the prompt. Pass matched `audiences[].id` into `generate_insights.enforced_audiences`.
  </Step>

  <Step title="4. audience_generation — when the user describes a segment">
    Use when the user describes a cohort, interest, job, or behavior (not a saved title). Skip generic baselines such as “all internet users”. Pass `location_codes` / `wave_codes` from `global_filters` when present. Use returned `audiences[].id` in `enforced_audiences`.
  </Step>

  <Step title="5. generate_insights — always for insight questions">
    Primary discovery (replaces v1 `chat_gwi` / `search`). One focused topic per call. Pass `enforced_audiences` when you have audience IDs; forward non-empty `location_codes` / `wave_codes`; pass `dataset_codes` only if dataset scope was set earlier.
  </Step>

  <Step title="6. explore_insight — only on explicit drill-down">
    Replaces v1 `explore_insight_gwi` / `fetch`. Call only when the user asks for more detail on a specific `insights[].id`. Returns structured JSON (figures and provenance), not prose. Do not call automatically after discovery.
  </Step>
</Steps>

Never call `search_audiences`, `audience_generation`, or `generate_insights` before `global_filters` on a new analysis.

## Tools at a glance

| Tool                  | Purpose                           | When                                                                       |
| :-------------------- | :-------------------------------- | :------------------------------------------------------------------------- |
| `list_datasets`       | Accessible dataset codes          | Dataset named, USA-specific with no dataset chosen, or USA vs Core unclear |
| `global_filters`      | Location and timeframe codes      | **Every** new analysis, before audiences or insights                       |
| `search_audiences`    | Saved audience by title           | User names an existing audience (before `audience_generation`)             |
| `audience_generation` | Audience from a description       | User describes who to analyze; after `global_filters`                      |
| `generate_insights`   | Insight findings                  | Insight questions; after `global_filters` (and audiences when needed)      |
| `explore_insight`     | Structured detail for one insight | User explicitly asks for more on a specific `insights[].id`                |

## Example flow

1. User asks: *“Profile Gen Z skincare buyers in the UK and how to reach them.”*
2. `global_filters` with a location/timeframe-focused prompt (for example `"UK"`).
3. `audience_generation` for the cohort (or `search_audiences` first if they named a saved audience).
4. `generate_insights` with a short topic prompt, `enforced_audiences`, and codes from `global_filters`.
5. `explore_insight` only if the user picks a specific insight and asks for more detail.

## Lifecycle

Follow the standard [MCP lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle): `initialize` → `notifications/initialized` → `tools/list` → `tools/call`.