Docs

Period-over-Period Reporting in the MCP

Every analytics tool in the Knowatoa MCP supports period-over-period comparisons. Instead of just seeing the latest snapshot, you can compare any date range to a previous period and see exactly how your metrics changed.

How it works

When you ask your AI assistant about your data with a date range, it automatically:

  1. Fetches data for the period you specified
  2. Fetches data for an equal-length comparison period (or one you specify)
  3. Calculates the changes: absolute difference and percentage change
  4. Returns all four values for every metric

Basic example

Ask Claude:

“Show me my visibility for September 2026”

Behind the scenes, Claude calls:

json { "name": "get_visibility", "arguments": { "site_id": "tpc_abc123", "start_date": "2026-09-01", "end_date": "2026-09-30" } }

The response includes September’s data compared to the 30 days before (August 2-31):

json { "period": { "start": "2026-09-01", "end": "2026-09-30", "refresh_count": 12 }, "compare_to": { "start": "2026-08-02", "end": "2026-08-31", "refresh_count": 11 }, "metrics": { "mention_rate": { "current": 48.0, "previous": 37.0, "change_points": 11.0, "change_percent": 29.7 } } }

Claude then tells you: “Your mention rate increased from 37% to 48% — that’s an 11 percentage point increase, or 30% growth.”

The four values

Every metric returns:

Field What it means Example
current Value in the period you asked about 48.0
previous Value in the comparison period 37.0
change_points Absolute difference (percentage points for rates) 11.0
change_percent Relative change as a percentage 29.7

If there’s no data for a period (no completed AI responses), the values are null instead of 0. This prevents data gaps from looking like -100% drops.

Date parameters

All period-aware tools accept these parameters:

Parameter Format Required Notes
start_date YYYY-MM-DD Yes (with end_date) Beginning of the period
end_date YYYY-MM-DD Yes (with start_date) End of the period (inclusive)
compare_start YYYY-MM-DD Optional Beginning of comparison period
compare_end YYYY-MM-DD Optional End of comparison period

Maximum period: 366 days.

If you don’t specify compare_start and compare_end, the comparison period is automatically calculated as the same number of days immediately before your requested period.

Custom comparison periods

Want to compare September to July instead of August?

Ask:

“Compare September 2026 to July 2026”

Claude sends:

json { "start_date": "2026-09-01", "end_date": "2026-09-30", "compare_start": "2026-07-01", "compare_end": "2026-07-31" }

This is useful for: - Seasonal comparisons (December vs. December last year) - Skip periods with unusual events - A/B test windows

Which tools support periods

Tools with optional date ranges

These tools show the latest refresh by default, but accept dates for period comparisons:

get_visibility — Mention rates and ranking positions across AI services

Example question: “Show visibility for September compared to August”

Returns: mention_rate, mentions, samples, average_position — all with current/previous/change

get_sentiment — Sentiment scores and positive/neutral/negative counts

Example: “How did sentiment change in Q3?”

Returns: sentiment_score, sentiment_evaluated, positive_count, neutral_count, negative_count

get_citations — Citation domains AI services reference

Example: “Which domains got more citations this month?”

Returns: Per-domain citation_count with change, plus category rollups

get_competitors — Your brand vs. competitors

Example: “Compare our visibility to competitors for the last 30 days”

Returns: Each brand’s mention_rate and sentiment_score with changes

get_competitor_sentiment — Detailed sentiment per brand × AI service

Example: “Show competitor sentiment breakdown for September”

Returns: Long-format table with one row per brand per AI service

get_negative_mentions — Negative sentiment diagnostic

Example: “Show negative mentions in the last week”

Returns: Each negative AI answer with excerpts, plus counts per question and AI service

Tools that require date ranges

get_series_performance — Per-AI-service performance

This tool has no “latest refresh” mode because per-AI-service comparisons only make sense over time. You must provide start_date and end_date.

Example: “Show me ChatGPT vs. Perplexity performance for September”

Returns: mention_rate, average_position, sentiment_score, citation_count, prompt_coverage (% of questions mentioned), and question counts — all with current/previous/change, overall and per AI service.

get_question_performance — Per-question × AI service

Defaults to the last 30 days if you don’t specify dates.

Example: “Which questions improved the most this month?”

Returns: One row per question × AI service with mentioned (yes/no), mention_rate, average_position, sentiment_score, competitor mentions, and top cited domains — all compared to the previous period.

Example workflows

Monthly client report

Ask Claude:

“Give me a month-over-month visibility report for September 2026”

Claude calls get_visibility with start_date: 2026-09-01 and end_date: 2026-09-30, then formats the response:

  • Overall mention rate: 48% (was 37%, +30%)
  • ChatGPT: 60% (was 45%, +33%)
  • Perplexity: 40% (was 30%, +33%)
  • Average position improved from 3.1 to 2.3

Copy that into your deck.

Sentiment trend analysis

“Show me how sentiment changed in the last quarter”

Claude calls get_sentiment with Q3 dates:

  • Sentiment score: 0.42 (was 0.31, +36%)
  • Positive mentions: 15 (was 10, +50%)
  • Negative mentions: 2 (unchanged)

You can follow up: “Show me the actual negative mentions” → Claude calls get_negative_mentions to list them.

Competitor analysis

“Compare us to our top competitor for the last 60 days”

Claude calls get_competitors and shows:

  • Your brand: 48% visibility (was 37%, +30%)
  • Competitor A: 52% visibility (was 48%, +8%)

You’re gaining ground.

Drilling into specific questions

“Which questions drove the visibility increase?”

Claude calls get_question_performance and ranks questions by mention_rate change, showing which questions went from rarely mentioned to frequently mentioned.

Tips

1. Use natural language

You don’t need to specify exact date formats. Say: - “Show me last month vs. the month before” - “Compare Q3 to Q2” - “How did this week compare to last week?”

Your AI assistant translates that into the right date parameters.

2. Ask follow-up questions

If you see an interesting change, drill in: - “Why did sentiment improve?” → Claude might call get_negative_mentions to see if negative mentions decreased - “Which AI service drove that?” → Claude calls get_series_performance for a per-service breakdown - “Was it one question or all of them?” → Claude calls get_question_performance

3. Combine with non-period tools

You can mix period comparisons with snapshot tools. For example: - Call get_visibility with dates to see trends - Then call get_rankings (which always returns the latest refresh) to see the actual AI responses driving those numbers

4. Check refresh counts

The response includes refresh_count for both periods. If a period has 0 refreshes, all metrics will be null. If the counts are very different (e.g., 1 vs. 12), the comparison might be misleading — one refresh isn’t a full sample.

Null vs. zero

When a period has no completed AI responses (none ran, or they’re still running/failed), metrics return null instead of 0:

json { "mention_rate": { "current": 48.0, "previous": null, "change_points": null, "change_percent": null } }

This prevents gaps from appearing as -100% drops in your reports. Check refresh_count to confirm.

A completed response that doesn’t mention your brand does count as 0, so a 0% mention rate means “AI services are responding but not mentioning you,” while null means “we don’t have data for that period yet.”

Limits

  • Maximum period: 366 days
  • Citation sources in period mode are capped at the top 100 domains (the metrics.citation_count total is uncapped)
  • Per-question performance defaults to a 100-question page (max 200); use limit and offset to page through more

Complete tool list

All tools that support period-over-period:

  1. get_visibility — Mention rates and positions (optional dates)
  2. get_sentiment — Sentiment scores and counts (optional dates)
  3. get_citations — Citation domains and categories (optional dates)
  4. get_competitors — Brand comparison (optional dates)
  5. get_series_performance — Per-AI-service breakdown (dates required)
  6. get_question_performance — Per-question × AI service (defaults to 30 days)
  7. get_competitor_sentiment — Sentiment per brand × AI service (optional dates)
  8. get_negative_mentions — Negative sentiment diagnostic (optional dates)

All return the same {current, previous, change_points, change_percent} structure.

More information

  • What is MCP? — Overview and setup
  • API v2 Period Comparison — The same functionality in the REST API
  • The MCP uses the same period logic as the API, so the behavior is identical whether you’re using Claude Desktop or making REST calls

If you’re building automated reports or dashboards, the API might be a better fit. If you’re preparing one-off client decks or exploratory analysis, the MCP lets you ask questions conversationally and get answers instantly.