Meikai MCP v2 is the compact MCP profile for ChatGPT and other clients with tool-count limits. It is currently available for early access testing; the URL and tool names are intended to remain stable.
Meikai monitors and optimizes how your brand is represented across ChatGPT, Gemini, Perplexity, Grok, Copilot, and more.
Ask your favorite AI engine to check your share of voice, track which topics drive brand mentions, benchmark your visibility against competitors, analyze citation sources, or get prioritized optimization recommendations for your brand's presence in AI.
Connect Meikai to your AI assistant in a few steps.
Meikai
Meikaihttps://mcp.meikai.ai/v2Verify: ask Claude “List my Meikai brands” or “What is our share of voice over the last 7 days?”
MeikaiOptimize your brand across AI engineshttps://mcp.meikai.ai/v2Verify: ask ChatGPT “Show my brands in Meikai” or “Which URLs are most cited for my brand?”
MeikaiOptimize your brand across AI engineshttps://mcp.meikai.ai/v2Verify: ask Perplexity “List my Meikai brands” or “What is our share of voice over the last 7 days?”
Meikaihttps://mcp.meikai.ai/v2Grok auto-detects OAuth from Meikai’s MCP metadata — you do not need to enter Client ID or token URLs manually.
Verify: ask Grok “List my Meikai brands” or “Which topics drive the most brand mentions?”
Use this for any MCP client that supports OAuth over Streamable HTTP (Gemini CLI, Windsurf, or other IDE integrations).
Example — add to your client's MCP config (same OAuth block as Cursor):
{
"mcpServers": {
"meikai": {
"url": "https://mcp.meikai.ai/v2",
"auth": {
"CLIENT_ID": "mcp",
"scopes": ["openid", "profile", "offline_access", "mcp"]
}
}
}
}
client_id=mcp).Verify: ask your assistant to list your Meikai brands or fetch visibility metrics.
Use these URLs when configuring a custom client:
| Role | URL |
|---|---|
| MCP server | https://mcp.meikai.ai/v2 |
| Documentation | https://mcp.meikai.ai/v2/docs/ |
| OAuth authorize | https://mcp.meikai.ai/oauth/authorize/ |
| OAuth token | https://mcp.meikai.ai/oauth/token/ |
Browse available Meikai MCP tools by product area in the Tools tab. Each tool returns data from your workspace; most are read-only. Your AI client chooses which tools to call based on your question.
Nine MCP tools expose the full Prompt Studio wizard (create personas/topics, generate prompts, publish to monitoring). This is authoring — distinct from Brand Monitor prompt analytics (getPromptList, getPrompts, etc.).
getPromptStudioSession after starting brand analysis or prompt generation.Other Meikai MCP tools available on your account.
Read Ads dashboard summaries, trends, creatives, prompts, topics, and visibility comparisons.
Preview, validate, and apply brand administration changes, including the tag taxonomy and tag assignments. Use mode='preview' before apply.
Read Brand Monitor metadata such as topics, cycles, and prompt personas. For prompt content, responses, and fanouts, use meikai_prompt_analysis_read instead.
Read visibility, competitive, and prompt performance breakdowns. Match the requested metric, result granularity, grouping dimension, and entity coverage to the operation capabilities. Classic visibility uses all analyzed responses in the identical scope as its denominator. When explicit start_date and end_date are known, omit lookback_days. getCompetitiveBreakdown is the canonical single operation when each group must include both the target brand and its top favorite competitor; do not combine getVisibilityBreakdown with an overall getVisibilityRank for that result. For headline visibility metrics, ranks, and share of voice, use meikai_visibility_read instead - including getVisibilityRankByTopic, which ranks brands inside each topic, not the topics themselves.
Read citations, authority KPIs, cited URLs, cited prompts, and citation correlations. For domain-level analysis and top-domain insights, use meikai_domain_insights_read instead.
Preview, validate, and apply competitor create/import changes.
Read competitor-level aggregate metrics across the selected filter scope, topic-by-competitor matrices, presence distributions, and one named competitor's detail. A filter narrows the data; it does not create grouped result rows. For the tracked brand's own headline visibility metrics, use meikai_visibility_read instead. For target-versus-competitor rows grouped by platform, topic, or funnel, use meikai_breakdown_read instead.
Read AI agent conversation history.
Export Brand Monitor and dashboard decks as PDF or PowerPoint. For asynchronous Brand Monitor export jobs use meikai_export_job, and to render a custom SlideDeckSpec use meikai_deck_render.
Build a custom PowerPoint (.pptx) download: read the SlideDeckSpec guide, validate a slide deck spec, or render a deck. For ready-made dashboard decks, use meikai_dashboard_export instead.
Read Meikai MCP guides, API-key and OAuth setup, KPI definitions, and visibility guidance. For recommendation Exposure, Faithful Credit, Causal Impact, scientific evidence, and score limits, use getCoreConceptsDocumentation with arguments.sections=['optimization'].
Read domain analysis and top-domain platform insights. For cited URLs, citation rates, and citation rankings, use meikai_citation_authority_read instead.
Start, poll, and download asynchronous Brand Monitor export jobs. For a one-shot dashboard or Brand Monitor deck export, use meikai_dashboard_export instead.
List companies, brands, users, and the tag taxonomy available to the account.
Read keyword counts, momentum, popular keywords, and trending keywords.
Read Brand Perception topics, summary, radar, trends, competitors, responses, and distribution.
Read prompts, prompt details, response lists/details, brand-monitor prompt lists, and fanouts. For Prompt Studio sessions use meikai_prompt_studio_read, and for topics, cycles, or personas use meikai_brand_monitor_metadata_read.
Read Prompt Studio sessions, history, audits, and generation quota. For prompts already running in Brand Monitor and their responses, use meikai_prompt_analysis_read instead.
Start, refine, generate, and publish Prompt Studio sessions.
Read recommendations, content folders, content pages, and content page detail. To tick recommendation tasks or change a completion date, use meikai_recommendations_write instead.
Preview and apply recommendation progress changes: task statuses and completion dates. Use mode='preview' before apply. To read recommendation plans and their current completion dates, use meikai_recommendations_content_read instead.
Analyze web content, page GEO readiness, and robots policy.
Read Product Tracker shopping metrics, retailer presence, category performance, products, pricing, and comparisons.
Read bot traffic, referral, and real-prompt analytics. For AI-platform prompts and responses rather than site traffic, use meikai_prompt_analysis_read instead.
Preview, validate, and apply user invitations, access changes, and user status changes.
Read AI visibility metrics, average brand position rank, competitive rankings, share of voice/model/platform, and KPI cards. Match the requested metric, result granularity, grouping dimension, and entity coverage to the operation capabilities. When explicit start_date and end_date are known, omit lookback_days. For visibility, competitive, or prompt performance breakdowns, use meikai_breakdown_read instead - except the per-topic competitive leaderboard, getVisibilityRankByTopic, which lives here.
Read portfolio and markets summaries for the current workspace.
Try these once connected (replace with your brand or date range):
| Use case | Example prompt |
|---|---|
| Visibility | What is our share of voice vs competitors over the last 7 days? |
| Citations | Which domains cite us most often in AI answers? |
| Competitors | How does our visibility compare to favorite competitors by topic? |
| Prompts | Which monitored prompts mention our brand least often? |
| Shopping | What is our share of shelf in AI shopping results? |
| Recommendations | What are our highest-priority GEO recommendations? |
| Guides | What are Meikai’s GEO best practices for improving AI visibility? |
| Prompt Studio | List Prompt Studio versions for my brand and show the current session state. |
| Getting oriented | Explain Meikai’s core concepts and main product areas. |
| Issue | What to do |
|---|---|
invalid_request after OAuth redirect |
Confirm that your Meikai account supports the callback URL used by your AI client (Perplexity: www.perplexity.ai/rest/connections/oauth_callback; Grok: grok.com/connectors-oauth-exchange-code). |
| 401 or tools stop working | Reconnect via OAuth and confirm that the MCP server URL is https://mcp.meikai.ai. |
| Connector / Apps option missing | Confirm Team/Enterprise plan; ask workspace admin to allow custom connectors. |
| Claude Client ID field | Optional — leave empty; Meikai defaults to client_id=mcp. |
For connector issues, include your AI client (Claude, ChatGPT, Perplexity, Grok, Cursor, etc.), the MCP server URL you configured, and a screenshot of any error after sign-in.
| Document | Web page | PDF download |
|---|---|---|
| Standard Terms and Conditions | https://www.meikai.ai/terms-and-conditions | |
| Terms of Service | https://www.meikai.ai/terms-of-service | |
| Privacy Policy | https://www.meikai.ai/privacy-policy | |
| Cookie Policy | https://www.meikai.ai/cookie-policy | |
| Subprocessors | https://www.meikai.ai/subprocessors | |
| Security overview | https://www.meikai.ai/security |
Do not link policy HTML pages under /legal/ on the public website (for example /legal/privacy-policy returns 404). HTML pages live at the site root; only PDF downloads use /legal/pdf/.
For additional help, email support@meikai.ai with your client name, MCP server URL, and any error screenshots.
JSON schemas and full tool descriptions for API clients.
Execute tools via POST /v2/tools/<name>/execute/ with a Bearer token,
or browse the tools JSON API.
Read Ads dashboard summaries, trends, creatives, prompts, topics, and visibility comparisons. Set operation to one of: getAdsSummary, getAdsTopAdvertisers, getAdsTrend, getAdsByPrompt, getAdsCreatives, getAdsShareOverTime, getAdsByTopic, getAdsVsVisibility. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getAdsSummary",
"getAdsTopAdvertisers",
"getAdsTrend",
"getAdsByPrompt",
"getAdsCreatives",
"getAdsShareOverTime",
"getAdsByTopic",
"getAdsVsVisibility"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided. Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": [],
"title": "getAdsSummary",
"description": "getAdsSummary: Get summary card metrics for the Ads Analytics dashboard. Returns ads penetration rate, period-over-period change, share of shelf for the monitored brand, total responses with ads, unique ad brands, and total ad cards. Use when users ask about ad presence, ad penetration, or share of shelf in AI responses. If brand_id, start_date, or end_date are not provided, uses defaults from UI context."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided. Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": [],
"title": "getAdsTopAdvertisers",
"description": "getAdsTopAdvertisers: Get the top advertisers (brands) appearing in ads, sorted by frequency. Returns up to 50 brands with ad count, total cards, brand URL, and favicon. Use when users ask who is advertising most in AI responses, or which competitors run ads."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided. Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": [],
"title": "getAdsTrend",
"description": "getAdsTrend: Get daily ad penetration trend for AI responses over the selected date range. Returns a time series with date, responses_with_ads, total_responses, and ads_penetration_pct per day. Use when users ask about ad trends, how ad presence evolved over time, or for charting ad penetration."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided. Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": [],
"title": "getAdsByPrompt",
"description": "getAdsByPrompt: Get the prompts that trigger ads most frequently, up to 50 results. Returns prompt text, topic name, total responses, responses with ads, ads penetration %, brand-in-ads %, and top advertisers per prompt. Use when users want to know which queries trigger ads, or whether their brand appears in ads for specific prompts."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided. Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (alias of ai_platform). Comma-separated platforms supported."
},
"funnel": {
"type": "string",
"description": "Optional funnel filter: awareness, consideration, conversion (comma-separated allowed)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"persona_id": {
"type": "string",
"description": "Optional Prompt Studio persona UUID or comma-separated UUIDs."
},
"iteration_start_date": {
"type": "string",
"description": "Optional topic iteration start date YYYY-MM-DD."
},
"advertiser": {
"type": "string",
"description": "Optional advertiser name filter."
},
"search": {
"type": "string",
"description": "Optional search across creative title/body/advertiser."
},
"page": {
"type": "integer",
"minimum": 1,
"description": "Page number (default 1)."
},
"page_size": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Results per page (default 20, max 100)."
},
"sort_by": {
"type": "string",
"enum": [
"ad_penetration",
"appearances",
"prompt_coverage",
"trend",
"share_of_advertiser",
"share_of_advertiser_rank",
"last_seen_at",
"title",
"advertiser"
],
"description": "Sort field (default ad_penetration)."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (default desc)."
},
"company_id": {
"type": "string",
"description": "Optional company UUID scope when not using brand_id alone."
},
"prompt_id": {
"type": "string",
"description": "Optional prompt UUID or comma-separated UUIDs."
},
"tag_id": {
"type": "string",
"description": "Optional prompt-tag UUID or comma-separated UUIDs."
}
},
"required": [],
"title": "getAdsCreatives",
"description": "getAdsCreatives: Get the aggregated Ad Creative library (same data as the Ad Creative page / the corresponding Meikai service). Returns paginated creatives with stable creative_id, advertiser, title, body, target_url, image_url, platforms, last_seen_at, share_of_advertiser_rank, metrics (ad_penetration, appearances, prompt_coverage, share_of_advertiser, trend), and presence[]. Default sort is ad_penetration descending. For CSV/XLSX download use startAsyncExportJob with export_type=ads_creatives."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided. Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": [],
"title": "getAdsShareOverTime",
"description": "getAdsShareOverTime: Get daily advertiser share of ad cards over time, showing the top 7 advertisers plus 'Others'. Returns a time series with date, brand_name, and cards_count per day, suitable for a stacked area chart. Use when users want to see how ad share evolved over time or compare advertiser dominance."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided. Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": [],
"title": "getAdsByTopic",
"description": "getAdsByTopic: Get ad metrics aggregated by topic/intent, ordered by responses with ads. Returns topic name, total responses, responses with ads, ads penetration %, brand-in-ads %, and top advertisers per topic. Use when users want to know which topics or intents attract the most advertising activity."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided. Ads data is available from 2026-04-09; earlier dates are clamped automatically."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Use getBrandTopics to discover topic IDs."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (optional). Defaults to 'chatgpt'; use 'googleaioverview' for Google AI Overview ads."
}
},
"required": [],
"title": "getAdsVsVisibility",
"description": "getAdsVsVisibility: Compare organic brand visibility against ad coverage in AI responses. Returns aggregate counts split by whether the brand is organically visible or not, each further split by ad presence: visible_with_ads, visible_without_ads, not_visible_with_ads, not_visible_without_ads (plus totals). Use when users want to understand the relationship between their organic presence and competitor ad activity."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Ads summary KPI row."
},
"description": "the corresponding Meikai service"
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAdsSummary output",
"x-meikai-operation": "getAdsSummary"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Top advertisers (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAdsTopAdvertisers output",
"x-meikai-operation": "getAdsTopAdvertisers"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Ads trend series (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAdsTrend output",
"x-meikai-operation": "getAdsTrend"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Ads by prompt (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAdsByPrompt output",
"x-meikai-operation": "getAdsByPrompt"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Aggregated ad creative row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAdsCreatives output",
"x-meikai-operation": "getAdsCreatives"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Ads share over time (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAdsShareOverTime output",
"x-meikai-operation": "getAdsShareOverTime"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Ads by topic (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAdsByTopic output",
"x-meikai-operation": "getAdsByTopic"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Ads vs visibility aggregate (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAdsVsVisibility output",
"x-meikai-operation": "getAdsVsVisibility"
}
]
}Preview, validate, and apply brand administration changes, including the tag taxonomy and tag assignments. Use mode='preview' before apply. Set operation to one of: setBrandAIGuidelines, createBrand, bulkCreateBrands, updateBrandSettings, setBrandStatus, validateCreateBrand, validateBulkCreateBrands, validateUpdateBrandSettings, validateSetBrandStatus, manageTagTaxonomy, manageTagAssignments. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"setBrandAIGuidelines",
"createBrand",
"bulkCreateBrands",
"updateBrandSettings",
"setBrandStatus",
"validateCreateBrand",
"validateBulkCreateBrands",
"validateUpdateBrandSettings",
"validateSetBrandStatus",
"manageTagTaxonomy",
"manageTagAssignments"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if present in context)."
},
"proposed_ai_guidelines": {
"type": "string",
"description": "Proposed brand ai_guidelines content. Use empty string to clear."
},
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
],
"description": "preview validates and returns confirmation_token; apply persists only when confirmation requirements are met."
},
"confirmation_token": {
"type": "string",
"description": "Token returned by preview; required for apply mode."
},
"confirmation_phrase": {
"type": "string",
"description": "Must be exactly CONFIRM_AI_GUIDELINES_UPDATE in apply mode."
}
},
"required": [
"proposed_ai_guidelines"
],
"title": "setBrandAIGuidelines",
"description": "setBrandAIGuidelines: Safely update a brand's AI guidelines using a two-step flow. First call with mode='preview' to validate and receive a confirmation_token. Then call with mode='apply', confirmation_token, and confirmation_phrase='CONFIRM_AI_GUIDELINES_UPDATE' to persist the change. Requires brand_settings permission."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"company_id": {
"type": "string",
"description": "Target company UUID; defaults to the current MCP company context when omitted."
},
"brand": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255
},
"plan": {
"type": "string",
"maxLength": 40,
"description": "A shared catalog code (starter, growth, enterprise) or a company dedicated plan code. A static enum cannot list dedicated codes, which are created per company, so the value is validated server-side against the plans that company may assign."
},
"website": {
"type": "string",
"maxLength": 255
},
"aliases": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Brand aliases; stored and returned as name_variants."
},
"country_iso2": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "Two-letter ISO 3166-1 market code."
},
"language": {
"type": "string",
"maxLength": 5,
"description": "ISO 639-1 language, optionally with region (for example en or en-US)."
},
"tracked_name": {
"type": "string",
"maxLength": 255
},
"tracking_context": {
"type": "string"
},
"excluded_name_variants": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
}
},
"favorite_products": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 5
},
"favorite_attributes": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 5
},
"default_topics": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 12
},
"owned_domains": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"description": "Web domains the brand itself publishes on, beyond 'website'. Hostnames only, optionally with a scheme, path or '*.' prefix: 'voyages.leclerc', 'https://www.example.com/blog', '*.example.com'. Used to classify citations as Owned Media and to scope the OnSite agent's search for existing pages, so a non-domain value is rejected. Never put keywords, search terms, product names or competitor brands here; topics belong in 'default_topics' and competitors are set separately."
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Existing Brand tags, by id, 'Namespace:Value', or bare value when unambiguous. An import never creates a tag: an unknown one rejects its record."
},
"llms": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Models this brand tracks, overriding its plan catalogue. Requires prompts_per_model, and every listed model must be available in the brand's country."
},
"prompts_per_model": {
"type": "integer",
"minimum": 1,
"description": "Prompts each model in llms tracks. Requires llms."
},
"name_variants": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Canonical alias field retained for backward compatibility; prefer aliases."
},
"company_id": {
"type": "string",
"description": "Backward-compatible nested company ID; prefer top-level company_id."
},
"auto_purchase_plan_license": {
"type": "boolean",
"description": "Purchase a missing plan license when permitted."
}
},
"required": [
"name"
],
"additionalProperties": true
},
"user_access_assignments": {
"type": "array",
"description": "Optional home-company user grants applied atomically with brand create/import. Company Admins are always granted OWNER even when omitted. Each entry: {user_id, role} where role is OWNER | EDITOR | VIEWER | MONITOR_ONLY. On bulk import, the same assignments apply to every created brand.",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "Target user UUID in the brand home company."
},
"role": {
"type": "string",
"enum": [
"OWNER",
"EDITOR",
"VIEWER",
"MONITOR_ONLY"
]
}
},
"required": [
"user_id",
"role"
],
"additionalProperties": false
}
}
},
"required": [
"brand"
],
"title": "createBrand",
"description": "createBrand: Create a brand through the existing brand management REST flow with preview/apply confirmation. Plan defaults to starter when omitted. company administrators auto-purchase plan licenses by default (set auto_purchase_plan_license=false to opt out). The typed brand object accepts aliases, favorite products/attributes, default topics, owned domains, and brand/product tracking metadata. Use top-level company_id to target a company; it defaults to the current company context."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"company_id": {
"type": "string",
"description": "Target company UUID; defaults to the current MCP company context when omitted."
},
"auto_purchase_plan_license": {
"type": "boolean",
"description": "Explicitly purchase missing plan licenses so imported brands can be active."
},
"brands": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255
},
"plan": {
"type": "string",
"maxLength": 40,
"description": "A shared catalog code (starter, growth, enterprise) or a company dedicated plan code. A static enum cannot list dedicated codes, which are created per company, so the value is validated server-side against the plans that company may assign."
},
"website": {
"type": "string",
"maxLength": 255
},
"aliases": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Brand aliases; stored and returned as name_variants."
},
"country_iso2": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "Two-letter ISO 3166-1 market code."
},
"language": {
"type": "string",
"maxLength": 5,
"description": "ISO 639-1 language, optionally with region (for example en or en-US)."
},
"tracked_name": {
"type": "string",
"maxLength": 255
},
"tracking_context": {
"type": "string"
},
"excluded_name_variants": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
}
},
"favorite_products": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 5
},
"favorite_attributes": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 5
},
"default_topics": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 12
},
"owned_domains": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"description": "Web domains the brand itself publishes on, beyond 'website'. Hostnames only, optionally with a scheme, path or '*.' prefix: 'voyages.leclerc', 'https://www.example.com/blog', '*.example.com'. Used to classify citations as Owned Media and to scope the OnSite agent's search for existing pages, so a non-domain value is rejected. Never put keywords, search terms, product names or competitor brands here; topics belong in 'default_topics' and competitors are set separately."
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Existing Brand tags, by id, 'Namespace:Value', or bare value when unambiguous. An import never creates a tag: an unknown one rejects its record."
},
"llms": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Models this brand tracks, overriding its plan catalogue. Requires prompts_per_model, and every listed model must be available in the brand's country."
},
"prompts_per_model": {
"type": "integer",
"minimum": 1,
"description": "Prompts each model in llms tracks. Requires llms."
}
},
"required": [
"name"
],
"additionalProperties": true
},
"maxItems": 100
},
"user_access_assignments": {
"type": "array",
"description": "Optional home-company user grants applied atomically with brand create/import. Company Admins are always granted OWNER even when omitted. Each entry: {user_id, role} where role is OWNER | EDITOR | VIEWER | MONITOR_ONLY. On bulk import, the same assignments apply to every created brand.",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "Target user UUID in the brand home company."
},
"role": {
"type": "string",
"enum": [
"OWNER",
"EDITOR",
"VIEWER",
"MONITOR_ONLY"
]
}
},
"required": [
"user_id",
"role"
],
"additionalProperties": false
}
},
"on_invalid_records": {
"type": "string",
"enum": [
"reject",
"skip"
],
"description": "What to do when some records are invalid: 'reject' (the default) imports nothing, 'skip' imports only the records that hold up. Never pick 'skip' on your own."
}
},
"required": [
"brands"
],
"title": "bulkCreateBrands",
"description": "bulkCreateBrands: Bulk create brands through the corresponding Meikai service with preview/apply confirmation. Each brand plan defaults to starter when omitted. Set auto_purchase_plan_license=true only after explicit user approval to buy missing licenses; otherwise over-capacity imports create disabled brands. Brand rows accept aliases (returned as name_variants), country_iso2 for the measurement market, product/perception defaults, owned domains, and brand/product tracking metadata. Do not suffix names with market codes solely to disambiguate market variants; country_iso2 carries that distinction. Every record is validated before anything is created. A rejected record is not an error to retry: details.report lists every invalid record with its index, what identifies it, and what is wrong with it. Report those to the user, then ask which they want -- fix the records and preview again, or import the valid ones with on_invalid_records='skip' and leave the rest out. Do not choose for them, and do not silently drop records."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"brand_id": {
"type": "string",
"description": "Brand UUID; defaults to the current brand context."
},
"settings": {
"type": "object",
"description": "Partial brand settings patch. Send only the fields to change; omitted fields are untouched and every supplied array replaces the stored list, so read the current values with getBrands first when adding to a list. Read-only fields such as favorite_competitors, tags, effective_* and tracking_context_inferred are ignored.",
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"description": "Brand display name."
},
"website": {
"type": "string",
"maxLength": 255,
"description": "Primary brand website; OnSite falls back to it when owned_domains is empty."
},
"country_iso2": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "Two-letter ISO 3166-1 market code. Locked while active prompts are in the current cycle (see getBrands locale_lock_reason)."
},
"language": {
"type": "string",
"maxLength": 5,
"description": "ISO 639-1 language, optionally with region (for example fr or fr-FR). Same lock as country_iso2."
},
"name_variants": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Aliases that count as mentions of this brand in AI responses."
},
"excluded_name_variants": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Phrases that must not count as mentions of this brand."
},
"owned_domains": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"description": "Web domains the brand itself publishes on, beyond 'website'. Hostnames only, optionally with a scheme, path or '*.' prefix: 'voyages.leclerc', 'https://www.example.com/blog', '*.example.com'. Used to classify citations as Owned Media and to scope the OnSite agent's search for existing pages, so a non-domain value is rejected. Never put keywords, search terms, product names or competitor brands here; topics belong in 'default_topics' and competitors are set separately."
},
"tag_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Brand tag UUIDs; replaces all current tags. Prefer manageTagAssignments, which previews the Workspace access impact."
},
"tracked_name": {
"type": [
"string",
"null"
],
"maxLength": 255,
"description": "Exact wording matched in AI responses for this brand (for example 'Lipton' when the display name is 'Lipton (Ice Tea)'). Empty or null uses name."
},
"tracking_context": {
"type": [
"string",
"null"
],
"description": "What this brand covers and who it competes with (for example 'Lipton in the ready-to-drink ice tea space'). Fed verbatim to competitor discovery; when empty, the context inferred by Prompt Studio is used."
},
"favorite_products": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 5,
"description": "Product categories used in Brand Perception prompts; overrides company defaults and generated products. Unique non-empty strings."
},
"favorite_attributes": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 5,
"description": "English canonical attribute names for Brand Perception; overrides company defaults. Unique non-empty strings."
},
"default_topics": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 12,
"description": "Topic cluster names used as Prompt Studio defaults instead of generated topics. Unique non-empty strings."
},
"ai_guidelines": {
"type": "string",
"maxLength": 3000,
"description": "Persistent brand instructions for AI Chat and content-generation agents. Replaces the stored text; an empty string clears it. Prefer setBrandAIGuidelines, which shows the current text and blocks unsafe patterns."
},
"onsite_agent_enabled": {
"type": "boolean",
"description": "OnSite content recommendations. Also requires completed clustering. Enabling requires active prompts whose first one is at least 7 days old and generated prompt embeddings; non-staff users also need the brand agent settings feature."
},
"offsite_agent_enabled": {
"type": "boolean",
"description": "OffSite earned media recommendations. Also requires completed clustering. Enabling requires active prompts whose first one is at least 7 days old and generated prompt embeddings; non-staff users also need the brand agent settings feature."
},
"shared_media_agent_enabled": {
"type": "boolean",
"description": "Shared Media (YouTube, Reddit, ...) recommendations. Enabling requires active prompts whose first one is at least 7 days old and generated prompt embeddings; non-staff users also need the brand agent settings feature."
},
"pdp_agent_enabled": {
"type": "boolean",
"description": "Product detail page recommendations. Enabling requires active prompts whose first one is at least 7 days old and generated prompt embeddings; non-staff users also need the brand agent settings feature."
},
"ads_campaign_planner_enabled": {
"type": "boolean",
"description": "Ads campaign planner tab and generated campaign/ad group/ad recommendations. Non-staff users need the brand agent settings feature."
},
"plan": {
"type": "string",
"maxLength": 40,
"description": "Commercial plan; changes entitlements and may consume a plan license slot. A shared catalog code (starter, growth, enterprise) or a company dedicated plan code, validated server-side against the plans that company may assign. Company admins and brand owners only; legacy assignments cannot change here, and 'custom' is reserved for company administrators and partner provisioning."
},
"llm_config": {
"type": "object",
"additionalProperties": {
"type": "integer"
},
"description": "Per-model prompt limits, for example {\"chatgpt\": 100, \"gemini\": 100}. company administrators and partner provisioning only; every model must be available in the brand's country and within plan caps."
},
"status": {
"type": "string",
"description": "Brand status. Prefer setBrandStatus, which handles bulk changes and activation checks."
}
},
"additionalProperties": true
}
},
"required": [],
"title": "updateBrandSettings",
"description": "updateBrandSettings: Patch brand management settings through the corresponding Meikai service with preview/apply confirmation. Covers identity, market, owned domains, tracked name and tracking context, Brand Perception and Prompt Studio defaults, AI guidelines, agent toggles, and plan. Requires brand_settings permission, or company brand management; tracked_name and tracking_context alone need only Prompt Studio edit. Competitors are managed with createCompetitor/bulkCreateCompetitors."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"brand_ids": {
"type": "array",
"maxItems": 100
},
"status": {
"type": "string"
}
},
"required": [],
"title": "setBrandStatus",
"description": "setBrandStatus: Set one or more brand statuses through the corresponding Meikai service with preview/apply confirmation."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "Target company UUID; defaults to the current MCP company context when omitted."
},
"brand": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255
},
"plan": {
"type": "string",
"maxLength": 40,
"description": "A shared catalog code (starter, growth, enterprise) or a company dedicated plan code. A static enum cannot list dedicated codes, which are created per company, so the value is validated server-side against the plans that company may assign."
},
"website": {
"type": "string",
"maxLength": 255
},
"aliases": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Brand aliases; stored and returned as name_variants."
},
"country_iso2": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "Two-letter ISO 3166-1 market code."
},
"language": {
"type": "string",
"maxLength": 5,
"description": "ISO 639-1 language, optionally with region (for example en or en-US)."
},
"tracked_name": {
"type": "string",
"maxLength": 255
},
"tracking_context": {
"type": "string"
},
"excluded_name_variants": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
}
},
"favorite_products": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 5
},
"favorite_attributes": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 5
},
"default_topics": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 12
},
"owned_domains": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"description": "Web domains the brand itself publishes on, beyond 'website'. Hostnames only, optionally with a scheme, path or '*.' prefix: 'voyages.leclerc', 'https://www.example.com/blog', '*.example.com'. Used to classify citations as Owned Media and to scope the OnSite agent's search for existing pages, so a non-domain value is rejected. Never put keywords, search terms, product names or competitor brands here; topics belong in 'default_topics' and competitors are set separately."
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Existing Brand tags, by id, 'Namespace:Value', or bare value when unambiguous. An import never creates a tag: an unknown one rejects its record."
},
"llms": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Models this brand tracks, overriding its plan catalogue. Requires prompts_per_model, and every listed model must be available in the brand's country."
},
"prompts_per_model": {
"type": "integer",
"minimum": 1,
"description": "Prompts each model in llms tracks. Requires llms."
},
"name_variants": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Canonical alias field retained for backward compatibility; prefer aliases."
},
"company_id": {
"type": "string",
"description": "Backward-compatible nested company ID; prefer top-level company_id."
},
"auto_purchase_plan_license": {
"type": "boolean",
"description": "Purchase a missing plan license when permitted."
}
},
"required": [
"name"
],
"additionalProperties": true
},
"user_access_assignments": {
"type": "array",
"description": "Optional home-company user grants applied atomically with brand create/import. Company Admins are always granted OWNER even when omitted. Each entry: {user_id, role} where role is OWNER | EDITOR | VIEWER | MONITOR_ONLY. On bulk import, the same assignments apply to every created brand.",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "Target user UUID in the brand home company."
},
"role": {
"type": "string",
"enum": [
"OWNER",
"EDITOR",
"VIEWER",
"MONITOR_ONLY"
]
}
},
"required": [
"user_id",
"role"
],
"additionalProperties": false
}
}
},
"required": [
"brand"
],
"title": "validateCreateBrand",
"description": "validateCreateBrand: Validate a typed brand create payload via the corresponding Meikai service without persisting. Accepts aliases, product/perception defaults, tracking metadata, and company context."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "Target company UUID; defaults to the current MCP company context when omitted."
},
"auto_purchase_plan_license": {
"type": "boolean",
"description": "Explicitly purchase missing plan licenses so imported brands can be active."
},
"brands": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255
},
"plan": {
"type": "string",
"maxLength": 40,
"description": "A shared catalog code (starter, growth, enterprise) or a company dedicated plan code. A static enum cannot list dedicated codes, which are created per company, so the value is validated server-side against the plans that company may assign."
},
"website": {
"type": "string",
"maxLength": 255
},
"aliases": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Brand aliases; stored and returned as name_variants."
},
"country_iso2": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "Two-letter ISO 3166-1 market code."
},
"language": {
"type": "string",
"maxLength": 5,
"description": "ISO 639-1 language, optionally with region (for example en or en-US)."
},
"tracked_name": {
"type": "string",
"maxLength": 255
},
"tracking_context": {
"type": "string"
},
"excluded_name_variants": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
}
},
"favorite_products": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 5
},
"favorite_attributes": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 5
},
"default_topics": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"maxItems": 12
},
"owned_domains": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"description": "Web domains the brand itself publishes on, beyond 'website'. Hostnames only, optionally with a scheme, path or '*.' prefix: 'voyages.leclerc', 'https://www.example.com/blog', '*.example.com'. Used to classify citations as Owned Media and to scope the OnSite agent's search for existing pages, so a non-domain value is rejected. Never put keywords, search terms, product names or competitor brands here; topics belong in 'default_topics' and competitors are set separately."
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Existing Brand tags, by id, 'Namespace:Value', or bare value when unambiguous. An import never creates a tag: an unknown one rejects its record."
},
"llms": {
"type": "array",
"items": {
"type": "string",
"maxLength": 255
},
"description": "Models this brand tracks, overriding its plan catalogue. Requires prompts_per_model, and every listed model must be available in the brand's country."
},
"prompts_per_model": {
"type": "integer",
"minimum": 1,
"description": "Prompts each model in llms tracks. Requires llms."
}
},
"required": [
"name"
],
"additionalProperties": true
},
"maxItems": 100
},
"user_access_assignments": {
"type": "array",
"description": "Optional home-company user grants applied atomically with brand create/import. Company Admins are always granted OWNER even when omitted. Each entry: {user_id, role} where role is OWNER | EDITOR | VIEWER | MONITOR_ONLY. On bulk import, the same assignments apply to every created brand.",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "Target user UUID in the brand home company."
},
"role": {
"type": "string",
"enum": [
"OWNER",
"EDITOR",
"VIEWER",
"MONITOR_ONLY"
]
}
},
"required": [
"user_id",
"role"
],
"additionalProperties": false
}
},
"on_invalid_records": {
"type": "string",
"enum": [
"reject",
"skip"
],
"description": "What to do when some records are invalid: 'reject' (the default) imports nothing, 'skip' imports only the records that hold up. Never pick 'skip' on your own."
}
},
"required": [
"brands"
],
"title": "validateBulkCreateBrands",
"description": "validateBulkCreateBrands: Validate bulk brand import via the corresponding Meikai service without persisting. Brand rows accept plan (a shared catalog code such as 'starter', 'growth' or 'enterprise', or a code dedicated to the company), aliases (returned as name_variants), product/perception defaults, owned domains, and brand/product tracking metadata. Same brand names are allowed when country_iso2 differs. Set auto_purchase_plan_license=true only after explicit user approval to buy missing licenses. Every record is validated on its own: a 400 carries details.report with each invalid record. A rejected record is not an error to retry: details.report lists every invalid record with its index, what identifies it, and what is wrong with it. Report those to the user, then ask which they want -- fix the records and preview again, or import the valid ones with on_invalid_records='skip' and leave the rest out. Do not choose for them, and do not silently drop records."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string"
},
"settings": {
"type": "object"
}
},
"required": [
"brand_id",
"settings"
],
"title": "validateUpdateBrandSettings",
"description": "validateUpdateBrandSettings: Validate brand settings patch via the corresponding Meikai service without persisting."
},
{
"type": "object",
"properties": {
"brand_ids": {
"type": "array",
"maxItems": 100
},
"status": {
"type": "string"
}
},
"required": [
"brand_ids",
"status"
],
"title": "validateSetBrandStatus",
"description": "validateSetBrandStatus: Validate bulk brand status change via the corresponding Meikai service without persisting."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"company_id": {
"type": "string",
"format": "uuid",
"description": "Company scope; defaults to the current company context."
},
"target_type": {
"type": "string",
"enum": [
"BRAND",
"PROMPT"
],
"description": "Which objects the namespace tags: BRAND for brand tags, PROMPT for prompt tags. Defaults to PROMPT when omitted."
},
"operation": {
"type": "string",
"enum": [
"create_namespace",
"update_namespace",
"archive_namespace",
"create_tag",
"update_tag",
"archive_tag"
]
},
"namespace_id": {
"type": "string",
"format": "uuid",
"description": "Required for namespace updates/archives and tag creation."
},
"tag_id": {
"type": "string",
"format": "uuid",
"description": "Required for tag updates/archives."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"icon": {
"type": "string",
"maxLength": 64
},
"color": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$"
},
"position": {
"type": "integer",
"minimum": 0
}
},
"required": [
"operation",
"target_type"
],
"additionalProperties": false,
"title": "manageTagTaxonomy",
"description": "manageTagTaxonomy: Create, update, or soft-archive company-owned tag namespaces and values for one target type: pass target_type=BRAND for brand tags or PROMPT for prompt tags (PROMPT when omitted). Use preview first, then apply with the returned confirmation token and phrase. Supported operations are create_namespace, update_namespace, archive_namespace, create_tag, update_tag, and archive_tag. Global taxonomy is discoverable but read-only. Create is retry-safe: an existing active company record with the same normalized name is returned without creating a duplicate. Archiving a namespace also archives its values."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"company_id": {
"type": "string",
"format": "uuid",
"description": "Company scope; defaults to the current company context."
},
"operation": {
"type": "string",
"enum": [
"set_tag_targets",
"set_brand_tags",
"set_prompt_tags"
]
},
"tag_id": {
"type": "string",
"format": "uuid",
"description": "Tag to reassign, for set_tag_targets."
},
"brand_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 200,
"description": "Brands carrying the tag, for set_tag_targets on a Brand tag."
},
"prompt_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 200,
"description": "Prompts carrying the tag, for set_tag_targets on a Prompt tag."
},
"brand_id": {
"type": "string",
"format": "uuid",
"description": "Brand to retag, for set_brand_tags."
},
"prompt_id": {
"type": "string",
"format": "uuid",
"description": "Prompt to retag, for set_prompt_tags."
},
"tag_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 200,
"description": "Tags carried by the object, for set_brand_tags/set_prompt_tags."
},
"access_resolution": {
"type": "object",
"description": "How to settle a workspace access impact: {'mode': 'MASK_INELIGIBLE'} or {'mode': 'GRANT_ACCESS', 'grants': [{'user_id', 'brand_id', 'role'}]} with one grant per reported pair. Re-run preview with it, then apply with the new token."
}
},
"required": [
"operation"
],
"additionalProperties": false,
"title": "manageTagAssignments",
"description": "manageTagAssignments: Replace tag assignments with preview/apply confirmation. set_tag_targets replaces which brands (brand_ids) or prompts (prompt_ids) carry one tag; set_brand_tags replaces the Brand tags of one brand (tag_ids); set_prompt_tags replaces the Prompt tags of one prompt (tag_ids). Every operation replaces, so the list you send becomes the full membership and anything missing from it is unassigned; preview returns the added/removed diff before you commit. Brand tags drive dynamic workspaces: when the change would hide brands from users, preview returns workspace_access_impact with requires_access_resolution=true plus the suggested grants; re-run preview with access_resolution (MASK_INELIGIBLE, or GRANT_ACCESS carrying those grants) and apply with the token that second preview returns, because the token covers that choice. Discover tag UUIDs with getTagTaxonomy."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Updated brand AI guidelines."
}
},
"additionalProperties": false,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "setBrandAIGuidelines output",
"x-meikai-operation": "setBrandAIGuidelines"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand creation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "createBrand output",
"x-meikai-operation": "createBrand"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk brand creation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "bulkCreateBrands output",
"x-meikai-operation": "bulkCreateBrands"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand settings update preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "updateBrandSettings output",
"x-meikai-operation": "updateBrandSettings"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand status update preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "setBrandStatus output",
"x-meikai-operation": "setBrandStatus"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand creation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateCreateBrand output",
"x-meikai-operation": "validateCreateBrand"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk brand creation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateBulkCreateBrands output",
"x-meikai-operation": "validateBulkCreateBrands"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand settings validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateUpdateBrandSettings output",
"x-meikai-operation": "validateUpdateBrandSettings"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Brand status validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateSetBrandStatus output",
"x-meikai-operation": "validateSetBrandStatus"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt tag taxonomy mutation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "manageTagTaxonomy output",
"x-meikai-operation": "manageTagTaxonomy"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Tag assignment change preview (added/removed diff) or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "manageTagAssignments output",
"x-meikai-operation": "manageTagAssignments"
}
]
}Read Brand Monitor metadata such as topics, cycles, and prompt personas. For prompt content, responses, and fanouts, use meikai_prompt_analysis_read instead. Set operation to one of: getBrandTopics, getTopics, getIterationStartDates, getPromptPersonas. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getBrandTopics",
"getTopics",
"getIterationStartDates",
"getPromptPersonas"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"page_size": {
"type": "number",
"description": "Number of topics to return per page. Use large values when user wants 'all' topics or comprehensive data."
},
"page": {
"type": "number",
"description": "Page number for pagination"
}
},
"required": [],
"title": "getBrandTopics",
"description": "getBrandTopics: Get topics for a specific brand. Returns a list of topics associated with the brand. If brand_id is not provided, uses the current brand from UI context."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
}
},
"required": [],
"title": "getTopics",
"description": "getTopics: Get simplified list of topics for a brand in Brand Monitor format (id + text only). Returns only regular topics (excludes evergreen). Different from getBrandTopics which returns more detailed information from the ViewSet."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"classification": {
"type": "string",
"enum": [
"standard",
"evergreen"
],
"description": "Optional dashboard classification. 'standard' = cycles with \u22651 unbranded prompt under a regular topic (Visibility scope). 'evergreen' = cycles with \u22651 branded prompt under an evergreen topic (Perception scope). Omit to return all cycles."
}
},
"required": [],
"title": "getIterationStartDates",
"description": "getIterationStartDates: Get distinct iteration start dates for a brand. Returns dates from Topic model, sorted most recent first. Each result includes the date value (ISO format YYYY-MM-DD) and an index (where 1 is the oldest iteration). Optionally pass classification='standard' to restrict to cycles containing \u22651 unbranded prompt under a regular topic (Visibility dashboard scope), or classification='evergreen' for cycles containing \u22651 branded prompt under an evergreen topic (Perception dashboards scope)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio iteration start date (YYYY-MM-DD). Restricts to personas with prompt assignments in that iteration. Get valid values from getIterationStartDates."
}
},
"required": [],
"title": "getPromptPersonas",
"description": "getPromptPersonas: List Prompt Studio personas available for Brand Monitor filtering. Returns personas that have at least one assigned active regular prompt for the brand. Use the returned id values as persona_id when calling visibility, prompt list, citations, query fanouts, competitor, or export tools."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandTopics output",
"x-meikai-operation": "getBrandTopics"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Topic id and label."
},
"description": "Brand topics list."
}
},
"additionalProperties": false,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getTopics output",
"x-meikai-operation": "getTopics"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "array",
"items": {
"type": "string"
},
"description": "Iteration start dates (YYYY-MM-DD)."
}
},
"additionalProperties": false,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getIterationStartDates output",
"x-meikai-operation": "getIterationStartDates"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"name"
]
},
"description": "Prompt Studio personas available for filtering."
}
},
"additionalProperties": false,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptPersonas output",
"x-meikai-operation": "getPromptPersonas"
}
]
}Read visibility, competitive, and prompt performance breakdowns. Match the requested metric, result granularity, grouping dimension, and entity coverage to the operation capabilities. Classic visibility uses all analyzed responses in the identical scope as its denominator. When explicit start_date and end_date are known, omit lookback_days. getCompetitiveBreakdown is the canonical single operation when each group must include both the target brand and its top favorite competitor; do not combine getVisibilityBreakdown with an overall getVisibilityRank for that result. For headline visibility metrics, ranks, and share of voice, use meikai_visibility_read instead - including getVisibilityRankByTopic, which ranks brands inside each topic, not the topics themselves. Set operation to one of: getVisibilityBreakdown, getCompetitiveBreakdown, getPromptPerformanceBreakdown. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded. Select using these operation capabilities (machine-readable JSON): [{"entity_coverage":"target_brand","evidence_fields":["responses_with_mentions","responses_count","visibility"],"grouping_dimensions":["platform","model","topic","funnel"],"metrics":["visibility_rate","share_of_voice","mentions","analyzed_responses"],"operation":"getVisibilityBreakdown","result_granularity":"dimension_breakdown"},{"entity_coverage":"target_brand_favorites_and_top_competitor_per_group","evidence_fields":["targetResponsesWithMentions","topCompetitorResponsesWithMentions","totalResponses","denominatorScope","targetVisibility"],"grouping_dimensions":["platform","topic","funnel"],"metrics":["visibility_rate","share_of_voice","mentions","visibility_rank"],"operation":"getCompetitiveBreakdown","result_granularity":"dimension_breakdown"},{"entity_coverage":"target_brand_with_optional_top_competitors","evidence_fields":["mentions","citations","share_of_voice"],"grouping_dimensions":["prompt"],"metrics":["share_of_voice","mentions","citations"],"operation":"getPromptPerformanceBreakdown","result_granularity":"dimension_breakdown"}]. Grouping dimensions use these meanings (machine-readable JSON): {"funnel":"journey stage","model":"concrete named model or version within a platform; use only when the request identifies a model/version or explicitly asks for models","platform":"provider or product surface; Meikai grouping for an unqualified LLM or environment","prompt":"individual monitored prompt","topic":"configured semantic topic"}.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getVisibilityBreakdown",
"getCompetitiveBreakdown",
"getPromptPerformanceBreakdown"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID"
},
"start_date": {
"type": "string",
"description": "YYYY-MM-DD"
},
"end_date": {
"type": "string",
"description": "YYYY-MM-DD"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"group_by": {
"type": "string",
"enum": [
"platform",
"funnel",
"topic",
"model"
],
"description": "Single dimension to group by (required)"
},
"topic_id": {
"type": "string"
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
]
},
"platform": {
"type": "string"
},
"model": {
"type": "string"
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"page": {
"type": "number"
},
"page_size": {
"type": "number"
},
"sort_by": {
"type": "string",
"enum": [
"visibility",
"share_of_voice",
"mentions",
"mentions_avg",
"responses_count",
"responses_with_mentions",
"rank",
"key"
]
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
},
"required": [
"group_by"
],
"title": "getVisibilityBreakdown",
"description": "getVisibilityBreakdown: Get visibility, share of voice, mentions, and response counts grouped by one dimension (platform, funnel, topic, or model). V1: exactly one dimension is supported \u2014 arrays are rejected. Ratios are 0-1, not percentages. Default date range: last 7 days. Supports calculation_mode classic (default) or weighted (Statcounter AI outbound-referral share weights). Success: paginated list of breakdown rows (visibility, share_of_voice, mentions, rank, key). Response always includes weightMetadata with calculationMode and unit='ratio_0_1'. In weighted mode weightMetadata also includes referralShareMonth, weightSource, weightMetric, market, weightCoverage, and platformsWithoutWeight. weightCoverage is a ratio between 0 and 1 when coverage can be computed (1.0 = all measured platforms have a weight, 0-1 = partial coverage). weightCoverage may be null when coverage is not computed or not applicable for the current aggregation (e.g. market-share data unavailable for the period). platformsWithoutWeight lists measured platforms using the neutral 1.0 fallback because no referral-share weight was available. Note: platformsWithoutWeight=[] does not imply weightCoverage=1.0 when weightCoverage is null. sort_by: visibility (default), share_of_voice, mentions, mentions_avg, responses_count, responses_with_mentions, rank, key. order: desc (default) or asc. Pagination: page and page_size (max 200). Slide decks: use group_by=topic for 'Top N topics' rankings (one row per topic via label). Do NOT use getPrompts + topicName for topic leaderboards \u2014 multiple prompts share a topic. For prompt-level rankings use getPrompts or getPromptPerformanceBreakdown instead. Filters: brand_id, lookback_days, start_date, end_date, group_by, topic_id, funnel, platform, model, calculation_mode. Error: {success:false,error:string}."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string"
},
"start_date": {
"type": "string"
},
"end_date": {
"type": "string"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"group_by": {
"type": "string",
"enum": [
"topic",
"funnel",
"platform"
],
"description": "Optional single dimension for by_dimension array"
},
"topic_id": {
"type": "string"
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
]
},
"platform": {
"type": "string"
},
"model": {
"type": "string"
},
"competitor_name": {
"type": "string"
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"sort_by": {
"type": "string",
"enum": [
"visibility",
"share_of_voice",
"mentions",
"rank",
"name"
],
"description": "Sort field for competitor list (default: rank)"
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order for competitor list (default: asc)"
},
"dimension_sort_by": {
"type": "string",
"enum": [
"target_visibility",
"target_share_of_voice",
"gap_visibility",
"gap_share_of_voice",
"key"
],
"description": "Sort field for by_dimension rows (default: target_visibility)"
},
"dimension_order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order for by_dimension rows (default: desc)"
},
"page": {
"type": "number"
},
"page_size": {
"type": "number"
}
},
"title": "getCompetitiveBreakdown",
"description": "getCompetitiveBreakdown: Get competitive breakdown: target brand metrics, favorite competitor rows, and optional by_dimension slice (topic, funnel, or platform). Use this operation when the requested result needs the target brand and the top favorite competitor within each requested group. Classic visibility means responses with a brand mention divided by all analyzed responses in the identical selected scope; weighted mode applies the documented platform weights to the numerator and that same all-responses denominator. Default date range: last 7 days. Supports weighted mode (calculation_mode=weighted). Success: targetBrand, competitors[], optional byDimension[]. Response always includes weightMetadata with calculationMode and unit='ratio_0_1'. In weighted mode weightMetadata also includes referralShareMonth, weightSource, weightMetric, market, weightCoverage, and platformsWithoutWeight. weightCoverage is a ratio between 0 and 1 when coverage can be computed (1.0 = all measured platforms have a weight, 0-1 = partial coverage). weightCoverage may be null when coverage is not computed or not applicable for the current aggregation (e.g. market-share data unavailable for the period). platformsWithoutWeight lists measured platforms using the neutral 1.0 fallback because no referral-share weight was available. Note: platformsWithoutWeight=[] does not imply weightCoverage=1.0 when weightCoverage is null. Competitor list sort: sort_by (visibility, share_of_voice, mentions, rank [default], name) and order (asc [default], desc). Dimension slice sort: dimension_sort_by (target_visibility [default], target_share_of_voice, gap_visibility, gap_share_of_voice, key) and dimension_order (desc [default], asc). by_dimension also exposes gapVisibility and gapShareOfVoice (target minus top competitor). Each by_dimension row includes targetResponsesWithMentions, topCompetitorResponsesWithMentions, totalResponses, and denominatorScope ('all_analyzed_responses' in classic mode or 'weighted_all_analyzed_responses' in weighted mode) so visibility can be audited. For identical filters and calculation mode, targetVisibility must equal the target row returned by getVisibilityRank and the corresponding getVisibilityBreakdown visibility value. Choose group_by from the dimension requested in the result: platform groups by provider surface, while the model filter selects a concrete model name and does not create grouped rows. A by_dimension row contains only the top favorite competitor, not a complete competitor ranking. Pagination (page, page_size up to 200) applies to by_dimension rows when group_by is set. Only favorite competitors are included by default; competitor_name can filter to a specific competitor (if not a favorite, a suggestion is returned). Filters: brand_id, lookback_days, start_date, end_date, group_by, calculation_mode, COMPETITORS permission. Error: {success:false,error:string}."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"format": "uuid",
"description": "Brand UUID. Optional when context provides the current brand."
},
"start_date": {
"type": "string"
},
"end_date": {
"type": "string"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string"
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
]
},
"platform": {
"type": "string"
},
"model": {
"type": "string"
},
"persona_id": {
"type": "string",
"description": "Prompt Studio persona UUID (assigned active regular prompts)."
},
"search": {
"type": "string"
},
"include_fanouts": {
"type": "boolean",
"description": "Include fanout aggregates (default false)"
},
"include_competitors": {
"type": "boolean"
},
"sort_by": {
"type": "string",
"enum": [
"last_run_date",
"share_of_voice",
"mentions",
"citations"
],
"description": "Sort field (default: last_run_date). 'visibility' and 'avg_queries_per_response' are not supported in V1."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"type": "number"
},
"page_size": {
"type": "number"
}
},
"title": "getPromptPerformanceBreakdown",
"description": "getPromptPerformanceBreakdown: Get prompt-level performance breakdown (share of voice, mentions, citations). Classic-only in V1 \u2014 weighted metrics are not meaningful at prompt level. Default date range: last 7 days. Success: paginated prompt rows with optional fanout and competitor slices. Optional include_fanouts (default false) adds fanout aggregate fields per prompt (avgQueriesPerResponse, responsesWithWebSearch, fanoutsCount, totalQueries). Fanout fields may be null when no fanout data is available, when fanout data is not joinable for the prompt/date/platform filters, or when the backend did not compute fanouts for that scope. null means not available / not computed, not zero. A numeric 0 means fanout data was computed and the count is zero. Do not treat null fanout values as 0 when aggregating across prompts. Optional include_competitors adds top 3 competitors by mentions. sort_by: last_run_date (default), share_of_voice, mentions, citations. Note: 'visibility' and 'avg_queries_per_response' are not supported sort fields in V1. Filters: brand_id, lookback_days, start_date, end_date, include_fanouts, include_competitors, search, sort_by. Error: {success:false,error:string}."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Visibility breakdown (calculationMode, data rows, pagination, optional weightMetadata). the corresponding Meikai service."
}
},
"additionalProperties": true,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getVisibilityBreakdown output",
"x-meikai-operation": "getVisibilityBreakdown"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"calculationMode": {
"type": "string",
"enum": [
"classic",
"weighted"
]
},
"targetBrand": {
"type": "object",
"additionalProperties": true,
"description": "Target-brand aggregate metrics."
},
"competitors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Favorite-competitor aggregate metrics."
}
},
"byDimension": {
"type": "array",
"items": {
"type": "object",
"properties": {
"dimension": {
"type": "string",
"enum": [
"platform",
"topic",
"funnel"
]
},
"key": {
"type": "string"
},
"label": {
"type": "string"
},
"targetResponsesWithMentions": {
"type": [
"integer",
"number",
"null"
],
"minimum": 0
},
"topCompetitorResponsesWithMentions": {
"type": [
"integer",
"number",
"null"
],
"minimum": 0
},
"totalResponses": {
"type": [
"integer",
"number",
"null"
],
"minimum": 0
},
"denominatorScope": {
"type": "string",
"enum": [
"all_analyzed_responses",
"weighted_all_analyzed_responses"
]
},
"targetVisibility": {
"type": [
"number",
"null"
],
"description": "Target responses with mentions divided by all analyzed responses in this row's scope."
},
"targetShareOfVoice": {
"type": [
"number",
"null"
],
"description": "Target mentions divided by all tracked mentions in this row's scope."
},
"topCompetitor": {
"type": [
"string",
"null"
]
},
"topCompetitorVisibility": {
"type": [
"number",
"null"
],
"description": "Top favorite competitor visibility in the identical row scope."
},
"topCompetitorShareOfVoice": {
"type": [
"number",
"null"
],
"description": "Top favorite competitor share of voice in the identical row scope."
},
"gapVisibility": {
"type": [
"number",
"null"
],
"description": "Target minus top-competitor visibility."
},
"gapShareOfVoice": {
"type": [
"number",
"null"
],
"description": "Target minus top-competitor share of voice."
}
},
"additionalProperties": true,
"required": [
"dimension",
"key",
"label",
"targetResponsesWithMentions",
"topCompetitorResponsesWithMentions",
"totalResponses",
"denominatorScope",
"targetVisibility",
"targetShareOfVoice",
"topCompetitor",
"topCompetitorVisibility",
"topCompetitorShareOfVoice",
"gapVisibility",
"gapShareOfVoice"
]
}
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination for byDimension rows."
},
"weightMetadata": {
"type": "object",
"additionalProperties": true,
"description": "Calculation mode, ratio unit, and optional weighting evidence."
}
},
"additionalProperties": true,
"required": [
"success",
"calculationMode",
"targetBrand",
"competitors",
"byDimension",
"pagination",
"weightMetadata"
],
"description": "Competitive breakdown with auditable numerator and denominator evidence."
}
},
"additionalProperties": true,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCompetitiveBreakdown output",
"x-meikai-operation": "getCompetitiveBreakdown"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Prompt performance breakdown (rows, pagination, optional fanouts). the corresponding Meikai service."
}
},
"additionalProperties": true,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptPerformanceBreakdown output",
"x-meikai-operation": "getPromptPerformanceBreakdown"
}
]
}Read citations, authority KPIs, cited URLs, cited prompts, and citation correlations. For domain-level analysis and top-domain insights, use meikai_domain_insights_read instead. Set operation to one of: getCitations, getCitationRate, getCitationRank, getCitationMediaType, getCitationByPlatform, getMostCitedUrls, getHighlyCitedPrompts, getLowlyCitedPrompts, getAuthorityCorrelationData, getPromptsByCitation. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getCitations",
"getCitationRate",
"getCitationRank",
"getCitationMediaType",
"getCitationByPlatform",
"getMostCitedUrls",
"getHighlyCitedPrompts",
"getLowlyCitedPrompts",
"getAuthorityCorrelationData",
"getPromptsByCitation"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). PREFERRED over search when filtering by topic - use this when you have topic_id from getBrandTopics or user message."
},
"prompt_id": {
"type": "string",
"description": "Filter by prompt ID(s). Can be a single UUID or comma-separated list of UUIDs. Use this to get citations for specific prompts (e.g., prompts in a cluster)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID (restricts to that persona's assigned active regular prompts)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"platforms": {
"type": "string",
"description": "Filter by multiple AI platforms in one query (comma-separated, e.g. 'chatgpt,gemini,google-ai-mode'). Prefer over repeated single-platform calls."
},
"per_platform_url_cap": {
"type": "integer",
"description": "With multi-platform platforms filter, keep only the top N citation URLs per platform before merging across platforms. Used by OffSite earned-media analysis to preserve legacy per-platform top-N semantics in one query."
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"media_type": {
"type": "string",
"enum": [
"Reference & Informational",
"Public & Institutional",
"Competitor",
"Earned Media",
"Commercial Media",
"Owned Media",
"Shared Media"
],
"description": "Filter by media type. Valid values: 'Reference & Informational' (reference sites, informational content), 'Public & Institutional' (public institutions, government sites), 'Competitor' (competitor websites), 'Earned Media' (unpaid media coverage like press mentions, reviews, articles), 'Commercial Media' (commercial/advertising media), 'Owned Media' (content you own/control like your website, blog), 'Shared Media' (shared/social platforms)"
},
"is_mentioning_brand": {
"type": "string",
"enum": [
"true",
"false",
"unknown"
],
"description": "Filter citations by whether the URL mentions the brand. 'true' = only URLs that mention the brand; 'false' = only URLs that do not mention the brand; 'unknown' = only URLs where brand mention status is unknown. Omit to return all citations."
},
"favorite_competitor_mentioned_not_brand": {
"type": "string",
"enum": [
"true",
"false"
],
"description": "Filter by competitor-only: 'true' = only URLs where a favorite competitor is mentioned in scraped content but the brand is not; 'false' = only URLs that do not match that. Response fields isMentioningAnyFavoriteCompetitor and isFavoriteCompetitorMentionedNotBrand may be null until backend data is available."
},
"exclude_domains": {
"type": "string",
"description": "Exclude citations from these domains. Comma-separated list of domain names (e.g. 'example.com, foo.org'). Case-insensitive."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
},
"domain": {
"type": "string",
"description": "Filter URL rows to a specific domain (case-insensitive, supports apex/subdomain matching in backend)."
},
"view": {
"type": "string",
"enum": [
"urls",
"domains"
],
"description": "Result mode: 'urls' (default) for URL-level rows, or 'domains' for grouped domain rows."
},
"search": {
"type": "string",
"description": "Search query for URL or title text. Use ONLY when you don't have topic_id or prompt_id filters available. Prefer ID-based filters (topic_id, prompt_id) over search when possible."
},
"include_total": {
"type": "boolean",
"description": "When true (default in backend), include totalCount in pagination metadata."
},
"count_only": {
"type": "boolean",
"description": "When true, only returns pagination totals (no data rows). Useful to fetch counts quickly."
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of citations per page. Maximum allowed is 200 to prevent token limit issues. Use values up to 200 when user wants comprehensive data, 'all' results, or analysis of top/most items. Default is 50."
},
"sort_by": {
"type": "string",
"enum": [
"url",
"domain",
"mediaType",
"title",
"citationsCount",
"domainCitationCount",
"domainUrlCount",
"isMentioningBrand",
"isFavoriteCompetitorMentionedNotBrand",
"domainBrandMentions",
"domainCompetitorOnlyMentions",
"domainCompetitorOnlyPresence",
"shareOfCitation",
"shareOfCitationDomain",
"promptsImpactedByUrl",
"promptsImpactedByDomain",
"lastSeenAt",
"firstSeenAt"
],
"description": "Field to sort by. ALWAYS use appropriate sorting based on query intent: 'citationsCount' for most/least cited (with order='desc' for most, order='asc' for least), 'domainBrandMentions' for most/least URLs mentioning brand per domain (with order='desc' for most, order='asc' for least), 'shareOfCitation' for highest/lowest share (with order='desc' for highest, order='asc' for lowest), 'lastSeenAt' for recent/oldest (with order='desc' for recent, order='asc' for oldest), 'firstSeenAt' for earliest/latest first appearance (with order='asc' for earliest, order='desc' for latest), 'isFavoriteCompetitorMentionedNotBrand' for competitor-only flag, 'url' or 'domain' for alphabetical (with order='asc'). NEVER rely on defaults - always specify sort_by and order. Valid values: url, domain, mediaType, title, citationsCount, domainCitationCount, isMentioningBrand, isFavoriteCompetitorMentionedNotBrand, domainBrandMentions, shareOfCitation, shareOfCitationDomain, promptsImpactedByUrl, promptsImpactedByDomain, lastSeenAt, firstSeenAt"
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' for ascending or 'desc' for descending. ALWAYS specify: Use 'desc' for top/most/highest/recent, 'asc' for least/lowest/oldest/alphabetical. Must ALWAYS be provided when sort_by is used - never rely on defaults."
},
"include_prompt_ids": {
"type": "boolean",
"description": "When true and prompt_id is set, response includes promptIds (array of prompt UUIDs) per citation row for client-side batching (e.g. split citations by cluster)."
}
},
"required": [],
"title": "getCitations",
"description": "getCitations: Get citations with filters, pagination, and sorting. Returns stored Meikai citation metrics; it does not fetch or return live page content. Brand-mention fields may use stored scraped signals when available. CRITICAL: ALWAYS prefer using topic_id or prompt_id filter over search when you have topic_id or prompt_id (from getBrandTopics, getPrompts, or user message). Use search ONLY when filtering by URL/title text and you don't have a specific topic_id or prompt_id. Supports filtering by topic_id (PREFERRED), prompt_id (single UUID or comma-separated list for multiple prompts), media_type (Reference & Informational, Public & Institutional, Competitor, Earned Media, Commercial Media, Owned Media, Shared Media), funnel (awareness, consideration, conversion), platform, model, is_mentioning_brand ('true', 'false', or 'unknown' to filter by whether the citation URL mentions the brand), favorite_competitor_mentioned_not_brand ('true' or 'false' to filter URLs where a favorite competitor is mentioned but not the brand; may be null in response until data is available), exclude_domains (comma-separated domains to exclude), and search (use only when topic_id/prompt_id filters are not available). IMPORTANT: page_size has a 200-row PER-PAGE maximum to protect the model context; it is not a total or per-domain cap. For 'all' or comprehensive analysis, inspect pagination.coverageStatus and retrieve every page until the full filtered set has been analyzed. NEVER claim full-set coverage when pagination.isFullSet is false or coverageStatus is unknown. ALWAYS use appropriate sorting: sort_by='citationsCount' with order='desc' for most cited, sort_by='domainBrandMentions' with order='desc' for domains with most URLs mentioning brand, sort_by='shareOfCitation' with order='desc' for highest share, sort_by='lastSeenAt' with order='desc' for recent, sort_by='url' with order='asc' for alphabetical. Never rely on default sorting - always specify sort_by and order based on the query intent. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days). Every URL row carries scrapeStatus, which explains why the page text was or was not available to the brand-mention check: 'scraped' (page read), 'title_or_url_match' (brand found in the title or URL, no page needed), 'pending' (queued at the scraper), 'fetch_failed', 'retry_exhausted', 'unsupported' (PDF, or a host that blocks the scraper), or 'not_selected' (no attempt on record yet). Use it to explain an Unknown brand mention rather than reporting it as an absence of mention. It is null on rows stored before the field existed and on domain rows, which aggregate many pages."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
}
},
"required": [],
"title": "getCitationRate",
"description": "getCitationRate: Get the citation rate metric for the company (publisher). Citation rate = company_domain_citations / total_earned_media_citations (Earned Media only). Returns value (0-1), previous_value, change, total_citations, previous_total_citations, total_opportunities. Use when user asks about citation rate, share of citations, or authority metrics."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"page": {
"type": "integer",
"description": "Page number (default 1)"
},
"page_size": {
"type": "integer",
"description": "Items per page (default 20, max 200)"
}
},
"required": [],
"title": "getCitationRank",
"description": "getCitationRank: Get a ranked list of domains by citation rate (Earned Media). Returns paginated data with rank, domain, citation_rate, total_citations, trend. Use for domain ranking or citation leaderboard."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
}
},
"required": [],
"title": "getCitationMediaType",
"description": "getCitationMediaType: Get distribution of citations by media type (percentages). Use for citation source breakdown."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
}
},
"required": [],
"title": "getCitationByPlatform",
"description": "getCitationByPlatform: Get citation statistics by AI platform (Earned Media). Citation rate per platform = company domain citations / total Earned Media citations for that platform."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
}
},
"required": [],
"title": "getMostCitedUrls",
"description": "getMostCitedUrls: Get the most cited URLs for the company's domain (Earned Media). Returns URLs that received the most citations within the period (top 20)."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
}
},
"required": [],
"title": "getHighlyCitedPrompts",
"description": "getHighlyCitedPrompts: Get prompts where the publisher has higher share of citations (Earned Media). Returns prompt_id, citations, total_citations, citation_rate, domain_urls (top 20)."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
}
},
"required": [],
"title": "getLowlyCitedPrompts",
"description": "getLowlyCitedPrompts: Get prompts where the publisher has lower share of citations (Earned Media). Returns prompt_id, citations, citation_rate (top 20)."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"description": "The UUID of the company (optional, defaults to context company_id; required for publisher context)"
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand to scope to (optional; if provided with company_id, filters to that brand)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., chatgpt, gemini, perplexity, googleaioverview)"
},
"model": {
"type": "string",
"description": "Filter by AI model name"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
}
},
"required": [],
"title": "getAuthorityCorrelationData",
"description": "getAuthorityCorrelationData: Get daily correlation between visibility and citation rate (Earned Media). Returns date, visibility, citation_rate per day for charts."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"url": {
"type": "string",
"description": "Citation URL to match (UTM/tracking params are stripped before lookup)."
},
"domain": {
"type": "string",
"description": "Citation domain to match (alternative to url)."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID filter."
},
"prompt_id": {
"type": "string",
"description": "Optional prompt UUID filter (comma-separated list supported)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel stage filter."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional AI model filter."
},
"page": {
"type": "number",
"description": "Page number for pagination (default 1)."
},
"page_size": {
"type": "number",
"description": "Prompts per page (default 50, max 200)."
}
},
"required": [],
"title": "getPromptsByCitation",
"description": "getPromptsByCitation: List prompts whose AI responses cited a specific citation URL or domain. UTM and other tracking query parameters are stripped from the URL before matching, so https://example.com/page?utm_source=chatgpt.com matches https://example.com/page. Provide either url or domain (url preferred when both are known). Returns promptId, promptText, citationsCount, firstSeenAt, lastSeenAt, topic metadata. Use when the user asks which prompts generated or linked to a citation URL. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCitations output",
"x-meikai-operation": "getCitations"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Citation rate KPI row."
},
"description": "Citation rate card (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCitationRate output",
"x-meikai-operation": "getCitationRate"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCitationRank output",
"x-meikai-operation": "getCitationRank"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Citation media-type breakdown (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCitationMediaType output",
"x-meikai-operation": "getCitationMediaType"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Citations by platform (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCitationByPlatform output",
"x-meikai-operation": "getCitationByPlatform"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Top cited URLs (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getMostCitedUrls output",
"x-meikai-operation": "getMostCitedUrls"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Highly cited prompts (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getHighlyCitedPrompts output",
"x-meikai-operation": "getHighlyCitedPrompts"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Lowly cited prompts (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getLowlyCitedPrompts output",
"x-meikai-operation": "getLowlyCitedPrompts"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Authority correlation series (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAuthorityCorrelationData output",
"x-meikai-operation": "getAuthorityCorrelationData"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptsByCitation output",
"x-meikai-operation": "getPromptsByCitation"
}
]
}Preview, validate, and apply competitor create/import changes. Set operation to one of: createCompetitor, bulkCreateCompetitors, validateCreateCompetitor, validateBulkCreateCompetitors. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"createCompetitor",
"bulkCreateCompetitors",
"validateCreateCompetitor",
"validateBulkCreateCompetitors"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"competitor": {
"type": "object"
}
},
"required": [],
"title": "createCompetitor",
"description": "createCompetitor: Create or update one competitor through the corresponding Meikai service with preview/apply confirmation."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"brand_id": {
"type": "string"
},
"competitors": {
"type": "array",
"maxItems": 100
},
"on_invalid_records": {
"type": "string",
"enum": [
"reject",
"skip"
],
"description": "What to do when some records are invalid: 'reject' (the default) imports nothing, 'skip' imports only the records that hold up. Never pick 'skip' on your own."
}
},
"required": [],
"title": "bulkCreateCompetitors",
"description": "bulkCreateCompetitors: Bulk create or update competitors through the corresponding Meikai service with preview/apply confirmation. Every record is validated before anything is written. A rejected record is not an error to retry: details.report lists every invalid record with its index, what identifies it, and what is wrong with it. Report those to the user, then ask which they want -- fix the records and preview again, or import the valid ones with on_invalid_records='skip' and leave the rest out. Do not choose for them, and do not silently drop records."
},
{
"type": "object",
"properties": {
"competitor": {
"type": "object"
}
},
"required": [
"competitor"
],
"title": "validateCreateCompetitor",
"description": "validateCreateCompetitor: Validate competitor create payload via the corresponding Meikai service without persisting."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string"
},
"competitors": {
"type": "array",
"maxItems": 100
},
"on_invalid_records": {
"type": "string",
"enum": [
"reject",
"skip"
],
"description": "What to do when some records are invalid: 'reject' (the default) imports nothing, 'skip' imports only the records that hold up. Never pick 'skip' on your own."
}
},
"required": [
"brand_id",
"competitors"
],
"title": "validateBulkCreateCompetitors",
"description": "validateBulkCreateCompetitors: Validate bulk competitor import via the corresponding Meikai service without persisting. Every record is validated on its own: a 400 carries details.report with each invalid record. A rejected record is not an error to retry: details.report lists every invalid record with its index, what identifies it, and what is wrong with it. Report those to the user, then ask which they want -- fix the records and preview again, or import the valid ones with on_invalid_records='skip' and leave the rest out. Do not choose for them, and do not silently drop records."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Competitor creation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "createCompetitor output",
"x-meikai-operation": "createCompetitor"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk competitor creation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "bulkCreateCompetitors output",
"x-meikai-operation": "bulkCreateCompetitors"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Competitor creation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateCreateCompetitor output",
"x-meikai-operation": "validateCreateCompetitor"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk competitor creation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateBulkCreateCompetitors output",
"x-meikai-operation": "validateBulkCreateCompetitors"
}
]
}Read competitor-level aggregate metrics across the selected filter scope, topic-by-competitor matrices, presence distributions, and one named competitor's detail. A filter narrows the data; it does not create grouped result rows. For the tracked brand's own headline visibility metrics, use meikai_visibility_read instead. For target-versus-competitor rows grouped by platform, topic, or funnel, use meikai_breakdown_read instead. Set operation to one of: getCompetitorMetrics, getCompetitorsTopicsMatrix, getCompetitorsPresenceDistribution, getCompetitorDetail. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded. Select using these operation capabilities (machine-readable JSON): [{"entity_coverage":"target_brand_and_favorite_competitors","evidence_fields":["visibility","mentions","share_of_voice","brand_position"],"grouping_dimensions":[],"metrics":["visibility_rate","share_of_voice","mentions","average_brand_position"],"operation":"getCompetitorMetrics","result_granularity":"entity_leaderboard"},{"entity_coverage":"target_brand_and_favorite_or_all_observed_competitors","evidence_fields":["topic","competitor","visibility"],"grouping_dimensions":["topic","competitor"],"metrics":["visibility_rate"],"operation":"getCompetitorsTopicsMatrix","result_granularity":"entity_dimension_matrix"},{"entity_coverage":"target_brand_and_favorite_competitors","evidence_fields":["brandOnly","shared","competitorOnly"],"grouping_dimensions":["presence_category"],"metrics":["response_presence_distribution"],"operation":"getCompetitorsPresenceDistribution","result_granularity":"dimension_breakdown"},{"entity_coverage":"one_named_competitor_against_target_brand","evidence_fields":["topics","domains","prompts"],"grouping_dimensions":[],"metrics":["visibility_rate","share_of_voice","mentions","average_brand_position","citation_advantage"],"operation":"getCompetitorDetail","result_granularity":"entity_detail"}]. Grouping dimensions use these meanings (machine-readable JSON): {"competitor":"tracked or observed competitor entity","presence_category":"exclusive, shared, or competitor-only response presence","topic":"configured semantic topic"}.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getCompetitorMetrics",
"getCompetitorsTopicsMatrix",
"getCompetitorsPresenceDistribution",
"getCompetitorDetail"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"competitor_name": {
"type": "string",
"description": "Optional exact competitor name to compare. If this competitor is not in the brand's favorite competitors, the response will include a suggestion to add it as a favorite first."
}
},
"required": [],
"title": "getCompetitorMetrics",
"description": "getCompetitorMetrics: Get comparative metrics with favorite competitors (visibility, mentions, share of voice, and average Brand Position). Brand Position is the average response-level first-mention rank; lower is better. Returns one aggregate entity row for the tracked brand and each favorite competitor over the entire filtered scope. Topic, funnel, platform, and model parameters only filter that scope; they never create one result row per dimension value. Use getCompetitiveBreakdown with group_by when the requested result is grouped by platform, topic, or funnel. When competitor_name is provided and it is not a favorite competitor, the response includes a suggestion to add it as favorite first."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"competitor_scope": {
"type": "string",
"enum": [
"favorites",
"all"
],
"description": "Competitor set. Defaults to configured favorite competitors."
},
"page": {
"type": "integer",
"minimum": 1,
"description": "One-based competitor-column page for competitor_scope=all."
},
"page_size": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"description": "Competitors per page for competitor_scope=all (maximum 50)."
}
},
"required": [],
"title": "getCompetitorsTopicsMatrix",
"description": "getCompetitorsTopicsMatrix: Get visibility scores matrix for topics \u00d7 competitors showing a heatmap of visibility scores for each topic \u00d7 competitor combination. Returns visibility scores (percentage) for your brand and favorite competitors by default; set competitor_scope=all to retrieve every observed, non-ignored competitor in paginated columns. Use this when users ask about 'competitors matrix', 'topics matrix', 'visibility by topic and competitor', or want to see a comprehensive comparison of visibility across topics and competitors. The matrix shows which topics each competitor dominates and where your brand has opportunities. Supports filtering by topic_id (from getBrandTopics), funnel (awareness, consideration, conversion), platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
}
},
"required": [],
"title": "getCompetitorsPresenceDistribution",
"description": "getCompetitorsPresenceDistribution: Get competitive presence distribution showing how responses are distributed across three categories for each brand (your brand and favorite competitors): 'brandOnly' (brand present, no competitors present), 'shared' (brand + \u22651 competitor present), and 'competitorOnly' (\u22651 competitor present, brand absent). This helps understand competitive positioning - high 'brandOnly' means your brand dominates those responses, high 'shared' means competitive overlap, high 'competitorOnly' means missed opportunities. Use this when users ask about 'presence distribution', 'competitive presence', 'where do competitors appear', or want to understand competitive overlap. Supports filtering by topic_id (from getBrandTopics), funnel (awareness, consideration, conversion), platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"competitor_name": {
"type": "string",
"description": "Exact competitor name to inspect (required)."
}
},
"required": [
"competitor_name"
],
"title": "getCompetitorDetail",
"description": "getCompetitorDetail: Get the aggregated Competitor Detail for a single competitor: compact snapshot (visibility, share of voice, average mentions, rank), the topics where the competitor outperforms the current brand (biggest visibility advantages), the domains where the competitor appears in more prompts than the current brand (citation advantage), and the prompts where the competitor performs best. Requires competitor_name and a single brand_id. Use this when a user wants to understand why a specific competitor is performing well."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Competitor metric row with optional assistant_suggestion."
}
}
},
"additionalProperties": true,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCompetitorMetrics output",
"x-meikai-operation": "getCompetitorMetrics"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Topics x competitors matrix for favorite competitors."
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Topics x competitors matrix page."
},
"competitorScope": {
"type": "string",
"const": "all"
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Competitor-column pagination metadata."
}
},
"additionalProperties": true,
"required": [
"data",
"competitorScope",
"pagination"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCompetitorsTopicsMatrix output",
"x-meikai-operation": "getCompetitorsTopicsMatrix"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Competitive presence distribution (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCompetitorsPresenceDistribution output",
"x-meikai-operation": "getCompetitorsPresenceDistribution"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Aggregated competitor detail (competitor, currentBrand, snapshot, topicAdvantages, citationAdvantages, topProducts, topPrompts). the corresponding Meikai service."
}
},
"additionalProperties": true,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCompetitorDetail output",
"x-meikai-operation": "getCompetitorDetail"
}
]
}Read AI agent conversation history. Set operation to one of: getAgentConversations. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getAgentConversations"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"conversation_id": {
"type": "string",
"description": "If provided, returns details of a specific conversation. If not provided, returns list of conversations."
},
"brand_id": {
"type": "string",
"description": "Filter conversations by brand (optional)"
},
"workspace_id": {
"type": "string",
"description": "Filter conversations by workspace (optional, defaults to active workspace context)"
},
"archived": {
"type": "boolean",
"description": "Filter by archived status (optional, true/false)"
},
"search": {
"type": "string",
"description": "Search conversations by title (case-insensitive partial match, optional)"
},
"page": {
"type": "number",
"description": "Page number for pagination (for list, optional, default: 1)"
},
"page_size": {
"type": "number",
"description": "Number of conversations per page (optional, default: 10, max: 20)"
},
"limit_messages": {
"type": "number",
"description": "Maximum number of messages to return in conversation details (optional, default: 50, max: 100)"
}
},
"required": [],
"title": "getAgentConversations",
"description": "getAgentConversations: Get conversation history with the AI agent. Can list conversations or get details of a specific conversation. Supports filtering by brand or workspace, archived status, and search by title. Returns maximum 20 conversations per page and maximum 100 messages per conversation to prevent token limit issues."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {},
"additionalProperties": true,
"description": "Conversation list, detail, or messages payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAgentConversations output",
"x-meikai-operation": "getAgentConversations"
}
]
}Export Brand Monitor and dashboard decks as PDF or PowerPoint. For asynchronous Brand Monitor export jobs use meikai_export_job, and to render a custom SlideDeckSpec use meikai_deck_render. Set operation to one of: exportBrandMonitorPdf, exportBrandMonitorPpt, exportAudienceDashboardDeck, exportBrandPerceptionDashboardDeck, exportCompetitorsDashboardDeck, exportAdsDashboardDeck, exportShoppingDashboardDeck, exportPortfolioDashboardDeck. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"exportBrandMonitorPdf",
"exportBrandMonitorPpt",
"exportAudienceDashboardDeck",
"exportBrandPerceptionDashboardDeck",
"exportCompetitorsDashboardDeck",
"exportAdsDashboardDeck",
"exportShoppingDashboardDeck",
"exportPortfolioDashboardDeck"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending on `reference_end_date` when available, otherwise on the server's last complete day (yesterday). When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
}
},
"title": "exportBrandMonitorPdf",
"description": "exportBrandMonitorPdf: Generate the standard Brand Monitor visibility PDF report for the selected brand and date range. Returns pdfUrl (temporary download, 7 days). Use when the user asks for a Brand Monitor PDF export or report download in chat. Prefer this over startAsyncExportJob when the user wants an immediate download link."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending on `reference_end_date` when available, otherwise on the server's last complete day (yesterday). When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
}
},
"title": "exportBrandMonitorPpt",
"description": "exportBrandMonitorPpt: Generate the standard Brand Monitor visibility PowerPoint report for the selected brand and date range. Returns pptxUrl (temporary download, 7 days) and warnings. Use when the user asks for a Brand Monitor PPT/PowerPoint export in chat."
},
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_month": {
"type": "string",
"description": "Start month YYYY-MM (required)."
},
"end_month": {
"type": "string",
"description": "End month YYYY-MM (defaults to start_month)."
},
"gender": {
"type": "string",
"description": "Optional audience filter."
},
"age_band": {
"type": "string",
"description": "Optional audience filter."
},
"language": {
"type": "string",
"description": "Optional audience filter."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"country_code": {
"type": "string",
"description": "Optional audience filter."
},
"household_income": {
"type": "string",
"description": "Optional audience filter."
}
},
"required": [
"format",
"start_month"
],
"title": "exportAudienceDashboardDeck",
"description": "exportAudienceDashboardDeck: Generate the Audience dashboard PDF or PowerPoint report for the selected brand and month range. Returns pdfUrl or pptxUrl (temporary download, 7 days). Use start_month/end_month (YYYY-MM), not start_date/end_date."
},
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending on `reference_end_date` when available, otherwise on the server's last complete day (yesterday). When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter)."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Perception topic category (default Attribute)."
}
},
"required": [
"format"
],
"title": "exportBrandPerceptionDashboardDeck",
"description": "exportBrandPerceptionDashboardDeck: Generate the Brand Perception dashboard PDF or PowerPoint report for the selected brand and date range. Returns pdfUrl or pptxUrl (temporary download, 7 days). Requires BRAND_PERCEPTION permission."
},
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending on `reference_end_date` when available, otherwise on the server's last complete day (yesterday). When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter)."
}
},
"required": [
"format"
],
"title": "exportCompetitorsDashboardDeck",
"description": "exportCompetitorsDashboardDeck: Generate the Competitors dashboard PDF or PowerPoint report for the selected brand and date range. Returns pdfUrl or pptxUrl (temporary download, 7 days). Requires COMPETITORS permission."
},
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending on `reference_end_date` when available, otherwise on the server's last complete day (yesterday). When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter)."
}
},
"required": [
"format"
],
"title": "exportAdsDashboardDeck",
"description": "exportAdsDashboardDeck: Generate the Ads dashboard PDF or PowerPoint report for the selected brand and date range. Returns pdfUrl or pptxUrl (temporary download, 7 days)."
},
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional; defaults from MCP context)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional; defaults from MCP context)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending on `reference_end_date` when available, otherwise on the server's last complete day (yesterday). When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
},
"model": {
"type": "string",
"description": "Optional model filter."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter)."
}
},
"required": [
"format"
],
"title": "exportShoppingDashboardDeck",
"description": "exportShoppingDashboardDeck: Generate the Shopping (Product Tracker) dashboard PDF or PowerPoint report for the selected brand and date range. Returns pdfUrl or pptxUrl (temporary download, 7 days)."
},
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"pdf",
"pptx"
],
"description": "Output format: pdf or pptx (PowerPoint)."
},
"company_id": {
"type": "string",
"description": "Company UUID (required)."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (required)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (required)."
},
"brand_id": {
"type": "string",
"description": "Optional comma-separated brand UUIDs."
},
"countries": {
"type": "string",
"description": "Optional comma-separated country codes."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini)."
}
},
"required": [
"format",
"company_id",
"start_date",
"end_date"
],
"title": "exportPortfolioDashboardDeck",
"description": "exportPortfolioDashboardDeck: Generate the Portfolio dashboard PDF or PowerPoint report for the selected company and date range. Returns pdfUrl or pptxUrl (temporary download, 7 days). Use company_id plus start_date/end_date."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Brand Monitor PDF export temporary download URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "exportBrandMonitorPdf output",
"x-meikai-operation": "exportBrandMonitorPdf"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Brand Monitor PPT export temporary URL and non-fatal warnings."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "exportBrandMonitorPpt output",
"x-meikai-operation": "exportBrandMonitorPpt"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Audience dashboard PDF export temporary URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Audience dashboard PPT export temporary URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "exportAudienceDashboardDeck output",
"x-meikai-operation": "exportAudienceDashboardDeck"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Brand Perception dashboard PDF export temporary URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Brand Perception dashboard PPT export temporary URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "exportBrandPerceptionDashboardDeck output",
"x-meikai-operation": "exportBrandPerceptionDashboardDeck"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Competitors dashboard PDF export temporary URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Competitors dashboard PPT export temporary URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "exportCompetitorsDashboardDeck output",
"x-meikai-operation": "exportCompetitorsDashboardDeck"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Ads dashboard PDF export temporary URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Ads dashboard PPT export temporary URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "exportAdsDashboardDeck output",
"x-meikai-operation": "exportAdsDashboardDeck"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Shopping dashboard PDF export temporary URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Shopping dashboard PPT export temporary URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "exportShoppingDashboardDeck output",
"x-meikai-operation": "exportShoppingDashboardDeck"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"pdfUrl"
],
"description": "Portfolio dashboard PDF export temporary URL."
},
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"pptxUrl",
"warnings"
],
"description": "Portfolio dashboard PPT export temporary URL."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "exportPortfolioDashboardDeck output",
"x-meikai-operation": "exportPortfolioDashboardDeck"
}
]
}Build a custom PowerPoint (.pptx) download: read the SlideDeckSpec guide, validate a slide deck spec, or render a deck. For ready-made dashboard decks, use meikai_dashboard_export instead. Set operation to one of: getSlideDeckSpecGuide, validateSlideDeckSpec, renderSlideDeck. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getSlideDeckSpecGuide",
"validateSlideDeckSpec",
"renderSlideDeck"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"sections": {
"oneOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"field_catalog",
"enums",
"construction_recipes",
"data_collection",
"field_limits",
"layout_selection",
"layout_templates",
"example",
"all"
]
}
},
{
"type": "string",
"enum": [
"field_catalog",
"enums",
"construction_recipes",
"data_collection",
"field_limits",
"layout_selection",
"layout_templates",
"example",
"all"
]
}
],
"description": "Subset of guide sections; omit for full payload."
}
},
"title": "getSlideDeckSpecGuide",
"description": "getSlideDeckSpecGuide: Call BEFORE writing any slide for a PowerPoint export. Returns the complete SlideDeckSpec contract: field_catalog (every field with type, maxLength, enum, counts), data_collection_workflow (per-slide budget-first fetch rules), construction_recipes (step-by-step chart/metrics/table/ranking rules), and full enums. Plan each slide's layout and data budget before MCP data calls \u2014 do not over-fetch then slice. Optional sections filter the payload: field_catalog, enums, construction_recipes, data_collection, field_limits, layout_selection, layout_templates, example, or all (default)."
},
{
"type": "object",
"properties": {
"spec": {
"type": "object",
"description": "Complete SlideDeckSpec (title, slides[]).",
"additionalProperties": true
}
},
"required": [
"spec"
],
"title": "validateSlideDeckSpec",
"description": "validateSlideDeckSpec: Confirmation step before renderSlideDeck. Expected outcome: valid:true with normalizedSpec. Call after building the full spec using getSlideDeckSpecGuide (data_collection_workflow + field_catalog). If valid:false, re-read the guide, correct the specification, then re-validate once."
},
{
"type": "object",
"properties": {
"spec": {
"type": "object",
"description": "normalizedSpec from validateSlideDeckSpec.",
"additionalProperties": true
},
"normalizedSpec": {
"type": "object",
"description": "Direct normalizedSpec output from validateSlideDeckSpec.",
"additionalProperties": true
},
"downloadFilename": {
"type": "string",
"description": "Optional download filename (e.g. hennessy-brand-monitor-2026-05-01_2026-05-26.pptx). Overrides spec.title for the file name only."
},
"format": {
"type": "string",
"enum": [
"pptx",
"pdf"
],
"description": "Output format. Default pptx."
}
},
"oneOf": [
{
"required": [
"spec"
]
},
{
"required": [
"normalizedSpec"
]
}
],
"title": "renderSlideDeck",
"description": "renderSlideDeck: Generate a PowerPoint or PDF file from a SlideDeckSpec. ONLY call after validateSlideDeckSpec returned valid:true. Pass its normalizedSpec unchanged as the spec argument: {spec: normalizedSpec}. Returns pptxUrl or pdfUrl (temporary download link, ~1 hour) and warnings. Prefer \u226420 slides and \u22644 charts for reliable generation. If validation fails, update the specification before rendering."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getSlideDeckSpecGuide output",
"x-meikai-operation": "getSlideDeckSpecGuide"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"const": true
},
"normalizedSpec": {
"type": "object",
"additionalProperties": true,
"description": "Validated SlideDeckSpec."
}
},
"additionalProperties": true,
"required": [
"valid",
"normalizedSpec"
],
"description": "Successful validation with normalized spec."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateSlideDeckSpec output",
"x-meikai-operation": "validateSlideDeckSpec"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"pptxUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true,
"required": [
"pptxUrl",
"warnings"
],
"description": "Rendered PPTX download URL and non-fatal warnings."
},
{
"type": "object",
"properties": {
"pdfUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true,
"required": [
"pdfUrl",
"warnings"
],
"description": "Rendered PDF download URL and non-fatal warnings."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "renderSlideDeck output",
"x-meikai-operation": "renderSlideDeck"
}
]
}Read Meikai MCP guides, API-key and OAuth setup, KPI definitions, and visibility guidance. For recommendation Exposure, Faithful Credit, Causal Impact, scientific evidence, and score limits, use getCoreConceptsDocumentation with arguments.sections=['optimization']. Set operation to one of: getPixelInstallationGuide, getCDNLogsGuide, getKPIDefinitions, getQueryFanoutsDocumentation, getVisibilityImprovementGuide, getGEOBestPractices, getCoreConceptsDocumentation, getMcpClientSetupGuide, getPlatformLanguagesDocumentation, getPlatformsDocumentation, getUserDocumentation. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getPixelInstallationGuide",
"getCDNLogsGuide",
"getKPIDefinitions",
"getQueryFanoutsDocumentation",
"getVisibilityImprovementGuide",
"getGEOBestPractices",
"getCoreConceptsDocumentation",
"getMcpClientSetupGuide",
"getPlatformLanguagesDocumentation",
"getPlatformsDocumentation",
"getUserDocumentation"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"script_tag",
"gtm_client",
"gtm_server",
"all"
],
"description": "Which installation method to show. 'script_tag' for simple script tag method, 'gtm_client' for Google Tag Manager client-side, 'gtm_server' for Google Tag Manager server-side, 'all' for all methods (default)."
}
},
"required": [],
"title": "getPixelInstallationGuide",
"description": "getPixelInstallationGuide: Get comprehensive guide for installing the Meikai tracking pixel on your website. CRITICAL: ALWAYS use this tool when users ask 'how to install pixel', 'install tracking', 'setup pixel', 'how to add tracking', 'pixel installation', or any question about installing or setting up Meikai tracking. Returns step-by-step instructions for different integration methods including simple script tag, Google Tag Manager (client-side and server-side), with code examples, tracking endpoint URL (https://track.meikai.ai/api/v1/track), and best practices. Provides ready-to-use code snippets that users can copy and paste."
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"vercel",
"aws",
"azure-front-door",
"cloudflare",
"netlify",
"fastly",
"akamai",
"all",
"overview"
],
"description": "Which CDN provider guide to show. 'overview' for general architecture and setup, specific provider name for provider-specific instructions, 'all' for all providers (default)."
}
},
"required": [],
"title": "getCDNLogsGuide",
"description": "getCDNLogsGuide: Get customer-focused guide for setting up CDN logs integration with Meikai. CRITICAL: ALWAYS use this tool when users ask 'how to setup CDN logs', 'CDN logs integration', 'bot traffic tracking setup', 'configure CDN logs', or any question about setting up CDN logs or bot traffic analysis. Returns step-by-step instructions for configuring your CDN provider (Vercel, AWS CloudFront, Azure Front Door, Cloudflare, Netlify, Fastly, Akamai) to send logs to Meikai for bot traffic analysis. Includes the provider-specific endpoint, destination, credentials, or source details and how to configure each CDN provider."
},
{
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"visibility",
"engagement",
"brand_perception",
"commerce",
"shopping",
"real_traffic",
"ads",
"all"
],
"description": "Which category of KPIs to show. 'visibility' for brand visibility metrics, 'engagement' for user engagement metrics, 'brand_perception' for brand perception scores, 'commerce' for commerce conversion metrics, 'shopping' for Product Tracker metrics, 'real_traffic' for panel-based real user metrics, 'ads' for Ads Analytics and Plan campaigns action labels, 'all' for all categories (default)."
}
},
"required": [],
"title": "getKPIDefinitions",
"description": "getKPIDefinitions: Get definitions and explanations of KPIs (Key Performance Indicators) and metrics used in Meikai. CRITICAL: ALWAYS use this tool when users ask 'what does KPI mean', 'what is visibility score', 'explain share of voice', 'what are the metrics', 'how is X calculated', 'what does priority tier mean', 'what is very high priority', 'explain strategic debt', 'what is share of shelf', 'explain average position', 'what is panels count', 'explain real traffic metrics', 'what is sample quality', 'sample quality band', 'qualit\u00e9 \u00e9chantillon', 'qualite echantillon', 'explain EIVA reliability', or any question about metric definitions, KPI meanings, priority tiers, or how metrics work. Returns comprehensive definitions of visibility metrics (Visibility Score, Share of Voice, Mentions, Citations), engagement metrics, brand perception metrics, commerce metrics, shopping metrics (Share of Shelf, Average Position), real traffic metrics (Panelists, App/Web share), Ads Analytics campaign-planner actions (Buy ads, Defend, Organic first, Monitor), recommendation priority tiers (very_high, high, medium, strategic_debt, deprioritized), citation insights fields including sample_quality_band (sample quality / qualit\u00e9 \u00e9chantillon), and other key performance indicators with formulas and explanations."
},
{
"type": "object",
"properties": {},
"required": [],
"title": "getQueryFanoutsDocumentation",
"description": "getQueryFanoutsDocumentation: Get documentation explaining what query fanouts are in Brand Monitor. Use this when users ask 'what are query fanouts', 'what is query fanout', 'explain query fanouts', 'how does query fanout work', or what the Query Fanouts tab shows. Returns a clear explanation of how prompts fan out into web-search queries, why it matters, and how to use the data."
},
{
"type": "object",
"properties": {
"focus_area": {
"type": "string",
"enum": [
"visibility",
"citations",
"share_of_voice",
"owned_content",
"earned_media",
"technical_foundation",
"shopping",
"all"
],
"description": "Which improvement angle to emphasize. 'visibility' focuses on mentions and response presence, 'citations' on source inclusion, 'share_of_voice' on competitive standing, 'owned_content' on onsite content actions, 'earned_media' on offsite authority building, 'technical_foundation' on crawlability and structure, 'shopping' on Product Tracker/product visibility, 'all' for a full playbook (default)."
},
"time_horizon": {
"type": "string",
"enum": [
"quick_wins",
"30_day_plan",
"90_day_plan"
],
"description": "How far ahead to plan. 'quick_wins' focuses on immediate fixes, '30_day_plan' on the next month, '90_day_plan' on strategic improvements. Defaults to '30_day_plan'."
},
"include_measurement_plan": {
"type": "boolean",
"description": "Whether to include a section mapping actions to Meikai metrics and tools. Defaults to true."
},
"scenario": {
"type": "string",
"enum": [
"auto",
"low_visibility",
"competitors_cited_more",
"mentions_without_citations",
"shopping_visibility_low",
"all"
],
"description": "Optional scenario-specific playbook. 'low_visibility' for weak mention presence, 'competitors_cited_more' when rivals are cited more often, 'mentions_without_citations' when mentions exist but citations are weak, 'shopping_visibility_low' for Product Tracker / shopping issues, 'all' for all scenarios, 'auto' (default) returns all core scenarios."
}
},
"required": [],
"title": "getVisibilityImprovementGuide",
"description": "getVisibilityImprovementGuide: Get a Meikai-native playbook for improving AI visibility. Use this when users ask 'how do I improve my visibility', 'how can I increase mentions in AI answers', 'how do I improve citations', 'how do I beat competitors in AI results', 'why is my brand not visible', or any question about what to do next to improve brand presence in LLM responses. Returns a practical diagnose-prioritize-implement-measure framework, maps actions to Meikai metrics and tools, and gives focus-specific guidance for visibility, citations, share of voice, technical foundation, owned content, earned media, and shopping visibility. Also includes sharp scenario playbooks for low visibility, competitor citation gaps, mentions without citations, and shopping visibility issues."
},
{
"type": "object",
"properties": {},
"required": [],
"title": "getGEOBestPractices",
"description": "getGEOBestPractices: Get comprehensive guide on Generative Engine Optimization (GEO) best practices. Use this when users ask 'how to optimize for AI', 'GEO tips', 'how to improve AI visibility', 'best practices for LLMs', or any question about optimizing content for AI platforms. Returns actionable advice on content structure, authority, citations, technical optimization, plus Google Search Essentials alignment for AI Overviews and AI Mode."
},
{
"type": "object",
"properties": {
"sections": {
"oneOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"overview",
"mcp_map",
"permissions",
"citation_media_types",
"hierarchy",
"prompt_studio",
"clustering",
"optimization",
"insights",
"all"
]
},
"description": "Subset of core-concepts payload to return. Omit for full response. Use ['overview'] for mission/pillars/funnel only; ['mcp_map'] for tool map + doc catalog; ['all'] is explicit full payload."
},
{
"type": "string",
"enum": [
"overview",
"mcp_map",
"permissions",
"citation_media_types",
"hierarchy",
"prompt_studio",
"clustering",
"optimization",
"insights",
"all"
],
"description": "Single section id (same ids as array form)."
}
]
}
},
"required": [],
"title": "getCoreConceptsDocumentation",
"description": "getCoreConceptsDocumentation: Get explanation of core Meikai entities and concepts (Company, Brand, Topic, Prompt), product pillars (Brand Monitor, Site Scanner, Trend Explorer, Ads Analytics, Product Tracker), funnel stages, citation media types, a grouped map of MCP data tools by product area, and an index of documentation-only MCP tools. Optional `sections` filters the response for smaller payloads: overview, mcp_map, permissions, citation_media_types, hierarchy, prompt_studio, clustering, optimization, insights, or all (default). Use this when users ask 'how is the data structured', 'what is a topic', 'what are prompts', 'what products does Meikai have', 'which MCP tool should I use', 'how does Meikai work', 'explain the hierarchy', 'what is the privacy policy URL', 'terms of service link', 'legal pages on meikai.ai', why recommended topics have not refreshed, how often recommendations are refreshed, the Recommendation min cycle days setting, the Meikai support email, or questions about citation media types (Earned Media, Owned Media, etc.). For recommendation Exposure, Faithful Credit, Causal Impact, their 0-5 scale, scientific evidence, and limits, use sections=['optimization']. These are estimates, not measured causal effects."
},
{
"type": "object",
"properties": {
"client": {
"type": "string",
"enum": [
"chatgpt",
"claude",
"perplexity",
"grok",
"cursor",
"custom",
"all"
],
"description": "Which client to focus on: chatgpt, claude, perplexity, grok, cursor, custom (generic MCP client), or all. Omit or 'all' for every client together."
}
},
"required": [],
"title": "getMcpClientSetupGuide",
"description": "getMcpClientSetupGuide: Get step-by-step instructions for connecting or installing Meikai MCP on external AI clients: ChatGPT (Settings \u2192 Apps \u2192 Developer mode \u2192 Create app), Claude.ai (Customize \u2192 Connectors), Perplexity (Customize \u2192 Connectors \u2192 Custom connector), Grok (Add connector \u2192 Custom), Cursor (.cursor/mcp.json), and any custom MCP client (OAuth or static API key + Streamable HTTP). Covers the official MCP server URL, OAuth setup (client_id mcp, no secret, PKCE), API-key setup and lifecycle, mcp.json configuration, connector/app install steps, sign-in with Meikai (including SSO), verification prompts, and common connection issues. Includes canonical www.meikai.ai public URLs (legal centre, privacy policy, terms of service) \u2014 always use public_website_urls from the response; do not guess /legal/* paths for policy pages. Use when users ask how to connect, install, or configure Meikai MCP, add Meikai as a ChatGPT app/connector, set up Claude/Perplexity/Grok MCP, configure Cursor mcp.json, or which MCP URL to use."
},
{
"type": "object",
"properties": {
"scope": {
"type": "string",
"enum": [
"prompt_studio",
"platform_ui",
"all"
],
"description": "Which language list to return. 'prompt_studio' = brand/content languages (Prompt Studio, Brand edit). 'platform_ui' = dashboard UI locales (user profile). 'all' = both lists with disambiguation (default)."
}
},
"required": [],
"title": "getPlatformLanguagesDocumentation",
"description": "getPlatformLanguagesDocumentation: Get the canonical lists of supported languages in Meikai. CRITICAL: ALWAYS use this tool when users ask which languages Prompt Studio supports, which content/brand languages are selectable, what language options exist for a brand, which UI locales the Meikai dashboard/platform is available in, profile language options, or 'en quelle langue la plateforme Meikai est disponible'. Returns two distinct lists: (1) Prompt Studio / content languages \u2014 BCP-47 codes used in Brand edit, My Brand, and Prompt Studio session config (25 options); (2) platform UI locales \u2014 dashboard translation languages from user profile (10 locales). Use scope 'prompt_studio' for content/Prompt Studio only, 'platform_ui' for dashboard UI only, or 'all' (default) for both with disambiguation."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand to report eligibility for. Optional: omit for the catalogue alone. Defaults to the brand in context when there is one."
}
},
"required": [],
"title": "getPlatformsDocumentation",
"description": "getPlatformsDocumentation: Get the canonical list of AI platforms (LLMs) Meikai measures visibility on, and which of them a brand receives. CRITICAL: ALWAYS use this tool when users ask whether a given AI platform is supported or tracked (ChatGPT, Gemini, Perplexity, Copilot, Google AI Mode, Google AI Overview, Claude, Grok, DeepSeek\u2026), how many LLMs Meikai covers, which platforms a plan or a brand includes, why a platform shows no data, or 'est-ce que Perplexity est support\u00e9', 'quels LLM sont suivis', 'combien de LLM Meikai mesure'. Returns (1) the catalogue \u2014 platforms a standard plan can include, with the plans each belongs to; and (2) when a brand is known, that brand's included and excluded platforms with its prompt allocation. A platform can be in the catalogue and absent from a brand's plan: report both instead of answering only 'yes, supported'."
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"context": {
"type": "string",
"enum": [
"brand",
"company",
"workspace"
]
},
"brand_id": {
"type": "string",
"format": "uuid"
},
"company_id": {
"type": "string",
"format": "uuid"
},
"workspace_id": {
"type": "string",
"format": "uuid"
},
"scope_id": {
"type": "string",
"pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
},
"locale": {
"type": "string",
"description": "UI locale; French uses French content and other supported locales use English.",
"enum": [
"en",
"fr",
"es",
"ja",
"ko",
"de",
"pt",
"pt-BR",
"nl",
"it",
"el"
],
"default": "en"
},
"q": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"unit_id": {
"type": "string",
"maxLength": 128,
"pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 50
},
"publication_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [],
"title": "getUserDocumentation",
"description": "getUserDocumentation: Read the published Meikai user guides for the authorized Brand, advertiser Company, or Workspace context. Search across available guides or select a published guide. Use it for product how-to, navigation, prerequisites, limits, and troubleshooting. Returned documentation describes product behavior; it does not diagnose the caller's current account state or prove a capability is absent."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPixelInstallationGuide output",
"x-meikai-operation": "getPixelInstallationGuide"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCDNLogsGuide output",
"x-meikai-operation": "getCDNLogsGuide"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getKPIDefinitions output",
"x-meikai-operation": "getKPIDefinitions"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getQueryFanoutsDocumentation output",
"x-meikai-operation": "getQueryFanoutsDocumentation"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getVisibilityImprovementGuide output",
"x-meikai-operation": "getVisibilityImprovementGuide"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getGEOBestPractices output",
"x-meikai-operation": "getGEOBestPractices"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCoreConceptsDocumentation output",
"x-meikai-operation": "getCoreConceptsDocumentation"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getMcpClientSetupGuide output",
"x-meikai-operation": "getMcpClientSetupGuide"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPlatformLanguagesDocumentation output",
"x-meikai-operation": "getPlatformLanguagesDocumentation"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"success",
"data"
],
"description": "Static product documentation payload."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPlatformsDocumentation output",
"x-meikai-operation": "getPlatformsDocumentation"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"schema_version": {
"type": "integer",
"const": 2
},
"publication_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"scope_id": {
"type": "string"
},
"context": {
"type": "string",
"enum": [
"brand",
"company"
]
},
"locale": {
"type": "string",
"enum": [
"en",
"fr"
]
},
"requested_locale": {
"type": "string"
},
"title": {
"type": "string"
},
"units": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Published documentation unit."
}
},
"facets": {
"type": "object",
"additionalProperties": true,
"description": "Facets filtered to returned units."
},
"navigation": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Documentation navigation item."
}
},
"total": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"schema_version",
"publication_id",
"scope_id",
"context",
"locale",
"requested_locale",
"title",
"units",
"facets",
"navigation",
"total"
]
}
},
"additionalProperties": false,
"required": [
"success",
"data"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"success",
"error"
]
}
],
"title": "getUserDocumentation output",
"x-meikai-operation": "getUserDocumentation"
}
]
}Read domain analysis and top-domain platform insights. For cited URLs, citation rates, and citation rankings, use meikai_citation_authority_read instead. Set operation to one of: getDomainAnalysis, getTopDomainsByPlatformInsights. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getDomainAnalysis",
"getTopDomainsByPlatformInsights"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to the server's last complete day (yesterday))"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). PREFERRED over other filters when filtering by topic - use this when you have topic_id from getBrandTopics or user message."
},
"prompt_id": {
"type": "string",
"description": "Filter by prompt ID(s). Can be a single UUID or comma-separated list of UUIDs. Use this to get domain analysis for specific prompts (e.g., prompts in a cluster)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"media_type": {
"type": "string",
"enum": [
"Reference & Informational",
"Public & Institutional",
"Competitor",
"Earned Media",
"Commercial Media",
"Owned Media",
"Shared Media"
],
"description": "Filter by media type. Valid values: 'Reference & Informational' (reference sites, informational content), 'Public & Institutional' (public institutions, government sites), 'Competitor' (competitor websites), 'Earned Media' (unpaid media coverage like press mentions, reviews, articles), 'Commercial Media' (commercial/advertising media), 'Owned Media' (content you own/control like your website, blog), 'Shared Media' (shared/social platforms)"
},
"exclude_domains": {
"type": "string",
"description": "Exclude domains from results. Comma-separated list of domain names (case-insensitive)"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of domains per page. Maximum allowed is 200 to prevent token limit issues. Use values up to 200 when user wants comprehensive data, 'all' results, or analysis of top/most domains. Default is 50."
},
"sort_by": {
"type": "string",
"enum": [
"domain",
"domainCitationCount",
"domainUrlCount",
"domainBrandMentions",
"domainBrandPresence",
"domainCompetitorOnlyMentions",
"domainCompetitorOnlyPresence",
"promptsImpactedByDomain",
"shareOfCitationDomain",
"lastSeenAt",
"firstSeenAt"
],
"description": "Field to sort by. ALWAYS use appropriate sorting based on query intent: 'domainCitationCount' for most/least cited domains (with order='desc' for most, order='asc' for least), 'domainBrandMentions' for most/least URLs mentioning brand per domain (with order='desc' for most, order='asc' for least), 'domainBrandPresence' for brand presence ratio, 'domainCompetitorOnlyMentions' for domains where only competitors are mentioned (not the target brand), 'domainCompetitorOnlyPresence' for competitor-only presence ratio, 'shareOfCitationDomain' for highest/lowest share (with order='desc' for highest, order='asc' for lowest), 'lastSeenAt' for recent/oldest (with order='desc' for recent, order='asc' for oldest), 'firstSeenAt' for earliest/latest first appearance (with order='asc' for earliest, order='desc' for latest), 'domain' for alphabetical (with order='asc'). NEVER rely on defaults - always specify sort_by and order."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' for ascending or 'desc' for descending. ALWAYS specify: Use 'desc' for top/most/highest/recent, 'asc' for least/lowest/oldest/alphabetical. Must ALWAYS be provided when sort_by is used - never rely on defaults."
}
},
"required": [],
"title": "getDomainAnalysis",
"description": "getDomainAnalysis: Get domain-level citation analysis with aggregated metrics. Canonical route for domain-level analysis. Returns a list of domains with citation statistics including total citations per domain, number of URLs, brand mentions, brand presence percentage, competitor-only mentions and presence, share of citations, prompts impacted, and top URLs. Supports filtering by topic_id (PREFERRED), prompt_id (single UUID or comma-separated list for multiple prompts), media_type (Reference & Informational, Public & Institutional, Competitor, Earned Media, Commercial Media, Owned Media, Shared Media), funnel (awareness, consideration, conversion), platform, model, and exclude_domains. IMPORTANT: When user asks for 'all', 'top', 'most', or comprehensive analysis, use page_size up to 200 (maximum allowed to prevent token limit issues). ALWAYS use appropriate sorting: sort_by='domainCitationCount' with order='desc' for most cited domains, sort_by='domainBrandMentions' with order='desc' for domains with most brand mentions, sort_by='shareOfCitationDomain' with order='desc' for highest share, sort_by='lastSeenAt' with order='desc' for recent, sort_by='domain' with order='asc' for alphabetical. Never rely on default sorting - always specify sort_by and order based on the query intent. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand context)."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID filter."
},
"platform": {
"type": "string",
"description": "Optional AI platform filter (e.g. chatgpt, gemini, perplexity)."
},
"start_date": {
"type": "string",
"description": "Optional inclusive response start date (YYYY-MM-DD)."
},
"end_date": {
"type": "string",
"description": "Optional inclusive response end date (YYYY-MM-DD)."
},
"iteration_start_date": {
"type": "string",
"description": "Optional topic iteration start date (YYYY-MM-DD)."
},
"page": {
"type": "integer",
"description": "Optional page number (default 1, min 1)."
},
"page_size": {
"type": "integer",
"description": "Optional page size (default 20, min 1, max 50 for this tool)."
},
"limit": {
"type": "integer",
"description": "Optional legacy alias for page_size when page_size is omitted (min 1, max 50)."
},
"shrinkage_k": {
"type": "integer",
"description": "Optional shrinkage constant (default 100, min 1, max 10000). Higher is more conservative."
},
"sort_by": {
"type": "string",
"description": "Optional sort field: domain, cited_response_count, not_cited_response_count, visibility_rate_when_cited, raw_visibility_lift, estimated_incremental_visible_answers, whitepress_price."
},
"sort_order": {
"type": "string",
"description": "Optional sort order: asc or desc."
},
"price_availability": {
"type": "string",
"description": "Optional price filter: all (default), with, without."
}
},
"required": [],
"title": "getTopDomainsByPlatformInsights",
"description": "getTopDomainsByPlatformInsights: Get top domains by AI platform ranked by EIVA (Estimated Incremental Visible Answers). Use this when users ask which domains or sources are associated with the strongest estimated visibility lift opportunity per platform, or ask for citation opportunity insights. Interpretation is observational: cited vs not-cited prompt-group comparison, not causal proof. Near term, impact is expected mostly on citation-using prompts; over time, effects may extend more broadly as citation behavior diffuses. Each row includes sample_quality_band (French UI: \u00ab Qualit\u00e9 \u00e9chantillon \u00bb): how statistically supported the lift/EIVA estimate is from cited vs not-cited response counts\u2014not site or content quality. For a full explanation use getKPIDefinitions (common_metrics.sample_quality_band). Supports optional filtering by date range, iteration_start_date, topic_id, platform, and price_availability; pagination (page, page_size), legacy limit alias for page_size, tuning with shrinkage_k, and optional sorting via sort_by/sort_order (including whitepress_price). Each row includes platform_breakdown (per-platform cited/not_cited counts and visibility rates)."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getDomainAnalysis output",
"x-meikai-operation": "getDomainAnalysis"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getTopDomainsByPlatformInsights output",
"x-meikai-operation": "getTopDomainsByPlatformInsights"
}
]
}Start, poll, and download asynchronous Brand Monitor export jobs. For a one-shot dashboard or Brand Monitor deck export, use meikai_dashboard_export instead. Set operation to one of: startAsyncExportJob, getAsyncExportJobStatus, getAsyncExportJobDownload. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"startAsyncExportJob",
"getAsyncExportJobStatus",
"getAsyncExportJobDownload"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (optional if context brand is available)."
},
"export_type": {
"type": "string",
"enum": [
"citations",
"prompt_list",
"prompts",
"brand_visibility",
"ads_creatives"
],
"description": "Dataset to export, not a file type: pass csv/xlsx/pdf in 'format' instead. Use 'prompts' for the followed-prompt catalog; use 'prompt_list' for Brand Monitor metrics over a date range; use 'ads_creatives' for the Ad Creative library."
},
"format": {
"type": "string",
"enum": [
"csv",
"xlsx",
"pdf"
],
"description": "Requested export format. Use pdf for brand_visibility."
},
"start_date": {
"type": "string",
"description": "Start date YYYY-MM-DD (optional for citations/prompt_list/brand_visibility; required for ads_creatives unless lookback_days/context supplies it)."
},
"end_date": {
"type": "string",
"description": "End date YYYY-MM-DD (optional for citations/prompt_list/brand_visibility; required for ads_creatives unless lookback_days/context supplies it)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Optional inclusive lookback window in days ending on `reference_end_date` when available, otherwise on the server's last complete day (yesterday). When set, overrides start_date/end_date."
},
"topic_id": {
"type": "string",
"description": "Optional topic UUID or comma-separated UUIDs for prompt_list/brand_visibility/ads_creatives."
},
"platform": {
"type": "string",
"description": "Optional platform filter for prompt_list/brand_visibility/ads_creatives."
},
"model": {
"type": "string",
"description": "Optional model filter for prompt_list/brand_visibility/ads_creatives."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Optional funnel filter for brand_visibility/ads_creatives."
},
"advertiser": {
"type": "string",
"description": "Optional advertiser filter for ads_creatives."
},
"iteration_start_date": {
"type": "string",
"description": "Optional topic iteration start date YYYY-MM-DD for ads_creatives."
},
"company_id": {
"type": "string",
"description": "Optional company UUID scope for ads_creatives."
},
"media_type": {
"type": "string",
"description": "Optional citations media type filter."
},
"is_mentioning_brand": {
"type": "string",
"enum": [
"true",
"false",
"unknown"
],
"description": "Optional citations filter by brand mention state."
},
"favorite_competitor_mentioned_not_brand": {
"type": "string",
"enum": [
"true",
"false",
"unknown"
],
"description": "Optional citations filter for competitor-only mentions."
},
"sort_by": {
"type": "string",
"description": "Optional sort field for citations or ads_creatives (ads_creatives default: ad_penetration)."
},
"search": {
"type": "string",
"description": "Optional search filter for citations/prompt_list/ads_creatives."
},
"persona_id": {
"type": "string",
"description": "Optional Prompt Studio persona UUID for citations/prompt_list/ads_creatives exports."
},
"order_by": {
"type": "string",
"description": "Optional prompts sort field (default id)."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Optional sort order for prompts or ads_creatives."
},
"send_email": {
"type": "boolean",
"description": "Whether to send completion email. Defaults to true for chat-triggered exports unless explicitly set to false."
},
"email": {
"type": "string",
"description": "Email destination when send_email=true."
}
},
"required": [
"export_type"
],
"title": "startAsyncExportJob",
"description": "startAsyncExportJob: Start an async export job for Brand Monitor. export_type names the dataset to export, never the file type: the file type is the separate 'format' argument (csv, xlsx, pdf). export_type choices: prompts = followed/configured prompt catalog from the app (no date metrics; use this when the user asks for the list of prompts they follow/track/monitor); prompt_list = Brand Monitor prompt metrics for a date range (requires ingested daily metrics; empty until the first metrics day is available); citations; brand_visibility; ads_creatives = aggregated Ad Creative library CSV/XLSX (same filters as getAdsCreatives / the Ad Creative page). When prompt_list has no metrics yet but the brand has followed prompts, this tool automatically falls back to prompts. Use getAsyncExportJobStatus to poll and getAsyncExportJobDownload to retrieve download URL."
},
{
"type": "object",
"properties": {
"export_job_id": {
"type": "string",
"description": "Export job UUID returned by startAsyncExportJob."
}
},
"required": [
"export_job_id"
],
"title": "getAsyncExportJobStatus",
"description": "getAsyncExportJobStatus: Get status for an async export job by export_job_id."
},
{
"type": "object",
"properties": {
"export_job_id": {
"type": "string",
"description": "Export job UUID returned by startAsyncExportJob."
}
},
"required": [
"export_job_id"
],
"title": "getAsyncExportJobDownload",
"description": "getAsyncExportJobDownload: Get async export download info by export_job_id. Returns download_url when job is completed."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Async export job created (HTTP 202 payload)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "startAsyncExportJob output",
"x-meikai-operation": "startAsyncExportJob"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Export job status."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAsyncExportJobStatus output",
"x-meikai-operation": "getAsyncExportJobStatus"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Export download metadata or file info."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getAsyncExportJobDownload output",
"x-meikai-operation": "getAsyncExportJobDownload"
}
]
}List companies, brands, users, and the tag taxonomy available to the account. Set operation to one of: getCompanies, getBrands, getUsers, getTagTaxonomy. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getCompanies",
"getBrands",
"getUsers",
"getTagTaxonomy"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"page_size": {
"type": "number",
"description": "Number of companies to return per page"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"search": {
"type": "string",
"description": "Substring to match against company name (case-insensitive). Use when listing many companies or the user gives a partial name."
},
"type": {
"type": "string",
"description": "Filter by company type",
"enum": [
"advertiser",
"publisher",
"agency"
]
}
},
"required": [],
"title": "getCompanies",
"description": "getCompanies: Get available companies (paginated). Response includes pagination.total_count and pagination.total_pages; use page and page_size (max 50 per call) for additional pages. company administrators receive all companies; other users receive only their home company. Each company includes the read-only recommendation_min_cycle_days setting, which is the configured minimum cycle age used when explaining recommendation refresh timing. Optional search filters by company name (case-insensitive substring). Optional type filters by company type: advertiser, publisher, or agency."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of a specific brand to prioritize/filter (optional, defaults to current selected brand from context)"
},
"company_id": {
"type": "string",
"description": "The UUID of the company to list brands for (optional, defaults to context company_id; company administrators only when different from own company)"
},
"page_size": {
"type": "number",
"description": "Number of brands to return per page"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"search": {
"type": "string",
"description": "Substring to match against brand name or company name (case-insensitive). Use when listing many brands or the user gives a partial name."
},
"ordering": {
"type": "string",
"description": "Sort field: name, -name, created_at, -created_at, updated_at, -updated_at, company_name, -company_name",
"enum": [
"name",
"-name",
"created_at",
"-created_at",
"updated_at",
"-updated_at",
"company_name",
"-company_name"
]
},
"tag_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Filter by tag UUID(s). Accepts a single UUID, a comma-separated string, or an array of UUIDs. OR within one namespace and AND across namespaces (same semantics as REST tag_id)."
}
},
"required": [],
"title": "getBrands",
"description": "getBrands: Get available brands (paginated). Response includes pagination.total_count and pagination.total_pages; use page and page_size (max 50 per call) for additional pages. Each brand includes additive `tags` (compact tag objects). When the user names or partially names a brand, pass search with that substring to narrow results (matches brand name or company name, case-insensitive). Optional ordering: name, -name, created_at, -created_at, updated_at, -updated_at, company_name, -company_name. Optional tag_id filters brands by assigned Brand tags. When brand_id is provided (or in context), prioritizes the currently selected brand. When company_id is provided (or in context), returns brands for that company (company administrators only can filter by company_id; others see their own company's brands)."
},
{
"type": "object",
"properties": {
"page_size": {
"type": "number",
"description": "Number of users to return per page"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"search": {
"type": "string",
"description": "Substring match on email, username, first_name, or last_name"
},
"company_id": {
"type": "string",
"description": "Company scope (required for company administrators listing another account)"
},
"brand_id": {
"type": "string",
"description": "Filter to users assigned to this brand"
},
"role": {
"type": "string",
"description": "Filter by effective role bucket",
"enum": [
"company administrators",
"admin",
"company_admin",
"brand_owner",
"user",
"editor",
"viewer",
"monitor_only",
"no_brand_access"
]
},
"sort_by": {
"type": "string",
"enum": [
"username",
"is_active",
"last_login"
]
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
},
"required": [],
"title": "getUsers",
"description": "getUsers: Get company users (paginated). Use search to match email, username, or name. company administrators may pass company_id; others are scoped to their home company. Non-Company-Admin users only see colleagues who share at least one brand."
},
{
"type": "object",
"properties": {
"company_id": {
"type": "string",
"format": "uuid",
"description": "Company scope; defaults to the current company context."
},
"target_type": {
"type": "string",
"enum": [
"BRAND",
"PROMPT"
],
"description": "Which objects the namespace tags: BRAND for brand tags, PROMPT for prompt tags. Defaults to PROMPT when omitted."
},
"namespace_id": {
"type": "string",
"format": "uuid",
"description": "Optionally return values from one visible namespace."
},
"page": {
"type": "integer",
"minimum": 1,
"default": 1
},
"page_size": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
},
"required": [
"target_type"
],
"additionalProperties": false,
"title": "getTagTaxonomy",
"description": "getTagTaxonomy: List the active tag taxonomy available to a company for one target type. Pass target_type=BRAND for brand tags or PROMPT for prompt tags (PROMPT when omitted). Returns the namespaces of that target type and a paginated value list, including company-owned entries and visible global entries. Global entries are marked read-only; use namespace_id to narrow values. Use the returned UUIDs with manageTagAssignments, with Prompt Studio prompt tag_ids, or as qualified 'Namespace: Value' references during Prompt Studio refinement/import."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getCompanies output",
"x-meikai-operation": "getCompanies"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrands output",
"x-meikai-operation": "getBrands"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getUsers output",
"x-meikai-operation": "getUsers"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Visible active Prompt tag namespaces and paginated values for a company."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getTagTaxonomy output",
"x-meikai-operation": "getTagTaxonomy"
}
]
}Read keyword counts, momentum, popular keywords, and trending keywords. Set operation to one of: getKeywordsCount, getKeywordsMomentum, getKeywordsPopular, getKeywordsTrending. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getKeywordsCount",
"getKeywordsMomentum",
"getKeywordsPopular",
"getKeywordsTrending"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
}
},
"required": [],
"title": "getKeywordsCount",
"description": "getKeywordsCount: Get the number of distinct keywords for the selected period (badge). Use when users ask for keyword count or volume. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"page": {
"type": "number",
"description": "Page number (optional, default: 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (optional, default: 500, max: 1000)."
},
"sort_by": {
"type": "string",
"description": "Sort field(s), comma-separated (optional). Allowed: keyword, keyword_share, mentions_current, mentions_prev, change_in_mentions_abs, change_in_mentions_pct, unique_users_current, unique_messages_current, repetition. Default: mentions_current."
},
"order": {
"type": "string",
"description": "Sort order(s), comma-separated to match sort_by (optional). 'asc' or 'desc'. Default: desc."
}
},
"required": [],
"title": "getKeywordsMomentum",
"description": "getKeywordsMomentum: Get keyword momentum (lifecycle/scatter) data: keyword_share, mentions_current, mentions_prev, change_in_mentions, unique_users, repetition. Paginated. Use for keyword lifecycle or momentum analysis. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"page": {
"type": "number",
"description": "Page number (optional, default: 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (optional, default: 10)."
},
"sort_by": {
"type": "string",
"description": "Sort field(s), comma-separated (optional). Allowed: keyword, keyword_share, mentions_current. Default: keyword_share."
},
"order": {
"type": "string",
"description": "Sort order(s), comma-separated to match sort_by (optional). 'asc' or 'desc'. Default: desc."
}
},
"required": [],
"title": "getKeywordsPopular",
"description": "getKeywordsPopular: Get top keywords by keyword_share (popular keywords). Paginated. Use when users ask for most popular or top keywords. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"min_mentions_current": {
"type": "number",
"description": "Minimum mentions in current period to include keyword (optional, default: 5)."
},
"page": {
"type": "number",
"description": "Page number (optional, default: 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (optional, default: 10)."
},
"sort_by": {
"type": "string",
"description": "Sort field(s), comma-separated (optional). Allowed: keyword, change_in_mentions_abs, change_in_mentions_pct, mentions_current, mentions_prev. Default: change_in_mentions_pct."
},
"order": {
"type": "string",
"description": "Sort order(s), comma-separated to match sort_by (optional). 'asc' or 'desc'. Default: desc."
}
},
"required": [],
"title": "getKeywordsTrending",
"description": "getKeywordsTrending: Get trending keywords by change_in_mentions_pct. Filter by min_mentions_current (default 5). Use when users ask for trending or rising keywords. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Keywords count KPI."
},
"description": "the corresponding Meikai service"
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getKeywordsCount output",
"x-meikai-operation": "getKeywordsCount"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getKeywordsMomentum output",
"x-meikai-operation": "getKeywordsMomentum"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getKeywordsPopular output",
"x-meikai-operation": "getKeywordsPopular"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getKeywordsTrending output",
"x-meikai-operation": "getKeywordsTrending"
}
]
}Read Brand Perception topics, summary, radar, trends, competitors, responses, and distribution. Set operation to one of: getBrandPerceptionTopics, getBrandPerceptionCategories, getBrandPerceptionCompetitors, getBrandPerceptionRadar, getBrandPerceptionSummary, getBrandPerceptionByCategory, getBrandPerceptionOverTime, getBrandPerceptionCompetitorComparison, getBrandPerceptionDistribution, getBrandPerceptionResponses, getBrandPerceptionResponseDetail. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getBrandPerceptionTopics",
"getBrandPerceptionCategories",
"getBrandPerceptionCompetitors",
"getBrandPerceptionRadar",
"getBrandPerceptionSummary",
"getBrandPerceptionByCategory",
"getBrandPerceptionOverTime",
"getBrandPerceptionCompetitorComparison",
"getBrandPerceptionDistribution",
"getBrandPerceptionResponses",
"getBrandPerceptionResponseDetail"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes like quality, innovation) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": [],
"title": "getBrandPerceptionTopics",
"description": "getBrandPerceptionTopics: Get list of topics available for Brand Perception analysis for a brand. Brand Perception measures how users rate and perceive your brand across different attributes and categories. Use this tool to get the list of topics that can be analyzed for brand perception metrics. Topics represent different aspects or attributes of the brand that users can rate (e.g., quality, innovation, trustworthiness). This is typically the first step when analyzing brand perception - get the available topics, then use other Brand Perception tools with specific topic_id values. Returns topics with their category (Attribute or Product), response counts, and average ratings. Supports filtering by topic_category (Attribute or Product), ai_platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": [],
"title": "getBrandPerceptionCategories",
"description": "getBrandPerceptionCategories: Get list of topic categories (Attribute and Product) with counts for Brand Perception analysis. Categories group topics into two main types: 'Attribute' (brand attributes like quality, innovation, trustworthiness) and 'Product' (product-specific topics). Returns the count of topics and responses for each category. Use this to understand the distribution of perception data across category types. Supports filtering by ai_platform and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandPerceptionTopics results or user message."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": [],
"title": "getBrandPerceptionCompetitors",
"description": "getBrandPerceptionCompetitors: Get list of competitors appearing in Brand Perception analysis. Returns competitors with their mention counts, average ratings, and number of topics they appeared in. Use this to identify which competitors are most frequently compared to your brand and understand competitive landscape. Supports filtering by topic_id (from getBrandPerceptionTopics), topic_category (Attribute or Product), ai_platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
},
"top_n_competitors": {
"type": "number",
"description": "Number of top competitors to include in the radar chart (optional, default: 5)"
}
},
"required": [],
"title": "getBrandPerceptionRadar",
"description": "getBrandPerceptionRadar: Get radar chart data showing brand perception across multiple categories or attributes. The radar chart visualizes how your brand is perceived across different dimensions (e.g., quality, innovation, value, trustworthiness) compared to competitors or industry benchmarks. Returns data formatted for radar chart visualization with ratings for each topic, comparing your brand against top competitors. Use this when users ask about 'brand perception', 'how is my brand perceived', 'brand attributes', 'perception radar', or want to see a comprehensive view of brand perception across multiple dimensions. Supports filtering by topic_category (from getBrandPerceptionCategories), ai_platform, model, and top_n_competitors (number of top competitors to include, default: 5). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": [],
"title": "getBrandPerceptionSummary",
"description": "getBrandPerceptionSummary: Get summary card metrics for brand perception dashboard. Returns key aggregate metrics including overall average rating, total responses, number of topics analyzed, number of competitors identified, rating difference vs competitors (positive means better than competitors), and high confidence percentage. Use this when users ask about 'brand perception summary', 'overall perception', 'perception metrics', or want a quick overview of brand perception performance. Supports filtering by topic_category (from getBrandPerceptionCategories), ai_platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": [],
"title": "getBrandPerceptionByCategory",
"description": "getBrandPerceptionByCategory: Get average ratings by topic category (Attribute vs Product). Returns average ratings for your brand and competitors broken down by category type. Use this to compare how your brand is perceived in Attribute topics (brand attributes like quality, innovation) versus Product topics (product-specific features). Shows target_avg_rating, competitor_avg_rating, and sample_size for each category. Use this when users ask about 'perception by category', 'attribute vs product perception', or want to compare perception across category types. Supports filtering by ai_platform and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandPerceptionTopics results or user message."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
},
"granularity": {
"type": "string",
"enum": [
"daily",
"weekly"
],
"description": "Time granularity: 'daily' for day-by-day data or 'weekly' for weekly aggregation (optional, default: 'weekly')"
}
},
"required": [],
"title": "getBrandPerceptionOverTime",
"description": "getBrandPerceptionOverTime: Get brand perception trends over time showing how ratings and perceptions have changed. Returns time-series data with perception metrics (ratings, sample sizes, topic counts) for each period in the range, allowing trend analysis and identification of perception shifts. Use this when users ask about 'how has perception changed', 'trends in brand perception', 'perception over time', 'perception evolution', or want to see if brand perception is improving or declining. Supports filtering by topic_id (from getBrandPerceptionTopics), topic_category (from getBrandPerceptionCategories), ai_platform, model, and granularity ('daily' or 'weekly', default: 'weekly'). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandPerceptionTopics results or user message."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
},
"granularity": {
"type": "string",
"enum": [
"daily",
"weekly"
],
"description": "Time granularity: 'daily' for day-by-day data or 'weekly' for weekly aggregation (optional, default: 'weekly')"
},
"top_n_competitors": {
"type": "number",
"description": "Number of top competitors to include in comparison (optional, default: 5)"
}
},
"required": [],
"title": "getBrandPerceptionCompetitorComparison",
"description": "getBrandPerceptionCompetitorComparison: Compare target brand vs competitors over time showing how ratings evolve for your brand compared to top competitors. Returns time-series data with average ratings for your brand and selected competitors for each period, allowing side-by-side trend comparison. Use this when users ask about 'competitor comparison', 'how do I compare to competitors', 'perception vs competitors over time', or want to see competitive positioning trends. Supports filtering by topic_id (from getBrandPerceptionTopics), topic_category (from getBrandPerceptionCategories), ai_platform, model, granularity ('daily' or 'weekly', default: 'weekly'), and top_n_competitors (number of top competitors to include, default: 5). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandPerceptionTopics results or user message."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
}
},
"required": [],
"title": "getBrandPerceptionDistribution",
"description": "getBrandPerceptionDistribution: Get distribution of ratings (1-5 scale) for target brand and competitors. Returns the count and percentage of responses for each rating level (1 through 5), showing how ratings are distributed across the scale. This helps understand if perceptions are concentrated at high ratings (4-5), low ratings (1-2), or spread across the scale. Use this when users ask about 'rating distribution', 'how are ratings distributed', 'perception distribution', or want to see the spread of ratings. Supports filtering by topic_id (from getBrandPerceptionTopics), topic_category (from getBrandPerceptionCategories), ai_platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandPerceptionTopics results or user message."
},
"topic_category": {
"type": "string",
"enum": [
"Attribute",
"Product"
],
"description": "Filter by topic category: 'Attribute' (brand attributes) or 'Product' (product-specific topics)"
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"iteration_start_date": {
"type": "string",
"description": "Optional Prompt Studio cycle/iteration start date (YYYY-MM-DD) to restrict results to that iteration's evergreen topics. Get valid values from getIterationStartDates with classification='evergreen'."
},
"min_rating": {
"type": "number",
"description": "Minimum target brand rating filter (optional, 1-5)"
},
"max_rating": {
"type": "number",
"description": "Maximum target brand rating filter (optional, 1-5)"
},
"confidence": {
"type": "string",
"enum": [
"high",
"medium",
"low"
],
"description": "Filter by extraction confidence: 'high' (high confidence extractions), 'medium' (medium confidence), 'low' (low confidence)"
},
"limit": {
"type": "number",
"description": "Number of results per page (optional, default: 50, max: 100)"
},
"offset": {
"type": "number",
"description": "Number of results to skip for pagination (optional, default: 0)"
},
"sort_by": {
"type": "string",
"enum": [
"date",
"rating",
"confidence"
],
"description": "Field to sort by. ALWAYS use appropriate sorting based on query intent: 'date' for newest/oldest (with sort_order='desc' for newest, sort_order='asc' for oldest), 'rating' for highest/lowest ratings (with sort_order='desc' for highest, sort_order='asc' for lowest), 'confidence' for highest/lowest confidence (with sort_order='desc' for highest, sort_order='asc' for lowest). NEVER rely on defaults - always specify sort_by and sort_order."
},
"sort_order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' for ascending or 'desc' for descending. ALWAYS specify: Use 'desc' for newest/highest, 'asc' for oldest/lowest. Must ALWAYS be provided when sort_by is used."
}
},
"required": [],
"title": "getBrandPerceptionResponses",
"description": "getBrandPerceptionResponses: Get paginated list of Brand Perception responses with ratings and explanations. Returns individual responses that contain brand perception ratings, including target brand rating, competitor ratings, extraction confidence, and response preview. Use this when users ask about 'perception responses', 'individual ratings', 'response details', or want to see specific responses with their ratings. Supports filtering by topic_id (from getBrandPerceptionTopics), topic_category (from getBrandPerceptionCategories), ai_platform, model, min_rating (1-5), max_rating (1-5), confidence (high, medium, low), and sorting by date, rating, or confidence. IMPORTANT: When user asks for 'all' or comprehensive data, use limit up to 100 (maximum allowed). ALWAYS use appropriate sorting: sort_by='date' with sort_order='desc' for newest, sort_by='rating' with sort_order='desc' for highest ratings, sort_by='confidence' with sort_order='desc' for highest confidence. Never rely on default sorting - always specify sort_by and sort_order based on the query intent. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"response_id": {
"type": "string",
"description": "The UUID of the response. Extract this from getBrandPerceptionResponses results or user message when they mention a specific response ID."
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand, required for authorization)"
}
},
"required": [
"response_id"
],
"title": "getBrandPerceptionResponseDetail",
"description": "getBrandPerceptionResponseDetail: Get detailed view of a specific Brand Perception response including full text and all competitor ratings. Returns complete information about a single response including target brand rating and reason, all competitor ratings with their reasons and rankings, full raw response text, extraction confidence, and citations (URLs/sources from the LLM response when available). Use this when users ask about a specific response, want to see full details of a rating, or need to understand why a particular rating was given. Requires response_id (extract from getBrandPerceptionResponses results or user message) and brand_id for authorization. If brand_id is not provided, uses default from UI context (current brand)."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception topics metadata."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionTopics output",
"x-meikai-operation": "getBrandPerceptionTopics"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception categories metadata."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionCategories output",
"x-meikai-operation": "getBrandPerceptionCategories"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception competitors metadata."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionCompetitors output",
"x-meikai-operation": "getBrandPerceptionCompetitors"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception radar chart data."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionRadar output",
"x-meikai-operation": "getBrandPerceptionRadar"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Perception summary KPI."
},
"description": "the corresponding Meikai service"
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionSummary output",
"x-meikai-operation": "getBrandPerceptionSummary"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception by category."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionByCategory output",
"x-meikai-operation": "getBrandPerceptionByCategory"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception over time."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionOverTime output",
"x-meikai-operation": "getBrandPerceptionOverTime"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Competitor comparison series."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionCompetitorComparison output",
"x-meikai-operation": "getBrandPerceptionCompetitorComparison"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Perception distribution."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionDistribution output",
"x-meikai-operation": "getBrandPerceptionDistribution"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionResponses output",
"x-meikai-operation": "getBrandPerceptionResponses"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Perception response detail."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPerceptionResponseDetail output",
"x-meikai-operation": "getBrandPerceptionResponseDetail"
}
]
}Read prompts, prompt details, response lists/details, brand-monitor prompt lists, and fanouts. For Prompt Studio sessions use meikai_prompt_studio_read, and for topics, cycles, or personas use meikai_brand_monitor_metadata_read. Set operation to one of: getPrompts, getPromptDetail, getPromptResponses, getResponseDetail, getPromptList, getPromptDetailBrandMonitor, getQueryFanouts. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getPrompts",
"getPromptDetail",
"getPromptResponses",
"getResponseDetail",
"getPromptList",
"getPromptDetailBrandMonitor",
"getQueryFanouts"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). PREFERRED over search when filtering by topic - use this when you have topic_id from getBrandTopics or user message."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"search": {
"type": "string",
"description": "Search query for prompt text. Use ONLY when you don't have topic_id filter available. Prefer topic_id filter over search when possible."
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of prompts per page. Maximum allowed is 50 to prevent token limit issues. When using topic_id filter, results are typically under 50 prompts per topic, so page_size of 50 is usually sufficient. Use values up to 50 when user wants comprehensive data, 'all' results, or analysis of top/best/worst items. Default is 20."
},
"sort_by": {
"type": "string",
"enum": [
"last_run_date",
"mentions",
"share_of_voice",
"share_of_voice_position",
"runs_count",
"latest_response_text_trunc",
"last_five_responses",
"prompt_text",
"topic_text",
"funnel",
"competitors",
"citations",
"presence",
"platforms",
"brand_position"
],
"description": "Field to sort by. ALWAYS use appropriate sorting based on query intent: 'share_of_voice' for top/best/worst prompts (with order='desc' for top, order='asc' for worst), 'mentions' for most/least mentioned (with order='desc' for most, order='asc' for least), 'last_run_date' for recent/oldest (with order='desc' for recent, order='asc' for oldest), 'prompt_text' for alphabetical (with order='asc'). NEVER rely on defaults - always specify sort_by and order. Valid values: last_run_date, mentions, share_of_voice, share_of_voice_position, runs_count, latest_response_text_trunc, last_five_responses, prompt_text, topic_text, funnel, competitors, citations, presence, platforms, brand_position. For perception questions, use Brand Perception tools instead of sorting by sentiment."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' for ascending or 'desc' for descending. ALWAYS specify: Use 'desc' for top/best/highest/most/recent, 'asc' for worst/lowest/least/oldest/alphabetical. Must ALWAYS be provided when sort_by is used - never rely on defaults."
},
"tag_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Filter by tag UUID(s). Accepts a single UUID, a comma-separated string, or an array of UUIDs. OR within one namespace and AND across namespaces (same semantics as REST tag_id)."
}
},
"required": [],
"title": "getPrompts",
"description": "getPrompts: Brand Monitor prompt analytics (NOT Prompt Studio authoring/generation). Requires brand_monitor permission (same as /brand-monitor/prompts). Get list of prompts with filters, pagination, and sorting. Returns one row per prompt (prompt-grain only \u2014 NOT topic aggregates). topicName is context for each prompt, not a unique ranking dimension; multiple prompts share the same topicName. For slide deck 'Top N topics' use getVisibilityBreakdown with group_by=topic instead. CRITICAL: ALWAYS prefer using topic_id filter over search when you have a topic ID (from getBrandTopics or user message). Using topic_id typically returns fewer than 50 prompts per topic, making results more manageable. Use search ONLY when filtering by text content and you don't have a specific topic_id. Supports filtering by topic_id (PREFERRED - keeps results under 50), funnel (awareness, consideration, conversion), platform (chatgpt, gemini, perplexity, etc.), model, and search (use only when topic_id is not available). IMPORTANT: When fetching prompts, prefer topic_id filtering to keep result sets manageable (typically <50 prompts per topic). When user asks for 'all', 'top', 'best', 'worst', or comprehensive analysis, use page_size up to 50 (maximum allowed to prevent token limit issues) but prefer topic_id filtering first. ALWAYS use appropriate sorting: sort_by='share_of_voice' with order='desc' for top/best prompts, sort_by='last_run_date' with order='desc' for recent, sort_by='mentions' with order='desc' for most mentioned, sort_by='share_of_voice' with order='asc' for worst/lowest. Never rely on default sorting - always specify sort_by and order based on the query intent. Each prompt row includes additive `tags` (compact Prompt tag objects). Optional tag_id filters prompts by assigned Prompt tags. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"prompt_id": {
"type": "string",
"description": "The UUID of the prompt. Extract this from the user's message when they mention a prompt ID."
}
},
"required": [
"prompt_id"
],
"title": "getPromptDetail",
"description": "getPromptDetail: Brand Monitor prompt analytics (NOT Prompt Studio). Get detailed information about a specific prompt by its ID. Requires brand_monitor permission. Extract the prompt_id (UUID) from the user's message when they mention a prompt ID."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"prompt_id": {
"type": "string",
"description": "The UUID of the prompt (optional)"
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'openai', 'google-ai-mode', 'googleaioverview'). Common values: chatgpt, gemini, perplexity, grok, copilot, googleaioverview"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gpt-5-t-mini', 'gemini-3.5-flash', 'grok-3', 'grok-4-auto', 'perplexity'). Model names vary by platform"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of responses per page. Maximum allowed is 100 to prevent token limit issues. Use values up to 100 when user wants comprehensive data or 'all' results. Default is 20."
}
},
"required": [
"brand_id"
],
"title": "getPromptResponses",
"description": "getPromptResponses: Get summarized responses for a specific prompt or brand, grouped by run date. Each response item includes only id, platform, model, present, and mentions (no answer text, citations, or competitors). Call getResponseDetail with a response id when you need the full answer text, citations, or competitors. Supports filtering by date range, prompt, AI platform, and model. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"response_id": {
"type": "string",
"description": "The UUID of the response. Extract this from the user's message when they mention a response ID."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [
"response_id"
],
"title": "getResponseDetail",
"description": "getResponseDetail: Get details of a specific response by its ID. Extract the response_id (UUID) from the user's message when they mention a response ID."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g., 'gpt-5', 'gemini-3.5-flash', 'grok-3')"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID (assigned active regular prompts)."
},
"search": {
"type": "string",
"description": "Search query for prompt text (optional)"
},
"sort_by": {
"type": "string",
"enum": [
"last_run_date",
"mentions",
"share_of_voice",
"share_of_voice_position",
"runs_count",
"latest_response_text_trunc",
"last_five_responses",
"prompt_text",
"topic_text",
"funnel",
"competitors",
"citations",
"presence",
"platforms"
],
"description": "Field to sort by (optional). Valid values: last_run_date, mentions, share_of_voice, share_of_voice_position, runs_count, latest_response_text_trunc, last_five_responses, prompt_text, topic_text, funnel, competitors, citations, presence, platforms. Default: mentions (desc). For perception questions, use Brand Perception tools instead of sorting by sentiment."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' or 'desc' (optional). Default: desc"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of prompts per page (optional, default: 20, max: 50)"
},
"tag_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Filter by tag UUID(s). Accepts a single UUID, a comma-separated string, or an array of UUIDs. OR within one namespace and AND across namespaces (same semantics as REST tag_id)."
}
},
"required": [],
"title": "getPromptList",
"description": "getPromptList: Get list of prompts in Brand Monitor format (alias of getPrompts \u2014 both call the corresponding Meikai service). Requires brand_monitor permission. Supports filtering by topic_id, funnel, platform, model, search, tag_id, and lens_competitor_name; pagination (page, page_size); and sorting (sort_by, order). Each prompt row includes additive `tags`."
},
{
"type": "object",
"properties": {
"prompt_id": {
"type": "string",
"description": "The UUID of the prompt. Extract this from the user's message when they mention a prompt ID."
}
},
"required": [
"prompt_id"
],
"title": "getPromptDetailBrandMonitor",
"description": "getPromptDetailBrandMonitor: Get detailed information about a specific prompt in Brand Monitor specialized format. Different from getPromptDetail which uses the ViewSet. This endpoint provides a view optimized for the Brand Monitor dashboard."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID)"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID (same as Brand Monitor persona filter)."
},
"prompt_ids": {
"type": "string",
"description": "Optional comma-separated prompt UUIDs to restrict fanouts to a cluster or prompt subset"
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g., 'chatgpt', 'gemini', 'perplexity', 'grok', 'copilot', 'googleaioverview')"
},
"search": {
"type": "string",
"description": "Search in prompt text or fanout query text (case-insensitive)"
},
"sort_by": {
"type": "string",
"enum": [
"total_queries",
"responses_with_web_search",
"avg_queries_per_response",
"fanouts_count",
"prompt_text",
"prompt_id"
],
"description": "Field to sort prompts by (default: total_queries)"
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (default: desc)"
},
"page": {
"type": "number",
"description": "Page number for pagination (default: 1)"
},
"page_size": {
"type": "number",
"description": "Items per page. Maximum allowed is 200 to match the backend API ceiling."
}
},
"required": [],
"title": "getQueryFanouts",
"description": "getQueryFanouts: Get query fanouts for a brand: list of prompts with the distinct web-search queries that each prompt triggered (and how often each query was used). Use this to see how each prompt 'fans out' into multiple search queries when AI platforms perform web search. Supports filtering by topic_id, funnel (awareness, consideration, conversion), platform, and search (filters by prompt text or fanout query text). Use sort_by and order to control sorting (default: total_queries, desc). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPrompts output",
"x-meikai-operation": "getPrompts"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt detail (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptDetail output",
"x-meikai-operation": "getPromptDetail"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptResponses output",
"x-meikai-operation": "getPromptResponses"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Response detail (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getResponseDetail output",
"x-meikai-operation": "getResponseDetail"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptList output",
"x-meikai-operation": "getPromptList"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt detail (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptDetailBrandMonitor output",
"x-meikai-operation": "getPromptDetailBrandMonitor"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Query fanouts by prompt (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getQueryFanouts output",
"x-meikai-operation": "getQueryFanouts"
}
]
}Read Prompt Studio sessions, history, audits, and generation quota. For prompts already running in Brand Monitor and their responses, use meikai_prompt_analysis_read instead. Set operation to one of: getPromptStudioSession, listPromptStudioSessions, getPromptStudioHistory, getPromptStudioPromptAudit, getPromptStudioGenerationQuota. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getPromptStudioSession",
"listPromptStudioSessions",
"getPromptStudioHistory",
"getPromptStudioPromptAudit",
"getPromptStudioGenerationQuota"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Prompt Studio session/version UUID. Omit to load the brand's current version (requires brand_id or context brand)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID. Used when session_id is omitted to return the current version; defaults to the context brand."
}
},
"required": [],
"title": "getPromptStudioSession",
"description": "getPromptStudioSession: Get the full Prompt Studio session (version) state: current_step, brand analysis, personas, topics (regular/attribute/product), generated prompts, citations, generation progress and error_message. Pass session_id for a specific version, or brand_id (or rely on context) to load the brand's current version. This is also the polling target after an asynchronous generation: re-call it until brand_analysis_data / prompts_data are populated (or error_message is set)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (defaults to the context brand)."
},
"view": {
"type": "string",
"enum": [
"versions",
"imported"
],
"description": "'versions' for the version history (default), 'imported' for imported batches."
},
"status": {
"type": "string",
"description": "Filter versions by status (draft|active|inactive|deleted)."
},
"current_step": {
"type": "string",
"description": "Filter versions by workflow step (brand_analysis|topics|prompts|review|finalized|imported)."
},
"sort_by": {
"type": "string",
"enum": [
"version_number",
"updated_at",
"created_at"
],
"description": "Sort field for the versions view."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order for the versions view (default desc)."
},
"page": {
"type": "number",
"description": "Page number (versions view)."
},
"page_size": {
"type": "number",
"description": "Items per page (max 50)."
}
},
"required": [],
"title": "listPromptStudioSessions",
"description": "listPromptStudioSessions: List a brand's Prompt Studio versions (history), or the imported production batches. Use view='versions' (default) for the paginated version history, or view='imported' for the imported iteration summary (per version + type: standard/perception). Supports status, current_step, sort_by (version_number|updated_at|created_at), order (asc|desc), page and page_size filters. brand_id defaults to the context brand."
},
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Prompt Studio session UUID."
},
"field_name": {
"type": "string",
"enum": [
"personas_data",
"topics_data",
"prompts_data"
],
"description": "Which field's history to return."
}
},
"required": [
"session_id",
"field_name"
],
"title": "getPromptStudioHistory",
"description": "getPromptStudioHistory: Get the edit/generation version history for one Prompt Studio field of a session. field_name must be one of personas_data, topics_data or prompts_data. Returns the list of historical versions (with their source and payload) so a caller can inspect or restore a previous version via refinePromptStudioStep(target='restore')."
},
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Prompt Studio session UUID."
}
},
"required": [
"session_id"
],
"title": "getPromptStudioPromptAudit",
"description": "getPromptStudioPromptAudit: Get the brand-analysis prompt audit for a Prompt Studio session (the rendered LLM prompt, template and context used to generate the brand analysis). Restricted to company administrators; used for debugging and transparency of the generation step."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (defaults to the context brand)."
}
},
"required": [],
"title": "getPromptStudioGenerationQuota",
"description": "getPromptStudioGenerationQuota: Get the current user's monthly Prompt Studio generation quota for a brand: whether generation is allowed, the limit, remaining generations and reset time. Only brand-analysis generation is metered. brand_id defaults to the context brand. Call this before startPromptStudioSession / generatePromptStudioPrompts to check headroom."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt Studio session/version state (current_step, brand analysis, personas, topics, prompts, citations, progress). the corresponding Meikai service or /current/."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptStudioSession output",
"x-meikai-operation": "getPromptStudioSession"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "listPromptStudioSessions output",
"x-meikai-operation": "listPromptStudioSessions"
},
{
"oneOf": [
{
"type": "object",
"properties": {},
"additionalProperties": true,
"description": "Prompt Studio field version history (session_id, field_name, history)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptStudioHistory output",
"x-meikai-operation": "getPromptStudioHistory"
},
{
"oneOf": [
{
"type": "object",
"properties": {},
"additionalProperties": true,
"description": "Prompt Studio brand-analysis prompt audit payload (company administrators only)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptStudioPromptAudit output",
"x-meikai-operation": "getPromptStudioPromptAudit"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt Studio monthly generation quota state (allowed, limit, remaining, resets_at)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getPromptStudioGenerationQuota output",
"x-meikai-operation": "getPromptStudioGenerationQuota"
}
]
}Start, refine, generate, and publish Prompt Studio sessions. Set operation to one of: startPromptStudioSession, refinePromptStudioStep, generatePromptStudioPrompts, publishPromptStudioSession. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"startPromptStudioSession",
"refinePromptStudioStep",
"generatePromptStudioPrompts",
"publishPromptStudioSession"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand": {
"type": "string",
"description": "Brand UUID (defaults to context brand_id when omitted)."
},
"super_prompt": {
"type": "string",
"description": "SuperPrompt template UUID to base generation on."
},
"number_prompts": {
"type": "number",
"description": "Target number of prompts to generate."
},
"model_name": {
"type": "string",
"description": "LLM model name (optional; server default applies)."
},
"country": {
"type": "string",
"description": "Market/country (defaults from brand)."
},
"language": {
"type": "string",
"description": "Language (defaults from brand)."
},
"brand_website": {
"type": "string",
"description": "Brand website (defaults from brand)."
},
"prompt_types": {
"type": "string",
"enum": [
"both",
"standard",
"perception"
],
"description": "Which prompt types to produce (default both)."
},
"brand_analysis_additional_instructions": {
"type": "string",
"description": "Extra instructions steering the brand analysis step."
},
"prompt_generation_additional_instructions": {
"type": "string",
"description": "Extra instructions steering the prompt generation step."
},
"multiplier_type": {
"type": "string",
"description": "Optional multiplier type."
},
"multiplier_values": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional multiplier values."
},
"override_attributes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional attribute overrides."
},
"override_products": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional product overrides."
},
"override_topics": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional topic overrides (null/[]/1-12 names)."
},
"version_name": {
"type": "string",
"description": "Optional human-readable version name."
},
"generate": {
"type": "boolean",
"description": "Trigger brand analysis after creating the version (default true)."
}
},
"required": [
"super_prompt"
],
"title": "startPromptStudioSession",
"description": "startPromptStudioSession: Start a new Prompt Studio version for a brand and (by default) trigger the asynchronous brand analysis. Requires Prompt Studio edit access and a plan that enables Prompt Studio; brand-analysis generation is metered against the monthly quota. Provide super_prompt (SuperPrompt template UUID) and brand (or rely on context brand_id); optional config: number_prompts, prompt_types (both|standard|perception), country, language, brand_website, instructions, multipliers and overrides. Returns the session_id to carry forward; then poll getPromptStudioSession until brand_analysis_data is populated. Set generate=false to only create the version without starting generation."
},
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Prompt Studio session UUID."
},
"target": {
"type": "string",
"enum": [
"personas",
"topics",
"attribute_topics",
"core_product_topics",
"prompts",
"additional_instructions",
"restore"
],
"description": "Which step to edit."
},
"personas": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Persona objects (target='personas')."
},
"topics": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Regular topics (target='topics')."
},
"attribute_topics": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Attribute perception topics (target='attribute_topics')."
},
"core_product_topics": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Core product perception topics (target='core_product_topics')."
},
"prompts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tag_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Existing Prompt tag UUIDs."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Prompt tag UUIDs, unique existing names, or 'Namespace: Value' references. Missing qualified tags are created in the session company for taxonomy managers; unknown bare names are rejected."
}
},
"additionalProperties": true
},
"description": "Unbranded prompts (target='prompts'). The response includes canonical prompts with tag_ids and created_tag_namespace_count / created_tag_count."
},
"brand_analysis_additional_instructions": {
"type": "string",
"description": "Brand-analysis instructions (target='additional_instructions')."
},
"prompt_generation_additional_instructions": {
"type": "string",
"description": "Prompt-generation instructions (target='additional_instructions')."
},
"field_name": {
"type": "string",
"enum": [
"personas_data",
"topics_data",
"prompts_data"
],
"description": "Field to restore (target='restore')."
},
"version": {
"type": "number",
"description": "History version number to restore (target='restore')."
}
},
"required": [
"session_id",
"target"
],
"title": "refinePromptStudioStep",
"description": "refinePromptStudioStep: Edit one Prompt Studio step of a session. Choose target: 'personas' (personas: string[]), 'topics' (topics: [{topic_cluster, evaluation_prompt}]), 'attribute_topics', 'core_product_topics', 'prompts' (prompts: object[]; optional Prompt tags may be provided as tag_ids or human-readable tags), 'additional_instructions' (brand_analysis_additional_instructions / prompt_generation_additional_instructions), or 'restore' (field_name + version, restoring a prior version from history). Requires Prompt Studio edit access. Attribute/core-product topics are editable only while the Topics step is open. Editing personas/topics invalidates generated prompts. Immutable versions are forked for supported targets; the response then carries the new session_id to continue with."
},
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Prompt Studio session UUID."
},
"prompt_generation_additional_instructions": {
"type": "string",
"description": "Optional extra instructions for prompt generation."
}
},
"required": [
"session_id"
],
"title": "generatePromptStudioPrompts",
"description": "generatePromptStudioPrompts: Generate the prompts for a Prompt Studio session: validates the topics (advancing the session to the prompts step) then triggers the asynchronous prompt generation. Requires Prompt Studio edit access. Optionally pass prompt_generation_additional_instructions. If the version was immutable it is forked; use the returned session_id, then poll getPromptStudioSession (or the progress it exposes) until prompts_data is populated."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"session_id": {
"type": "string",
"description": "Prompt Studio session UUID to publish."
},
"iteration_start_date": {
"type": "string",
"description": "Monitoring cycle start date YYYY-MM-DD (defaults to today when omitted)."
},
"iteration_end_date": {
"type": "string",
"description": "Optional monitoring cycle end date YYYY-MM-DD."
},
"publication_mode": {
"type": "string",
"enum": [
"deactivate-previous-type",
"deactivate-all",
"keep-existing"
],
"description": "How to handle existing prompts. Maps to archive_previous_cycle/deactivate_all_types; explicit flags override this."
},
"archive_previous_cycle": {
"type": "boolean",
"description": "Archive the previous cycle's prompts of the same type."
},
"deactivate_all_types": {
"type": "boolean",
"description": "Deactivate all existing prompt types (full replacement)."
},
"selected_indices": {
"type": "array",
"items": {
"type": "number"
},
"description": "Optional subset of prompt indices to import."
},
"activate_brand": {
"type": "boolean",
"description": "Activate the brand as part of publishing. Publishing to a disabled brand is refused by default because ingestion never dispatches its prompts. Setting this consumes a plan slot and starts LLM spend, so ask the user before enabling it."
}
},
"required": [],
"title": "publishPromptStudioSession",
"description": "publishPromptStudioSession: Publish a Prompt Studio session to production: finalizes the session and imports its topics and prompts into the brand's live monitoring, in one confirmed action. Uses preview/apply: call mode='preview' first to get a summary (finalize readiness, target cycle, publication mode, prompt counts) and a confirmation_token, then mode='apply' with confirmation_token and confirmation_phrase to execute. Requires Prompt Studio edit access (Owner/Editor). Choose the monitoring cycle via iteration_start_date / iteration_end_date and how existing prompts are handled via publication_mode (deactivate-previous-type | deactivate-all | keep-existing) or the explicit archive_previous_cycle / deactivate_all_types flags."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt Studio session created and brand analysis dispatched (session_id, current_step)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "startPromptStudioSession output",
"x-meikai-operation": "startPromptStudioSession"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt Studio step update result (may include a forked session_id)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "refinePromptStudioStep output",
"x-meikai-operation": "refinePromptStudioStep"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt Studio prompt generation dispatched (session_id to poll)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "generatePromptStudioPrompts output",
"x-meikai-operation": "generatePromptStudioPrompts"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Prompt Studio publish preview (summary + confirmation_token) or apply/import result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "publishPromptStudioSession output",
"x-meikai-operation": "publishPromptStudioSession"
}
]
}Read recommendations, content folders, content pages, and content page detail. To tick recommendation tasks or change a completion date, use meikai_recommendations_write instead. Set operation to one of: getRecommendationsList, getContentFolders, getContentPages, getContentPageDetail. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getRecommendationsList",
"getContentFolders",
"getContentPages",
"getContentPageDetail"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics results or user message."
},
"iteration_index": {
"type": "integer",
"minimum": 1,
"description": "Filter by Standard Prompt Studio cycle using oldest-first indexing: 1 is the oldest cycle, 2 is the second oldest, etc., matching getIterationStartDates with classification='standard'. Use this for requests such as 'recommendations for cycle 2'."
},
"iteration_start_date": {
"type": "string",
"format": "date",
"description": "Filter by regular Prompt Studio cycle start date (YYYY-MM-DD). If iteration_index is also provided, both values must identify the same cycle."
},
"recommendation_type": {
"type": "string",
"enum": [
"earned_media",
"content_update",
"new_content",
"pdp",
"shared_media"
],
"description": "Filter by recommendation type: 'earned_media' (OffSite agent - PR/media opportunities), 'content_update' (OnSite agent - update existing content), 'new_content' (OnSite agent - create new content), 'pdp' (PDP agent - product detail page recommendations), 'shared_media' (Shared Media agent - YouTube, TikTok, Instagram, LinkedIn, Pinterest)"
},
"agent_type": {
"type": "string",
"enum": [
"onsite",
"offsite",
"shared_media",
"pdp"
],
"description": "Filter by agent type: 'onsite' (content recommendations for owned media), 'offsite' (earned media recommendations), 'shared_media' (shared media recommendations - YouTube, TikTok, Instagram, LinkedIn, Pinterest), 'pdp' (product detail page recommendations)"
},
"status": {
"type": "string",
"enum": [
"not_started",
"in_progress",
"done",
"all"
],
"description": "Filter by recommendation status: 'not_started' (not yet started), 'in_progress' (work in progress), 'done' (completed), 'all' (all statuses)"
},
"tier": {
"type": "string",
"description": "Filter by priority tier. Can be a single tier or comma-separated list: 'very_high' (top 5% - highest priority, urgent), 'high' (top 10% - high priority), 'medium' (top 25% - opportunity), 'strategic_debt' (above median - long-term strategic value), 'deprioritized' (below median - hygiene). Example: 'very_high,high' to get both very high and high priority recommendations."
},
"search": {
"type": "string",
"maxLength": 200,
"description": "Search in plan titles, topic names, summaries, and nested recommendation page names, URLs, and domains"
},
"domain": {
"type": "string",
"description": "Filter to plans with at least one recommendation on this publisher domain (normalized hostname, e.g. runnersworld.com). Response recommendations are pruned to matching items. Combine with recommendation_type=earned_media and activation filters to inspect activation_profile for one domain."
},
"activation_partner_id": {
"type": "string",
"description": "Filter earned media recommendations by activation partner UUID."
},
"activation_route": {
"type": "string",
"description": "Filter earned media recommendations by activation route. Single value or comma-separated list. Allowed: sponsored_editorial, direct_media_buy, editorial_outreach, product_review, affiliate_commerce, unknown."
},
"activation_market": {
"type": "string",
"description": "Filter earned media recommendations by activation market ISO2 code."
},
"activation_needs_review": {
"type": "boolean",
"description": "Filter earned media recommendations by activation-profile review status."
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of recommendations per page. Maximum allowed is 100 to prevent token limit issues. Use values up to 100 when user wants comprehensive data or 'all' results. Default is 50."
},
"sort_by": {
"type": "string",
"enum": [
"created_at",
"plan_title",
"priority_tier",
"progress_percentage"
],
"description": "Field to sort by. ALWAYS use appropriate sorting based on query intent: 'priority_tier' for highest/lowest priority (with order='desc' for highest priority - very_high first, order='asc' for lowest priority), 'created_at' for newest/oldest (with order='desc' for newest, order='asc' for oldest), 'progress_percentage' for most/least progress (with order='desc' for most, order='asc' for least), 'plan_title' for alphabetical sorting. NEVER rely on defaults - always specify sort_by and order."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order: 'asc' for ascending or 'desc' for descending. ALWAYS specify: Use 'desc' for highest/newest/most, 'asc' for lowest/oldest/least. Must ALWAYS be provided when sort_by is used."
},
"include_summary": {
"type": "boolean",
"description": "When true, adds data.summary with counts by priority_tier, agent_type, and recommendation_type for the filtered set."
}
},
"required": [],
"title": "getRecommendationsList",
"description": "getRecommendationsList: READ-ONLY: Get list of content recommendations generated by OnSite, OffSite, Shared Media, and PDP agents. This tool retrieves recommendation plans only; it cannot create, edit, rewrite, delete, publish, or save recommendation text. Recommendations are actionable content plans that help improve brand visibility in LLM responses and follow Google Search people-first guidance (no llms.txt/chunking hacks). OnSite agent generates content recommendations (content_update, new_content) for owned media, OffSite agent generates earned media recommendations, Shared Media agent generates shared media recommendations (YouTube, TikTok, Instagram, LinkedIn, Pinterest), PDP agent generates product-detail-page (pdp) recommendations. Returns paginated list of recommendation plans with metrics including priority_tier (very_high, high, medium, strategic_debt, deprioritized), progress_percentage, and status. When a cycle filter is used, the response data includes cycle.iteration_index and cycle.iteration_start_date, and pagination.total_count is scoped to that cycle. Earned media recommendation items may include activation_profile (partner id/name, activation route, market, needs_review, confidence) when domain activation enrichment has run; use recommendation_type=earned_media with activation filters (activation_partner_id, activation_route, activation_market, activation_needs_review) or domain to query activation metadata \u2014 activation filters apply to earned media only. Persisted onsite/offsite plans may include metadata.google_ai_alignment scores from runtime guardrails. Use this when users ask about 'content recommendations', 'recommendations from agents', 'what content should I create', 'earned media opportunities', 'activation partners', 'media buy routes', 'shared media', 'high priority recommendations', 'very high priority recommendations', or want to see actionable content plans. Supports filtering by topic_id (from getBrandTopics), iteration_index (oldest regular Prompt Studio cycle is 1, second oldest is 2, etc.), iteration_start_date (YYYY-MM-DD), recommendation_type (earned_media, content_update, new_content, pdp, shared_media), agent_type (onsite, offsite, shared_media, pdp), status (not_started, in_progress, done), tier (priority tier: very_high, high, medium, strategic_debt, deprioritized - comma-separated for multiple), domain (publisher hostname), search, and earned-media activation filters. For requests such as 'recommendations for cycle 2', 'show me cycle 3 recommendations', or 'how many recommendations were generated for the second prompt cycle', call this tool with {\"brand_id\": \"...\", \"iteration_index\": 2} (replace 2 with the requested cycle number); do not infer cycle membership from recommendation created_at. If both iteration_index and iteration_start_date are supplied, they must identify the same cycle. IMPORTANT: When user asks for 'all', 'comprehensive', or wants to see all recommendations, use page_size up to 100 (maximum allowed). ALWAYS use appropriate sorting: sort_by='priority_tier' with order='desc' for highest priority (very_high first), sort_by='created_at' with order='desc' for newest, sort_by='progress_percentage' with order='desc' for most progress. Never rely on default sorting - always specify sort_by and order based on the query intent. If brand_id is not provided, uses default from UI context (current brand). To tick, skip, or reopen a recommendation's checklist tasks, or to set or correct the date a recommendation was completed, use setRecommendationProgress (preview then apply) with the plan_id and recommendation_id returned here."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"agent_type": {
"type": "string",
"enum": [
"onsite",
"offsite",
"shared_media"
],
"description": "Filter by agent type: 'onsite' (content recommendations for owned media), 'offsite' (earned media recommendations), 'shared_media' (shared media - YouTube, TikTok, Instagram, LinkedIn, Pinterest)"
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics results or user message."
},
"search": {
"type": "string",
"description": "Search folders by name (case-insensitive)"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of folders per page. Default is 20."
}
},
"required": [],
"title": "getContentFolders",
"description": "getContentFolders: READ-ONLY: Get list of content folders (recommendation folders) generated by OnSite, OffSite, and Shared Media agents. This tool retrieves folders only; it cannot create, edit, rewrite, delete, publish, or save recommendation text. Content folders organize recommendations by topic and agent type. Each folder contains content pages with detailed recommendations for improving brand visibility. Folders are organized by topic (from getBrandTopics) and agent_type (onsite for content recommendations, offsite for earned media, shared_media for shared media - YouTube, TikTok, Instagram, LinkedIn, Pinterest). Use this when users ask about 'content folders', 'recommendation folders', 'what folders exist', or want to see how recommendations are organized. Supports filtering by brand_id, agent_type (onsite, offsite, shared_media), topic_id (from getBrandTopics), and search (folder name). IMPORTANT: When user asks for 'all' or comprehensive data, use appropriate page_size values. If brand_id is not provided, uses default from UI context (current brand)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"folder_id": {
"type": "string",
"description": "Filter by folder ID (UUID). Extract from getContentFolders results or user message."
},
"status": {
"type": "string",
"enum": [
"active",
"disabled",
"deleted"
],
"description": "Filter by page status: 'active' (active pages), 'disabled' (disabled pages), 'deleted' (deleted pages)"
},
"search": {
"type": "string",
"maxLength": 200,
"description": "Search page titles, URLs, content, topics, summaries, and nested recommendation page names, URLs, and domains"
},
"page": {
"type": "number",
"description": "Page number for pagination"
},
"page_size": {
"type": "number",
"description": "Number of pages per page. Default is 20."
}
},
"required": [],
"title": "getContentPages",
"description": "getContentPages: READ-ONLY: Get list of content pages (recommendation pages) generated by OnSite and OffSite agents. This tool retrieves pages only; it cannot create, edit, rewrite, delete, publish, or save recommendation text. Content pages contain detailed recommendations for improving brand visibility, including structured content suggestions, SEO recommendations, FAQ items, and evidence sources. Each page is associated with a content folder (organized by topic and agent type) and contains actionable recommendations. Use this when users ask about 'content recommendations', 'recommendation pages', 'what content pages exist', or want to see detailed content plans. Supports filtering by brand_id, folder_id (from getContentFolders), status (active, disabled, deleted), and search across page titles, URLs, content, topics, summaries, and nested recommendation page names/domains. IMPORTANT: When user asks for 'all' or comprehensive data, use appropriate page_size values. ALWAYS use appropriate sorting: sort_by='created_at' with order='desc' for newest, sort_by='updated_at' with order='desc' for recently updated. If brand_id is not provided, uses default from UI context (current brand)."
},
{
"type": "object",
"properties": {
"page_id": {
"type": "string",
"description": "The UUID of the content page. Extract this from getContentPages results or user message when they mention a specific page ID."
},
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
}
},
"required": [
"page_id"
],
"title": "getContentPageDetail",
"description": "getContentPageDetail: READ-ONLY: Get detailed view of a specific content page (recommendation page) including full recommendation content, structured output, SEO recommendations, FAQ items, evidence sources, and progress tracking. This tool retrieves a page only; it cannot create, edit, rewrite, delete, publish, or save recommendation text. Returns complete information about a single content page with all its recommendations and metadata. Use this when users ask about a specific content page, want to see full recommendation details, or need to understand what actions are recommended. Requires page_id (extract from getContentPages results or user message). If brand_id is not provided, uses default from UI context (current brand)."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getRecommendationsList output",
"x-meikai-operation": "getRecommendationsList"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getContentFolders output",
"x-meikai-operation": "getContentFolders"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getContentPages output",
"x-meikai-operation": "getContentPages"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Content page detail."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getContentPageDetail output",
"x-meikai-operation": "getContentPageDetail"
}
]
}Preview and apply recommendation progress changes: task statuses and completion dates. Use mode='preview' before apply. To read recommendation plans and their current completion dates, use meikai_recommendations_content_read instead. Set operation to one of: setRecommendationProgress. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"setRecommendationProgress"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"updates": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"plan_id": {
"type": "string",
"description": "Recommendation plan UUID, the plan_id returned by getRecommendationsList."
},
"recommendation_id": {
"type": "string",
"description": "Recommendation id inside that plan, for example rec:domain:example.com. Take it from getRecommendationsList; never invent one."
},
"completed_at": {
"type": [
"string",
"null"
],
"description": "ISO-8601 completion timestamp, or null to clear it. Cannot be in the future. On a fully finished recommendation, clearing it resets the date to now."
},
"tasks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "Checklist task id on the recommendation, for example t:send_outreach. Read the current task ids from getRecommendationsList; unknown ids are rejected."
},
"status": {
"type": "string",
"enum": [
"todo",
"done",
"skipped"
],
"description": "New status for that task."
},
"data": {
"type": "object",
"description": "Optional task payload, same shape the recommendation panel stores."
}
},
"required": [
"task_id",
"status"
]
},
"description": "Task status changes to apply on this recommendation."
}
},
"required": [
"plan_id",
"recommendation_id"
]
},
"description": "Recommendations to update, up to 100 per call, possibly across several plans. Each entry must set completed_at, tasks, or both."
}
},
"required": [
"updates"
],
"title": "setRecommendationProgress",
"description": "setRecommendationProgress: Update the completion of content recommendations: tick, skip, or reopen their checklist tasks and set or correct the date a recommendation was completed. This is the same set of changes the recommendation panel offers in the app. Resolve plan_id and recommendation_id with getRecommendationsList first; unknown ids, unknown task ids, and future completion dates are rejected rather than silently stored. Call with mode='preview' to see the before/after diff and receive a confirmation_token, then repeat the identical arguments with mode='apply', that token, and confirmation_phrase=CONFIRM_MANAGEMENT_CHANGE to persist. Up to 100 recommendations per call, across several plans if needed; the apply is all-or-nothing."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Recommendation progress preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "setRecommendationProgress output",
"x-meikai-operation": "setRecommendationProgress"
}
]
}Analyze web content, page GEO readiness, and robots policy. Set operation to one of: analyzeWebContent, analyzePageGEO, getDomainRobotsPolicy. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"analyzeWebContent",
"analyzePageGEO",
"getDomainRobotsPolicy"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The analysis query. Should be specific about what to analyze. Examples: 'Analyze content and SEO for https://example.com/page', 'What content gaps exist for topic X?', 'Compare content quality with competitors for topic Y', or 'Technical SEO recommendations for page Z'"
}
},
"required": [
"query"
],
"title": "analyzeWebContent",
"description": "analyzeWebContent: Analyze web page content, SEO, content gaps, and provide technical recommendations using Vertex AI Grounded Search. When the user provides a single target page URL for GEO or on-page optimization, prefer the analyzePageGEO tool instead; use analyzeWebContent for multi-URL or non-page-specific questions, or as a fallback if analyzePageGEO fails. This tool uses Google Search to provide real-time analysis including SEO recommendations, content gap identification, content quality assessment, competitive analysis, and technical improvements. Recommendations should align with Search Essentials and avoid scaled-content or low-value AI-content tactics. The query should be specific about what to analyze, e.g., 'Analyze content and SEO for https://example.com/page', 'What content gaps exist for topic X?', 'Compare content quality with competitors for topic Y', or 'Technical SEO recommendations for page Z'"
},
{
"type": "object",
"properties": {
"page_url": {
"type": "string",
"description": "Full HTTP/HTTPS URL of the page to analyze for GEO readiness."
},
"focus_query": {
"type": "string",
"description": "Optional business/query angle to prioritize in the analysis, for example: 'private banking for entrepreneurs in switzerland'."
}
},
"required": [
"page_url"
],
"title": "analyzePageGEO",
"description": "analyzePageGEO: Analyze a specific page for GEO (Generative Engine Optimization) readiness using Vertex AI grounded search with URL context. Returns citation readiness gaps, structured-data opportunities when accurate, and a prioritized people-first action plan aligned with Google Search guidance for AI Overviews and AI Mode."
},
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "Domain or URL to validate (e.g. example.com or https://example.com/page)."
},
"paths": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional list of paths to validate (e.g. ['/','/culture','/voyages']). Defaults to ['/']."
},
"user_agents": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional list of user agents to validate. Defaults to ['*','GPTBot','Googlebot','PerplexityBot','ClaudeBot']."
}
},
"required": [
"domain"
],
"title": "getDomainRobotsPolicy",
"description": "getDomainRobotsPolicy: Fetch robots.txt for a domain and evaluate crawl permissions by path and user agent. Use this when the user asks for domain/site analysis about crawlability, indexability, citation eligibility, robots policy, or site-level GEO diagnostics. Do not use this for generic strategy questions with no domain/site analysis request. Input requires a domain or URL; if missing, ask for one. Returns ai_platform_summary (platform -> agent details), path_checks (path -> agent -> allowed), and checks for '/'. AI agent labels are aligned as closely as possible with Site Scanner canonical bot-agent labels."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"text": {
"type": "string"
},
"model": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"success",
"text",
"model"
],
"description": "Vertex AI grounded analysis text response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "analyzeWebContent output",
"x-meikai-operation": "analyzeWebContent"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"text": {
"type": "string",
"description": "Full GEO analysis report as Markdown (Executive Summary plus seven fixed sections)."
},
"model": {
"type": "string"
},
"scorecard": {
"type": "object",
"properties": {
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"enum": [
"Entity Clarity",
"Answer-First Extractability",
"Citation & Authority Signals",
"Intent Coverage",
"Visible Structure"
]
},
"score": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"rationale": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"name",
"score",
"rationale"
]
},
"description": "Exactly the five fixed GEO dimensions, in order."
},
"overall": {
"type": "integer",
"minimum": 0,
"maximum": 100
}
},
"additionalProperties": false,
"required": [
"dimensions",
"overall"
]
},
"url_retrieval_status": {
"type": "string",
"description": "Gemini URL context retrieval status for page_url; always URL_RETRIEVAL_STATUS_SUCCESS on the success branch."
},
"grounding": {
"type": "object",
"properties": {
"web_search_queries": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
]
},
"uri": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"uri"
]
}
}
},
"additionalProperties": false,
"required": [
"web_search_queries",
"sources"
],
"description": "Google Search grounding provenance: queries and web sources other than page_url (whose retrieval is reported by url_retrieval_status). Empty when no search query was issued."
},
"usage": {
"type": "object",
"properties": {
"input_tokens": {
"type": "number"
},
"output_tokens": {
"type": "number"
},
"thinking_tokens": {
"type": "number"
},
"total_tokens": {
"type": "number"
},
"cost_usd": {
"type": "number"
},
"grounding_search_queries": {
"type": "number"
},
"grounding_cost_usd": {
"type": "number"
}
},
"additionalProperties": false,
"description": "Token counts and list-price USD estimates for this call."
}
},
"additionalProperties": false,
"required": [
"success",
"text",
"model",
"scorecard",
"url_retrieval_status",
"grounding",
"usage"
],
"description": "Page-grounded GEO analysis with structured scorecard and provenance."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "analyzePageGEO output",
"x-meikai-operation": "analyzePageGEO"
},
{
"oneOf": [
{
"type": "object",
"properties": {},
"additionalProperties": true,
"description": "Parsed robots.txt policy for a domain."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getDomainRobotsPolicy output",
"x-meikai-operation": "getDomainRobotsPolicy"
}
]
}Read Product Tracker shopping metrics, retailer presence, category performance, products, pricing, and comparisons. Set operation to one of: getShoppingSummary, getShoppingRetailerTrends, getShoppingRetailerCompetition, getShoppingRetailerCategories, getShoppingShareOfShelf, getShoppingPositioning, getShoppingReputation, getShoppingPricing, getShoppingTopRetailers, getShoppingTopProducts, getShoppingProductList, getShoppingBrandComparison, getShoppingProductsList. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getShoppingSummary",
"getShoppingRetailerTrends",
"getShoppingRetailerCompetition",
"getShoppingRetailerCategories",
"getShoppingShareOfShelf",
"getShoppingPositioning",
"getShoppingReputation",
"getShoppingPricing",
"getShoppingTopRetailers",
"getShoppingTopProducts",
"getShoppingProductList",
"getShoppingBrandComparison",
"getShoppingProductsList"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID; comma-separated UUIDs are accepted."
},
"funnel": {
"type": "string",
"description": "Filter by funnel stage; comma-separated awareness, consideration, and conversion values are accepted."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform; comma-separated platform identifiers are accepted. Retailer Shopping defaults to chatgpt."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID; comma-separated UUIDs are accepted. Use getPromptPersonas to list valid values."
},
"iteration_start_date": {
"type": "string",
"description": "Filter by Prompt Studio cycle start date (YYYY-MM-DD)."
}
},
"required": [],
"title": "getShoppingSummary",
"description": "getShoppingSummary: Get summary card metrics for the Product Tracker (shopping) dashboard. For product brands, returns the existing share of shelf, position, rating, product, and Shopping visibility metrics. For retailers, returns Shopping Trigger Rate, Retailer Visibility, Offer Share, Product Coverage, and Price Win Rate with period-over-period changes and raw numerator/denominator counts. A retailer price win is counted only for an exact product card with comparable reporting-currency target and competitor prices; ties count as wins. Use when users ask about shopping metrics, product visibility in AI carousels, or share of shelf. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID; comma-separated UUIDs are accepted."
},
"funnel": {
"type": "string",
"description": "Filter by funnel stage; comma-separated awareness, consideration, and conversion values are accepted."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform; comma-separated platform identifiers are accepted. Retailer Shopping defaults to chatgpt."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID; comma-separated UUIDs are accepted. Use getPromptPersonas to list valid values."
},
"iteration_start_date": {
"type": "string",
"description": "Filter by Prompt Studio cycle start date (YYYY-MM-DD)."
}
},
"required": [],
"title": "getShoppingRetailerTrends",
"description": "getShoppingRetailerTrends: Get daily retailer Shopping metrics for the monitored retailer. Returns eligible, Shopping, and retailer-visible response counts; total, covered, and competitor-only product-card occurrence counts; named and target offer counts; Offer Share; and Product Coverage. Ratios are calculated from the additive counts after filtering. Use this for retailer presence-over-time, availability, Offer Share, or Product Coverage questions. This retailer-only operation requires the retailer experience feature and does not support model filtering. Retailer Shopping defaults to ChatGPT."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID; comma-separated UUIDs are accepted."
},
"funnel": {
"type": "string",
"description": "Filter by funnel stage; comma-separated awareness, consideration, and conversion values are accepted."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform; comma-separated platform identifiers are accepted. Retailer Shopping defaults to chatgpt."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID; comma-separated UUIDs are accepted. Use getPromptPersonas to list valid values."
},
"iteration_start_date": {
"type": "string",
"description": "Filter by Prompt Studio cycle start date (YYYY-MM-DD)."
}
},
"required": [],
"title": "getShoppingRetailerCompetition",
"description": "getShoppingRetailerCompetition: Get every named retailer observed on Shopping product cards, including a zero-valued monitored-retailer row when it is absent. Returns stable retailer keys, offer counts and shares, shared and competitor-only product-card occurrences, plus the monitored retailer's exact-card price wins and comparison count against each competitor. Interpret target_price_win_rate_pct together with target_price_win_count and price_comparison_count; a null rate means there is no comparable same-currency evidence. Tied target prices count as wins. This retailer-only operation requires the retailer experience feature and does not support model filtering."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID; comma-separated UUIDs are accepted."
},
"funnel": {
"type": "string",
"description": "Filter by funnel stage; comma-separated awareness, consideration, and conversion values are accepted."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform; comma-separated platform identifiers are accepted. Retailer Shopping defaults to chatgpt."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID; comma-separated UUIDs are accepted. Use getPromptPersonas to list valid values."
},
"iteration_start_date": {
"type": "string",
"description": "Filter by Prompt Studio cycle start date (YYYY-MM-DD)."
}
},
"required": [],
"title": "getShoppingRetailerCategories",
"description": "getShoppingRetailerCategories: Get retailer Shopping performance grouped by the Prompt Studio monitoring taxonomy associated with each originating prompt. Each category includes its stable drill-down key, taxonomy IDs, name, definition, rank, recommended products, Shopping responses, Shopping Presence, Product Coverage, Offer Share, Price Win Rate, comparison count, median price gap, and all raw metric numerators/denominators. The response also reports classified, unclassified, and pending product counts; do not infer categories for pending or unclassified products. Interpret price_win_rate_pct only with price_comparison_count. This retailer-only operation requires the retailer experience feature and does not support model filtering."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"granularity": {
"type": "string",
"enum": [
"day",
"week"
],
"description": "Time granularity: 'day' or 'week' (optional, default: 'day')."
},
"top_brands": {
"type": "number",
"description": "Max number of brands before aggregating into 'Others' (optional, default: 10, max: 50)."
}
},
"required": [],
"title": "getShoppingShareOfShelf",
"description": "getShoppingShareOfShelf: Get share of shelf by brand (target and competitors) over time. Share of shelf is the percentage of products in shopping carousels per brand. Use for share-of-shelf trends and competitor comparison. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"granularity": {
"type": "string",
"enum": [
"day",
"week"
],
"description": "Time granularity: 'day' or 'week' (optional, default: 'day')."
}
},
"required": [],
"title": "getShoppingPositioning",
"description": "getShoppingPositioning: Get average position (rank) in shopping carousels over time. Lower position is better (1 = first). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"granularity": {
"type": "string",
"enum": [
"day",
"week"
],
"description": "Time granularity: 'day' or 'week' (optional, default: 'day')."
}
},
"required": [],
"title": "getShoppingReputation",
"description": "getShoppingReputation: Get average rating and review count over time for products in shopping carousels. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"granularity": {
"type": "string",
"enum": [
"day",
"week"
],
"description": "Time granularity: 'day' or 'week' (optional, default: 'day')."
}
},
"required": [],
"title": "getShoppingPricing",
"description": "getShoppingPricing: Get price competitiveness analytics over time (average price, etc.) for products in shopping carousels. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"limit": {
"type": "number",
"description": "Number of top retailers to return (optional, default: 10)."
}
},
"required": [],
"title": "getShoppingTopRetailers",
"description": "getShoppingTopRetailers: Get top retailers for the brand's products (share of offers by retailer). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"brand_category": {
"type": "string",
"enum": [
"target_brand",
"competitor",
"all"
],
"description": "Filter by brand category (optional, default: 'target_brand')."
},
"limit": {
"type": "number",
"description": "Number of top products to return (optional, default: 10)."
}
},
"required": [],
"title": "getShoppingTopProducts",
"description": "getShoppingTopProducts: Get top products by frequency of recommendation in shopping carousels. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID; comma-separated UUIDs are accepted."
},
"funnel": {
"type": "string",
"description": "Filter by funnel stage; comma-separated awareness, consideration, and conversion values are accepted."
},
"ai_platform": {
"type": "string",
"description": "Filter by AI platform; comma-separated platform identifiers are accepted. Retailer Shopping defaults to chatgpt."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID; comma-separated UUIDs are accepted. Use getPromptPersonas to list valid values."
},
"iteration_start_date": {
"type": "string",
"description": "Filter by Prompt Studio cycle start date (YYYY-MM-DD)."
},
"brand_category": {
"type": "string",
"enum": [
"target_brand",
"competitor",
"all"
],
"description": "Filter by brand category (optional, default: 'all')."
},
"page": {
"type": "number",
"description": "Page number (optional, default: 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (optional, default: 20, max: 100)."
},
"search": {
"type": "string",
"description": "Search in product_title, product_link, matched_brand, manufacturer_brand, or retailer (optional)."
},
"retailer": {
"type": "string",
"description": "Filter by retailer name contains (optional)."
},
"retailer_key": {
"type": "string",
"description": "Exact retailer identity key returned by getShoppingRetailerCompetition. Cannot be combined with retailer."
},
"monitoring_category_key": {
"type": "string",
"description": "Retailer-only category key returned by getShoppingRetailerCategories, including the literal unclassified."
},
"sort_by": {
"type": "string",
"enum": [
"appearance_count",
"avg_position",
"avg_rating",
"total_reviews",
"product_title",
"brand_category",
"matched_brand",
"manufacturer_brand",
"retailer"
],
"description": "Sort field (optional, default: 'appearance_count')."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (optional, default: 'desc')."
}
},
"required": [],
"title": "getShoppingProductList",
"description": "getShoppingProductList: Get paginated list of products from shopping results with search and sort. For retailer drill-downs, use retailer_key for an exact retailer identity match or monitoring_category_key for a Prompt Studio taxonomy category; the legacy retailer filter remains a fuzzy name match. Use page_size up to 100. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
}
},
"required": [],
"title": "getShoppingBrandComparison",
"description": "getShoppingBrandComparison: Get comparison of brand metrics vs competitors in shopping results (share of shelf, position, rating, price). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from getBrandTopics or user message."
},
"brand_category": {
"type": "string",
"enum": [
"target_brand",
"competitor",
"all"
],
"description": "Filter by brand category (optional, default: 'all')."
},
"page": {
"type": "number",
"description": "Page number (optional, default: 1)."
},
"page_size": {
"type": "number",
"description": "Items per page (optional, default: 20, max: 100)."
},
"sort_by": {
"type": "string",
"enum": [
"date",
"position",
"rating",
"reviews",
"product_title"
],
"description": "Sort field (optional, default: 'date')."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (optional, default: 'desc')."
}
},
"required": [],
"title": "getShoppingProductsList",
"description": "getShoppingProductsList: Get paginated list of product rows (one per response/product) from shopping results. Use page_size up to 100. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Shopping summary KPI row. Retailer rows include trigger rate, retailer visibility, offer share, product coverage, price-win rate, and raw counts."
},
"description": "the corresponding Meikai service"
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingSummary output",
"x-meikai-operation": "getShoppingSummary"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"eligible_response_count": {
"type": "integer",
"minimum": 0
},
"shopping_response_count": {
"type": "integer",
"minimum": 0
},
"retailer_visible_response_count": {
"type": "integer",
"minimum": 0
},
"total_product_occurrence_count": {
"type": "integer",
"minimum": 0
},
"covered_product_occurrence_count": {
"type": "integer",
"minimum": 0
},
"competitor_only_product_occurrence_count": {
"type": "integer",
"minimum": 0
},
"named_offer_count": {
"type": "integer",
"minimum": 0
},
"target_offer_count": {
"type": "integer",
"minimum": 0
},
"offer_share_pct": {
"type": [
"number",
"null"
],
"description": "Target-retailer offers divided by named-retailer offers, in percent."
},
"product_coverage_pct": {
"type": [
"number",
"null"
],
"description": "Product-card occurrences with the target retailer divided by all product-card occurrences, in percent."
}
},
"additionalProperties": true,
"required": [
"date",
"eligible_response_count",
"shopping_response_count",
"retailer_visible_response_count",
"total_product_occurrence_count",
"covered_product_occurrence_count",
"competitor_only_product_occurrence_count",
"named_offer_count",
"target_offer_count",
"offer_share_pct",
"product_coverage_pct"
]
},
"description": "Daily retailer Shopping trend and availability rows."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingRetailerTrends output",
"x-meikai-operation": "getShoppingRetailerTrends"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"retailer_key": {
"type": "string"
},
"retailer": {
"type": "string"
},
"is_target_retailer": {
"type": "boolean"
},
"offer_count": {
"type": "integer",
"minimum": 0
},
"offer_share_pct": {
"type": [
"number",
"null"
],
"description": "Retailer offers divided by all named-retailer offers, in percent."
},
"product_occurrence_count": {
"type": "integer",
"minimum": 0
},
"shared_product_occurrence_count": {
"type": "integer",
"minimum": 0
},
"competitor_only_product_occurrence_count": {
"type": "integer",
"minimum": 0
},
"price_comparison_count": {
"type": "integer",
"minimum": 0
},
"target_price_win_count": {
"type": "integer",
"minimum": 0
},
"target_price_win_rate_pct": {
"type": [
"number",
"null"
],
"description": "Target-retailer wins divided by exact-card same-currency comparisons, in percent; ties count as wins."
}
},
"additionalProperties": true,
"required": [
"retailer_key",
"retailer",
"is_target_retailer",
"offer_count",
"offer_share_pct",
"product_occurrence_count",
"shared_product_occurrence_count",
"competitor_only_product_occurrence_count",
"price_comparison_count",
"target_price_win_count",
"target_price_win_rate_pct"
]
},
"description": "Named-retailer offer, overlap, and target-relative price rows."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingRetailerCompetition output",
"x-meikai-operation": "getShoppingRetailerCompetition"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"monitoring_category_key": {
"type": "string"
},
"monitoring_category_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"definition": {
"type": [
"string",
"null"
]
},
"rank": {
"type": [
"integer",
"null"
]
},
"recommended_product_count": {
"type": "integer",
"minimum": 0
},
"shopping_response_count": {
"type": "integer",
"minimum": 0
},
"shopping_presence_pct": {
"type": [
"number",
"null"
],
"description": "Category Shopping responses with a target-retailer offer, in percent."
},
"product_coverage_pct": {
"type": [
"number",
"null"
],
"description": "Category product-card occurrences with a target-retailer offer, in percent."
},
"offer_share_pct": {
"type": [
"number",
"null"
],
"description": "Target-retailer offers divided by named offers in the category, in percent."
},
"price_win_rate_pct": {
"type": [
"number",
"null"
],
"description": "Target price wins divided by exact-card same-currency comparisons, in percent."
},
"price_comparison_count": {
"type": "integer",
"minimum": 0
},
"median_target_price_gap_pct": {
"type": [
"number",
"null"
],
"description": "Median target price gap versus the best competitor across comparable product cards, in percent."
},
"responses_with_target_retailer": {
"type": "integer",
"minimum": 0
},
"product_occurrence_count": {
"type": "integer",
"minimum": 0
},
"covered_product_occurrence_count": {
"type": "integer",
"minimum": 0
},
"named_offer_count": {
"type": "integer",
"minimum": 0
},
"target_retailer_offer_count": {
"type": "integer",
"minimum": 0
},
"target_price_win_count": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true,
"required": [
"monitoring_category_key",
"monitoring_category_ids",
"name",
"definition",
"rank",
"recommended_product_count",
"shopping_response_count",
"shopping_presence_pct",
"product_coverage_pct",
"offer_share_pct",
"price_win_rate_pct",
"price_comparison_count",
"median_target_price_gap_pct",
"responses_with_target_retailer",
"product_occurrence_count",
"covered_product_occurrence_count",
"named_offer_count",
"target_retailer_offer_count",
"target_price_win_count"
]
},
"description": "Retailer Shopping category-performance rows."
},
"classification": {
"type": "object",
"properties": {
"classifiedProductCount": {
"type": "integer",
"minimum": 0
},
"unclassifiedProductCount": {
"type": "integer",
"minimum": 0
},
"pendingProductCount": {
"type": "integer",
"minimum": 0
},
"complete": {
"type": "boolean"
}
},
"additionalProperties": false,
"required": [
"classifiedProductCount",
"unclassifiedProductCount",
"pendingProductCount",
"complete"
]
}
},
"additionalProperties": false,
"required": [
"success",
"data",
"classification"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingRetailerCategories output",
"x-meikai-operation": "getShoppingRetailerCategories"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Share of shelf (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingShareOfShelf output",
"x-meikai-operation": "getShoppingShareOfShelf"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Positioning (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingPositioning output",
"x-meikai-operation": "getShoppingPositioning"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Reputation (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingReputation output",
"x-meikai-operation": "getShoppingReputation"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Pricing (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingPricing output",
"x-meikai-operation": "getShoppingPricing"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Top retailers (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingTopRetailers output",
"x-meikai-operation": "getShoppingTopRetailers"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Top products (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingTopProducts output",
"x-meikai-operation": "getShoppingTopProducts"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Product list (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingProductList output",
"x-meikai-operation": "getShoppingProductList"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Brand comparison (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingBrandComparison output",
"x-meikai-operation": "getShoppingBrandComparison"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Result rows."
},
"pagination": {
"type": "object",
"additionalProperties": true,
"description": "Pagination metadata (page, page_size, total_count, etc.)."
}
},
"additionalProperties": true,
"description": "Paginated Meikai API list response."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShoppingProductsList output",
"x-meikai-operation": "getShoppingProductsList"
}
]
}Read bot traffic, referral, and real-prompt analytics. For AI-platform prompts and responses rather than site traffic, use meikai_prompt_analysis_read instead. Set operation to one of: getBotsData, getReferralData, getRealPromptsOverview, getRealPromptsBreakdown, getRealPromptsDemographics, getRealPromptsSampleMessages. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getBotsData",
"getReferralData",
"getRealPromptsOverview",
"getRealPromptsBreakdown",
"getRealPromptsDemographics",
"getRealPromptsSampleMessages"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID for brand website scope (XOR with company_id). Requires CDN log customer IDs on the brand."
},
"company_id": {
"type": "string",
"description": "Company UUID for publisher corporate website scope (XOR with brand_id). Requires publisher company type and CDN log customer IDs on the company."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (required)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (required)"
},
"host": {
"type": "string",
"description": "Optional host filter (e.g., 'www.meikai.ai'). If not provided, returns data for all hosts."
},
"platform": {
"type": "string",
"enum": [
"OpenAI",
"Perplexity",
"Google",
"Microsoft"
],
"description": "Optional verified platform filter. Only verified bot platforms are supported."
},
"bot_agent": {
"type": "string",
"description": "Optional verified bot-agent label filter (for example: 'GPTBot (OpenAI training crawler)' or 'Googlebot (Google search crawler)')."
},
"path_contains": {
"type": "string",
"description": "Optional case-insensitive substring filter for path coverage checks (for example: 'pricing', '/blog/', 'product'). Useful to check whether specific page groups are crawled by verified bots."
}
},
"required": [
"start_date",
"end_date"
],
"title": "getBotsData",
"description": "getBotsData: Get verified bot traffic data from CDN logs for a brand website or a publisher company website. This data only includes crawler traffic that matches both a known bot User-Agent and official vendor IP ranges. It shows which pages on your website are being crawled by verified AI platforms like OpenAI, Perplexity, Google, and Microsoft. Returns verified platform breakdown, verified bot-agent breakdown, daily trends, top pages (readable pages), and unreadable pages with HTTP status >= 400 (for example 404/403/500) so you can see what LLM bots cannot read. Bot-agent labels use canonical Site Scanner names (for example: 'GPTBot (OpenAI training crawler)' and 'Googlebot (Google search crawler)') and are aligned with domain robots policy summaries. Provide exactly one of brand_id or company_id (publisher company). Requires CDN log customer IDs configured on the brand or company. If ids or dates are not provided, uses defaults from UI context when available."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID (XOR with company_id)."
},
"company_id": {
"type": "string",
"description": "Publisher company UUID for corporate website pixel (XOR with brand_id)."
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (required)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (required)"
},
"platform": {
"type": "string",
"enum": [
"OpenAI",
"Perplexity",
"Anthropic",
"Gemini",
"Google Search",
"Bing",
"Copilot",
"You.com",
"DeepSeek"
],
"description": "Optional platform filter. If not provided, returns data for all platforms."
}
},
"required": [
"start_date",
"end_date"
],
"title": "getReferralData",
"description": "getReferralData: Get referral traffic data from tracking_events (website traffic captured by tracking pixel) for a brand website or publisher company website. This data shows website visitors who came from LLM platforms (OpenAI, Perplexity, Anthropic, Google, Microsoft, You.com, DeepSeek) based on the utm_source parameter in the URL. When users click links from LLM platforms, those links contain utm_source that identifies the source platform. Returns platform breakdown, daily trends, and top pages. This is different from getBotsData which uses CDN logs - this uses actual user traffic data from tracking pixels. Provide exactly one of brand_id or company_id (publisher). If ids or dates are not provided, uses defaults from UI context when available."
},
{
"type": "object",
"properties": {
"start_month": {
"type": "string",
"description": "Start month in YYYY-MM format (optional). If not provided, uses latest available month only. If only start_month is provided, uses it as both start and end (single month)."
},
"end_month": {
"type": "string",
"description": "End month in YYYY-MM format (optional). If not provided, uses latest available month only. If only end_month is provided, uses it as both start and end (single month)."
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional). If provided, automatically filters by the brand's country."
}
},
"required": [],
"title": "getRealPromptsOverview",
"description": "getRealPromptsOverview: Get overview of real user traffic: number of panelists and time-series events (messages over time). Data is only available monthly (no daily granularity). Latest available data depends on current date: after the 20th of current month, previous month is available; before the 20th, month before previous is available. Maximum 12 months of data returned to prevent token limit issues."
},
{
"type": "object",
"properties": {
"dimension": {
"type": "string",
"enum": [
"models",
"apps",
"devices",
"languages",
"subscriptions"
],
"description": "Dimension to breakdown by: 'models' (model usage), 'apps' (app usage), 'devices' (device breakdown), 'languages' (language breakdown), 'subscriptions' (subscription breakdown)"
},
"start_month": {
"type": "string",
"description": "Start month in YYYY-MM format (optional). If not provided, uses latest available month only. If only start_month is provided, uses it as both start and end (single month)."
},
"end_month": {
"type": "string",
"description": "End month in YYYY-MM format (optional). If not provided, uses latest available month only. If only end_month is provided, uses it as both start and end (single month)."
},
"limit": {
"type": "number",
"description": "Number of results to return (optional, default: 10, max: 20)"
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional). If provided, automatically filters by the brand's country."
}
},
"required": [
"dimension"
],
"title": "getRealPromptsBreakdown",
"description": "getRealPromptsBreakdown: Get breakdown of real user traffic by dimension (models, apps, devices, languages, subscriptions). Data is only available monthly (no daily granularity). Latest available data depends on current date: after the 20th of current month, previous month is available; before the 20th, month before previous is available. Returns top N results per dimension to limit size. Maximum 20 items per dimension."
},
{
"type": "object",
"properties": {
"start_month": {
"type": "string",
"description": "Start month in YYYY-MM format (optional). If not provided, uses latest available month only. If only start_month is provided, uses it as both start and end (single month)."
},
"end_month": {
"type": "string",
"description": "End month in YYYY-MM format (optional). If not provided, uses latest available month only. If only end_month is provided, uses it as both start and end (single month)."
},
"demographic_dimension": {
"type": "string",
"enum": [
"age",
"gender",
"income",
"education",
"employment",
"marital_status"
],
"description": "Demographic dimension to breakdown by (optional, defaults to all). Options: 'age' (age_band), 'gender', 'income' (household_income), 'education', 'employment', 'marital_status'"
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional). If provided, automatically filters by the brand's country."
}
},
"required": [],
"title": "getRealPromptsDemographics",
"description": "getRealPromptsDemographics: Get demographic breakdown of real user traffic (age, gender, income, etc.). Data is only available monthly (no daily granularity). Latest available data depends on current date: after the 20th of current month, previous month is available; before the 20th, month before previous is available. Returns aggregated data, not individual records."
},
{
"type": "object",
"properties": {
"start_month": {
"type": "string",
"description": "Start month in YYYY-MM format (optional). If not provided, uses latest available month only. If only start_month is provided, uses it as both start and end (single month)."
},
"end_month": {
"type": "string",
"description": "End month in YYYY-MM format (optional). If not provided, uses latest available month only. If only end_month is provided, uses it as both start and end (single month)."
},
"limit": {
"type": "number",
"description": "Number of sample messages to return (optional, default: 5, max: 10)"
},
"platform": {
"type": "string",
"description": "Filter by platform (optional, e.g., 'chatgpt', 'perplexity', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by model (optional, e.g., 'gpt-4', 'gemini-3.5-flash')"
},
"brand_id": {
"type": "string",
"description": "Brand UUID (optional). If provided, automatically filters by the brand's country."
}
},
"required": [],
"title": "getRealPromptsSampleMessages",
"description": "getRealPromptsSampleMessages: Get sample real user messages from the traffic. Useful for understanding query patterns. Data is only available monthly (no daily granularity). Latest available data depends on current date: after the 20th of current month, previous month is available; before the 20th, month before previous is available. Returns maximum 10 examples to avoid huge results. IMPORTANT: This tool returns metadata only (date, platform, model, country, device, etc.) but NOT the actual message content for privacy protection. When presenting results, focus on aggregated statistics and patterns from metadata, not specific message text."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Bot traffic data (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBotsData output",
"x-meikai-operation": "getBotsData"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Referral data (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getReferralData output",
"x-meikai-operation": "getReferralData"
},
{
"oneOf": [
{
"type": "object",
"properties": {},
"additionalProperties": true,
"description": "Panelists and events overview (the corresponding Meikai service and events/)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getRealPromptsOverview output",
"x-meikai-operation": "getRealPromptsOverview"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Real traffic breakdown by dimension."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getRealPromptsBreakdown output",
"x-meikai-operation": "getRealPromptsBreakdown"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Demographics (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getRealPromptsDemographics output",
"x-meikai-operation": "getRealPromptsDemographics"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Sample messages metadata (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getRealPromptsSampleMessages output",
"x-meikai-operation": "getRealPromptsSampleMessages"
}
]
}Preview, validate, and apply user invitations, access changes, and user status changes. Set operation to one of: inviteUser, bulkInviteUsers, setUserBrandAccess, setUserStatus, validateInviteUser, validateBulkInviteUsers, validateSetUserBrandAccess, validateSetUserStatus. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"inviteUser",
"bulkInviteUsers",
"setUserBrandAccess",
"setUserStatus",
"validateInviteUser",
"validateBulkInviteUsers",
"validateSetUserBrandAccess",
"validateSetUserStatus"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"user": {
"type": "object"
}
},
"required": [],
"title": "inviteUser",
"description": "inviteUser: Invite one user through the corresponding Meikai service with preview/apply confirmation."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"users": {
"type": "array",
"maxItems": 100
},
"on_invalid_records": {
"type": "string",
"enum": [
"reject",
"skip"
],
"description": "What to do when some records are invalid: 'reject' (the default) imports nothing, 'skip' imports only the records that hold up. Never pick 'skip' on your own."
}
},
"required": [],
"title": "bulkInviteUsers",
"description": "bulkInviteUsers: Invite up to 100 users through the corresponding Meikai service with preview/apply confirmation. Always call mode=preview first; the response includes confirmation_token required for apply. Each user object supports email, company_id (company administrators), brand_access_assignments [{brand_id, role}] for home-company brands, shared_brand_access_assignments [{brand_id, role}] for cross-company (external) brands, or legacy brand_ids + brand_role. The preview validates every record and reports the invalid ones; apply then invites each record on its own and returns a per-record result, so a record that fails at that point does not hold back the others. A rejected record is not an error to retry: details.report lists every invalid record with its index, what identifies it, and what is wrong with it. Report those to the user, then ask which they want -- fix the records and preview again, or import the valid ones with on_invalid_records='skip' and leave the rest out. Do not choose for them, and do not silently drop records."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"user_id": {
"type": "string"
},
"assignments": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"brand_id": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"OWNER",
"EDITOR",
"VIEWER",
"MONITOR_ONLY"
],
"description": "Brand Owner in the UI is OWNER, not BRAND_OWNER."
}
},
"required": [
"brand_id",
"role"
]
}
}
},
"required": [],
"title": "setUserBrandAccess",
"description": "setUserBrandAccess: Replace a user's home-company brand access through the corresponding Meikai service with preview/apply confirmation. Each assignment needs brand_id and role (OWNER | EDITOR | VIEWER | MONITOR_ONLY). UI label Brand Owner = role OWNER."
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"preview",
"apply"
]
},
"confirmation_token": {
"type": "string"
},
"confirmation_phrase": {
"type": "string",
"enum": [
"CONFIRM_MANAGEMENT_CHANGE"
]
},
"user_ids": {
"type": "array",
"maxItems": 100
},
"emails": {
"type": "array",
"maxItems": 100
},
"company_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive"
]
}
},
"required": [],
"title": "setUserStatus",
"description": "setUserStatus: Activate or deactivate up to 100 users through the corresponding Meikai service with preview/apply confirmation. Pass user_ids and/or emails; when using emails as a company administrators, include company_id."
},
{
"type": "object",
"properties": {
"user": {
"type": "object"
}
},
"required": [
"user"
],
"title": "validateInviteUser",
"description": "validateInviteUser: Validate user invite payload via the corresponding Meikai service without persisting."
},
{
"type": "object",
"properties": {
"users": {
"type": "array",
"maxItems": 100
},
"on_invalid_records": {
"type": "string",
"enum": [
"reject",
"skip"
],
"description": "What to do when some records are invalid: 'reject' (the default) imports nothing, 'skip' imports only the records that hold up. Never pick 'skip' on your own."
}
},
"required": [
"users"
],
"title": "validateBulkInviteUsers",
"description": "validateBulkInviteUsers: Validate bulk user invites via the corresponding Meikai service without persisting. Every record is validated on its own: a 400 carries details.report with each invalid record. A rejected record is not an error to retry: details.report lists every invalid record with its index, what identifies it, and what is wrong with it. Report those to the user, then ask which they want -- fix the records and preview again, or import the valid ones with on_invalid_records='skip' and leave the rest out. Do not choose for them, and do not silently drop records."
},
{
"type": "object",
"properties": {
"user_id": {
"type": "string"
},
"assignments": {
"type": "array",
"maxItems": 100
}
},
"required": [
"user_id",
"assignments"
],
"title": "validateSetUserBrandAccess",
"description": "validateSetUserBrandAccess: Validate brand access replacement via the corresponding Meikai service without persisting."
},
{
"type": "object",
"properties": {
"user_ids": {
"type": "array",
"maxItems": 100
},
"emails": {
"type": "array",
"maxItems": 100
},
"company_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"status"
],
"title": "validateSetUserStatus",
"description": "validateSetUserStatus: Validate bulk user status change via the corresponding Meikai service without persisting."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User invitation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "inviteUser output",
"x-meikai-operation": "inviteUser"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk user invitation preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "bulkInviteUsers output",
"x-meikai-operation": "bulkInviteUsers"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User brand access preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "setUserBrandAccess output",
"x-meikai-operation": "setUserBrandAccess"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User status update preview or apply result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "setUserStatus output",
"x-meikai-operation": "setUserStatus"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User invitation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateInviteUser output",
"x-meikai-operation": "validateInviteUser"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Bulk user invitation validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateBulkInviteUsers output",
"x-meikai-operation": "validateBulkInviteUsers"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User brand access validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateSetUserBrandAccess output",
"x-meikai-operation": "validateSetUserBrandAccess"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "User status validation result."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "validateSetUserStatus output",
"x-meikai-operation": "validateSetUserStatus"
}
]
}Read AI visibility metrics, average brand position rank, competitive rankings, share of voice/model/platform, and KPI cards. Match the requested metric, result granularity, grouping dimension, and entity coverage to the operation capabilities. When explicit start_date and end_date are known, omit lookback_days. For visibility, competitive, or prompt performance breakdowns, use meikai_breakdown_read instead - except the per-topic competitive leaderboard, getVisibilityRankByTopic, which lives here. Set operation to one of: getDailyVisibility, getVisibilityRank, getVisibilityRankByTopic, getShareOfVoice, getShareOfModel, getShareOfPlatform, getVisibilityMetric, getBrandPositionMetric, getMentionsMetric, getResponsesMetric, getShareOfVoiceCard, getSourceOfCitations, getVisibilityMetrics. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded. Select using these operation capabilities (machine-readable JSON): [{"entity_coverage":"target_brand","evidence_fields":["date","visibility"],"grouping_dimensions":[],"metrics":["visibility_rate"],"operation":"getDailyVisibility","result_granularity":"time_series"},{"entity_coverage":"target_brand_and_all_competitors","evidence_fields":["responses_with_mentions","total_responses","visibility","rank"],"grouping_dimensions":[],"metrics":["visibility_rate","visibility_rank"],"operation":"getVisibilityRank","result_granularity":"entity_leaderboard"},{"entity_coverage":"target_brand_and_all_competitors_per_topic","evidence_fields":["visibility","rank"],"grouping_dimensions":["topic"],"metrics":["visibility_rate","visibility_rank"],"operation":"getVisibilityRankByTopic","result_granularity":"entity_leaderboard"},{"entity_coverage":"target_brand_and_competitors","evidence_fields":["mentions","share_of_voice"],"grouping_dimensions":[],"metrics":["share_of_voice"],"operation":"getShareOfVoice","result_granularity":"entity_leaderboard"},{"entity_coverage":"target_brand","evidence_fields":["visibility"],"grouping_dimensions":["model"],"metrics":["visibility_rate"],"operation":"getShareOfModel","result_granularity":"dimension_breakdown"},{"entity_coverage":"target_brand","evidence_fields":["visibility"],"grouping_dimensions":["platform"],"metrics":["visibility_rate"],"operation":"getShareOfPlatform","result_granularity":"dimension_breakdown"},{"entity_coverage":"target_brand","evidence_fields":["responses_with_mentions","total_responses","value"],"grouping_dimensions":[],"metrics":["visibility_rate"],"operation":"getVisibilityMetric","result_granularity":"metric_card"},{"entity_coverage":"target_brand","evidence_fields":["observation_count","brand_count_avg","value"],"grouping_dimensions":[],"metrics":["average_brand_position"],"operation":"getBrandPositionMetric","result_granularity":"metric_card"},{"entity_coverage":"target_brand","evidence_fields":["brand_mentions","responses_with_mentions","value"],"grouping_dimensions":[],"metrics":["mentions"],"operation":"getMentionsMetric","result_granularity":"metric_card"},{"entity_coverage":"target_brand","evidence_fields":["value"],"grouping_dimensions":[],"metrics":["analyzed_responses"],"operation":"getResponsesMetric","result_granularity":"metric_card"},{"entity_coverage":"target_brand","evidence_fields":["brand_mentions","all_brand_mentions","value"],"grouping_dimensions":[],"metrics":["share_of_voice"],"operation":"getShareOfVoiceCard","result_granularity":"metric_card"},{"entity_coverage":"target_brand","evidence_fields":["citations"],"grouping_dimensions":["citation_media_type"],"metrics":["citations"],"operation":"getSourceOfCitations","result_granularity":"dimension_breakdown"},{"entity_coverage":"target_brand","evidence_fields":["responses_with_mentions","total_responses","value"],"grouping_dimensions":[],"metrics":["visibility_rate"],"operation":"getVisibilityMetrics","result_granularity":"metric_card"}]. Grouping dimensions use these meanings (machine-readable JSON): {"citation_media_type":"citation source category","model":"concrete named model or version within a platform; use only when the request identifies a model/version or explicitly asks for models","platform":"provider or product surface; Meikai grouping for an unqualified LLM or environment","topic":"configured semantic topic"}.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getDailyVisibility",
"getVisibilityRank",
"getVisibilityRankByTopic",
"getShareOfVoice",
"getShareOfModel",
"getShareOfPlatform",
"getVisibilityMetric",
"getBrandPositionMetric",
"getMentionsMetric",
"getResponsesMetric",
"getShareOfVoiceCard",
"getSourceOfCitations",
"getVisibilityMetrics"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to the server's last complete day (yesterday))"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics). Use this to filter data to a specific topic. To include topic as a dimension in the output, use dimensions=['topic'] instead or in addition."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage. Use this to filter data to a specific funnel stage. To include funnel as a dimension in the output, use dimensions=['funnel'] instead or in addition."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-3.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
},
"dimensions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"topic",
"funnel"
]
},
"description": "Dimensions to include in the result set. Provide an array of dimension names, e.g., ['topic', 'funnel']. When 'topic' is included, each result row will have a 'topicId' field. When 'funnel' is included, each result row will have a 'funnel' field. This enables dimensional analysis. You can combine this with topic_id and/or funnel filter parameters to filter while including dimensions."
}
},
"required": [],
"title": "getDailyVisibility",
"description": "getDailyVisibility: Get daily visibility data for a brand over a date range. Visibility is the percentage of LLM responses that mention the brand (responses_with_mentions / total_responses). Returns per-day visibility values for each date in the range, allowing day-over-day trend analysis. Each result includes: date, brandName, value (visibility percentage), responses_with_mentions (count of responses mentioning the brand), and total_responses (total responses analyzed for that date). IMPORTANT: To enable dimensional analysis, use the 'dimensions' parameter. Provide dimensions as an array of strings, e.g., ['topic', 'funnel'] to include both topic and funnel as dimensions in the result set. When 'topic' is in dimensions, each result row will include a 'topicId' field. When 'funnel' is in dimensions, each result row will include a 'funnel' field. You can also provide topic_id and/or funnel as separate filter parameters to filter the data while including dimensions. For example: dimensions=['topic', 'funnel'] with topic_id='xxx' will show visibility broken down by topic and funnel dimensions, filtered to the specified topic. Also supports filtering by platform and model (these do not appear as dimensions). If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to the server's last complete day (yesterday))"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-3.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getVisibilityRank",
"description": "getVisibilityRank: Get one visibility leaderboard showing how the target brand ranks against all competitors in one filtered scope. It returns an entity leaderboard, not a grouped breakdown. Use a breakdown operation when the requested result must contain one row per platform, model, topic, or funnel. Use each row's `rank` value as-is (do not subtract 1 or recompute excluding the target brand). Supports filtering by funnel, platform, model, and topic. A platform filter selects a provider surface; a model filter selects a concrete model name. When explicit start_date and end_date are known, omit lookback_days. Missing brand or dates use the UI-context defaults."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
},
"limit_per_topic": {
"type": "integer",
"minimum": 1,
"maximum": 15,
"default": 10,
"description": "Max brands returned per topic (default 10, max 15). The monitored brand is included even when its rank exceeds this."
},
"page": {
"type": "integer",
"minimum": 1,
"default": 1,
"description": "Page of TOPICS (not of brands)."
},
"page_size": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 10,
"description": "Topics per page (default and max 10)."
},
"sort_topics_by": {
"type": "string",
"enum": [
"responses",
"name"
],
"default": "responses",
"description": "Topic ordering: by response volume (default) or alphabetically."
},
"favorite_competitors_only": {
"type": "boolean",
"default": false,
"description": "Restrict to the target brand plus favorite competitors. This changes the ranking universe, so ranks differ from the full-market ones."
}
},
"required": [],
"title": "getVisibilityRankByTopic",
"description": "getVisibilityRankByTopic: Get the competitive leaderboard broken down by topic: for every topic the brand tracks, the ranked list of brands by visibility, with rank, previous_rank, trend, visibility_pct and previous_visibility_pct computed WITHIN that topic (the denominator is the topic's own response volume, not the brand-wide one). Use it for questions like 'which topics am I winning or losing', 'where does competitor X beat me', or 'on which topic did my rank drop'. Results are grouped per topic and each group reports ranked_brand_count, returned_count and truncated. IMPORTANT: ranks restart at 1 in every topic, so they are NOT comparable across topics, and NOT comparable to getVisibilityRank, which ranks across all topics combined - never merge the two into one ordering. A brand missing from a topic can mean four different things: it is outside the top limit_per_topic, it has no data in the current period, it is an ignored competitor, or ranking_scope restricts the list to favorites; it never means the brand left the market. Setting favorite_competitors_only CHANGES THE RANKING (ranks are then computed inside the favorite set only), it does not merely shorten the payload. The monitored brand is always included when it has data, even below the cap. For the full uncapped leaderboard of a single topic, call getVisibilityRank with that topic_id instead. Requires one explicit brand_id; the company-wide scope is not supported."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to the server's last complete day (yesterday))"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-3.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getShareOfVoice",
"description": "getShareOfVoice: Get share of voice metrics showing what percentage of total brand mentions belong to your brand versus competitors. Share of voice is calculated as your brand's mentions divided by total mentions across all brands. A higher share means your brand dominates the conversation in LLM responses. Returns breakdown by brand with percentages. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to the server's last complete day (yesterday))"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-3.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getShareOfModel",
"description": "getShareOfModel: Get share of model metrics showing visibility breakdown by AI model (e.g. GPT-5, Gemini 3.5 Flash). Shows which specific models mention your brand most often and the visibility percentage for each model. Helps identify which models are most important for your brand's AI visibility. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to the server's last complete day (yesterday))"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-3.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getShareOfPlatform",
"description": "getShareOfPlatform: Get share of platform metrics showing visibility breakdown by AI platform (e.g. ChatGPT, Gemini). Shows which platforms mention your brand most often and the visibility percentage for each platform. Helps identify which platforms are most important for your brand's AI visibility. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getVisibilityMetric",
"description": "getVisibilityMetric: Brand Monitor visibility card: share of analyzed responses that mention the target brand. Success: JSON array (usually one row). value = responses_with_mentions / total_responses; previous_value; pct_change; responses_with_mentions; total_responses. Filters: brand_id, lookback_days (preferred for relative periods; overrides dates), start_date, end_date (API-required unless MCP context fills them), topic_id, funnel, platform (maps to ai_platform), model, calculation_mode, lens_competitor_name (Competitor Lens: analyze a competitor instead of the brand). Error: {success:false,error:string}."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getBrandPositionMetric",
"description": "getBrandPositionMetric: Get the brand's average position rank in LLM responses. Use this for questions such as 'what is my brand average position?', 'average brand rank?', or 'brand position rank?'. This is not visibility rank and not shopping carousel position. Lower is better; position 1 means the brand is the first eligible brand mentioned. Success: JSON array (usually one row). value = average response-level position rank across responses mentioning the brand; previous_value; pct_change (positive means the average numeric rank increased/worsened, negative means it improved); observation_count; previous_observation_count; brand_count_avg = average distinct eligible brands mentioned in those responses. Filters: brand_id, lookback_days (preferred for relative periods; overrides dates), start_date, end_date (API-required unless MCP context fills them), topic_id, funnel, platform (maps to ai_platform), model, calculation_mode, lens_competitor_name (Competitor Lens: analyze a competitor instead of the brand). Error: {success:false,error:string}."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "Brand UUID. Optional when MCP context provides the current brand."
},
"start_date": {
"type": "string",
"description": "Start date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided."
},
"end_date": {
"type": "string",
"description": "End date (YYYY-MM-DD). Omitted dates are resolved server-side from MCP context date_range_preset + reference_end_date, or from lookback_days when provided; otherwise defaults to the server's last complete day (yesterday)."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic UUID (comma-separated UUIDs allowed)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage."
},
"platform": {
"type": "string",
"description": "Filter by AI platform (maps to query param ai_platform), e.g. chatgpt, gemini, googleaioverview."
},
"model": {
"type": "string",
"description": "Filter by AI model name (platform-specific)."
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getMentionsMetric",
"description": "getMentionsMetric: Brand Monitor mentions card: average target-brand mentions per response that mentions the brand (not raw mention volume). Success: JSON array (usually one row). value = brand_mentions / responses_with_mentions; previous_value; pct_change; brand_mentions (raw weighted count); responses_with_mentions (denominator). Filters: brand_id, lookback_days (preferred for relative periods; overrides dates), start_date, end_date (API-required unless MCP context fills them), topic_id, funnel, platform (maps to ai_platform), model, calculation_mode, lens_competitor_name (Competitor Lens: analyze a competitor instead of the brand). Error: {success:false,error:string}."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to the server's last complete day (yesterday))"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-3.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getResponsesMetric",
"description": "getResponsesMetric: Get responses count metric showing the total number of LLM responses analyzed for a brand, with period-over-period comparison. This is the denominator used in visibility calculations (visibility = mentions / responses_count). Returns current response count, previous count, and percentage change. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to the server's last complete day (yesterday))"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-3.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getShareOfVoiceCard",
"description": "getShareOfVoiceCard: Get share of voice card data showing what percentage of total brand mentions belong to your brand versus competitors, with period-over-period comparison. Share of voice = your_brand_mentions / total_mentions_all_brands. Returns current share percentage, previous share, and percentage change to track competitive positioning trends. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to the server's last complete day (yesterday))"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Extract from the user's message or from previous tool results (e.g., from getBrandTopics)."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-3.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getSourceOfCitations",
"description": "getSourceOfCitations: Get source of citations breakdown by media type showing where citations come from (Earned Media, Competition, Social Media, Owned Media). Citations are URLs/sources that LLMs reference when mentioning your brand. This shows the distribution of citation sources, helping understand which types of media drive your brand's AI visibility. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, or end_date are not provided, uses defaults from UI context (current brand and last 7 days)."
},
{
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"description": "The UUID of the brand (optional, defaults to current brand)"
},
"start_date": {
"type": "string",
"description": "Start date in YYYY-MM-DD format (optional, defaults to last 7 days)"
},
"end_date": {
"type": "string",
"description": "End date in YYYY-MM-DD format (optional, defaults to the server's last complete day (yesterday))"
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Inclusive lookback window in days (language-agnostic). Ends at reference_end_date from MCP context when available (last available data day / lastRunDate), otherwise at the server's last complete day (yesterday). When set, overrides start_date/end_date. Prefer this alone for relative periods such as 'last 30 days' \u2014 omit start_date and end_date."
},
"topic_id": {
"type": "string",
"description": "Filter by topic ID (UUID). Optional, defaults to current topic from UI context if available."
},
"funnel": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
],
"description": "Filter by funnel stage"
},
"platform": {
"type": "string",
"description": "Filter by AI platform (e.g. 'chatgpt', 'gemini', 'googleaioverview')"
},
"model": {
"type": "string",
"description": "Filter by AI model name (e.g. 'gpt-5', 'gemini-3.5-flash'). Model names vary by platform"
},
"persona_id": {
"type": "string",
"description": "Filter by Prompt Studio persona UUID. Resolves to the persona's assigned active regular prompts (same as Brand Monitor persona filter). Use getPromptPersonas to list valid ids for the brand."
},
"calculation_mode": {
"type": "string",
"enum": [
"classic",
"weighted"
],
"description": "Calculation mode for visibility metrics. 'classic' uses unweighted calculations (default). 'weighted' applies Statcounter AI outbound-referral share weighting; this does not represent users or total AI usage."
},
"lens_competitor_name": {
"type": "string",
"description": "Competitor Lens: analyze this competitor instead of the monitored brand, keeping every other filter identical (same scope as the webapp's Competitor Lens selector). Accepts the competitor's name or any of its aliases, case-insensitive. Use getCompetitorMetrics to list the brand's competitors. Omit to analyze the brand itself."
}
},
"required": [],
"title": "getVisibilityMetrics",
"description": "getVisibilityMetrics: Get visibility metrics for a brand within a date range. Returns visibility data (percentage of LLM responses mentioning the brand) and trends with period-over-period comparison. Visibility = responses_with_mentions / total_responses. This is a comprehensive metric showing how visible your brand is in AI responses. Supports filtering by funnel (awareness, consideration, conversion), platform, model, and topic. If brand_id, start_date, end_date, or topic_id are not provided, uses defaults from UI context (current brand, last 7 days, and current topic if available)."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Daily visibility time series (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getDailyVisibility output",
"x-meikai-operation": "getDailyVisibility"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Visibility rank rows (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getVisibilityRank output",
"x-meikai-operation": "getVisibilityRank"
},
{
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Per-topic leaderboard groups, each with its own ranking and caps (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getVisibilityRankByTopic output",
"x-meikai-operation": "getVisibilityRankByTopic"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Share of voice breakdown (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShareOfVoice output",
"x-meikai-operation": "getShareOfVoice"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Share of model breakdown (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShareOfModel output",
"x-meikai-operation": "getShareOfModel"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Share of platform breakdown (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShareOfPlatform output",
"x-meikai-operation": "getShareOfPlatform"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Metric value for the current period."
},
"previous_value": {
"type": [
"number",
"null"
],
"description": "Metric value for the previous period of equal length."
},
"pct_change": {
"type": [
"number",
"null"
],
"description": "Relative change vs previous_value (decimal, e.g. 0.1 = +10%)."
},
"responses_with_mentions": {
"type": [
"number",
"null"
],
"description": "Responses mentioning the target brand (weighted)."
},
"total_responses": {
"type": [
"number",
"null"
],
"description": "Total responses analyzed (weighted)."
}
},
"additionalProperties": false,
"description": "Visibility card row: value = responses_with_mentions / total_responses."
},
"description": "Visibility card rows (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getVisibilityMetric output",
"x-meikai-operation": "getVisibilityMetric"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Metric value for the current period."
},
"previous_value": {
"type": [
"number",
"null"
],
"description": "Metric value for the previous period of equal length."
},
"pct_change": {
"type": [
"number",
"null"
],
"description": "Relative change in average numeric rank vs the previous period. Positive means the rank increased/worsened; negative means it decreased/improved."
},
"observation_count": {
"type": "integer",
"minimum": 0,
"description": "Responses used for the current average position."
},
"previous_observation_count": {
"type": "integer",
"minimum": 0,
"description": "Responses used for the previous-period average position."
},
"brand_count_avg": {
"type": [
"number",
"null"
],
"description": "Average distinct eligible brands mentioned in current-period responses where the analyzed brand has a position."
}
},
"additionalProperties": false,
"description": "Average Brand Monitor position card. For each response mentioning the analyzed brand, brands are ranked by first mention; value is the average response-level rank. Lower is better and 1 means mentioned first."
},
"description": "Average brand-position card rows (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getBrandPositionMetric output",
"x-meikai-operation": "getBrandPositionMetric"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Metric value for the current period."
},
"previous_value": {
"type": [
"number",
"null"
],
"description": "Metric value for the previous period of equal length."
},
"pct_change": {
"type": [
"number",
"null"
],
"description": "Relative change vs previous_value (decimal, e.g. 0.1 = +10%)."
},
"brand_mentions": {
"type": [
"number",
"null"
],
"description": "Weighted sum of target-brand mention counts in the period."
},
"responses_with_mentions": {
"type": [
"number",
"null"
],
"description": "Weighted count of responses that mention the target brand."
}
},
"additionalProperties": false,
"description": "Mentions card row: value = brand_mentions / responses_with_mentions (average mentions per response with a brand mention)."
},
"description": "Mentions card rows (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getMentionsMetric output",
"x-meikai-operation": "getMentionsMetric"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Total responses in the current period."
},
"promptCount": {
"type": [
"number",
"null"
],
"description": "Distinct prompts in the period."
},
"modelCount": {
"type": [
"number",
"null"
],
"description": "Distinct models in the period."
}
},
"additionalProperties": false,
"description": "Responses count card (single object, not period comparison)."
},
"description": "Responses count card (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getResponsesMetric output",
"x-meikai-operation": "getResponsesMetric"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Metric value for the current period."
},
"previous_value": {
"type": [
"number",
"null"
],
"description": "Metric value for the previous period of equal length."
},
"pct_change": {
"type": [
"number",
"null"
],
"description": "Relative change vs previous_value (decimal, e.g. 0.1 = +10%)."
},
"brand_mentions": {
"type": [
"number",
"null"
],
"description": "Target brand mention count (weighted)."
},
"total_mentions": {
"type": [
"number",
"null"
],
"description": "Total mentions across target brand and competitors (weighted)."
}
},
"additionalProperties": false,
"description": "Share-of-voice card row: value = brand_mentions / total_mentions."
},
"description": "Share-of-voice card rows (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getShareOfVoiceCard output",
"x-meikai-operation": "getShareOfVoiceCard"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Analytics result row."
},
"description": "Citation media-type breakdown (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getSourceOfCitations output",
"x-meikai-operation": "getSourceOfCitations"
},
{
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Metric value for the current period."
},
"previous_value": {
"type": [
"number",
"null"
],
"description": "Metric value for the previous period of equal length."
},
"pct_change": {
"type": [
"number",
"null"
],
"description": "Relative change vs previous_value (decimal, e.g. 0.1 = +10%)."
},
"responses_with_mentions": {
"type": [
"number",
"null"
],
"description": "Responses mentioning the target brand (weighted)."
},
"total_responses": {
"type": [
"number",
"null"
],
"description": "Total responses analyzed (weighted)."
}
},
"additionalProperties": false,
"description": "Visibility card row: value = responses_with_mentions / total_responses."
},
"description": "Visibility card rows (the corresponding Meikai service)."
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getVisibilityMetrics output",
"x-meikai-operation": "getVisibilityMetrics"
}
]
}Read portfolio and markets summaries for the current workspace. Set operation to one of: getWorkspacePortfolioSummary, getWorkspaceMarketComparisonSummary. Use exactly one router envelope: {operation: <name>, arguments: {<legacy parameters>}}. Do not use a parameters key or nest another operation/arguments envelope. For compatibility, top-level parameters other than operation and arguments are also forwarded.
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": [
"getWorkspacePortfolioSummary",
"getWorkspaceMarketComparisonSummary"
],
"description": "Legacy Meikai MCP tool to run through this v2 router."
},
"arguments": {
"type": "object",
"description": "Arguments for the selected operation. Use the same fields as the legacy tool named by operation. A brand_id, when accepted, must be a UUID.",
"additionalProperties": true,
"anyOf": [
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace UUID; defaults to the active Workspace."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Relative lookback; overrides explicit dates."
},
"start_date": {
"type": "string",
"format": "date"
},
"end_date": {
"type": "string",
"format": "date"
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional ISO-2 market subset."
},
"funnel": {
"type": "array",
"items": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
]
}
},
"platform": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [],
"title": "getWorkspacePortfolioSummary",
"description": "getWorkspacePortfolioSummary: Get consolidated Portfolio KPIs and per-Brand metrics for the complete active Workspace scope. Composition is uncapped; optional filters only narrow the requested analysis."
},
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace UUID; defaults to the active Workspace."
},
"lookback_days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"description": "Relative lookback; overrides explicit dates."
},
"start_date": {
"type": "string",
"format": "date"
},
"end_date": {
"type": "string",
"format": "date"
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional ISO-2 market subset."
},
"funnel": {
"type": "array",
"items": {
"type": "string",
"enum": [
"awareness",
"consideration",
"conversion"
]
}
},
"platform": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [],
"title": "getWorkspaceMarketComparisonSummary",
"description": "getWorkspaceMarketComparisonSummary: Compare the markets in a GLOBAL_BRAND Workspace. Returns local metrics and competitors, equal-weight consolidated Visibility, Mentions avg., Share of Voice, and Brand position avg. (with previous-period deltas), total responses, and explicit covered/total market coverage."
},
{
"title": "Compatibility fallback",
"description": "Allows legacy top-level arguments, server-side coercion, and one-shot argument recovery to run before the selected operation enforces its contract.",
"type": "object",
"additionalProperties": true,
"x-meikai-compatibility-fallback": true
}
]
}
},
"required": [
"operation"
],
"additionalProperties": true
}{
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Workspace Portfolio KPIs and per-Brand metrics."
},
"workspace_version": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"success",
"data",
"workspace_version"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getWorkspacePortfolioSummary output",
"x-meikai-operation": "getWorkspacePortfolioSummary"
},
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Global Brand market rows, macro metrics, and coverage."
},
"workspace_version": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"success",
"data",
"workspace_version"
]
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
}
},
"required": [
"success",
"error"
],
"additionalProperties": false
}
],
"title": "getWorkspaceMarketComparisonSummary output",
"x-meikai-operation": "getWorkspaceMarketComparisonSummary"
}
]
}