> ## 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. # Execute GWI MCP v2beta tool calls > JSON-RPC endpoint for the v2beta MCP profile. Supported tools: 1. **list_skills** 2. **get_skills** 3. **list_datasets** 4. **explore_datasets** 5. **global_filters** 6. **explore_taxonomy** 7. **search_audiences** 8. **audience_generation** 9. **generate_insights** 10. **explore_insight** ## OpenAPI ````yaml post /v2beta/spark-api/mcp openapi: 3.0.0 info: title: GWI Spark API - MCP Server (v2beta) version: 2.0.0-beta description: > # GWI MCP Server v2beta for AI Assistants The v2beta MCP profile exposes a workflow-oriented tool chain for audience insights. It replaces v1 discovery tools (`chat_gwi` / `search`) with `generate_insights`, and adds `global_filters`, `audience_generation`, `explore_datasets`, and `explore_taxonomy` for scope and data discovery. Enrichment uses **`explore_insight`** (replaces v1 `explore_insight_gwi` on the client) and returns structured JSON rather than prose. It also exposes **`list_skills`** and **`get_skills`** for workflow skill discovery and retrieval. **Endpoint:** `POST /v2beta/spark-api/mcp` ## HTTP headers | Header | Value | | --- | --- | | `Content-Type` | `application/json` | | `Accept` | `application/json, text/event-stream` | | `Mcp-Protocol-Version` | `2026-07-28` (legacy clients may use `2025-11-25`) | | `Mcp-Method` | JSON-RPC method when using streamable HTTP routing (for example `server/discover`, `tools/list`, `tools/call`) | | `Authorization` | `Bearer YOUR_TOKEN` | ## Protocol This endpoint uses MCP over stateless HTTP (protocol `2026-07-28`). There is no session handshake and no `Mcp-Session-Id` header; each request is independent. **Supported protocol versions:** `2026-07-28` (current) and `2025-11-25` (legacy). **Discovery (optional):** Modern clients may call `server/discover` before other RPCs to learn supported versions, server capabilities, and server identity. Legacy clients that still call `initialize` negotiate down to `2025-11-25` or earlier and continue to work unchanged. **Typical flow:** 1. (Optional) `server/discover` or legacy `initialize` 2. `tools/list` to enumerate tools, input schemas, and annotations 3. `tools/call` to invoke a tool (documented in detail below) On `2026-07-28`, include protocol version, client info, and client capabilities in `params._meta` on each request (or set the `Mcp-Protocol-Version` HTTP header). Example `server/discover`: ```json { "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "my-app", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": {} } } } ``` **tools/list response fields (`2026-07-28`):** - `ttlMs` and `cacheScope` — cache hints for the tool list (SEP-2549) - Per-tool `idempotentHint` and `readOnlyHint` — always present on tool annotations ## Suggested workflow 1. **list_skills** — call at the start of each new analysis and when the user shifts to a different workflow type; returns catalogue keys and short descriptions 2. **get_skills** — only for keys whose `list_skills` descriptions match the user request; skip when none match, then follow the returned markdown body 3. **list_datasets** — optional; discover dataset codes when explicit scope is needed 4. **explore_datasets** — after `list_datasets` for dataset or Pulse coverage, summaries, and descriptive comparison; pure dataset discovery does not require the insight workflow 5. **global_filters** — required before audience and insight tools 6. **search_audiences** / **audience_generation** — when the user names a saved audience or describes a cohort 7. **explore_taxonomy** — discover survey coverage for a topic and inform recovery after a failed or weak audience 8. **generate_insights** — pass `enforced_audiences`, `location_codes`, and `wave_codes` from earlier steps 9. **explore_insight** — replaces v1 `explore_insight_gwi`; returns structured JSON (`id`, `title`, `text`, `url`, `metadata`). Call only when the user explicitly asks for more detail on a specific `results[].insights[].id` from `generate_insights` (reactive-only; do not call automatically) Example chain: `list_skills` → `get_skills` (when a description matches) → `global_filters` → `audience_generation` ("Gen Z") → `generate_insights` (`prompts`: `["social media habits"]`) → `explore_insight` (optional, user-initiated). Never invent skill keys. Never call `audience_generation`, `search_audiences`, or `generate_insights` before `global_filters` on a new analysis. ## Request/response format All requests use JSON-RPC 2.0 format: ### Request structure ```json { "jsonrpc": "2.0", "id": "unique-request-id", "method": "tools/call", "params": { "name": "tool_name", "arguments": { // tool-specific arguments } } } ``` ### Response structure ```json { "jsonrpc": "2.0", "id": "unique-request-id", "result": { "content": [ { "type": "text", "text": "..." } ] } } ``` On success, tools return **`structuredContent`** — a typed object that mirrors the JSON in `content[0].text`. Prefer `structuredContent` for programmatic parsing; the object shape depends on the tool (see response examples). ### Tool errors (`result.isError`) **When to check** After a successful JSON-RPC envelope (HTTP **200**, no top-level `error` field), look at **`result.isError`**: | `result.isError` | Meaning | | --- | --- | | `true` | Tool failed. Read `result.content` — usually one `text` item with a human-readable message. No `structuredContent` was returned. | **Why HTTP can still be 200** A failed tool is still a completed JSON-RPC call. The failure is signaled in **`result`**, not by HTTP status alone. **Common reasons for `isError: true`** 1. **Invalid arguments** — bad or missing inputs before or during validation, for example: - `get_skills`: missing/empty `skill_keys`; unknown key from `list_skills` - `global_filters`: empty `prompt` - `audience_generation`: empty `audiences` - `generate_insights`: empty `prompts`; more than 10 `prompts`; a `prompts` value that is a single string; invalid UUIDs in `enforced_audiences`; `limit` outside `1..20` - `explore_insight`: missing or invalid UUID `insight_id` - `explore_datasets`: missing/empty `dataset_codes`; invalid `length`; more than 5 `dataset_codes` - `explore_taxonomy`: empty `prompt`; invalid UUIDs in `enforced_audiences` - `search_audiences`: missing/empty `query`; invalid UUIDs in `exclude_audience_ids`; `limit` outside `1..100` - Other tools: same pattern where IDs or required strings are wrong 2. **Downstream / service errors** — GWI or infrastructure issues after arguments are accepted, for example: - Resource not found (insight, dataset, audience, etc.) - `enforced_audiences` incompatible with `dataset_codes` or mixed audiences from different datasets - Timeouts, cancelled requests, or generic internal failures **`_meta.isInternalError`** When **`result._meta.isInternalError`** is **`true`**, the server classified the failure as internal or timeout-style. It may be omitted or `false` for validation or not-found style errors. **Not covered here: JSON-RPC protocol errors** Invalid `method`, malformed JSON-RPC, and similar issues use the standard JSON-RPC **`error`** field. They are **not** expressed as `result.isError`. ### Soft failures and partial success These are **not** `result.isError`. The tool call completed; surface the warning or partial outcome to the user: - **`generate_insights`:** non-empty `structuredContent.results[].error` — use `structuredContent.results[].message` as the user-facing text. - **`global_filters`:** `structuredContent.global_filters.inaccessible_location_names` — some location terms were excluded for access; other filters still resolved. See example `global_filters_partial_access`. - **`audience_generation`:** `structuredContent.failed_audiences` — map of prompts that could not be mapped; `audiences` may be empty or partial. See example `audience_generation_all_failed`. - **`explore_datasets`:** `structuredContent.datasets[].summary_error` — that dataset summary failed; other requested datasets may still succeed. - **`explore_taxonomy`:** non-empty `structuredContent.error` — use `structuredContent.message` as the user-facing explanation. servers: - url: https://api.globalwebindex.com security: [] paths: /v2beta/spark-api/mcp: post: tags: - MCP Tools summary: Execute GWI MCP v2beta tool calls description: | JSON-RPC endpoint for the v2beta MCP profile. Supported tools: 1. **list_skills** 2. **get_skills** 3. **list_datasets** 4. **explore_datasets** 5. **global_filters** 6. **explore_taxonomy** 7. **search_audiences** 8. **audience_generation** 9. **generate_insights** 10. **explore_insight** operationId: mcpV2BetaToolCall requestBody: required: true description: JSON-RPC request for any supported v2beta MCP tool content: application/json: schema: oneOf: - $ref: '#/components/schemas/ListSkillsRequest' - $ref: '#/components/schemas/GetSkillsRequest' - $ref: '#/components/schemas/ListDatasetsRequest' - $ref: '#/components/schemas/ExploreDatasetsRequest' - $ref: '#/components/schemas/GlobalFiltersRequest' - $ref: '#/components/schemas/ExploreTaxonomyRequest' - $ref: '#/components/schemas/SearchAudiencesRequest' - $ref: '#/components/schemas/AudienceGenerationRequest' - $ref: '#/components/schemas/GenerateInsightsRequest' - $ref: '#/components/schemas/ExploreInsightRequest' responses: '200': description: > JSON-RPC response. HTTP 200 means the JSON-RPC call was processed, not that the tool succeeded. Inspect `result.isError` if present: - `true` — tool failed; the message is in `result.content[0].text`, and `result._meta.isInternalError` may be `true` for internal or timeout-style failures. See **Tool errors (`result.isError`)** in the overview above for full behavior. content: application/json: schema: $ref: '#/components/schemas/JsonRpcSuccessResponse' examples: list_skills_response: summary: list_skills value: jsonrpc: '2.0' id: 1 result: content: - type: text text: >- {"skills":[{"key":"audience-comparison","description":"Read this skill when the user asks to compare audiences or groups, contrast X vs Y, compare an attached audience, or explain similarities and differences."},{"key":"audience-investigation","description":"Read this skill when the user asks who to target, what audience to target, which audience is most likely to do or buy something, or how to target advertising, sponsorships, campaigns, or sales opportunities."},{"key":"gwi-dictionary","description":"Read this skill when the user asks what a GWI term or metric means, including responses, universe, audience percentage, data point percentage, or index."},{"key":"segment-requests","description":"Read this skill when the user asks for segments, segmentations, available segments, audience groups, market groups, or analysis of segment groups around a topic, location, or category."}]} structuredContent: skills: - key: audience-comparison description: >- Read this skill when the user asks to compare audiences or groups, contrast X vs Y, compare an attached audience, or explain similarities and differences. - key: audience-investigation description: >- Read this skill when the user asks who to target, what audience to target, which audience is most likely to do or buy something, or how to target advertising, sponsorships, campaigns, or sales opportunities. - key: gwi-dictionary description: >- Read this skill when the user asks what a GWI term or metric means, including responses, universe, audience percentage, data point percentage, or index. - key: segment-requests description: >- Read this skill when the user asks for segments, segmentations, available segments, audience groups, market groups, or analysis of segment groups around a topic, location, or category. get_skills_response: summary: get_skills value: jsonrpc: '2.0' id: 2 result: content: - type: text text: >- {"skills":[{"key":"audience-investigation","content":"# Audience Investigation\n\n## Prerequisites\n\n- Call `list_datasets` when the dataset is unclear.\n- Call `global_filters` before audience or insight tools on a new analysis.\n- Create or resolve the audience with `audience_generation` when the user describes a cohort, or `search_audiences` when they name a saved audience.\n- Use one `generate_insights` call with multiple focused prompts in `prompts` when the investigation spans several dimensions. Pass the same `enforced_audiences` from the generated or matched audience on that call.\n- Use `explore_insight` only when the user explicitly asks for more detail on a returned `insights[].id`.\n\n## Instructions\n\nUse this skill when the user asks who they should target, what audience they should target to sell or promote something, or which audience is more likely to do a specific behavior.\n\n1. Always create the target audience first with `audience_generation` (or resolve it with `search_audiences` when the user names a saved audience). The audience should represent the behavior or target group being investigated, such as \"luxury watch buyers\", \"eco-friendly apparel shoppers\", or \"people who buy premium skincare\".\n2. Reuse that audience in `enforced_audiences` for every prompt in the `generate_insights` call. Do not investigate the general population when the user asked for a target audience.\n3. Prefer one `generate_insights` call with multiple focused prompts in `prompts` rather than one broad prompt or several sequential `generate_insights` tool calls. Each prompt should cover one investigation dimension. Use additional `generate_insights` tool calls only when scope differs per call (for example different `wave_codes` for period comparison or different `location_codes` for market comparison).\n4. Useful investigation dimensions include demographics and overindex patterns, behaviors and interests, lifestyle indicators, media consumption, social media usage, purchase drivers, and decision factors.\n5. Focus on what differentiates the audience. Prefer overindex relationships and clear contrasts against the general population when useful.\n\n## Examples\n\n- User asks: \"What audience should I target to sell luxury watches?\"\n- Create audience: \"luxury watch buyers\".\n- Run one `generate_insights` call with separate prompts such as \"demographics and overindex patterns\", \"behaviors and interests\", \"social media usage\", and \"purchase drivers\", all with the same `enforced_audiences`.\n\n- User asks in one turn: \"Do Facebook users use Instagram Reels? What are they buying? Which media do they watch?\"\n- After audience resolution, run one `generate_insights` call with three prompts in `prompts` (one per question) and the same `enforced_audiences`, `location_codes`, and `wave_codes`.\n\n## Rules\n\n- Never collapse an entire multi-dimension investigation into a single prompt when the user asked about distinct topics.\n- Always pass the generated or matched audience in `enforced_audiences` for every prompt in the call.\n- Do not chain several single-prompt `generate_insights` tool calls when one call with multiple prompts shares the same audience, location, and timeframe scope.\n- Keep each prompt narrow and purposeful.\n- If an audience is only a proxy, evaluate whether it captures the same core intent before proceeding."}]} structuredContent: skills: - key: audience-investigation content: > # Audience Investigation ## Prerequisites - Call `list_datasets` when the dataset is unclear. - Call `global_filters` before audience or insight tools on a new analysis. - Create or resolve the audience with `audience_generation` when the user describes a cohort, or `search_audiences` when they name a saved audience. - Use one `generate_insights` call with multiple focused prompts in `prompts` when the investigation spans several dimensions. Pass the same `enforced_audiences` from the generated or matched audience on that call. - Use `explore_insight` only when the user explicitly asks for more detail on a returned `insights[].id`. ## Instructions Use this skill when the user asks who they should target, what audience they should target to sell or promote something, or which audience is more likely to do a specific behavior. 1. Always create the target audience first with `audience_generation` (or resolve it with `search_audiences` when the user names a saved audience). The audience should represent the behavior or target group being investigated, such as "luxury watch buyers", "eco-friendly apparel shoppers", or "people who buy premium skincare". 2. Reuse that audience in `enforced_audiences` for every prompt in the `generate_insights` call. Do not investigate the general population when the user asked for a target audience. 3. Prefer one `generate_insights` call with multiple focused prompts in `prompts` rather than one broad prompt or several sequential `generate_insights` tool calls. Each prompt should cover one investigation dimension. Use additional `generate_insights` tool calls only when scope differs per call (for example different `wave_codes` for period comparison or different `location_codes` for market comparison). 4. Useful investigation dimensions include demographics and overindex patterns, behaviors and interests, lifestyle indicators, media consumption, social media usage, purchase drivers, and decision factors. 5. Focus on what differentiates the audience. Prefer overindex relationships and clear contrasts against the general population when useful. ## Examples - User asks: "What audience should I target to sell luxury watches?" - Create audience: "luxury watch buyers". - Run one `generate_insights` call with separate prompts such as "demographics and overindex patterns", "behaviors and interests", "social media usage", and "purchase drivers", all with the same `enforced_audiences`. - User asks in one turn: "Do Facebook users use Instagram Reels? What are they buying? Which media do they watch?" - After audience resolution, run one `generate_insights` call with three prompts in `prompts` (one per question) and the same `enforced_audiences`, `location_codes`, and `wave_codes`. ## Rules - Never collapse an entire multi-dimension investigation into a single prompt when the user asked about distinct topics. - Always pass the generated or matched audience in `enforced_audiences` for every prompt in the call. - Do not chain several single-prompt `generate_insights` tool calls when one call with multiple prompts shares the same audience, location, and timeframe scope. - Keep each prompt narrow and purposeful. - If an audience is only a proxy, evaluate whether it captures the same core intent before proceeding. get_skills_unknown_key: summary: get_skills (unknown key) value: jsonrpc: '2.0' id: 2 result: isError: true content: - type: text text: unknown skill "missing-skill" explore_datasets_response: summary: explore_datasets (partial success) value: jsonrpc: '2.0' id: 10 result: content: - type: text text: >- {"datasets":[{"code":"ds-core","name":"GWI Core","summary":"Our primary data set on the attitudes and behaviors of digital consumers","url":"https://help.globalwebindex.com/en/collections/11937099-gwi-core"},{"code":"ds-usa","name":"GWI USA","summary_error":"summary unavailable"}]} structuredContent: datasets: - code: ds-core name: GWI Core summary: >- Our primary data set on the attitudes and behaviors of digital consumers url: >- https://help.globalwebindex.com/en/collections/11937099-gwi-core - code: ds-usa name: GWI USA summary_error: summary unavailable explore_taxonomy_response: summary: explore_taxonomy value: jsonrpc: '2.0' id: 11 result: content: - type: text text: >- {"dataset":{"code":"ds-core","name":"GWI Core"},"audiences":[],"questions":[{"label":"Social media behaviors","description":"Which social media behaviors apply to you?"}],"attributes":[{"text":"Uses TikTok daily"}],"message":""} structuredContent: dataset: code: ds-core name: GWI Core audiences: [] questions: - label: Social media behaviors description: Which social media behaviors apply to you? attributes: - text: Uses TikTok daily message: '' global_filters_response: summary: global_filters value: jsonrpc: '2.0' id: 4 result: content: - type: text text: >- {"global_filters":{"location_codes":["s2_44"],"location_names":["UK"],"wave_codes":["q1_2025"],"wave_names":["Q1 2025"]}} structuredContent: global_filters: location_codes: - s2_44 location_names: - UK wave_codes: - q1_2025 wave_names: - Q1 2025 global_filters_partial_access: summary: global_filters (partial access) value: jsonrpc: '2.0' id: 4 result: content: - type: text text: >- {"global_filters":{"inaccessible_location_names":["Albania"],"location_codes":["s2_30"],"location_names":["Greece"],"wave_codes":["q3_2025","q4_2025","q1_2026","q2_2026"],"wave_names":[]}} structuredContent: global_filters: inaccessible_location_names: - Albania location_codes: - s2_30 location_names: - Greece wave_codes: - q3_2025 - q4_2025 - q1_2026 - q2_2026 wave_names: [] audience_generation_response: summary: audience_generation value: jsonrpc: '2.0' id: 5 result: content: - type: text text: >- {"audiences":[{"datasets":["ds-core"],"description":"This audience consists of individuals who are part of Gen Z.","id":"259f6394-436c-4801-b83b-bbc926e8b4b9","name":"Generation: Gen Z"}]} structuredContent: audiences: - datasets: - ds-core description: >- This audience consists of individuals who are part of Gen Z. id: 259f6394-436c-4801-b83b-bbc926e8b4b9 name: 'Generation: Gen Z' audience_generation_all_failed: summary: audience_generation (all failed) value: jsonrpc: '2.0' id: 5 result: content: - type: text text: >- {"audiences":[],"failed_audiences":{"mars explorers":"no relevant attributes found for the terms: mars explorers: audience not found"}} structuredContent: audiences: [] failed_audiences: mars explorers: >- no relevant attributes found for the terms: mars explorers: audience not found generate_insights_response: summary: generate_insights value: jsonrpc: '2.0' id: 7 result: content: - type: text text: >- {"results":[{"prompt":"social media habits","has_more_insights":true,"inaccessible_locations":[],"insights":[{"id":"95c35f2c-9235-4536-ad46-44867a3a5996","text":"9.5% of Gen Z are social media scrollers, making them 100% more likely to do so than the average person.","url":"https://platform.globalwebindex.com/chart-builder/insights-v2/95c35f2c-9235-4536-ad46-44867a3a5996"}],"message":"Based on the prompt social media habits, the Insights tool generated the following insights:","sources":{"audiences":[{"description":"This audience consists of individuals who are part of Gen Z.","id":"259f6394-436c-4801-b83b-bbc926e8b4b9","name":"Generation: Gen Z"}],"datasets":[{"code":"ds-core","name":"GWI Core"}],"locations":[{"code":"s2_44","name":"UK"}],"topics":["social media habits"],"waves":[{"code":"q1_2025","name":"Q1 2025"}]},"state_id":"f08cef8d-1995-4097-9d6e-0d1a5ccddd40"}]} structuredContent: results: - prompt: social media habits has_more_insights: true inaccessible_locations: [] insights: - id: 95c35f2c-9235-4536-ad46-44867a3a5996 text: >- 9.5% of Gen Z are social media scrollers, making them 100% more likely to do so than the average person. url: >- https://platform.globalwebindex.com/chart-builder/insights-v2/95c35f2c-9235-4536-ad46-44867a3a5996 - id: a6b5d9a0-e0d3-486b-ac03-e09ac80e7d09 text: >- 24% of Gen Z use social media to avoid missing out on things, making them 64% more likely to do so than the average person. message: >- Based on the prompt social media habits, the Insights tool generated the following insights: sources: audiences: - description: >- This audience consists of individuals who are part of Gen Z. id: 259f6394-436c-4801-b83b-bbc926e8b4b9 name: 'Generation: Gen Z' datasets: - code: ds-core name: GWI Core locations: - code: s2_44 name: UK topics: - social media habits waves: - code: q1_2025 name: Q1 2025 state_id: f08cef8d-1995-4097-9d6e-0d1a5ccddd40 explore_insight_response: summary: explore_insight value: jsonrpc: '2.0' id: 8 result: content: - type: text text: >- {"id":"95c35f2c-9235-4536-ad46-44867a3a5996","metadata":{"attributes":[{"answer":"I am a social learner.","index":177.89999389648438,"percentage":16.899999618530273,"question":"This data is auto-generated based on responses to a variety of questions from GWI Core","sample":327,"universe_size":1737501},{"answer":"I am a Social TV Viewer.","index":130.5,"percentage":14.600000381469727,"question":"This data is auto-generated based on responses to a variety of questions from GWI Core","sample":287,"universe_size":1504625},{"answer":"I am interested in the data generated from responses to questions about memers in GWI Core.","index":193,"percentage":12.899999618530273,"question":"This data is auto-generated based on responses to a variety of questions from GWI Core","sample":248,"universe_size":1330784},{"answer":"I am a social media scroller.","index":200.39999389648438,"percentage":9.5,"question":"This data is auto-generated based on responses to a variety of questions from GWI Core","sample":185,"universe_size":978191}],"audiences":[{"description":"This audience consists of individuals who are part of Gen Z.","id":"259f6394-436c-4801-b83b-bbc926e8b4b9","title":"Generation: Gen Z"}],"datasets":[{"description":"Our primary data set on the attitudes and behaviors of digital consumers","id":"ds-core","title":"GWI Core","url":"https://help.globalwebindex.com/en/collections/11937099-gwi-core"}],"location_groups":[{"details":{"description":"Europe","locations":[{"id":"s2_44","name":"UK"}]},"group":"Europe"}],"timeframe_groups":[{"details":{"description":"2025 (Q1)","timeframes":[{"id":"q1_2025","name":"Q1 2025"}]},"group":"2025 (Q1)"}]},"text":"9.5% of Gen Z are social media scrollers, making them 100% more likely to do so than the average person.","title":"GWI Insight"} structuredContent: id: 95c35f2c-9235-4536-ad46-44867a3a5996 title: GWI Insight text: >- 9.5% of Gen Z are social media scrollers, making them 100% more likely to do so than the average person. metadata: attributes: - answer: I am a social learner. index: 177.89999389648438 percentage: 16.899999618530273 question: >- This data is auto-generated based on responses to a variety of questions from GWI Core sample: 327 universe_size: 1737501 - answer: I am a Social TV Viewer. index: 130.5 percentage: 14.600000381469727 question: >- This data is auto-generated based on responses to a variety of questions from GWI Core sample: 287 universe_size: 1504625 - answer: >- I am interested in the data generated from responses to questions about memers in GWI Core. index: 193 percentage: 12.899999618530273 question: >- This data is auto-generated based on responses to a variety of questions from GWI Core sample: 248 universe_size: 1330784 - answer: I am a social media scroller. index: 200.39999389648438 percentage: 9.5 question: >- This data is auto-generated based on responses to a variety of questions from GWI Core sample: 185 universe_size: 978191 audiences: - description: >- This audience consists of individuals who are part of Gen Z. id: 259f6394-436c-4801-b83b-bbc926e8b4b9 title: 'Generation: Gen Z' datasets: - description: >- Our primary data set on the attitudes and behaviors of digital consumers id: ds-core title: GWI Core url: >- https://help.globalwebindex.com/en/collections/11937099-gwi-core location_groups: - group: Europe details: description: Europe locations: - id: s2_44 name: UK timeframe_groups: - group: 2025 (Q1) details: description: 2025 (Q1) timeframes: - id: q1_2025 name: Q1 2025 list_datasets_response: summary: list_datasets (truncated tree) value: jsonrpc: '2.0' id: 3 result: content: - type: text text: >- {"datasets":[{"code":"ds-core","name":"GWI Core","description":"Our primary data set on the attitudes and behaviors of digital consumers","type":"dataset","children":[{"id":446,"name":"GWI Syndicated","type":"folder","children":[{"code":"ds-work","name":"GWI Work","description":"Attitudes and behaviors of business professionals in the workplace","type":"dataset"},{"id":435,"name":"GWI Pulse","type":"folder","children":[{"code":"ds-gwi-gwi-jos","name":"July 2026 Pulse Week 1 (USA)","description":"FIFA World Cup 2026, AI Saturation, NBA Finals, AI","type":"dataset"}]}]}]},{"code":"ds-usa","name":"GWI USA","description":"A 360-degree view of today's America","type":"dataset"},{"code":"ds-zqy-gyv","name":"GWI Kids","description":"Our data set on the attitudes and behaviors of kids aged 8-15.","type":"dataset"}]} structuredContent: datasets: - code: ds-core name: GWI Core description: >- Our primary data set on the attitudes and behaviors of digital consumers type: dataset children: - id: 446 name: GWI Syndicated type: folder children: - code: ds-work name: GWI Work description: >- Attitudes and behaviors of business professionals in the workplace type: dataset - id: 435 name: GWI Pulse type: folder children: - code: ds-gwi-gwi-jos name: July 2026 Pulse Week 1 (USA) description: >- FIFA World Cup 2026, AI Saturation, NBA Finals, AI type: dataset - code: ds-usa name: GWI USA description: A 360-degree view of today's America type: dataset - code: ds-zqy-gyv name: GWI Kids description: >- Our data set on the attitudes and behaviors of kids aged 8-15. type: dataset search_audiences_response: summary: search_audiences value: jsonrpc: '2.0' id: 6 result: content: - type: text text: >- {"audiences":[{"datasets":["ds-core"],"description":"","id":"d1125cd5-8384-4368-83a9-db9f9077165b","title":"Gen Z","type":"instant"}]} structuredContent: audiences: - datasets: - ds-core description: '' id: d1125cd5-8384-4368-83a9-db9f9077165b title: Gen Z type: instant tool_error_invalid_arguments: summary: validation error value: jsonrpc: '2.0' id: req-validation-1 result: isError: true content: - type: text text: 'could not validate input: insight ID is required' '401': description: Unauthorized - Invalid or missing bearer token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: ListSkillsRequest: title: list_skills description: > Discover workflow skill keys and short descriptions. Call at the start of each new GWI analysis and when the user shifts to a different workflow type on a follow-up. Match the user request to returned descriptions. Do not invent keys. Full skill bodies are not included — use `get_skills` for matching keys only. Do not mention this tool or skill mechanics in user-facing replies. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: oneOf: - type: string - type: integer example: 1 method: type: string enum: - tools/call params: type: object required: - name properties: name: type: string enum: - list_skills arguments: type: object description: No arguments required. example: jsonrpc: '2.0' id: 1 method: tools/call params: name: list_skills arguments: {} GetSkillsRequest: title: get_skills description: > Retrieve full GWI workflow skill bodies in markdown after `list_skills` when a catalogue description matches the user request. Retrieve only matching keys; skip this tool when none match. Unknown keys and empty `skill_keys` return `result.isError`. Do not mention this tool or skill mechanics in user-facing replies. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: oneOf: - type: string - type: integer example: 2 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - get_skills arguments: type: object required: - skill_keys properties: skill_keys: type: array description: >- Non-empty catalogue keys returned by `list_skills`. Do not invent keys. minItems: 1 items: type: string example: - audience-investigation example: jsonrpc: '2.0' id: 2 method: tools/call params: name: get_skills arguments: skill_keys: - audience-investigation ListDatasetsRequest: title: list_datasets description: > List accessible GWI datasets and valid dataset codes for downstream tools. Returns a hierarchical tree: `type: dataset` and `type: folder` nodes, with nested `children` where present. The live response can be large; examples below are truncated. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: oneOf: - type: string - type: integer example: 3 method: type: string enum: - tools/call params: type: object required: - name properties: name: type: string enum: - list_datasets arguments: type: object description: No arguments required. example: jsonrpc: '2.0' id: 3 method: tools/call params: name: list_datasets arguments: {} ExploreDatasetsRequest: title: explore_datasets description: > Retrieve short or verbose descriptions for 1–5 dataset codes returned by `list_datasets`. Use after `list_datasets` for dataset coverage, Pulse topics, module summaries, or help choosing between datasets. Pure dataset discovery does not require `global_filters`. A successful response can contain `summary_error` for individual datasets whose summary is unavailable; do not invent missing coverage. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: oneOf: - type: string - type: integer example: 10 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - explore_datasets arguments: type: object required: - dataset_codes - length properties: dataset_codes: type: array description: >- Non-empty list of 1–5 dataset codes returned by `list_datasets`. Never invent codes. minItems: 1 maxItems: 5 items: type: string length: type: string description: >- Use `short` for concise candidate context and `verbose` for detailed coverage or topic questions. enum: - short - verbose example: jsonrpc: '2.0' id: 10 method: tools/call params: name: explore_datasets arguments: dataset_codes: - ds-core length: verbose GlobalFiltersRequest: title: global_filters description: > Resolve location and wave filters. Required before audience_generation, search_audiences (when used in the same workflow), and generate_insights. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string example: 4 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - global_filters arguments: type: object required: - prompt properties: prompt: type: string description: > Non-empty. When the user named location and/or timeframe, include only terms needed to extract that scope. When `current_filters` is provided and new scope is requested, state whether to append or overwrite. example: social media habits of Gen Z in the UK in Q1 2025 dataset_codes: type: array description: Optional dataset codes from list_datasets (same tree). items: type: string example: - ds-core current_filters: type: object description: >- Prior successful response only — carry forward resolved names, not codes. properties: location_names: type: array items: type: string example: - UK wave_names: type: array items: type: string example: - Q1 2025 example: jsonrpc: '2.0' id: 4 method: tools/call params: name: global_filters arguments: prompt: social media habits of Gen Z in the UK in Q1 2025 ExploreTaxonomyRequest: title: explore_taxonomy description: > Discover GWI survey questions and attributes relevant to a topic. This is semantic data discovery, not computed insight generation. Call `global_filters` first on every new user message. Keep `prompt` topic-only; pass audience, location, timeframe, and dataset scope through their dedicated arguments. Use returned data points to explain available coverage or refine a later `generate_insights` prompt. Curate relevant results rather than presenting every match. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: oneOf: - type: string - type: integer example: 11 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - explore_taxonomy arguments: type: object required: - prompt properties: prompt: type: string minLength: 1 description: >- Topic or subject to search for. Do not include audiences, locations, or timeframes. dataset_codes: type: array description: >- Optional compatible dataset codes returned by `list_datasets`. items: type: string enforced_audiences: type: array description: >- Optional audience UUIDs returned by `audience_generation` or `search_audiences`. maxItems: 10 items: type: string format: uuid location_codes: type: array description: >- Optional flat location codes already resolved by `global_filters`. items: type: string wave_codes: type: array description: >- Optional flat wave codes already resolved by `global_filters`. items: type: string questions_k: type: integer description: >- Optional number of survey questions to retrieve. Defaults to 5 when omitted or zero; intended range 3–30. attributes_k: type: integer description: >- Optional number of attributes to retrieve. Defaults to 10 when omitted or zero; intended range 5–50. example: jsonrpc: '2.0' id: 11 method: tools/call params: name: explore_taxonomy arguments: prompt: social media usage dataset_codes: - ds-core enforced_audiences: - 550e8400-e29b-41d4-a716-446655440000 location_codes: - s2_1 wave_codes: - q1_2026 SearchAudiencesRequest: title: search_audiences description: > Search saved platform audiences. Pass audiences[].id to generate_insights.enforced_audiences. Response items use `title` (not `name`) for the audience label. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string example: 6 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - search_audiences arguments: type: object required: - query properties: query: type: string description: Required free-text audience search query. example: Gen Z dataset_codes: type: array items: type: string example: - ds-core exclude_audience_ids: type: array items: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ limit: type: integer minimum: 1 maximum: 100 example: 5 example: jsonrpc: '2.0' id: 6 method: tools/call params: name: search_audiences arguments: query: Gen Z limit: 5 AudienceGenerationRequest: title: audience_generation description: | Create platform audiences from natural-language descriptions. Call only after global_filters on the same user message. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string example: 5 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - audience_generation arguments: type: object required: - audiences properties: audiences: type: array description: Required natural-language audience descriptions. minItems: 1 items: type: string example: - Gen Z dataset_codes: type: array items: type: string example: - ds-core location_codes: type: array description: >- Forward non-empty values from global_filters.global_filters.location_codes. items: type: string example: - s2_44 wave_codes: type: array description: >- Forward non-empty values from global_filters.global_filters.wave_codes. items: type: string example: - q1_2025 example: jsonrpc: '2.0' id: 5 method: tools/call params: name: audience_generation arguments: audiences: - Gen Z location_codes: - s2_44 wave_codes: - q1_2025 GenerateInsightsRequest: title: generate_insights description: > Generate structured audience insights. Primary discovery tool on v2beta. Pass `enforced_audiences` with UUIDs from audience_generation or search_audiences. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string example: 7 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - generate_insights arguments: type: object required: - prompts properties: prompts: type: array description: >- Required array of strings. 1–10 short research questions per call. Each element is one topic. minItems: 1 maxItems: 10 items: type: string example: - social media habits - streaming preferences dataset_codes: type: array description: >- Optional. Only when dataset scope was established earlier in the workflow. items: type: string example: - ds-core enforced_audiences: type: array description: | Optional platform audience UUIDs (max 10). Use IDs from audience_generation or search_audiences only. maxItems: 10 items: type: string format: uuid example: - 259f6394-436c-4801-b83b-bbc926e8b4b9 location_codes: type: array description: Forward from global_filters when non-empty. items: type: string example: - s2_44 wave_codes: type: array description: Forward from global_filters when non-empty. items: type: string example: - q1_2025 limit: type: integer description: >- Optional maximum insights to return (1-20). Default 10 when omitted. minimum: 1 maximum: 20 example: 5 example: jsonrpc: '2.0' id: 7 method: tools/call params: name: generate_insights arguments: prompts: - social media habits enforced_audiences: - 259f6394-436c-4801-b83b-bbc926e8b4b9 location_codes: - s2_44 wave_codes: - q1_2025 limit: 5 ExploreInsightRequest: title: explore_insight description: > Deep dive into a specific insight from generate_insights. Returns structured JSON with narrative text, per-answer statistics in `metadata.attributes[]`, and provenance (audiences, datasets, locations, timeframes). Reactive-only on v2beta — call only when the user explicitly requests more detail on a specific `insights[].id`. Do not call automatically after `generate_insights`. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string example: 8 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - explore_insight arguments: type: object required: - insight_id properties: insight_id: type: string description: >- Exact UUID from a prior generate_insights response (insights[].id). pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ example: 95c35f2c-9235-4536-ad46-44867a3a5996 example: jsonrpc: '2.0' id: 8 method: tools/call params: name: explore_insight arguments: insight_id: 95c35f2c-9235-4536-ad46-44867a3a5996 JsonRpcSuccessResponse: type: object description: > JSON-RPC 2.0 success envelope for MCP `tools/call` (no top-level `error` field). When the tool fails, HTTP status is still typically **200** and this object is returned with `result.isError: true`. Use that flag rather than HTTP status alone. required: - jsonrpc - id - result properties: jsonrpc: type: string enum: - '2.0' id: type: string description: Request identifier echoed back result: type: object description: > MCP tool result. Inspect `isError` for tool-level success or failure. **`isError: true`** — the tool failed; `content` usually has one `text` item with a human-readable explanation. Typical causes: - **Invalid arguments** (e.g. empty `prompt`, invalid UUID for `insight_id` where required). - **Downstream errors** (e.g. resource not found, timeout, cancelled request, or generic internal failure). **`_meta.isInternalError`** — when present and `true`, the server classified the failure as internal or timeout-style. Omitted or `false` for most validation and not-found style errors. This is **not** the same as a JSON-RPC protocol error: invalid `method` or malformed requests use the standard JSON-RPC `error` field instead of a tool `result`. required: - content properties: content: type: array items: type: object required: - type - text properties: type: type: string enum: - text text: type: string description: >- Tool response if successful. When `result.isError` is `true`, it is the error message (exact wording may vary; do not rely on it for branching except for documented validation cases). On success, this is typically a JSON-encoded mirror of `structuredContent`. structuredContent: type: object description: >- Typed tool output when the call succeeds. Prefer this over parsing `content[0].text`. The object shape depends on the tool that was called — see the response examples below and the Tools overview. isError: type: boolean description: >- Tool-level failure indicator. `true` means the tool did not return a successful result; read `content[0].text` (when present) for details. Optional `_meta.isInternalError` refines internal failures. _meta: type: object description: Optional MCP result metadata. properties: isInternalError: type: boolean description: >- When `true`, indicates an internal or timeout-style failure path at the server. May be omitted for other error types. ErrorResponse: type: object properties: error: type: string example: unauthorized message: type: string example: Invalid or missing bearer token code: type: integer example: 401 securitySchemes: BearerAuth: type: apiKey in: header name: Authorization description: 'Format: Bearer YOUR_TOKEN' ````