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

Spark MCP v2beta exposes ten 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](https://api.globalwebindex.com/docs/spark-mcp/v2beta/reference/mcp-tools/execute-gwi-mcp-v2beta-tool-calls.md).

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

**1. 1. list\_skills — at the start of each analysis**

Call at the start of each new analysis, and again when the user shifts to a different type of workflow. Returns workflow skill keys with short descriptions (for example `audience-comparison`, `audience-investigation`, `gwi-dictionary`, `segment-requests`). Takes no arguments.

**2. 2. get\_skills — when a skill description matches**

Pass only the keys from `list_skills` whose descriptions match the user request in `skill_keys`. Skip this tool when none match. Returns each skill as a markdown body; follow its instructions for the rest of the analysis. Never invent keys. An unknown or empty `skill_keys` value returns `isError: true`.

**3. 3. 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.

**4. 4. explore\_datasets — when the user asks what a dataset covers**

Call after `list_datasets` for dataset or Pulse coverage, module summaries, or help choosing between datasets. Pass 1–5 `dataset_codes` from `list_datasets` and a `length` of `short` (concise context) or `verbose` (detailed coverage). Pure dataset discovery does not require `global_filters` or the insight workflow. If one summary is unavailable, that entry carries `summary_error` while the other datasets still return.

**5. 5. 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.

When a people label is ambiguous between where they live and nationality or ethnic origin (for example "Asian people", "American millennials", "Chinese men"), the host asks one clarifying question before calling `global_filters`. After clarification, a market label goes to `global_filters`, and a nationality or ethnic-origin label is omitted here and carried only in `audience_generation`. The host does not ask again when the user already distinguished residence from nationality (for example "people living in China", "Chinese nationals", "Asian Americans").

**6. 6. 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`.

**7. 7. 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`.

**8. 8. explore\_taxonomy — to discover survey coverage for a topic**

Semantic data discovery, not computed insights. Returns the GWI survey questions and attributes relevant to a topic. Call after `global_filters`. Keep `prompt` topic-only, and pass scope through `dataset_codes`, `enforced_audiences`, `location_codes`, and `wave_codes`. Optionally set `questions_k` (default 5) and `attributes_k` (default 10). Use the results to explain available coverage, refine a later `generate_insights` prompt, or recover after a failed or weak audience. When `structuredContent.error` is non-empty, show `structuredContent.message` to the user.

**9. 9. generate\_insights — always for insight questions**

Primary discovery (replaces v1 `chat_gwi` / `search`). Send one or more short, focused prompts in the `prompts` array (1–10 per call). Batch related topics from the same analysis into one 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. Read the per-prompt outcome from `results[]` (one entry per prompt, in order).

**10. 10. 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 `results[].insights[].id` from `generate_insights`. Returns structured JSON (figures and provenance), not prose. Do not call automatically after discovery.

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

## Tools at a glance

| Tool | Purpose | When |
| :- | :- | :- |
| `list_skills` | Workflow skill keys and descriptions | Start of each new analysis, or when the workflow type changes |
| `get_skills` | Full workflow skill instructions | A `list_skills` description matches the user request |
| `list_datasets` | Accessible dataset codes | Dataset named, USA-specific with no dataset chosen, or USA vs Core unclear |
| `explore_datasets` | Dataset summaries and coverage | User asks what a dataset covers or how datasets compare; after `list_datasets` |
| `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` |
| `explore_taxonomy` | Survey questions and attributes for a topic | User asks what data exists on a topic, or to refine a prompt or recover after a weak audience; 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 `results[].insights[].id` from `generate_insights` |

## Example flow

1. User asks: *“Profile Gen Z skincare buyers in the UK and how to reach them.”*
2. `list_skills`, then `get_skills` with `["audience-investigation"]` because its description matches a targeting question.
3. `global_filters` with a location/timeframe-focused prompt (for example `"UK"`).
4. `audience_generation` for the cohort (or `search_audiences` first if they named a saved audience).
5. `generate_insights` with a `prompts` array (one short topic per entry), `enforced_audiences`, and codes from `global_filters`. Read each prompt's outcome from `results[]` in the same order.
6. `explore_insight` only if the user picks a specific `results[].insights[].id` and asks for more detail.

### Example: explore\_taxonomy

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "explore_taxonomy",
    "arguments": {
      "prompt": "social media usage",
      "dataset_codes": ["ds-core"],
      "location_codes": ["s2_1"]
    }
  }
}
```

The response lists matching `questions` (with `label` and `description`) and `attributes` (with `text`) for the resolved `dataset`.

## Lifecycle

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