/aa-conversion-funnel-analysis

name: aa-conversion-funnel-analysis
description: >
  Analyzes a multi-step conversion funnel to find where visitors drop off and
  which steps have the worst leakage. Use this skill when someone describes a
  journey and asks about conversion rates, drop-off, fallout, or step
  completion. Trigger for "analyze our checkout funnel," "where are visitors
  dropping off," "what's our add-to-cart to purchase conversion rate," "funnel
  analysis," "show me fallout between steps," or "which step loses the most
  visitors."
license: Apache-2.0
metadata:
  author: Adobe
  version: "1.0"

Conversion Funnel Analysis (Adobe Analytics)

Analyze a multi-step conversion funnel to identify where visitors drop off, which steps have the worst leakage, and what drives visitors to convert or abandon. Uses AA visit-level segment-based reporting to simulate funnel steps.

> **AA Container Model:** AA funnels use **hit**, **visit**, and **visitor** > containers — not CJA's event/session/person. Funnel steps are defined as > visit-level segments (visitors who completed the step during a visit). > > **Reporting approach:** AA does not have a native sequential fallout API > accessible via MCP. This skill approximates fallout by creating or finding > visit-level segments for each funnel step, then running the metric for > each step segment to compute pass-through rates.

---

AA MCP Tools Used

• `findReportSuites` — select report suite
• `setSessionDefaults` — set session context (reportSuiteId + globalCompanyId)
• `findDimensions` — discover page/event dimensions for step definition
• `findMetrics` — find visits or orders as the counting metric
• `searchDimensionItems` — validate page names or event values
• `findSegments` — find existing step segments if available
• `upsertSegment` — create visit-level step segments if not found
• `runReport` — run visits count for each step segment

---

Phase 0 — Setup

1. Confirm report suite with `findReportSuites` / `setSessionDefaults`. 2. Ask the user about the overall funnel scope (visit or visitor level):

• **Visit-level funnel:** all steps happen within a single visit

(typical for checkout funnels)

• **Visitor-level funnel:** steps can span multiple visits

(typical for lifecycle funnels)

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

---

Phase 1 — Define the Funnel Steps

Ask the user to describe each step of the funnel in plain language. Prompt for 3–8 steps. Example:

1. Product page viewed 2. Add to cart 3. Checkout started 4. Payment info entered 5. Order confirmed (purchase)

For each step, ask:

• "Is this defined by a page view (page name or URL), a custom event, or

a combination?"

• "Should this step be at the **hit** level (single page/event) or

**visit** level (any visit where this happened)?"

---

Phase 2 — Discover Components

2.1 Validate page names

For page-based steps:

findDimensions(page: 1, limit: 500)   # returns all available dimensions; look for variables/page
searchDimensionItems(
  dimensionId: "variables/page",
  searchOr: "<step page keywords>",   # space-separated keywords OR'd together
  startDate: "<start>",
  endDate: "<end>",
  page: 1,
  limit: 20
)

Common page dimension IDs: `variables/page`, `variables/entrypage`, `variables/exitpage`. Confirm the correct page name value with the user if multiple matches exist.

> **Note:** `searchDimensionItems` uses `searchOr` or `searchAnd` for filtering — not `searchTerm`. > If no rows return, try a wider date range — some report suites only have historical data.

2.2 Validate events/metrics

For event-based steps (add to cart, checkout, purchase):

findMetrics(expansions: "componentType,categories", page: 0, limit: 200)
# Filter results locally by name: visits, orders, pageviews, etc.

---

Phase 3 — Find or Create Step Segments

For each funnel step, search for an existing segment:

findSegments(searchTerm: "<step description>")

If an appropriate visit-level segment exists, use it directly.

If not, create a new visit-level segment for each step:

upsertSegment(
  definition: {
    "name": "Visit: Checkout Started",
    "description": "Visits where the visitor reached the checkout page",
    "reportSuiteID": "<rsid>",
    "container": {
      "func": "segment",
      "context": "visits",
      "pred": {
        "func": "streq",
        "val": "/checkout",
        "str": "/checkout",
        "dimension": "variables/page"
      }
    },
    "tags": [{ "name": "funnel" }]
  }
)

Create all step segments before running reports. Record each segment `id`.

> **Important:** Only create new segments with explicit user confirmation. > Present the list of segments to be created and ask: "I need to create N > visit-level segments to define your funnel steps. Is that OK?"

---

Phase 4 — Run Funnel Step Reports

For each step segment, run the visits count over the analysis period:

runReport(
  dimensionId: "variables/page",    # required by AA runReport
  metricIds: "metrics/visits",      # note: plural field name "metricIds"
  segmentIds: "<step segment id>",  # note: plural field name "segmentIds"
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# summaryData.totals[0] is the total visits for this segment

This is 1 call per funnel step. For a 5-step funnel = 5 calls.

Also run total visits (no segment) as the 100% baseline:

runReport(
  dimensionId: "variables/page",
  metricIds: "metrics/visits",
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# Use summaryData.totals[0] as the baseline visit count

> **AA runReport field names:** Use `metricIds` (not `metricId`) and `segmentIds` (not `segmentId`). > Use `startDate`/`endDate` (ISO 8601) rather than a `dateRange` object. > Always read totals from `summaryData.totals[0]`, not from `rows`.

---

Phase 5 — Compute Funnel Metrics

For