Skip to main content
Glama
vantagemcp

vantage-mcp

by vantagemcp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Track a site's AI citations over time

analyze_citation_trend
Read-onlyIdempotent

Track monthly AI-citation counts to see if a domain's visibility is growing or fading, revealing whether AI visibility is improving or if content moved the needle.

Instructions

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

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
domainYes
monthsNo
countryNoUnited States
languageNoen
platformNochat_gpt

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.7.0
    • 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"
+}
  2. Addedv1.3.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantially beyond that: cost (1 quota unit per call, 30 units/month shared across all metered tools), the zero-in-history caveat, and the partial-current-month exclusion behavior. This is exactly the kind of behavioral context annotations cannot carry.

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?

Front-loaded with purpose, then cost, then return shape, then args — a sensible ordering. The return-shape block is long, but it is justified because no output schema exists; the only minor drag is some repetition around the partial-month/latest-month explanation.

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?

No output schema exists, so the description carries the full return contract and does so, including the trend object's possible values and the presence-condition on excluded_current_partial_month. Combined with quota, platform limits, and history depth, an agent has everything needed to call and interpret this correctly.

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?

With 0% schema description coverage, the description fully compensates: it documents all five parameters with formats ('example.com', no https:// or www), defaults, the 13-month cap with the reason (provider history starts 2025-08-01), and hard platform constraints (chat_gpt is US-only and en-only; use 'google' for other countries).

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+resource+scope: tracking a domain's AI-citation count month over month. It explicitly contrasts itself with point-in-time checking ('instead of only ever checking a single point in time'), which cleanly separates it from siblings like analyze_citation_gap or 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.

Usage Guidelines5/5

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

Gives concrete trigger questions ('is our AI visibility improving', 'did that content push actually move the needle') and a negative guideline: don't make a separate call just to read the current count, since the latest entry already is it. Context for when this beats a single-point check is explicit.

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

Deploy Server

Other Tools