/aa-top-movers-watchlist

name: aa-top-movers-watchlist
description: >
  Identifies which items (pages, campaigns, products, channels, regions) had
  the biggest increases or decreases for a key metric between two time periods.
  Use this skill when someone asks "what's up and what's down," "which campaigns
  moved the most," "top gainers and losers," "what pages are trending," "show
  me what changed by channel," or any variation of identifying the biggest
  movers and decliners for a metric.
license: Apache-2.0
metadata:
  author: Adobe
  version: "1.0"

Top Movers Watchlist (Adobe Analytics)

Identify which dimension items had the biggest increases and decreases for a key metric between two time periods. Surface the top gainers and losers across pages, channels, campaigns, products, or any other breakout dimension.

---

AA MCP Tools Used

• `findReportSuites` — select report suite
• `setSessionDefaults` — set session context (reportSuiteId + globalCompanyId)
• `describeAa(REPORT_SUITE_CONTEXT_GUIDE)` — load calendar/timezone context
• `findMetrics` — resolve the key metric ID
• `findDimensions` — discover available breakdown dimensions
• `runReport` — period A and period B for each dimension
• `searchDimensionItems` — validate specific items if needed

---

Phase 0 — Setup

1. Confirm report suite with `findReportSuites` / `setSessionDefaults`. 2. Call `describeAa(REPORT_SUITE_CONTEXT_GUIDE)` to load report suite context. Record:

• `WEEK_START_DOW` — first-day-of-week from the context guide. If the

context guide returns no value, use **Monday** (ISO 8601) as the explicit deterministic default. This is not a fallback that drifts between runs: every run on the same report suite resolves to the same `WEEK_START_DOW`, either from the context guide or from the fixed Monday default.

• `TIMEZONE` — report suite timezone.
• `WEEK_START_DOW_SOURCE` — `"context guide"` if the value came from

`describeAa`, `"default"` if the context guide was silent and Monday was used. Surface this in the artifact footer so the source is auditable.

You will use these values in Phase 1 when defining Period A and Period B.

findReportSuites(globalCompanyId: "<gcid>")
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")
describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")

---

Phase 1 — Confirm Parameters

Ask the user:

1. **Metric** — "Which metric should I rank movers by? (visits, revenue, conversions, page views, etc.)" If not specified, default to `metrics/visits`.

2. **Dimension** — "Which dimension should I break down?

• Pages
• Marketing Channel
• Campaigns
• Products
• Traffic Sources
• Geographic Regions
• Entry Pages"

If not specified, offer the above list.

3. **Time periods** — "What two periods should I compare?" Common defaults:

• This week vs. last week
• This month vs. last month
• Last 7 days vs. prior 7 days
• Last 30 days vs. prior 30 days

**Calendar rule (mandatory):** Period A and Period B MUST use the same `WEEK_START_DOW` from Phase 0 — both periods' `startDate` fall on the same day-of-week, both are exactly equal length, and Period B ends immediately before Period A starts. Never mix conventions (e.g., a Mon–Sun Period A with a Sun–Sat Period B) within the same run. For custom date ranges, compute Period B as the equal-length window ending immediately before Period A starts.

**Sanity check before calling `runReport`:** confirm `periodA.startDate` and `periodB.startDate` are the same day-of-week and that `periodA.startDate - periodB.endDate == 1 day`. If not, recompute.

4. **Item limit** — how many top gainers and losers to show (default: 10 each).

5. **Materiality threshold** — minimum absolute value in Period A or B to be included (filters out noise from low-volume items). Default: exclude items with fewer than 100 visits (or equivalent) in both periods.

Confirm: "I'll show the top 10 gainers and losers for [metric] broken down by [dimension], comparing [Period A] vs [Period B]."

---

Phase 2 — Resolve Components

findMetrics(expansions: "componentType")
findDimensions(page: 1, limit: 100)

> **Note:** `findMetrics` requires the `expansions` parameter (use `"componentType"` > or `"categories"`). `findDimensions` requires `page` and `limit`.

Record `id` for the metric and dimension.

---

Phase 3 — Run Period Reports

Run the metric for the selected dimension in both periods:

runReport(
  metricIds: "<metricId>",
  dimensionId: "<dimensionId>",
  startDate: "<period A start>T00:00",
  endDate: "<period A end>T23:59",
  limit: 200
)

runReport(
  metricIds: "<metricId>",
  dimensionId: "<dimensionId>",
  startDate: "<period B start>T00:00",
  endDate: "<period B end>T23:59",
  limit: 200
)

> **Note:** `runReport` uses `metricIds` (not `metricId`) and `startDate`/`endDate` > in ISO 8601 format (`YYYY-MM-DDTHH:mm`), not a `dateRange` parameter.

Use `limit: 200` to capture enough items for a meaningful mover analysis.

---

Phase 4 — Compute Deltas and Rank

For each dimension item present in either period:

1. Period A value (or 0 if not in results) 2. Period B value (or 0 if not in results) 3. Absolute delta: Period A - Period B 4. Percent change: delta / Period B × 100 (or "+100% new" if Period B = 0) 5. Apply materiality filter: exclude items where max(Period A, Period B) < materiality threshold

Sort by absolute delta descending for gainers (positive delta). Sort by absolute delta ascending for losers (negative delta).

Take top N from each list.

Special cases

• **New items** (present in Period A only): flag as "New — no prior period

data." Include if materiality threshold met.

• **Disappeared items** (present in Period B only, 0 in Period A): flag as

"Dropped — no current period data."

• **Near-zero items**: items with <1% of total metric value — consider

excluding from the watchlis