/aa-kpi-pulse

name: aa-kpi-pulse
description: >
  Produces a compact KPI digest showing how key metrics changed over a period
  and what's driving the movement. Use this skill when someone asks for a
  performance summary, a weekly recap, a morning briefing, a KPI update, or any
  variation of "how did we do this week/month." Also trigger for "give me a
  performance overview," "what moved in the last 7 days," "pull our AA KPI
  report," or "summarize our metrics."
license: Apache-2.0
metadata:
  author: Adobe
  version: "1.0"

KPI Pulse (Adobe Analytics)

Produce a compact, digestible KPI digest showing how key metrics changed over a chosen period, which items drove the change, and what stood out. Batches all KPIs into two `runReport` calls (current period + comparison period) and assembles results into an HTML performance card deck.

---

AA MCP Tools Used

• `findReportSuites` — select working report suite
• `setSessionDefaults` — set session context (reportSuiteId + globalCompanyId)
• `describeAa(REPORT_SUITE_CONTEXT_GUIDE)` — load org context, top metrics,

calendar config, and timezone

• `findMetrics` — discover and validate metric IDs
• `listComponentUsage` — identify top-used metrics if user hasn't specified
• `runReport` — all KPIs batched in one call per period (current + comparison)
• `searchDimensionItems` — find top contributors for top-mover callouts

---

Phase 0 — Setup

1. Confirm report suite with `findReportSuites` / `setSessionDefaults`. 2. Call `describeAa(REPORT_SUITE_CONTEXT_GUIDE)` to load organizational context: top metrics, calendar configuration, and timezone. Record the report suite's first-day-of-week as `WEEK_START_DOW` and the report suite timezone as `TIMEZONE` — you will use both when computing reporting periods in Phase 2. If the context guide returns no `WEEK_START_DOW`, default to **Monday** (ISO 8601).

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

---

Phase 1 — Select KPIs

1.1 If the user specified metrics

Resolve each to an AA metric ID:

findMetrics(searchTerm: "<metric name>")

Cap at 8 metrics for a focused pulse. If more are requested, ask the user to prioritize or offer to split into multiple reports.

1.2 If the user has not specified metrics

Use `listComponentUsage` to find the most-used metrics in the report suite:

listComponentUsage(componentType: "metric")

Select the top 5–7 by usage count. Confirm with the user: > "Based on usage, I'll track: Visits, Page Views, Revenue, Orders, > Conversion Rate, Bounce Rate. Does this look right, or would you like > to adjust?"

---

Phase 2 — Select Time Periods

Ask the user what period to report on, or infer from context:

| Request | Current Period | Comparison Period | |---|---|---| | "this week" | Last 7 days | Prior 7 days | | "this month" | Month-to-date | Same period last month | | "last month" | Last full calendar month | Same month prior year | | "this quarter" | Quarter-to-date | Same period last quarter | | "YTD" | Jan 1 to today | Same period prior year |

Confirm: "I'll compare [current period] vs [comparison period]. Is that right?"

**Calendar rule (mandatory):** the current period and the comparison period MUST use the same `WEEK_START_DOW` from Phase 0. For weekly pulses, both periods' `startDate` fall on the same day-of-week, both are exactly 7 days long, and the comparison period ends immediately before the current period starts. Never mix conventions (e.g., a Mon–Sun current with a Sun–Sat prior) within the same pulse. For custom date ranges, compute the comparison period as the equal-length window ending immediately before the current period starts.

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

**Edge case:** If today is within the first 3 days of a period, note that the current-period data may be incomplete and the comparison may look skewed.

---

Phase 3 — Fetch KPI Data

Batch all selected metrics into a single call per period:

runReport(
  metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
  dimensionId: "variables/daterangeday",
  startDate: "<current period start>T00:00",
  endDate: "<current period end>T23:59"
)

runReport(
  metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
  dimensionId: "variables/daterangeday",
  startDate: "<comparison period start>T00:00",
  endDate: "<comparison period end>T23:59"
)

> **Note:** `metricIds` accepts comma-separated IDs — pass all KPIs at once. > `startDate`/`endDate` (not `dateRange`); no `granularity` parameter. > Use `variables/daterangeday` for day-by-day breakdown. > `summaryData.totals[0]`, `totals[1]`, etc. correspond to each metric in order. > Unauthorized metrics surface in `columnErrors`; the rest of the call still succeeds.

2 calls total regardless of metric count.

From each pair, compute:

• Current value (total over period)
• Prior value (total over comparison period)
• Absolute delta: current - prior
• Percent change: (delta / prior) × 100
• Trend: ↑ if positive, ↓ if negative, → if within ±2%

---

Phase 4 — Top Mover Context

For the 1–2 metrics with the largest percent changes (positive or negative), run a dimension breakdown to find the top contributor:

runReport(
  metricIds: "<metricId>",
  dimensionId: "variables/marketingchannel",
  startDate: "<current period start>T00:00",
  endDate: "<current period end>T23:59",
  limit: 5
)

Repeat for a second dimension if relevant (e.g., pages for a traffic spike, products for a revenue change).

Use results to write a 1–2 sentence driver narrative: > "Visits rose 18% WoW, driven primarily by Organic Search (+34%) which > offset a decline in Direct traffic (-12%)."

---

Phase 5 — Generate HTML Report