Update to GSC Wizard - SEO analysis

{
  "description": "Compare search rankings between any two periods for one Search Console property with the GSC Wizard MCP tools: new, lost, improved and declined queries and pages, movement between position bands, daily drill-downs on the top movers in each direction, and the Google updates or logged site changes that explain them. The user picks both windows, from last week against the week before to this quarter against the same quarter last year. Use when the user asks \"what moved up or down\", \"winners and losers\", \"which keywords dropped\", \"ranking changes since\", \"compare this month with last month\", or \"year over year rankings\".",
  "included_files": [],
  "name": "ranking-changes",
  "skill_md_contents": "---\nname: ranking-changes\ndescription: Compare search rankings between any two periods for one Search Console property with the GSC Wizard MCP tools: new, lost, improved and declined queries and pages, movement between position bands, daily drill-downs on the top movers in each direction, and the Google updates or logged site changes that explain them. The user picks both windows, from last week against the week before to this quarter against the same quarter last year. Use when the user asks \"what moved up or down\", \"winners and losers\", \"which keywords dropped\", \"ranking changes since\", \"compare this month with last month\", or \"year over year rankings\".\n---\n\n# Ranking Changes\n\nReport the winners and losers between two periods on one property and explain the biggest moves. Unlike the weekly-report skill, which is a fixed digest over the last settled week, this skill lets the user choose both windows, including year over year. The user's request may contain a property, the two periods in any phrasing (\"September vs August\", \"last 14 days vs the 14 before\", \"Q3 2026 vs Q3 2025\"), a dimension to lead with (queries or pages), a search type, and a focus hint such as a country or a section; honor each.\n\n## Workflow\n\n1. **Resolve the property.** If the user's request or the conversation names a property, use it. Site URLs use GSC formats: `sc-domain:example.com` or `https://www.example.com/`. Otherwise call `list_sites` and pick the obvious match. If several plausible properties exist, ask the user which one before continuing.\n\n2. **Fix the two windows.** The default is the last 28 settled days compared with the previous 28, which is what the tools use when all four date fields are omitted. Otherwise:\n   - Translate the user's phrasing into `startDate`/`endDate` (the current window) and `comparisonStartDate`/`comparisonEndDate` (the baseline) as YYYY-MM-DD, and keep both windows the same length.\n   - Keep the newest 2 days out of the current window: GSC data lags about 2 to 3 days, so never treat the most recent 2 days as complete, and if a dip appears at the very edge of the range, say it is likely reporting lag, not a real drop.\n   - For year over year, use the same calendar dates one year earlier; on a site with a weekly rhythm shift by 364 days rather than 365 so the weekdays line up.\n   - State both windows on the first line of the output. If `get_position_distribution` answers the baseline window with `emptyBecause`, or `get_ranking_changes` files nearly every key as `new` with an empty `lost` bucket (its own `emptyBecause` appears only when both periods are empty), the stored history does not reach that far; say so instead of guessing.\n\n3. **Query movers.** Call `get_ranking_changes` with `dimension: \"query\"`, the four dates from step 2, and `limit: 50` (per bucket, 1 to 10000; raise it to 200 on a large property). Pass `searchType` only when the user asked for image, video or news; the default is web.\n   - Read `counts` for the full size of each bucket, then the buckets `new`, `lost`, `improved` and `declined`.\n   - Each row carries `key`, `clicks`, `impressions`, `ctr`, `position`, `prevClicks`, `prevImpressions`, `prevPosition` and `positionDelta` (prevPosition minus position: positive is an improvement, negative a decline; a new or lost key's missing side reads 0).\n   - `improved` and `declined` arrive sorted by the size of the position move, `new` by `clicks` and `lost` by `prevClicks`; re-rank improved and declined by click impact (`clicks` for improved, `prevClicks` for declined) before choosing the rows to show.\n   - Note `dataSource`: on the live API a key just below the scan cut can show as new or lost, so treat small new and lost rows there with care.\n\n4. **Page movers.** Repeat the call with `dimension: \"page\"`.\n   - Match page losers against query losers: a page that lost its top queries is the unit to fix.\n   - A query that moved although its page held means another page on the site took it over, which is the cannibalization skill's job; a page that is new while its queries are not points to a URL change, so check for a migration before calling it a win.\n\n5. **Band movement.** Call `get_position_distribution` twice with `granularity: \"period\"` and `dimension: \"query\"`: once with the current window as `startDate`/`endDate`, once with the baseline.\n   - Compare `buckets` by `label` (1-3, 4-10, 11-20, 21+) on `rows`, `impressions`, `clicks` and `impressionShare`; derive the share deltas yourself and say so.\n   - When the move built up over the window rather than landing on one day, call it once more with `granularity: \"daily\"` over the current window and read `days`, one row per date with the count of distinct queries per band, to see the day the counts shifted.\n   - If `truncated` is true on the live API path, raise `scanLimit` (1000 to 200000) and say the deep bands were understated.\n\n6. **Drill into the top three movers each way.** For the three largest gainers and the three largest losers by click impact, pull the daily series across both windows:\n   - `get_query_performance` with `query`, `startDate` set to the baseline start and `endDate` to the current end (add `pageUrl` when the user wants the query on one URL) returns `daily` rows.\n   - `get_page_performance` with `pageUrl` and the same dates does the same for a page.\n   - Read each series for its shape: a step on one date (look for a cause on that date), a slow slide (content decay; point to the content-decay skill), or a swing that reversed inside the window (volatility, not a trend). Say whether the move still holds in the last 7 settled days.\n\n7. **Explain.** Pull the events that span both windows:\n   - `list_annotations` with `siteUrl`, `startDate` set to the baseline start and `endDate` to the current end, for logged site changes.\n   - `list_algo_updates` with the same dates, for Google ranking updates (`updates` rows carry `name`, `beginISO`, `endISO`, `severity`); an empty list is not proof that nothing changed, since only confirmed updates are listed.\n   - Tie each top mover to an event on or just before its step date where the dates line up, and say plainly when nothing does. A year-over-year span covers many updates, so name only those overlapping the step dates found in step 6.\n\n## Interpretation rules\n\n- `ctr` values are already percentages on a 0-100 scale. Never multiply them by 100.\n- `position`: lower is better. A change toward a lower number is an improvement; never color it as a decline. `positionDelta` already has the sign the right way round: positive means improved.\n- Judge by clicks and impressions at stake, not by percentage or position change alone: a query falling from 2 to 5 on 3,000 clicks outranks one falling from 40 to 80 on 10.\n- Present every multi-row result as a compact markdown table (top rows only, typically 5 to 10); keep prose for interpretation, not for restating numbers.\n- Do not fabricate rows the tools did not return. If a bucket is empty, say so, and quote the tool's `emptyBecause` when it gives one.\n\n## Output\n\nState both windows and the lead dimension on the first line, then present, in this order:\n\n1. **Four compact tables**, one per bucket in the order improved, declined, new, lost. Each holds the top 5 queries followed by the top 5 pages for that bucket, and the bucket's `counts` value sits above it so the reader sees how many rows it really holds:\n\n   | Key | Clicks (current) | Clicks (baseline) | Position (current) | Position (baseline) | positionDelta |\n   |---|---|---|---|---|---|\n\n2. **Band movement**: a four-row table (1-3, 4-10, 11-20, 21+) with rows, impressions and impression share for both windows and the derived delta, plus one sentence on what the shift means (share leaving 1-3 is lost visibility on winning terms; rows entering 11-20 from 21+ are terms within reach):\n\n   | Band | Rows (current) | Rows (baseline) | Impressions (current) | Impressions (baseline) | Share (current) | Share (baseline) | Share delta |\n   |---|---|---|---|---|---|---|---|\n\n3. **Drill-downs**: for each of the six movers, two or three flowing sentences on the shape of the daily series, when it moved, whether it still holds, and the matched update or annotation if any.\n4. **Recommendations**: a short prioritized list of 3 to 7 concrete items, each naming the query or page and the action, for example refresh the page that slid, consolidate the two pages trading one query, strengthen a page that reached 4-10 and can take 1-3, or rewrite titles where position held but clicks fell.\n\n## Error handling\n\nIf any tool call fails with an authentication or subscription error, tell the user to reconnect the GSC Wizard app from their app or connector settings, and that a GSC Wizard account with an active plan or trial plus a connected Google Search Console account is required. If the property is not found, re-run `list_sites` and offer the closest matches instead of guessing a URL format. If a single tool fails for another reason, report the gap in the relevant section and complete the rest of the workflow with the remaining data.\n\n## Grounding\n\nEvery number you report must name the tool it came from and the date range it covers, for example \"clicks 12,340 (`get_site_summary`, 2026-09-21 to 2026-09-27)\". For a table, state the tool and date range once on the line above it. If you derive a figure yourself (a delta, a sum, a share), say so and name the tool outputs it was computed from. Never report a number no tool returned.\n"
}