Vantage is an MCP server that tells you whether AI answer engines like ChatGPT and Google's AI Overview cite your brand or domain, for which questions, and how that visibility is changing.
Check quota (get_usage): see how many checks remain in your billing period.
Find where you're cited (check_prompt_coverage): test up to 10 keywords against your domain and see cited vs. mentioned-but-not-cited.
See who's winning a topic (find_citation_leaders): list the top domains cited for a keyword and compare your domain's rank.
Track visibility over time (analyze_citation_trend): month-by-month citation counts and up/down trends for a domain.
Analyze winning answers (analyze_citation_structure / analyze_citation_structure_batch): inspect opening length, list-led structure, outline, table, source domains, and community-source mix for one or many keywords.
Get a fix brief (analyze_citation_gap): compare your page's structure to the cited answer and receive ordered rewrite instructions.
Optional context: set country/language, platform (ChatGPT or Google), and compare specific domains.
Allows checking whether a domain is cited in Perplexity answers, analyzing citation leaders for a topic, and inspecting the citation structure of winning answers.
Know if AI actually cites you.
Vantage is an MCP server that checks whether ChatGPT, Gemini, Perplexity and Google's AI Overview cite your brand, for which questions, and whether that is changing, callable directly from Claude Code, Cursor, or any MCP client. No dashboard to interpret, just a straight answer.
vantagemcp.dev/check runs a real citation check with no account, no email and no card. Give it a keyword and it returns the measured shape of the answer ChatGPT actually cites for it: whether the answer opens with a list, how long the opening is, how many sources it cites, and which domains those are.
Every answer keeps a permanent page, and they are all listed in check/sitemap.xml.
Published on the Official MCP Registry under the domain-verified namespace dev.vantagemcp/vantage.
Not to be confused with: vantage.sh, a cloud cost-management company with its own, unrelated MCP server also named Vantage. Different product, same name.
Related MCP server: agentaeo-mcp-server
If your client supports MCP sign-in (OAuth), add https://vantagemcp.dev/mcp with no key and sign in: a free account from your email, or an existing key. Otherwise add to your MCP client config:
{
"mcpServers": {
"vantage": {
"url": "https://vantagemcp.dev/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}Try it first with no account at all at vantagemcp.dev/check, or get a free API key (30 quota units a month, no card required) at vantagemcp.dev.
get_usageHow much of this billing period's quota is left, before spending any of it. Costs 0 units - reads Vantage's own record, never calls the paid data provider.
"How many checks do I have left?"
find_cited_questionsStarts from your domain instead of a keyword: the questions where AI answers already cite it, most asked first. 10 units.
"What does ChatGPT already cite us for?"
check_prompt_coverageWhich of several prompts actually cite a specific domain, and which don't - up to 10 keywords in one call. ChatGPT, Gemini or Perplexity (engine), 1 unit per keyword per sample. Pass samples=3 to get "cited in 2 of 3 answers" instead of one yes or no. Each result is remembered for 180 days, so the next check reports what changed (previous, change, newly_cited).
Cited and named are reported separately. An answer can name your brand without linking you (mentioned_not_cited: the model already knows you, it just isn't citing you) or link a page it never names. Pass brand (e.g. "Notion") so the name check looks for your real brand instead of a guess from the domain.
"Out of everything we care about, where do we already show up?"
get_check_historyYour earlier check_prompt_coverage results for a domain, newest first. 0 units.
"Did our changes last week move anything?"
find_citation_leadersWho dominates AI-answer citations for a topic, and whether a domain is among them.
"Who's winning AI search for this?"
analyze_citation_trendMonth-by-month mention counts for a domain, so you can see whether visibility is growing or fading.
"Is our AI visibility improving?"
analyze_citation_structureHow the winning AI answer for a topic is actually shaped: list-led, sources cited, opening length.
"What does a winning answer look like?"
analyze_citation_structure_batchSame as analyze_citation_structure, across up to 10 related topics in one call, for content planning across a cluster.
"What do winning answers look like across this whole topic cluster?"
analyze_citation_gapDiffs your own page's structure against the winning AI-cited answer for the same keyword and returns a fix_brief: ordered rewrite instructions your agent can carry out on the page (opening, sections, the answer's points your page does not cover, table, sources), ending with one step beyond the page: which community sites or other websites the answer relies on. The brief never contains the cited answer's text.
"What should I actually change on this page to get cited?"
Every tool that returns cited domains also returns source_mix: how much of them are community sites (Reddit, YouTube, X, Quora and similar) and which. A high share means the topic is won by what people say about a brand elsewhere, not by any one site's pages.
Every tool except get_usage takes optional country (e.g. "Italy") and language (e.g. "it"), default United States / en. Tools that read a live ChatGPT answer work in any supported market; find_citation_leaders and analyze_citation_trend only have ChatGPT data for the United States in English, so use platform: "google" for other countries.
> agent calls find_citation_leaders(
keyword: "best mood tracker app",
platform: "chat_gpt"
)
< response
{
"keyword": "best mood tracker app",
"platform": "chat_gpt",
"top_domains": [
{ "domain": "www.reddit.com", "mentions": 59 },
{ "domain": "apps.apple.com", "mentions": 55 },
{ "domain": "en.wikipedia.org", "mentions": 49 },
{ "domain": "www.makeuseof.com", "mentions": 12 },
{ "domain": "play.google.com", "mentions": 11 }
]
}This repo is the MCP server itself: API-key auth, usage metering, one tool per read (see Tools above). Billing and account provisioning are a separate internal service, not included here.
uv pip install -e .
export DATAFORSEO_USERNAME=...
export DATAFORSEO_PASSWORD=...
# stdio (local MCP client, e.g. Claude Desktop config pointing at this command)
python -m vantage_mcp.server
# streamable-http (network service, bind to loopback behind your own reverse proxy)
export VANTAGE_PORT=8420
python -m vantage_mcp.server --httpRequires a DataForSEO account for the underlying SERP/AI-answer data.
MIT
Compare your own page's structure against the AI-generated answer actually cited for this keyword, and return a fix brief: ordered rewrite instructions for your page, not just a description of the winner. Use this to answer 'what should I change on this page to get cited' rather than only 'what does a winning answer look like'. Carry out the fix_brief on the user's page in their own words; it never contains the cited answer's text.
Read-only: no side effects, safe to retry. Costs 1 quota unit/call (free tier is 30 units/month shared across every metered tool, so up to 30 calls to this tool alone if nothing else is used that period).
Returns: {"keyword", "your_url", "winning" (structure of the AI-cited answer, same shape as analyze_citation_structure), "yours" (same structure computed for your_url, including its own "outline" and "has_table", with "num_links_out"/"linked_domains" standing in for source count), "gaps" (list of plain-English differences worth acting on), "possibly_missing" (heads from the winning outline whose key words mostly do not appear on your page; word matching, so check each before adding it), "fix_brief" (list of instructions, most important first: opening, number, list, sections, missing points, table, sources, then a reminder to write in your own words - or a "no structural change indicated" line when every check already matches - and always last, one off-site step drawn from the winning answer's source_mix: which community sites (Reddit, YouTube, X...) it cites, or which other sites to get mentioned on. Page shape gets a page into the running; being cited is decided mostly by what other sites say about the brand)}, or {"error"} if either side couldn't be fetched/parsed.
Use analyze_citation_structure instead if you just want the winning answer's shape, not a comparison against your own page. Use check_prompt_coverage first if you have several keywords and do not yet know which ones you are missing from - this tool is for one keyword you already know needs work.
Args: keyword: the topic/query to check, e.g. "best project management tool". your_url: full URL of your own page to compare, e.g. "https://example.com/best-project-management-tools". country: market to read the cited answer in, e.g. "Italy". Defaults to "United States". language: language code, e.g. "it". Defaults to "en". engine: "chat_gpt" (default), "gemini" or "perplexity": whose answer to compare your page against.
| Name | Required | Description | Default |
|---|---|---|---|
| engine | No | chat_gpt | |
| country | No | United States | |
| keyword | Yes | ||
| language | No | en | |
| your_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable operational context: 'Read-only: no side effects, safe to retry. Costs 1 quota unit/call' and explains the quota tier. It also discloses return behavior, including the error case, the order of fix_brief items, and the fact that the brief never contains the cited answer's text. No annotation contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but it is dense and well-organized: purpose, alternative guidance, read-only/cost, return format, and args. The most important information is front-loaded, and every sentence contributes operational value. Given the absence of an output schema, the length is justified by complexity rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by detailing the return object fields (keyword, winning, yours, gaps, possibly_missing, fix_brief, error case). It also covers parameter semantics, quota cost, and sibling-tool differentiation. For a complex comparison tool with two required parameters and three optional ones, nothing essential is missing for an agent to call and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full responsibility for parameter meaning, and it succeeds. Each parameter is given a concise explanation with concrete examples (e.g., keyword: 'best project management tool'; your_url: 'https://example.com/best-project-management-tools'), plus defaults and engine options. This goes well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific action: compare your page's structure against the AI-cited answer and return a fix brief. It further distinguishes the tool by stating it provides ordered rewrite instructions for the user's page, not merely a description of the winning answer. This is a precise verb+resource statement that an agent can act on confidently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance: use analyze_citation_structure when only the winning answer's shape is needed, and use check_prompt_coverage first for multi-keyword discovery. It also frames the tool's purpose as answering 'what should I change on this page to get cited' rather than only describing the winner. This leaves no ambiguity about when to choose this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze the structural shape of the AI-generated answer actually cited for a keyword: does it lead with a list, how long is the opening passage, how many sources does it cite and from which domains. Use this to understand what a winning AI-search answer looks like for a topic, e.g. before writing content meant to get cited.
Read-only: no side effects, safe to retry. Costs 1 quota unit per sample (1 by default; free tier is 30 units/month shared across every metered tool, so up to 30 single-sample calls to this tool alone if nothing else is used that period).
Returns: {"keyword", "engine", "model" (the answering model's version, as the provider reports it), "checked_at" (when the answer was fetched, UTC), "leads_with_list" (bool), "opening_word_count" (int), "opening_has_number" (bool), "outline" (list of up to 12 section heads, in order: the answer's headings, or its top-level list items when it has fewer than two headings; heads only, never the text under them), "has_table" (bool), "num_sources_cited" (int), "source_domains" (list of up to 10 domain strings), "source_mix" ({"community_pct" (share of those sources that are community sites such as Reddit, YouTube, X, Quora), "community_domains", "other_domains"}), "country", "language"}. With samples above 1 the shape fields describe the first answer, plus "samples_ok" (answers that came back) and "source_frequency" (list of {"domain", "runs"}: how many of the answers cited each domain, most often first). Answers change from run to run, so a domain cited in every sample is a far stronger signal than one sample.
Use analyze_citation_structure_batch instead if you need this for more than one keyword - one call per topic here adds up fast for a cluster. Use analyze_citation_gap instead if you have your own page for this keyword and want the gap to the winner, not just the winner's shape.
Args: keyword: the topic/query to analyze, e.g. "how to reduce churn". country: market to read the answer in, e.g. "Italy". Defaults to "United States". For perplexity a 2-letter code also works. language: language code, e.g. "it". Defaults to "en". Write the keyword in that language too. engine: "chat_gpt" (default), "gemini" or "perplexity". chat_gpt and gemini are the answers a person sees in those apps; perplexity is Perplexity's sonar API with web search. samples: how many independent answers to read, 1 to 5. Default 1.
| Name | Required | Description | Default |
|---|---|---|---|
| engine | No | chat_gpt | |
| country | No | United States | |
| keyword | Yes | ||
| samples | No | ||
| language | No | en |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, and non-destructive behavior, and the description adds substantial extra context: quota cost per sample, free-tier limits, run-to-run variability of answers, and how multi-sample fields summarize the first answer vs. all samples. This goes well beyond the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but organized into clear sections (purpose, cost, returns, args, sibling routing) with every sentence adding operational value. It front-loads the primary purpose and alternatives before diving into return-shape details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description provides a complete return-shape definition, covers all five parameters, explains cost/limits, and warns about run-to-run variability. Nothing an agent needs to invoke this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. The Args section comprehensively explains each parameter with examples, defaults, accepted values, and usage notes (e.g., 'Write the keyword in that language too'). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Analyze the structural shape of the AI-generated answer'), then enumerates concrete outputs such as whether it leads with a list, opening passage length, and cited sources/domains. It also distinguishes itself from siblings by naming analyze_citation_structure_batch and analyze_citation_gap as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use context ('before writing content meant to get cited') and explicit routing rules: use the batch variant for more than one keyword, and use analyze_citation_gap when you already have a page and want the gap to the winner. This fully tells an agent when to pick this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze the structural shape of the winning AI answer across several related keywords/topics in one call: does each lead with a list, how long is the opening, how many sources it cites. Use this for content planning across a topic cluster, e.g. before writing several related pieces meant to get cited, instead of calling analyze_citation_structure once per topic.
Read-only: no side effects, safe to retry. Costs 1 quota unit per keyword in the batch (free tier is 30 units/month shared across all the metered tools, so up to 30 keywords total that period if nothing else is used). A per-keyword provider error doesn't fail the whole batch - that keyword's entry just carries an "error" field instead.
Returns: {"results" (list, one {"keyword", ...same shape as analyze_citation_structure, or "error"} per keyword, in the order given), "summary": {"topics_analyzed", "topics_requested", "list_led_count", "avg_sources_cited", "avg_community_pct" (average source_mix.community_pct across the analyzed topics)}}.
Args: keywords: topics/queries to analyze, e.g. ["how to reduce churn", "churn rate benchmarks", "reduce customer churn saas"]. Max 10. country: market to read the answers in, e.g. "Italy". Defaults to "United States". language: language code, e.g. "it". Defaults to "en". engine: "chat_gpt" (default), "gemini" or "perplexity", as in analyze_citation_structure. One answer per topic.
| Name | Required | Description | Default |
|---|---|---|---|
| engine | No | chat_gpt | |
| country | No | United States | |
| keywords | Yes | ||
| language | No | en |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces these with 'Read-only: no side effects, safe to retry.' It adds substantial context beyond annotations: per-keyword quota costs, free-tier monthly limits, and the behavior that per-keyword provider errors do not fail the whole batch but surface as an 'error' field.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, the description is well-structured and information-dense: purpose leads, use case follows, then side effects/cost, return shape, and parameters. Every section earns its place, especially because neither the schema nor an output schema provides this material.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Because there is no output schema, the description provides a precise return contract: a results list with one per-keyword entry in order, optional 'error' fields, and a summary object with field names. It also covers quota semantics, defaults, provider options, and batch failure behavior, making the tool fully callable as described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the entire burden for parameter documentation. It fully compensates by explaining keywords (topics/queries, max 10, with an example), country (market and default), language (code and default), and engine (available values and default).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb and resource ('Analyze the structural shape of the winning AI answer') and lists concrete outputs: lead list presence, opening length, source count. It also clearly differentiates from analyze_citation_structure by framing this as the batch version for multiple topics in one call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool ('content planning across a topic cluster, e.g. before writing several related pieces meant to get cited') and names the alternative pattern it avoids ('instead of calling analyze_citation_structure once per topic'). This gives an agent actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Track how a domain's AI-citation count has moved month over month, so you can see whether visibility is growing or fading instead of only ever checking a single point in time. Use this to answer 'is our AI visibility improving' or 'did that content push actually move the needle'.
Read-only: no side effects, safe to retry. Costs 1 quota unit/call (free tier is 30 units/month shared across every metered tool, so up to 30 calls to this tool alone if nothing else is used that period).
Returns: {"domain", "platform", "months" (list of {"year", "month",
"mentions" (int, 0 for a month with no tracked citations. A zero
between two large months can be a gap in the provider's history rather
than a real drop, so read isolated zeros with care), "ai_search_volume"},
oldest to newest),
"trend": {"direction" ("up"/"down"/"flat"/"no_data"), "earliest_mentions",
"latest_mentions", "excluded_current_partial_month" (bool, only present
and true when the most recent calendar month was excluded from the trend
calculation because it is still in progress and its count is not yet
final - it is still returned inside months, just not compared)}}.
The most recent entry in months (or trend.latest_mentions when the
current month is not excluded) already IS the current count, so there is
no need for a separate call just to see it right now.
Args: domain: bare domain to check, e.g. "example.com" (no https://, no www). platform: "chat_gpt" or "google" (Google's AI Overview). Defaults to chat_gpt. Perplexity and Gemini aren't available - the underlying data provider doesn't cover them for this check. months: how many recent months of history to return. Defaults to 6, capped at 13 - DataForSEO's historical data only goes back to 2025-08-01. country: market to check, e.g. "Italy". Defaults to "United States". chat_gpt only has data for the United States; use platform "google" for any other country. language: language code, e.g. "it". Defaults to "en" (the only option for chat_gpt).
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | ||
| months | No | ||
| country | No | United States | |
| language | No | en | |
| platform | No | chat_gpt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations already marking the tool as read-only and idempotent, the description adds significant behavioral detail: quota cost per call, shared monthly free-tier limit, data caveats for zero months (potential provider gaps), and the logic for excluding the current partial month from trend calculations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence serves a purpose. It is front-loaded with the core purpose and use cases, then proceeds to behavioral notes, return format, and parameter guidance in a logical structure. There is no fluff or repetition beyond a minor restatement of read-only safety, which is useful reinforcement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description thoroughly documents the return structure, including the months array, trend object, and the meaning of exclusion flags and zero mentions. It also explains the sufficient call count ('no need for a separate call') and covers quota, making it complete for correct invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates. Every parameter is explained with concrete examples, defaults, constraints, and platform-specific restrictions (e.g., domain format, months cap, country support differences, unsupported platforms). This is exactly the compensation a 0% coverage schema demands.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Track how a domain's AI-citation count has moved month over month.' It clearly distinguishes the tool from point-in-time checks and, though it doesn't name siblings, its trend-focused purpose is unambiguous given sibling names like analyze_citation_structure and find_citation_leaders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit use cases: 'is our AI visibility improving' or 'did that content push actually move the needle.' This gives clear context for when to call the tool, but it does not name alternative tools or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check which of several prompts/keywords actually cite a specific domain, and which ones don't. This is usually the first real question in an AI-answer-engine audit - not "what does a winning answer look like" (analyze_citation_structure) or "who wins this one topic" (find_citation_leaders), but "out of everything we care about, where do we already show up, and where are we invisible." Use this first, then use analyze_citation_gap on whichever keywords come back not cited to see what to actually change.
Read-only for the caller, safe to retry. Costs 1 quota unit per keyword per sample (1 sample by default; free tier is 30 units/month shared across every metered tool, so up to 30 keyword checks that period if nothing else is used). A per-keyword provider error doesn't fail the whole call - that keyword's entry just carries an "error" field instead. On the hosted endpoint each keyword's result is remembered for 180 days against your API key, so the next check of the same domain and keyword reports what changed (see "previous" and "change"); get_check_history reads that record back for free.
Returns: {"domain", "engine", "samples", "keywords_checked" (int, excludes any that errored), "keywords_cited" (int), "coverage_pct" (float, 0-100), "not_cited" (list of the keyword strings where domain was not cited - the actionable list), "newly_cited" and "no_longer_cited" (keywords whose status flipped since your last check of them), "results" (one entry per keyword, in the order given: {"keyword", "cited" (bool: cited in at least half of the samples), "cited_runs" (how many sampled answers cited it), "samples_ok" (how many answers came back), "rank" (int|null, best 1-based position among the answers' sources, null when never cited), "num_sources_cited", "source_domains" (who IS cited, for a keyword you are not in), "source_mix" (how much of that is community sites such as Reddit, YouTube, X - where to get discussed to close the gap), "source_frequency" (only with samples above 1: {"domain", "runs"} per domain), "leads_with_list", "opening_word_count", "mentioned" (bool - the answer's text names the domain or brand in at least half of the samples, whether or not it links to it), "model", "checked_at", "previous" ({"checked_at", "cited_runs", "samples", "best_rank"} from your last check of this domain and keyword on the same engine and market, or null), "change" ("first_check", "up", "down" or "same", comparing citation rates)}, or {"keyword", "error"} for one that failed), "keywords_mentioned" (int), "mentioned_not_cited" (keywords where the answer names you but does not cite you - the model already knows you, it just isn't linking you), "mention_terms" (exactly what was looked for in the answer text)}. "Cited" and "mentioned" are separate claims and are never merged. Answers change from run to run: with samples=1 a single answer decides "cited", so use samples=3 before telling someone they are or are not cited.
Args: domain: bare domain to check, e.g. "example.com" (no https://, no www). keywords: prompts/topics to check it against, e.g. ["best project management software", "asana alternatives", "free project management tool"]. Max 10. brand: optional brand name to look for in the answer text, e.g. "Notion". Without it, the domain's first label is used ("notion" for notion.so), which can match an ordinary word by accident for a dictionary-word domain, so pass the real brand when known. country: market to read the answers in, e.g. "Italy". Defaults to "United States". language: language code, e.g. "it". Defaults to "en". Write the keywords in that language too. engine: "chat_gpt" (default), "gemini" or "perplexity", as in analyze_citation_structure. samples: independent answers to read per keyword, 1 to 5. Default 1.
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | ||
| domain | Yes | ||
| engine | No | chat_gpt | |
| country | No | United States | |
| samples | No | ||
| keywords | Yes | ||
| language | No | en |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, but the description goes far beyond that: it discloses quota costs, per-keyword error handling, 180-day result retention, the separation of 'cited' vs 'mentioned', and the run-to-run variability of answers. This is exactly the kind of behavioral context annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: purpose, workflow position, cost, failure semantics, retention, return format, and parameter details. It is front-loaded with the core purpose and usage guidance before the detailed return spec. No filler or tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, no output schema, and a rich return payload, the description is complete: it documents all parameters, all major return fields, error behavior, cost, retention, and workflow ordering. It also covers edge cases like dictionary-word domains and samples=1 instability. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining every parameter in the Args section: domain format with anti-examples, keyword examples and max count, brand's purpose and dictionary-word pitfall, country/language defaults, engine values, and samples range. This is more valuable than a typical schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Check which of several prompts/keywords actually cite a specific domain, and which ones don't.' It then explicitly differentiates from siblings by naming analyze_citation_structure and find_citation_leaders and stating what this tool is not. An agent can immediately identify its role in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('usually the first real question in an AI-answer-engine audit'), how to sequence it ('Use this first, then use analyze_citation_gap'), and names the alternatives it is not. It also gives a practical recommendation to use samples=3 before making claims about citation status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find which domains dominate AI-answer citations for a topic/keyword, and optionally check whether a specific domain shows up among them. Use this to answer 'who's winning AI search for this topic' or 'is my competitor cited more than me for X'.
Read-only: no side effects, safe to retry. Costs 10 quota units/call (free tier is 30 units/month shared across every metered tool, so up to 3 calls to this tool alone if nothing else is used that period).
Returns: {"keyword", "platform", "top_domains" (list of {"domain",
"mentions"}, most-cited domains for this keyword/platform, order as
ranked by the provider), "top_domains_limit" (int, the provider's own
cap on this list - absence from it is NOT evidence a domain has zero
citations, only that it did not rank in the top top_domains_limit),
"compare_domain_rank" (int|null, only present when compare_domain was
passed: the domain's 1-based position in top_domains, or null if it
did not rank in the top top_domains_limit), "country", "language",
"source_mix" ({"community_pct" (share of these mentions that go to
community sites such as Reddit, YouTube, X, Quora), "community_domains",
"other_domains"}: a high community_pct means this topic is won by what
people say about a brand elsewhere, not by any one site's pages)}.
This tool's citation universe is the provider's tracked mention corpus for the keyword, which is a different measurement from analyze_citation_structure's single live answer - the two can legitimately disagree on whether a given domain shows up.
Use check_prompt_coverage instead if you already know which domain you care about and just want to know whether it is cited.
Args: keyword: the topic/query to check, e.g. "best project management tool". platform: "chat_gpt" or "google" (Google's AI Overview). Defaults to chat_gpt. Perplexity and Gemini aren't available - the underlying data provider doesn't cover them for this check. compare_domain: optional bare domain to look up in the results (exact match against the registrable domain, e.g. "notion.so" will not match "mynotion.so.example.com"). country: market to check, e.g. "Italy". Defaults to "United States". chat_gpt only has data for the United States; use platform "google" for any other country. language: language code, e.g. "it". Defaults to "en" (the only option for chat_gpt).
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | United States | |
| keyword | Yes | ||
| language | No | en | |
| platform | No | chat_gpt | |
| compare_domain | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, open-world behavior, and the description adds substantial extra context: exact quota cost (10 units/call), the caveat that absence from top_domains is not evidence of zero citations, and the source_mix interpretation. It also clarifies how this tool's citation universe differs from analyze_citation_structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: purpose, typical user questions, quota, return semantics, caveats, sibling differentiation, and per-parameter guidance are all front-loaded in a logical order. Nothing is redundant or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no enums, this description is unusually complete: it explains every parameter, the return shape, open-world absence semantics, quota costs, platform/country/language restrictions, and when to prefer a sibling tool. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden, and it succeeds: keyword usage, platform options with unavailable providers, compare_domain exact-match semantics with a concrete example, country restrictions tied to platform, and language defaults are all documented. This meaningfully exceeds the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: find which domains dominate AI-answer citations for a topic/keyword, with an optional domain comparison. It clearly differentiates this from siblings by naming analyze_citation_structure and check_prompt_coverage and explaining measurement differences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit use cases ('who's winning AI search for this topic' or competitor comparison), names the alternative check_prompt_coverage for when a domain is already known, and notes platform/country/language limitations. This leaves no ambiguity about when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the questions people ask AI answer engines where a domain is already cited as a source, most-asked first. Starts from the domain, so nobody has to guess keywords first. Use this to answer 'what does ChatGPT already cite us for' or to pick the keywords to feed check_prompt_coverage and analyze_citation_gap.
Read-only: no side effects, safe to retry. Costs 10 quota units/call (free tier is 30 units/month shared across every metered tool, so up to 3 calls to this tool alone if nothing else is used that period).
Returns: {"domain", "platform", "country", "language", "total_questions"
(int, every tracked question citing the domain, which can exceed the
list), "questions" (up to limit, most-asked first: {"question",
"ai_search_volume" (monthly asks as the provider estimates them),
"your_position" (1-based position of the domain among that answer's
sources), "source_domains" (who else that answer cites), "last_seen"
(when the provider last recorded this answer, UTC)})}. An empty list means
the provider's tracked answers do not cite the domain, not that no
answer anywhere does.
This reads the provider's tracked answer corpus, the same measurement as find_citation_leaders, not a live answer: re-check a question with check_prompt_coverage to see today's answer.
Args: domain: bare domain, e.g. "example.com" (no https://, no www). Subdomains are included. platform: "chat_gpt" (default) or "google" (Google's AI Overview). limit: how many questions to return, 1 to 20. Default 20. country: market, e.g. "Italy". Defaults to "United States". chat_gpt only has United States data; use platform "google" elsewhere. language: language code, e.g. "it". Defaults to "en", the only option for chat_gpt.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| domain | Yes | ||
| country | No | United States | |
| language | No | en | |
| platform | No | chat_gpt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description reinforces them with 'Read-only: no side effects, safe to retry.' It adds meaningful behavioral context beyond annotations: quota cost (10 units/call with free tier context), empty-list semantics ('not that no answer anywhere does'), and the fact that it reads a tracked corpus rather than live answers. This is exactly the kind of extra context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but tightly organized: purpose, usage route, side effects/cost, return shape, caveats, and args. Every sentence earns its place—even the quota warning is decision-relevant for an agent. Key differentiators are front-loaded in the first sentence, and the Args section is cleanly formatted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no output schema, and several siblings, the description is remarkably complete. It covers input constraints, return value shape including nested fields, special empty-list semantics, quota impact, platform/country/language limitations, and how it relates to sibling tools. An agent has everything needed to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden, and it fully delivers. Each parameter gets practical guidance: domain format ('bare domain, e.g. "example.com" (no https://, no www). Subdomains are included'), platform options and constraints, limit range and default, country semantics including the chat_gpt limitation to United States, and language with the note that 'en' is the only option for chat_gpt. This goes beyond the schema's raw type/default data.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-object pair: 'Find the questions people ask AI answer engines where a domain is already cited as a source, most-asked first.' It further clarifies the tool starts from the domain rather than keywords, which distinguishes it from sibling tools like check_prompt_coverage and analyze_citation_gap. The stated use case, 'what does ChatGPT already cite us for', makes the purpose immediately identifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool ('Use this to answer...' and 'to pick the keywords to feed check_prompt_coverage and analyze_citation_gap'). It also contrasts behavior with siblings: 'This reads the provider's tracked answer corpus, the same measurement as find_citation_leaders, not a live answer: re-check a question with check_prompt_coverage to see today's answer.' This gives clear routing guidance between alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read back your own earlier check_prompt_coverage results for a domain, newest first, to show progress over time or to confirm whether a change (a rewrite, a new mention somewhere) moved anything. Use this for 'has our citation status changed since last week' without spending units.
Costs 0 quota units: it only reads Vantage's own record of your checks, never the data provider. Results are kept 180 days per API key and are only visible to that key.
Returns: {"domain", "keyword" (or null for every keyword), "checks" (newest first: {"keyword", "engine", "country", "language", "samples", "cited_runs", "best_rank", "mentioned_runs", "checked_at"})}.
Args: domain: the bare domain the checks were run for, e.g. "example.com". keyword: optional, only this keyword's history. limit: how many rows to return, 1 to 200. Default 50.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| domain | Yes | ||
| keyword | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds substantial context: it costs 0 quota units, reads only Vantage's own records rather than the data provider, retains results for 180 days per API key, and restricts visibility to that key. These are meaningful behavioral disclosures beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every section earns its place: purpose, use case, cost/retention behavior, return shape, and argument definitions. It is front-loaded with the primary purpose and structured so an agent can quickly extract the key facts.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully specifies the return structure including the fields of each check and the 'newest first' ordering. Combined with annotations and full parameter documentation, an agent has everything needed to invoke the tool correctly and interpret its result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates: domain is specified as 'the bare domain... e.g. example.com', keyword is described as 'optional, only this keyword's history', and limit is given with a range and default. Every parameter is meaningfully explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Read back your own earlier check_prompt_coverage results for a domain, newest first.' It clearly distinguishes this history-retrieval tool from its analysis-oriented siblings by framing it as progress tracking rather than new analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete use case: 'Use this for "has our citation status changed since last week" without spending units.' This clearly signals when to reach for the tool, though it does not explicitly enumerate exclusions or name alternative sibling tools beyond the implicit reference to check_prompt_coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check how much of this billing period's quota is left, before spending any of it. Use this to answer 'how many checks do I have left' or to decide whether a batch call will fit before running it.
Costs 0 quota units - this never touches the paid data provider, it only reads Vantage's own record of what has been used.
Returns: {"tier", "period" (YYYY-MM), "units_used", "units_limit",
"units_remaining"}. find_citation_leaders and find_cited_questions cost
10 units/call; analyze_citation_trend, analyze_citation_structure (and
its batch form, per keyword), check_prompt_coverage (per keyword) and
analyze_citation_gap cost 1, times samples where a tool takes it.
get_check_history costs 0.
stdio/local-dev mode (no HTTP access token) has no metering at all - this returns tier "unmetered" with no real limit in that case.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses that the call costs 0 quota units, never touches the paid data provider, returns a specific field set, and behaves differently in unmetered stdio/local-dev mode. This is valuable non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence carries essential information: purpose, use case, cost behavior, return fields, sibling costs, and environment-specific behavior. The main purpose is front-loaded and the additional details are compactly grouped.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though there is no output schema, the description enumerates the returned fields. It also covers quota semantics, environment behavior, and the relationship to sibling tools, so an agent has everything needed to invoke and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters)Skip; the input schema is already fully complete. With no parameters to document, the description doesn't need to add parameter-level detail. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Check how much of this billing period's quota is left'. It also distinguishes itself from siblings by noting it 'never touches the paid data provider' and only reads Vantage's own usage record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: before spending quota, to answer quota questions like 'how many checks do I have left', and to decide if a batch call fits. It also lists the quota costs of sibling tools, making the workflow context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.8.0analyze_citation_gap1 field changedInput schema / properties / engineAdded value: +{
+ "default": "chat_gpt",
+ "title": "Engine",
+ "type": "string"
+}analyze_citation_structure2 fields changedInput schema / properties / engineAdded value: +{
+ "default": "chat_gpt",
+ "title": "Engine",
+ "type": "string"
+}Input schema / properties / samplesAdded value: +{
+ "default": 1,
+ "title": "Samples",
+ "type": "integer"
+}analyze_citation_structure_batch1 field changedInput schema / properties / engineAdded value: +{
+ "default": "chat_gpt",
+ "title": "Engine",
+ "type": "string"
+}check_prompt_coverage2 fields changedInput schema / properties / engineAdded value: +{
+ "default": "chat_gpt",
+ "title": "Engine",
+ "type": "string"
+}Input schema / properties / samplesAdded value: +{
+ "default": 1,
+ "title": "Samples",
+ "type": "integer"
+}find_cited_questionsget_check_historyv1.7.0analyze_citation_gap2 fields changedInput schema / properties / countryAdded value: +{
+ "default": "United States",
+ "title": "Country",
+ "type": "string"
+}Input schema / properties / languageAdded value: +{
+ "default": "en",
+ "title": "Language",
+ "type": "string"
+}analyze_citation_structure2 fields changedInput schema / properties / countryAdded value: +{
+ "default": "United States",
+ "title": "Country",
+ "type": "string"
+}Input schema / properties / languageAdded value: +{
+ "default": "en",
+ "title": "Language",
+ "type": "string"
+}analyze_citation_structure_batch2 fields changedInput schema / properties / countryAdded value: +{
+ "default": "United States",
+ "title": "Country",
+ "type": "string"
+}Input schema / properties / languageAdded value: +{
+ "default": "en",
+ "title": "Language",
+ "type": "string"
+}analyze_citation_trend2 fields changedInput schema / properties / countryAdded value: +{
+ "default": "United States",
+ "title": "Country",
+ "type": "string"
+}Input schema / properties / languageAdded value: +{
+ "default": "en",
+ "title": "Language",
+ "type": "string"
+}check_prompt_coverage2 fields changedInput schema / properties / countryAdded value: +{
+ "default": "United States",
+ "title": "Country",
+ "type": "string"
+}Input schema / properties / languageAdded value: +{
+ "default": "en",
+ "title": "Language",
+ "type": "string"
+}find_citation_leaders2 fields changedInput schema / properties / countryAdded value: +{
+ "default": "United States",
+ "title": "Country",
+ "type": "string"
+}Input schema / properties / languageAdded value: +{
+ "default": "en",
+ "title": "Language",
+ "type": "string"
+}v1.6.0check_ai_visibilitycheck_prompt_coverageget_usagev1.5.2analyze_citation_gapcitation_leadersfind_citation_leadersv1.3.0analyze_citation_structureanalyze_citation_structure_batchanalyze_citation_trendcitation_structurecitation_structure_batchv1.1.2check_ai_visibilitycitation_leaderscitation_structurecitation_structure_batchScored across 9 tools
Each tool targets a clearly distinct step in the citation-audit workflow: single vs batch structure analysis, domain coverage, gap analysis, leaders, cited questions, trends, history, and quota. Near-overlaps like structure vs gap or coverage vs leaders are explicitly cross-referenced in the descriptions, so an agent can reliably disambiguate them.
All tool names follow a consistent snake_case verb_noun pattern using the verbs analyze, check, find, and get. The only variation is the systematic _batch suffix, which clearly marks the batching variant of analyze_citation_structure.
Nine tools is well within the well-scoped range for this server's purpose. Each tool earns its place, including the two zero-cost meta tools (get_usage and get_check_history) that support the metered workflow without adding noise.
The tool surface covers the full read-only citation-audit lifecycle: discovery (find_citation_leaders, find_cited_questions), coverage (check_prompt_coverage), structure (analyze_citation_structure/batch), gap analysis (analyze_citation_gap), trend tracking (analyze_citation_trend), history (get_check_history), and quota management (get_usage). There are no obvious dead ends in the intended workflow.
Check if ChatGPT, Perplexity & Gemini mention or cite a brand. Share of voice + GEO/AEO tracking.
Track brand visibility in ChatGPT, Gemini and Google AI answers: competitors, cited sources, checks.
How often ChatGPT, Perplexity, Gemini and Claude mention and cite your brand vs competitors.
Query your brand's AI visibility across ChatGPT, Claude, Perplexity, and Gemini.
