Context. get_amplitude_context (no args) → again with projectId. Do not guess project IDs.
Reuse before rebuild. search_amp_entities for existing analyses of the same area — saved charts already encode correct event names and segments.
Verify taxonomy before querying. Inspect the connected catalog and use its current taxonomy reader to confirm candidate event names, status, and queryability, then read event, user, or group properties for exact names and scope. Never guess names—a wrong name returns a well-formed chart with empty data, which reads as "zero".
Check the event is live. check_for_recent_event_ingestion confirms first-seen/last-seen before you query — a silent event means the chart will be empty no matter how correct the definition is.
Quantify. query_amplitude_data bursts — one slice per call (by version, by reason property, by platform), not one mega-query. Prefer the typed chart parameter (kind: 'segmentation', events + where/group_by + date_range); it compiles server-side and validation + taxonomy checks run automatically — no separate pre-flight call needed. Compare prod vs staging/UAT projects when the question is environment-specific.
Find affected users. query_amplitude_data with a user-ID group_by to rank affected users → use_amplitude_cohorts action: 'find' for the full set.
Reconstruct timelines. get_amp_user_data include: 'timeline' per user, batched (10–20 parallel calls is normal for population analysis; the tool accepts up to 10 identifiers per call).

query_amplitude_data parameterization (this is where most errors come from)

Compile errors are self-serve. The typed path fails with a 400 naming the offending field plus a fix hint — fix that one field and retry, don't rebuild. The three seen most: relative range whose unit doesn't match interval ("Last 3 Years" at weekly interval — re-denominate as "Last 156 Weeks" or change the interval); funnel conversion_window missing unit; unknown filter operator for that chart kind (use set for presence — works in every kind).
Date range is required — set date_range explicitly, either {relative: "Last 30 Days"} or {start, end} epoch seconds, never both. Sub-daily intervals only allow short windows (hour caps ~8 days); daily granularity caps around 30 days.
Every filter needs a valid operator and matching scope — take op and scope from the taxonomy lookup, not intuition. A scope mismatch ("property X is not tracked on this event_type") means you used a user property as an event property or vice versa.
Segments combine property conditions and behaviors — where (property conditions) plus performed ("users who did event ≥N times in a window"). Omit segments entirely for all users.
Raw definition fallback (composition, revenueLtv, advanced params): on failure the response embeds the chart-type schema with valid enums and a working example — fix from that and retry.
read ETIMEDOUT is a backend timeout — narrow the date range/filters and retry once.

What to report back

Whether the event fires at all, volume, and since when (first-seen).
Impact: affected-user count and share of active users.
The slices that matter (version, platform, reason property).
Affected-user evidence: top users by volume + 2–3 reconstructed timelines.

live-data-forensics

Live Data Forensics

The arc