/aa-segment-performance-comparator

name: aa-segment-performance-comparator
description: >
  Compares the performance of two or more audience segments across key metrics
  side by side. Use this skill when someone wants to compare audiences or
  visitor groups — for example, "how do mobile visitors compare to desktop on
  conversion," "compare new vs. returning visitors," "show me the difference
  between these two segments," "compare these audiences on our KPIs," or
  "which segment performs better." Also trigger for "segment comparison" or
  "audience comparison."
license: Apache-2.0
metadata:
  author: Adobe
  version: "1.0"

Segment Performance Comparator (Adobe Analytics)

Compare the performance of two or more audience segments across key metrics side by side to understand how different visitor groups behave. Uses direct segment-vs-segment comparison to determine a winner, loser, and spread for each metric, with a separate context panel showing segment sizing.

> **AA Call Budget:** AA's `runReport` accepts a single `segmentId` per call. > For N segments × M metrics the comparison requires N×M calls, plus 1 > baseline call for the segment-size context panel. For 3 segments × 5 > metrics = 16 calls. Limit to 4 segments and 6 metrics for practical > performance. Always confirm the segment/metric list with the user before > starting.

---

AA MCP Tools Used

• `findReportSuites` — select report suite
• `setSessionDefaults` — set session context (reportSuiteId + globalCompanyId)
• `findSegments` — discover and select comparison segments
• `findMetrics` — resolve metric IDs
• `runReport` — one call per segment per metric, plus one unsegmented call for sizing context

---

Phase 0 — Setup

1. Confirm report suite with `findReportSuites` / `setSessionDefaults`.

findReportSuites(globalCompanyId: "<gcid>", page: 0, limit: 10)
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")

---

Phase 1 — Select Segments

Ask the user which segments to compare. If not specified, prompt: > "Which visitor audiences would you like to compare? For example: > Mobile vs. Desktop, New vs. Returning, Paid Search vs. Organic, or > specific named segments from your library."

Search for and confirm each segment:

findSegments(page: 0, limit: 50)
# Filter locally by name. Built-in IDs: "Paid_Search", "Purchasers", "Return_Visits"

> **Note:** `findSegments` does not accept a `searchTerm` parameter. Retrieve all segments > and filter by name locally. Built-in template segments have short IDs like "Paid_Search" > that can be passed directly as `segmentIds` in `runReport`.

If the user requests a segment that doesn't exist by name, offer to build it first using the aa-segment-builder skill, or suggest the closest existing segment from search results.

Limit: 4 segments maximum per comparison. Advise this limit upfront.

---

Phase 2 — Select Metrics

Ask the user which metrics to compare. Suggest a balanced mix:

• **Volume:** `metrics/visits`
• **Engagement:** `metrics/pageviews`, `metrics/bouncerate`,

`metrics/pagespervisit`

• **Conversion:** `metrics/orders`, conversion rate calculated metric
• **Revenue:** `metrics/revenue`

Call `findMetrics` to resolve each metric ID:

findMetrics(expansions: "componentType,categories", page: 0, limit: 200)
# Filter locally by name. Key IDs: metrics/visits, metrics/revenue, metrics/orders, metrics/bouncerate

Limit: 6 metrics maximum. Confirm the final list with the user: > "I'll compare these 3 segments across 5 metrics. This requires 16 report > calls (3 segments × 5 metrics + 1 sizing call). OK to proceed?"

---

Phase 3 — Select Date Range

Ask for or confirm the analysis period:

• Last 7 days (good for quick comparison)
• Last 30 days (recommended default)
• Last 90 days (for seasonal smoothing)
• Custom range

---

Phase 4 — Run Comparison Reports

4.1 Segment sizing (context only)

Run a single unsegmented call for `metrics/visits` to get the total population size, then one call per segment for `metrics/visits` to compute each segment's share of total. These sizing values populate the context panel — they are **not** used in the comparison matrix.

runReport(
  dimensionId: "variables/page",
  metricIds: "metrics/visits",
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# allVisitorVisits = summaryData.totals[0]

runReport(
  dimensionId: "variables/page",
  metricIds: "metrics/visits",
  segmentIds: "<segmentId>",
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# segmentVisits = summaryData.totals[0]; shareOfTotal = segmentVisits / allVisitorVisits × 100

> Reuse these results if `metrics/visits` is already a comparison metric.

4.2 Per segment per metric

For each segment × metric combination:

runReport(
  dimensionId: "variables/page",
  metricIds: "<metricId>",          # note: "metricIds" not "metricId"
  segmentIds: "<segmentId>",        # note: "segmentIds" not "segmentId"
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# Total = summaryData.totals[0]

> Read totals from `summaryData.totals[0]` (not `rows[]`). `dimensionId` is required — use any dimension with `limit: 1` for aggregate totals. Segment IDs are the raw `id` field from `findSegments`.

Track progress: "Fetching Segment 2 of 3, metric 3 of 5..."

---

Phase 5 — Build the Comparison Matrix

The matrix compares segments directly to each other — no baseline column.

For each metric row, compute:

| Computed Value | Formula | |---|---| | Segment value | Raw from `runReport` | | Winner | Segment with the best value for this metric | | Loser | Segment with the worst value for this metric | | Spread | (max − min) / max × 100 | | Significant? | `true` if spread > 10% |

For metrics where lower is better (bounce rate, cost per acquisition), invert the winner/loser logic — the segment with the **lowest** value wins. Mark these metrics clearly in the report.

5.1 Segment profile summary

For each segment, compu