vantage-mcp

Analyze a winning AI answer

analyze_citation_structure

Read-onlyIdempotent

Analyze the structure of AI-cited answers for a keyword: list vs paragraph, opening length, sources cited. Learn what winning AI-search content looks like to get cited.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Default
`engine`	No	chat_gpt
`country`	No	United States
`keyword`	Yes
`samples`	No
`language`	No	en

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.8.0Sep 23, 2026

addedInput schema / properties / engine

Added value: +{
+  "default": "chat_gpt",
+  "title": "Engine",
+  "type": "string"
+}

addedInput schema / properties / samples

Added value: +{
+  "default": 1,
+  "title": "Samples",
+  "type": "integer"
+}

Changed2 schema fields changedv1.7.0Sep 23, 2026

addedInput schema / properties / country

Added value: +{
+  "default": "United States",
+  "title": "Country",
+  "type": "string"
+}

addedInput schema / properties / language

Added value: +{
+  "default": "en",
+  "title": "Language",
+  "type": "string"
+}

Addedv1.3.0Aug 21, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing the metering model: 1 quota unit per sample, 30 units/month shared across all metered tools, and how that caps single-sample calls. It also warns that answers change run to run, so cross-sample domain frequency is a stronger signal than a single run — real behavioral context an agent cannot get from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and routing are front-loaded, and since there is no output schema the returns block is justified. It is nevertheless long and dense, with the quota explanation and the returns enumeration both sizeable for a 5-parameter read tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description documents the entire return shape (including conditional fields only present when samples > 1), plus cost, defaults, and the run-to-run variance caveat. Nothing an agent needs in order to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the full burden and does: it explains engine values with their real semantics (chat_gpt/gemini are in-app answers; perplexity is the sonar API with web search), gives examples for country and language, warns to write the keyword in the target language, and bounds samples at 1–5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('analyze the structural shape of the AI-generated answer actually cited for a keyword') and enumerates the exact dimensions measured (list-leading, opening length, source count/domains). It is clearly distinguishable from siblings like analyze_citation_gap and analyze_citation_structure_batch, which it names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: use the batch variant for more than one keyword, and analyze_citation_gap when you already have your own page and want the gap rather than the winner's shape. It also gives a concrete use case ('before writing content meant to get cited').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Analyze a winning AI answer

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools