Overview - GWI

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:

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.

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

User asks: “Profile Gen Z skincare buyers in the UK and how to reach them.”
list_skills, then get_skills with ["audience-investigation"] because its description matches a targeting question.
global_filters with a location/timeframe-focused prompt (for example "UK").
audience_generation for the cohort (or search_audiences first if they named a saved audience).
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.
explore_insight only if the user picks a specific results[].insights[].id and asks for more detail.

Example: explore_taxonomy

{
  "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: initialize → notifications/initialized → tools/list → tools/call.

​Call order

​Tools at a glance

​Example flow

​Example: explore_taxonomy

​Lifecycle

Call order

Tools at a glance

Example flow

Example: explore_taxonomy

Lifecycle