@digestseo/mcp-gsc 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.4.2] - 2026-09-21
+
+### Fixed
+- Cannibalization totals and impression shares now expose their query/page-row aggregation scope explicitly so clients do not mistake summed page impressions for a true query-level Search Console total.
+- Discover Search Analytics calls now reject unsupported query grouping/filtering before reaching Google, and query-centric/comparison tools no longer advertise Discover where their contracts depend on query or average-position data that Discover does not provide.
+- Quick-win guidance now treats Search Console position as an aggregate average-position metric rather than a literal current rank, and metadata no longer implies CTR is an eligibility filter when the implementation does not filter on CTR.
+
+## [0.4.1] - 2026-09-21
+
+### Changed
+- Large Search Analytics, comparison, cannibalization, quick-win, content-decay, page/query drilldown, and impression-page proxy responses now use deterministic bounded output with explicit pagination/truncation metadata instead of risking oversized MCP structured content.
+- Content-decay assessment now requires meaningful click evidence plus supporting impression or average-position deterioration for a `likely_decay` classification, while separately identifying weak evidence and improving visibility with click volatility.
+- Weekly-digest recommendations now keep measured Search Console observations separate from causal hypotheses and avoid unsupported publishing or indexing-speed prescriptions.
+
+### Fixed
+- True site-total `analytics.query` calls with `dimensions: []` now accept Google's valid aggregate rows when the `keys` field is omitted.
+- Query/page drilldowns now expose usable paging inputs instead of reporting pagination metadata that callers could not advance.
+- `indexing.list_pages` now makes its impressions-based proxy semantics explicit and safely pages large result sets.
+
 ## [0.4.0] - 2026-09-21
 
 ### Added

package/README.md

@@ -73,13 +73,13 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`server.capabilities`** | Read | List every tool this server exposes and report whether your Google connection is currently authenticated (`connected` / `not_connected`). Takes no arguments — a good first call for discovery. |
 | **`sites.list`** | Read | List the Search Console properties the connected Google account can access (`siteUrl`, `permissionLevel`). |
 | **`sites.get`** | Read | Retrieve one exact Search Console property and the connected account's permission level for it. |
-| **`analytics.query`** | Read | Impressions, clicks, CTR, and average position over a date range, with dimensions, filters, pagination, and selectable search type. |
-| **`insights.page_queries`** / **`insights.query_pages`** | Read | Drill from one exact page to its Search Console queries, or from one exact query to the pages Google surfaced for it. |
+| **`analytics.query`** | Read | Impressions, clicks, CTR, and average position over a date range, with dimensions, filters, safe pagination, and selectable search type. Pass `dimensions: []` for true site totals; Google's aggregate row may omit `keys`. |
+| **`insights.page_queries`** / **`insights.query_pages`** | Read | Drill from one exact page to its Search Console queries, or from one exact query to the pages Google surfaced for it, with `row_limit` / `start_row` pagination. |
 | **`urls.inspect`** | Read | Google's URL Inspection report for a single page. |
 | **`urls.inspect_many`** | Read | Inspect up to 10 URLs sequentially in one call. Each URL still consumes one Google URL Inspection request and one unit of the server's shared inspection safety budget. |
 | **`sitemaps.list`** / **`sitemaps.get`** | Read | List submitted sitemaps or retrieve one sitemap's details. |
-| **`insights.quick_wins`** / **`insights.cannibalization`** / **`insights.content_decay`** | Read | Surface optimization opportunities, competing pages, and declining content. |
-| **`indexing.list_pages`** / **`analytics.compare`** | Read | Analyze pages receiving impressions and compare two periods, optionally using the same search type and query/page/country/device/search-appearance filters for both periods. |
+| **`insights.quick_wins`** / **`insights.cannibalization`** / **`insights.content_decay`** | Read | Surface average-position opportunity rows, query/page overlap, and evidence-ranked click declines. Quick-win candidates are observed query/page rows selected by aggregate Search Console average position, not proof of a stable current rank, and CTR is context rather than an eligibility filter. Cannibalization candidate totals/shares are scoped to observed query/page rows rather than true query-level property totals; content-decay results distinguish likely decay from weak evidence and improving visibility with click volatility. |
+| **`indexing.list_pages`** / **`analytics.compare`** | Read | Analyze pages receiving Search Console impressions and compare two periods, optionally using the same search type and query/page/country/device/search-appearance filters for both periods. `indexing.list_pages` is performance data, not index coverage: a missing URL may still be indexed; use `urls.inspect` / `urls.inspect_many` for URL-level index status. |
 | **`reports.weekly_digest`** | Read | Generate a plain-language seven-day performance report with movers, top pages, and one recommended action. |
 | **`sites.add`** / **`sites.delete`** | Write | Add or remove a Search Console property. |
 | **`sitemaps.submit`** / **`sitemaps.delete`** | Write | Submit or remove a sitemap. |
@@ -87,6 +87,8 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 
 Read-write mode requests the Google Search Console read-write and Indexing API scopes. Read-only mode requests only `https://www.googleapis.com/auth/webmasters.readonly` (plus `openid` and `email`) and does not register the five write tools. Read-write remains the default so existing deployments retain their current behavior; see [SETUP.md](SETUP.md) to select a mode before connecting users.
 
+Large analytics responses are bounded at the MCP boundary instead of being generated and then discarded by clients with structured-content limits. List-style tools expose `start_row` / `next_start_row` where applicable; ranked analytical tools expose `limit`, `start_row`, and `result_page` metadata including `has_more`, `truncated`, and `byte_limit_reached`. Continue paging while `has_more` is true rather than assuming one response is complete.
+
 > **`indexing.request` eligibility.** Google's Indexing API is not a general-purpose page submission tool — as of this writing, Google's own documentation limits it to two content types: pages with `JobPosting` structured data, and livestream pages with `BroadcastEvent` structured data nested inside `VideoObject`. Before submitting, the server fetches the target URL and checks its JSON-LD for one of those two types; if neither is present (or the page can't be fetched), it returns an error explaining why the URL is ineligible instead of calling the Indexing API. A successful submission is only an acknowledgment that Google received the notification — it does not guarantee the URL will be indexed.
 
 ## What you can ask
@@ -96,7 +98,7 @@ Once connected, ask your assistant things like:
 - *"What are my top 20 queries by clicks in the last 28 days?"*
 - *"Compare impressions for example.com this month vs last month — which pages dropped?"*
 - *"Is `https://example.com/pricing` indexed? When was it last crawled?"*
-- *"Which queries does my blog rank position 5–15 for? Those are my quick wins."*
+- *"Which high-impression query/page rows have an average position between 5 and 15? Show me those optimization opportunities."*
 - *"Give me a weekly digest for `sc-domain:example.com` ending today."*
 - *"Do any of my sitemaps have errors or warnings?"*
 - *"Split my clicks into brand vs non-brand using a regex on the query."*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digestseo/mcp-gsc",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": false,
   "main": "scripts/glama-start.mjs",
   "bin": {

package/src/digest.ts

@@ -181,7 +181,7 @@ function totalsFromRow(row: SearchAnalyticsRow | undefined): SiteTotals {
 
 function rowsToQueries(rows: SearchAnalyticsRow[]): QueryRow[] {
   return rows.map((r) => ({
-    query: r.keys[0] ?? '',
+    query: r.keys?.[0] ?? '',
     clicks: r.clicks,
     impressions: r.impressions,
     ctr: r.ctr,
@@ -191,7 +191,7 @@ function rowsToQueries(rows: SearchAnalyticsRow[]): QueryRow[] {
 
 function rowsToPages(rows: SearchAnalyticsRow[]): PageRow[] {
   return rows.map((r) => ({
-    page: r.keys[0] ?? '',
+    page: r.keys?.[0] ?? '',
     clicks: r.clicks,
     impressions: r.impressions,
   }));
@@ -323,8 +323,8 @@ function pickActionAndBuild(
       key: 'investigate_drop',
       item: {
         headline: 'Search traffic for one of your queries dropped this week',
-        why: `Last week, '${bigDrop.query}' brought you ${bigDrop.prevClicks} clicks. This week, only ${bigDrop.currentClicks}. A drop this size in one week usually means either: a competitor outranked you, the page itself changed, or Google changed how it shows your page.`,
-        how: `1. Search Google for '${bigDrop.query}' and find your page.\n2. Compare your result to the top 3 results above and below you. What do they have that you don't?\n3. Either update your page to be more useful, or accept the drop if the query isn't strategic.`,
+        why: `Search Console recorded ${bigDrop.prevClicks} clicks for '${bigDrop.query}' last week and ${bigDrop.currentClicks} this week. That is a measured decline, but Search Console alone does not establish whether the cause was ranking movement, demand, SERP features, a site change, or competition.`,
+        how: `1. In Search Console, filter to '${bigDrop.query}' for both weeks and compare Pages, impressions, CTR, average position, Devices, and Countries.\n2. Review site changes made before the decline and treat them as hypotheses, not proven causes.\n3. If the same page lost useful visibility across supporting metrics, investigate that page and its search intent before changing it.`,
       },
     };
   }
@@ -358,9 +358,9 @@ function pickActionAndBuild(
   return {
     key: 'publish_one_post',
     item: {
-      headline: 'Publish one new piece of content this week',
-      why: 'Your numbers are steady — nothing broken, nothing breakthrough. The single biggest predictor of organic search growth is consistent publishing of content people are searching for.',
-      how: "1. Open your GSC and look at the 'Queries' tab — find a query with at least 5 impressions but where you don't have a dedicated page.\n2. Write a 500-1000 word page directly answering that query.\n3. Publish it. Submit the URL via 'URL inspection' for faster indexing.",
+      headline: 'Review one evidence-backed search opportunity this week',
+      why: 'The available Search Console data does not show one large mover that clearly deserves priority. Use the query/page rows to choose the next action instead of assuming more publishing is automatically the answer.',
+      how: "1. Review Queries and Pages for impressions with few clicks or improving average position.\n2. Check whether an existing page already matches that search intent before creating anything new.\n3. Update an existing page or create a new one only when the query/page evidence supports that choice; use URL Inspection to verify index status when needed, not as a guarantee of faster indexing.",
     },
   };
 }
@@ -443,20 +443,19 @@ function renderMarkdown(data: {
   }
 
   if (!hasAnyMovers) {
-    const siteImpressionsChangePct =
-      prevTotals.impressions > 0
-        ? ((currentTotals.impressions - prevTotals.impressions) /
-            prevTotals.impressions) *
-          100
-        : 0;
-    const siteClicksChangePct =
-      prevTotals.clicks > 0
-        ? ((currentTotals.clicks - prevTotals.clicks) / prevTotals.clicks) *
-          100
-        : 0;
+    const siteImpressionsChangePct = percentageChangeOrNull(
+      currentTotals.impressions,
+      prevTotals.impressions,
+    );
+    const siteClicksChangePct = percentageChangeOrNull(
+      currentTotals.clicks,
+      prevTotals.clicks,
+    );
     const sitePositionDelta = currentTotals.position - prevTotals.position;
 
     const siteHadBigMove =
+      siteImpressionsChangePct === null ||
+      siteClicksChangePct === null ||
       Math.abs(siteImpressionsChangePct) >= 25 ||
       Math.abs(siteClicksChangePct) >= 25 ||
       Math.abs(sitePositionDelta) >= 3;
@@ -537,6 +536,11 @@ function formatPctChange(current: number, prev: number): string {
   return `${sign}${pct.toFixed(0)}% vs last week`;
 }
 
+function percentageChangeOrNull(current: number, baseline: number): number | null {
+  if (baseline === 0) return current === 0 ? 0 : null;
+  return ((current - baseline) / baseline) * 100;
+}
+
 function formatPositionChange(current: number, prev: number): string {
   if (prev === 0 || current === 0) return 'no comparison available';
   const diff = current - prev;
@@ -585,15 +589,20 @@ function isWithinLast3Days(endDate: string): boolean {
 }
 
 function describeSiteLevelMove(
-  impressionsChangePct: number,
-  clicksChangePct: number,
+  impressionsChangePct: number | null,
+  clicksChangePct: number | null,
   positionDelta: number,
 ): string {
   const candidates: Array<{
     metric: 'impressions' | 'position' | 'clicks';
     ratio: number;
   }> = [];
-  if (Math.abs(impressionsChangePct) >= 25) {
+  if (impressionsChangePct === null) {
+    candidates.push({
+      metric: 'impressions',
+      ratio: Number.POSITIVE_INFINITY,
+    });
+  } else if (Math.abs(impressionsChangePct) >= 25) {
     candidates.push({
       metric: 'impressions',
       ratio: Math.abs(impressionsChangePct) / 25,
@@ -602,7 +611,20 @@ function describeSiteLevelMove(
   if (Math.abs(positionDelta) >= 3) {
     candidates.push({ metric: 'position', ratio: Math.abs(positionDelta) / 3 });
   }
-  if (Math.abs(clicksChangePct) >= 25 && Math.abs(impressionsChangePct) < 25) {
+  if (
+    clicksChangePct === null &&
+    impressionsChangePct !== null
+  ) {
+    candidates.push({
+      metric: 'clicks',
+      ratio: Number.POSITIVE_INFINITY,
+    });
+  } else if (
+    clicksChangePct !== null &&
+    impressionsChangePct !== null &&
+    Math.abs(clicksChangePct) >= 25 &&
+    Math.abs(impressionsChangePct) < 25
+  ) {
     candidates.push({ metric: 'clicks', ratio: Math.abs(clicksChangePct) / 25 });
   }
 
@@ -613,6 +635,9 @@ function describeSiteLevelMove(
   }
 
   if (winner.metric === 'impressions') {
+    if (impressionsChangePct === null) {
+      return 'Your site recorded search impressions this week after the previous period recorded none. A percentage change is unavailable from a zero baseline; inspect Queries and Pages to see where the new visibility appeared.';
+    }
     if (impressionsChangePct >= 25) {
       return `Your site recorded many more search impressions this week (+${impressionsChangePct.toFixed(0)}%), but the increase was spread across lots of small queries rather than one big winner.`;
     }
@@ -626,7 +651,18 @@ function describeSiteLevelMove(
     return `Your average Search Console position improved by ${Math.abs(positionDelta).toFixed(1)} this week. Treat this as a trend signal rather than proof of a specific cause, and inspect the query/page rows that contributed most to the change.`;
   }
 
+  if (clicksChangePct === null) {
+    const impressionsContext =
+      impressionsChangePct === null
+        ? 'impressions also started from a zero baseline'
+        : `impressions moved ${impressionsChangePct >= 0 ? '+' : ''}${impressionsChangePct.toFixed(0)}%`;
+    return `Your site recorded clicks this week after the previous period recorded none; a click percentage change is unavailable from a zero baseline (${impressionsContext}). Review query/page CTR and average position before assigning a cause.`;
+  }
+  if (impressionsChangePct === null) {
+    return `Your clicks changed sharply this week (${clicksChangePct >= 0 ? '+' : ''}${clicksChangePct.toFixed(0)}%), while impressions started from a zero baseline so an impression percentage change is unavailable. Review query/page CTR and average position before assigning a cause.`;
+  }
   const clicksSign = clicksChangePct >= 0 ? '+' : '';
-  const impressionsSign = impressionsChangePct >= 0 ? '+' : '';
-  return `Your click rate changed sharply this week (clicks ${clicksSign}${clicksChangePct.toFixed(0)}%, but impressions only moved ${impressionsSign}${impressionsChangePct.toFixed(0)}%). Worth looking at whether something changed about how your titles or descriptions appear in search results.`;
+  const impressionsSign =
+    impressionsChangePct >= 0 ? '+' : '';
+  return `Your clicks changed sharply this week (clicks ${clicksSign}${clicksChangePct.toFixed(0)}%, while impressions moved ${impressionsSign}${impressionsChangePct.toFixed(0)}%). Review CTR and average position by query and page before forming hypotheses about snippets, ranking, search intent, demand, or SERP features.`;
 }

package/src/google.ts

@@ -247,6 +247,8 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
   const filters = body.dimensionFilterGroups?.flatMap((group) => group.filters) ?? [];
   const hasPageGroupingOrFilter =
     body.dimensions.includes('page') || filters.some((filter) => filter.dimension === 'page');
+  const hasQueryGroupingOrFilter =
+    body.dimensions.includes('query') || filters.some((filter) => filter.dimension === 'query');
 
   for (const filter of filters) {
     if (filter.expression.length > 4096) {
@@ -267,6 +269,12 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
     }
   }
 
+  if (body.type === 'discover' && hasQueryGroupingOrFilter) {
+    throw new Error(
+      'Google Discover does not support the query dimension or query filters in Search Analytics.',
+    );
+  }
+
   if (body.aggregationType === 'byNewsShowcasePanel') {
     if (body.type !== 'discover' && body.type !== 'googleNews') {
       throw new Error(
@@ -302,7 +310,11 @@ export type PaginatedSearchAnalyticsQuery = Omit<
 >;
 
 export interface SearchAnalyticsRow {
-  keys: string[];
+  /**
+   * Dimension values returned by Google. Aggregate queries with
+   * dimensions: [] legitimately omit this field.
+   */
+  keys?: string[];
   clicks: number;
   impressions: number;
   ctr: number;
@@ -681,16 +693,21 @@ export function processQuickWins(
   return rows
     .filter(
       (row) =>
-        row.keys.length >= 2 &&
+        (row.keys?.length ?? 0) >= 2 &&
         row.position >= minPosition &&
         row.position <= maxPosition &&
         row.impressions >= minImpressions
     )
-    .sort((a, b) => b.impressions - a.impressions)
-    .slice(0, 100)
+    .sort(
+      (a, b) =>
+        b.impressions - a.impressions ||
+        a.position - b.position ||
+        (a.keys?.[0] ?? '').localeCompare(b.keys?.[0] ?? '') ||
+        (a.keys?.[1] ?? '').localeCompare(b.keys?.[1] ?? ''),
+    )
     .map((row) => ({
-      query: row.keys[0],
-      page: row.keys[1],
+      query: row.keys![0],
+      page: row.keys![1],
       clicks: row.clicks,
       impressions: row.impressions,
       ctr: row.ctr,
@@ -711,6 +728,7 @@ export interface CannibalizationResult {
   query: string;
   total_clicks: number;
   total_impressions: number;
+  aggregation_scope: 'observed_query_page_rows';
   pages: CannibalizationPage[];
 }
 
@@ -721,9 +739,9 @@ export function processCannibalization(
 ): CannibalizationResult[] {
   const queryGroups = new Map<string, Array<{ page: string; clicks: number; impressions: number; ctr: number; position: number }>>();
   for (const row of rows) {
-    if (row.keys.length < 2) continue;
-    const query = row.keys[0];
-    const page = row.keys[1];
+    if ((row.keys?.length ?? 0) < 2) continue;
+    const query = row.keys![0];
+    const page = row.keys![1];
     if (!queryGroups.has(query)) {
       queryGroups.set(query, []);
     }
@@ -754,18 +772,31 @@ export function processCannibalization(
         query,
         total_clicks: totalClicks,
         total_impressions: totalImpressions,
-        pages: competingPages.sort((a, b) => b.impressions - a.impressions),
+        aggregation_scope: 'observed_query_page_rows',
+        pages: competingPages.sort(
+          (a, b) => b.impressions - a.impressions || a.page.localeCompare(b.page),
+        ),
       });
     }
   }
 
   return cannibalizationCandidates
-    .sort((a, b) => b.total_impressions - a.total_impressions)
-    .slice(0, 100);
+    .sort(
+      (a, b) =>
+        b.total_impressions - a.total_impressions ||
+        a.query.localeCompare(b.query),
+    );
 }
 
+export type ContentDecayClassification =
+  | 'likely_decay'
+  | 'weak_insufficient_evidence'
+  | 'improving_visibility_with_click_volatility';
+
 export interface DecayPageResult {
   page: string;
+  classification: ContentDecayClassification;
+  evidence: string;
   previous_clicks: number;
   recent_clicks: number;
   click_difference: number;
@@ -773,8 +804,83 @@ export interface DecayPageResult {
   previous_impressions: number;
   recent_impressions: number;
   impression_difference: number;
+  impression_change_percentage: number | null;
   previous_position: number;
   recent_position: number;
+  position_change: number | null;
+}
+
+function percentageChange(current: number, baseline: number): number | null {
+  if (baseline === 0) return current === 0 ? 0 : null;
+  return Math.round(((current - baseline) / baseline) * 1000) / 10;
+}
+
+function classifyContentDecay(input: {
+  previousClicks: number;
+  recentClicks: number;
+  previousImpressions: number;
+  recentImpressions: number;
+  previousPosition: number;
+  recentPosition: number;
+}): { classification: ContentDecayClassification; evidence: string } {
+  const {
+    previousClicks,
+    recentClicks,
+    previousImpressions,
+    recentImpressions,
+    previousPosition,
+    recentPosition,
+  } = input;
+  const clickDrop = previousClicks - recentClicks;
+  const clickDropPercentage =
+    previousClicks > 0 ? (clickDrop / previousClicks) * 100 : 0;
+  const impressionGrowth =
+    previousImpressions > 0
+      ? ((recentImpressions - previousImpressions) / previousImpressions) * 100
+      : 0;
+  const impressionDrop =
+    previousImpressions > 0
+      ? ((previousImpressions - recentImpressions) / previousImpressions) * 100
+      : 0;
+  const positionImprovement =
+    previousPosition > 0 && recentPosition > 0
+      ? previousPosition - recentPosition
+      : 0;
+  const positionWorsening =
+    previousPosition > 0 && recentPosition > 0
+      ? recentPosition - previousPosition
+      : 0;
+
+  const lowClickSample = previousClicks < 10 && clickDrop < 5;
+  const improvingVisibility =
+    impressionGrowth >= 10 && positionImprovement >= 2;
+
+  if (lowClickSample && improvingVisibility) {
+    return {
+      classification: 'improving_visibility_with_click_volatility',
+      evidence:
+        'The click decline is small in absolute terms while impressions grew at least 10% and average position improved by at least 2 positions.',
+    };
+  }
+
+  const meaningfulClickDecline =
+    previousClicks >= 10 && clickDrop >= 5 && clickDropPercentage >= 20;
+  const corroboratingVisibilityDecline =
+    impressionDrop >= 10 || positionWorsening >= 2;
+
+  if (meaningfulClickDecline && corroboratingVisibilityDecline) {
+    return {
+      classification: 'likely_decay',
+      evidence:
+        'Clicks fell by at least 5 from a baseline of at least 10, the decline was at least 20%, and impressions or average position also deteriorated materially.',
+    };
+  }
+
+  return {
+    classification: 'weak_insufficient_evidence',
+    evidence:
+      'Clicks declined, but the absolute sample or supporting impression/position signals are not strong enough to label the page as likely content decay.',
+  };
 }
 
 export function processContentDecay(
@@ -783,8 +889,8 @@ export function processContentDecay(
 ): DecayPageResult[] {
   const recentMap = new Map<string, { clicks: number; impressions: number; ctr: number; position: number }>();
   for (const row of recentRows) {
-    if (row.keys.length < 1) continue;
-    recentMap.set(row.keys[0], {
+    if ((row.keys?.length ?? 0) < 1) continue;
+    recentMap.set(row.keys![0], {
       clicks: row.clicks,
       impressions: row.impressions,
       ctr: row.ctr,
@@ -795,8 +901,8 @@ export function processContentDecay(
   const decayCandidates: DecayPageResult[] = [];
 
   for (const row of previousRows) {
-    if (row.keys.length < 1) continue;
-    const page = row.keys[0];
+    if ((row.keys?.length ?? 0) < 1) continue;
+    const page = row.keys![0];
     const prevClicks = row.clicks;
     const prevImps = row.impressions;
     const prevPos = row.position;
@@ -810,8 +916,18 @@ export function processContentDecay(
     const impDiff = recImps - prevImps;
 
     if (clickDiff < 0) {
+      const { classification, evidence } = classifyContentDecay({
+        previousClicks: prevClicks,
+        recentClicks: recClicks,
+        previousImpressions: prevImps,
+        recentImpressions: recImps,
+        previousPosition: prevPos,
+        recentPosition: recPos,
+      });
       decayCandidates.push({
         page,
+        classification,
+        evidence,
         previous_clicks: prevClicks,
         recent_clicks: recClicks,
         click_difference: clickDiff,
@@ -819,15 +935,29 @@ export function processContentDecay(
         previous_impressions: prevImps,
         recent_impressions: recImps,
         impression_difference: impDiff,
+        impression_change_percentage: percentageChange(recImps, prevImps),
         previous_position: prevPos,
         recent_position: recPos,
+        position_change:
+          prevPos > 0 && recPos > 0
+            ? Math.round((recPos - prevPos) * 10) / 10
+            : null,
       });
     }
   }
 
-  return decayCandidates
-    .sort((a, b) => a.click_difference - b.click_difference)
-    .slice(0, 100);
+  const classificationOrder: Record<ContentDecayClassification, number> = {
+    likely_decay: 0,
+    weak_insufficient_evidence: 1,
+    improving_visibility_with_click_volatility: 2,
+  };
+  return decayCandidates.sort(
+    (a, b) =>
+      classificationOrder[a.classification] -
+        classificationOrder[b.classification] ||
+      a.click_difference - b.click_difference ||
+      a.page.localeCompare(b.page),
+  );
 }
 
 // Google's Indexing API is not a general-purpose submission API. It is
@@ -1129,8 +1259,8 @@ export function processPerformanceComparison(
 ): PerformanceComparisonRow[] {
   const mapB = new Map<string, { clicks: number; impressions: number; ctr: number; position: number }>();
   for (const row of rowsB) {
-    if (row.keys.length < 1) continue;
-    mapB.set(row.keys[0], {
+    if ((row.keys?.length ?? 0) < 1) continue;
+    mapB.set(row.keys![0], {
       clicks: row.clicks,
       impressions: row.impressions,
       ctr: row.ctr,
@@ -1141,8 +1271,8 @@ export function processPerformanceComparison(
   const comparison: PerformanceComparisonRow[] = [];
 
   for (const row of rowsA) {
-    if (row.keys.length < 1) continue;
-    const key = row.keys[0];
+    if ((row.keys?.length ?? 0) < 1) continue;
+    const key = row.keys![0];
     const clicksA = row.clicks;
     const impsA = row.impressions;
     const ctrA = row.ctr;
@@ -1172,10 +1302,14 @@ export function processPerformanceComparison(
     });
   }
 
-  const mapAKeys = new Set(rowsA.map((r) => r.keys[0]));
+  const mapAKeys = new Set(
+    rowsA
+      .map((r) => r.keys?.[0])
+      .filter((key): key is string => key !== undefined),
+  );
   for (const row of rowsB) {
-    if (row.keys.length < 1) continue;
-    const key = row.keys[0];
+    if ((row.keys?.length ?? 0) < 1) continue;
+    const key = row.keys![0];
     if (mapAKeys.has(key)) continue;
 
     const clicksB = row.clicks;
@@ -1198,7 +1332,12 @@ export function processPerformanceComparison(
     });
   }
 
-  return comparison.sort((a, b) => b.period_a.clicks - a.period_a.clicks);
+  return comparison.sort(
+    (a, b) =>
+      Math.abs(b.diff.clicks) - Math.abs(a.diff.clicks) ||
+      Math.abs(b.diff.impressions) - Math.abs(a.diff.impressions) ||
+      a.key.localeCompare(b.key),
+  );
 }