Key parameter facts validated during implementation:

• runReport

  →

  metricIds

  (plural), not

  metricId

  ; dates as

  YYYY-MM-DDTHH:mm:ss

• findMetrics

  →

  expansions

  is a required parameter (use

  "componentType"

  )

• describeAa

  → parameter is

  guideType

  , not

  guide

  ;

  REPORT_SUITE_CONTEXT_GUIDE

  may return empty for some report suites — skip gracefully and proceed

• metrics/uniquevisitors

  is often unauthorized — use

  metrics/visits

  instead

• setSessionDefaults

  is the correct tool name (not

  setDefaultReportSuite

  )

• findReportSuites

  — select report suite

• setSessionDefaults

  — set session context (reportSuiteId + globalCompanyId)

• describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")

  — load org context; note: may return no output for some report suites — proceed without it

• findMetrics(expansions: "componentType")

  — resolve metric IDs (expansions parameter is required)

• listComponentUsage(componentType: "metric")

  — identify most-used metrics if not specified by the user

• runReport

  — current and comparison period with all metrics batched in one call (

  metricIds

  accepts comma-separated IDs); dimension breakdowns for top movers

• searchDimensionItems

  — validate dimension values for driver callouts

1. Confirm report suite.
2. Load organizational context:

findReportSuites()
setSessionDefaults(reportSuiteId: "<rsid>", globalCompanyId: "<companyId>")
describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")   # may return empty — proceed if so

• The organization's name and industry
• Which metrics are most used (top KPIs)
• Calendar conventions and timezone. Record these values — they are inputs to every date computation in Phase 1:

  • WEEK_START_DOW

    — day of week each week starts on. Default: Monday (ISO 8601).

  • FISCAL_YEAR_START_MONTH

    — month the fiscal year begins. Default: January (calendar year).

  • TIMEZONE

    — for example,

    America/Los_Angeles

    .

  • CALENDAR_SOURCE

    — one of

    "context guide"

    ,

    "default fallback"

    , or

    "user override"

    .
• Any active report suite segments

1. Period — "What time period should this briefing cover?"
   • Last week
   • Last month
   • Month-to-date (MTD)
   • This quarter / QTD
   • Last quarter
   • Custom date range

runReport

1. current.startDate < current.endDate

2. comparison.startDate < comparison.endDate

3. comparison.endDate < current.startDate

   (no overlap)
4. The day after

   comparison.endDate

   equals

   current.startDate

   (contiguous)

5. current

   and

   comparison

   have the same length in days
6. The alignment rule for

   PERIOD_TYPE

   is satisfied:

   • weekly

     : both

     startDate

     s fall on

     WEEK_START_DOW

   • monthly

     : both

     startDate

     s fall on the 1st of a month

   • month-to-date

     : both

     startDate

     s fall on the 1st; both

     endDate

     s have the same day-of-month

   • quarterly

     : both

     startDate

     s fall on the first day of a fiscal quarter

   • quarter-to-date

     : both

     startDate

     s fall on a fiscal quarter start; both

     endDate

     s are the same number of days into the quarter

   • custom

     : lengths match; contiguity holds

current.startDate

1. Audience — "Who is this briefing for?"
   • C-suite / board (highest level, fewest metrics, most context)
   • VP/Director level (more detail, some dimension context)
   • Marketing leadership (channel and campaign focus) Default: C-suite tone (concise, business-focused).
2. North-star metric — "What is the single most important metric for this briefing?" (e.g., revenue, conversions, retention rate) If not specified, use the most-used metric from

   listComponentUsage

   .
3. Supporting metrics — "What other metrics should be included? (up to 5)"
4. Specific topic focus — "Is there anything you want to highlight or investigate? (e.g., mobile performance, campaign results)"

findMetrics(expansions: "componentType")  # expansions required
listComponentUsage(componentType: "metric")  # if metrics not specified

Important:

findMetrics

requires the

expansions

parameter (use

"componentType"

as a safe default). Without it the call will fail.

Avoid

metrics/uniquevisitors

— this metric is frequently restricted and returns an "unauthorized_metric" error. Prefer

metrics/visits

for audience size.

Reliable standard metrics for AA briefings:

metrics/pageviews

,

metrics/visits

,

metrics/orders

,

metrics/revenue

,

metrics/bouncerate

,

metrics/occurrences

1. If the user named metrics explicitly, resolve each to ONE specific metric ID via

   findMetrics

   . On ambiguity, pick the metric with the highest

   usageCount

   from

   listComponentUsage

   and document the choice.
2. Otherwise, take

   listComponentUsage(componentType: "metric")

   results, sort by

   usageCount

   descending with metric ID alphabetical as the tiebreak (stable secondary sort), and take the top 6 metric IDs.
3. Use

   describeMetric

   to resolve to display names.
4. Do NOT cherry-pick by metric "type" (volume vs conversion vs revenue) and do NOT swap in an alternative metric because its name reads better in the narrative. Different runs picking

   metrics/orders

   vs a calculated metric also called "Orders" produce wildly different numbers and break trust.

runReport

runReport(
  dimensionId: "variables/daterangeday",
  metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
  startDate: "<YYYY-MM-DDTHH:mm:ss>",
  endDate:   "<YYYY-MM-DDTHH:mm:ss>"
)

Critical: The

runReport

parameter is

metricIds

(plural), not

metricId

. It accepts comma-separated IDs — pass all metrics in one call. Dates must be ISO 8601 with time component:

2026-03-31T00:00:00

/

2026-04-06T23:59:59

. Use

variables/daterangeday

as

dimensionId

to get a day-by-day breakdown; totals for each metric are in

summaryData.totals[0]

,

totals[1]

, etc. in order. If a metric is unauthorized, it surfaces in

columnErrors

— the overall call still succeeds.

• Current total
• Prior total
• Absolute and percent delta
• Trend direction (up/flat/down)

1. Opening headline — 1 sentence capturing the period's overall result. "Q2 performance was strong, with revenue growing 14% and conversion rates reaching a 12-month high."
2. North-star metric — 2–3 sentences on the most important KPI: value, change, context, what drove it.
3. Supporting highlights — 1 sentence per additional metric (positive first, then concerns).
4. Key driver — 2 sentences identifying what primarily caused movement. "Paid Search drove 60% of revenue growth, up from 48% in the prior period. Email performance also improved materially with a 22% lift in conversions."
5. Risk or watch item — 1–2 sentences on anything concerning: "Bounce rate on mobile increased 4pp, suggesting friction in the mobile experience worth investigating."
6. Forward look / ask — optional: what does this imply for next period?

• KPI values (the big number in each tile) — use full digits with thousands separators (

  8,160

  ,

  77,584

  ,

  1,250,000

  ). Do NOT use SI suffixes like

  K

  or

  M

  , even for large values. Executives want exact numbers, not abbreviations.
• Percent change (in pills and narrative bullets) — always one decimal place, rounded half-away-from-zero. For example,

  −23.55%

  displays as

  −23.6%

  , never

  −23.5%

  . Compute on full-precision values; round only at display time.
• Percentage-point change (for already-percentage metrics like Conversion Rate or Bounce Rate) — same rounding, suffix

  pp

  . Example:

  +0.40 pp

  .
• Currency —

  $

  prefix with thousands separators and no decimals for values ≥ $100 (

  $1,240,000

  ); cents only when value < $100 (

  $45.20

  ).

• Both periods return 0 or NULL for a metric in the resolved set: render the tile with

  kpi-value

  =

  Data unavailable

  , pill class

  flat

  , pill text

  ⚠ N/A

  , and

  prior

  text =

  Both periods returned no data — validate instrumentation

  . The tile stays in the grid; do not omit it.
• One period returns valid data, the other 0 / NULL: render the tile with the valid value as

  kpi-value

  , pill class

  flat

  , pill text

  ⚠ N/A

  , and

  prior

  text =

  Prior {period_noun}: no data

  .
• Never substitute a derived metric (e.g., adding "Conversion Rate" because Revenue came back $0). The visible KPI set MUST match the resolved metric IDs disclosed in the footer.
• If a Revenue / monetary metric is unavailable, surface a

  .callout.note

  above the KPI grid explaining the gap. Do not invent a value.

{PLACEHOLDER}

• {ORG_NAME}

  — The customer's business or brand name, derived from the report suite context loaded in Phase 0. Strip technical/environment suffixes like

   — Prod

  ,

   - Demo

  ,

   Stage

  ,

   Test

  ,

   MCP

  . If the report suite name has no clean brand label, fall back to the report suite display name with suffixes removed. Do not invent a name and do not substitute a vendor name.

• {PERIOD_TYPE}

  — One of

  Weekly

  ,

  Monthly

  ,

  Quarterly

  , or

  Performance

  (default), chosen from the period inferred in Phase 1.

• {LEDE_SENTENCE}

  — Use exactly this pattern, with no vendor names:

  Leadership readout for the {period type lowercase} of {PERIOD_LABEL} compared to {COMPARISON_LABEL}.

• {REPORT_SUITE}

  — Report suite display name. Suffixes are acceptable here — this row is the technical identifier line, not the title.

• {PERIOD_LABEL}

  /

  {COMPARISON_LABEL}

  — Human-readable date ranges, e.g.,

  May 12–18, 2026

  .

• {GENERATED_DATE}

  — Today's date in the same human format.

• {METRIC_LABEL}

  /

  {FORMATTED_VALUE}

  /

  {PCT_CHANGE}

  /

  {PRIOR_VALUE}

  — Per-KPI values from Phase 3. Use the metric's customer-facing display name, not its internal ID.

• Lead with the positive, then address concerns.
• Express deltas as business impact, not just percentages ("revenue grew $42K, up 14%" not just "+14%").
• For metrics that went down, include a possible explanation or next step.

• Do not present raw API output — always narrate the numbers.
• If a metric change is within ±3%, describe as "roughly flat" not a directional story.
• Always identify the comparison period explicitly in the briefing header.
• If context from

  REPORT_SUITE_CONTEXT_GUIDE

  identifies the company name or industry, use it in the narrative for a more personalized output.

"Write an exec summary of last week's performance for our leadership team."

1. Confirm report suite; load context guide.
2. Identify period: last 7 days vs. prior 7 days. Audience: VP level.
3. Confirm metrics: revenue, visits, orders, conversion rate, bounce rate.
4. Run 2 reports (all 5 metrics batched in one call per period).
5. Run channel breakdown for revenue.
6. Compose narrative: "Revenue grew 9% WoW to $186K, led by Paid Search which contributed 58% of revenue. Visits grew 18%, but mobile bounce rate increased 4pp, signaling a checkout experience issue worth investigating."
7. Generate HTML briefing and open.
8. Deliver the narrative as inline text for immediate use.