A user describes a metric or question in plain language and wants a chart built
You need to visualize a KPI, funnel, retention cohort, or user journey
An existing chart doesn't exist and you need to create one from scratch
You want to save an ad-hoc analysis so others can revisit and share it
Building a dashboard and gaps exist in available charts
Core Jobs
1. Get Context
Call mcp__Amplitude__get_context to understand the user's organization, active project, and available projects. This returns the projectId (appId) you will need for all subsequent calls. Never guess or hardcode a projectId.
2. Decompose the Request into Chart Components
Break the natural language request into structured chart components before touching any tool:
相关技能
Chart type: what kind of visualization is appropriate (see chart types below)
Metric: what is being measured (count, DAU, conversion rate, p50 latency, etc.)
Time range: last 7 days, last 30 days, custom range
Primary event: the core action being tracked
Filters: conditions that narrow the dataset (platform = iOS, plan = Pro, country = US)
Groupings: dimensions to break the metric down by (by platform, by cohort, by geography)
Secondary events: for funnels and retention — the sequence or return event
3. Search Events Broadly First
Use mcp__Amplitude__get_event_properties to discover valid event and property names. Search broadly — do not assume exact event names. Try multiple search terms if the first attempt returns no results. Event names are project-specific and must be discovered, never guessed.
4. Review All Results
Examine all returned events and properties. Look for naming conventions (snake_case, camelCase, verb-noun patterns). Understand the data model before selecting specific events.
5. Select Best Events with Rationale
Choose the most semantically appropriate events for the chart. If multiple candidates exist, select the one most likely to capture the user's intent. Document your selection rationale in the output so the user can validate.
6. Find Similar Existing Charts as Reference
Use mcp__Amplitude__get_charts to search for existing charts similar to what you are about to build. This serves two purposes: (a) avoid duplicating an existing chart, and (b) use an existing chart's structure as a template to ensure correctness.
7. Build the Chart Definition
Construct the chart definition object with all required fields based on the chart type. Use the existing chart structure as reference if found in step 6.
8. Query the Dataset
Execute the chart query to fetch real data and validate that the chart produces meaningful results. If the result is empty, revisit your event selection and filters.
9. Save the Result
Use the appropriate save tool to persist the chart. Return the chart URL so the user can view and share it.
Chart Types
eventsSegmentation: Most versatile type. Use for trends over time, KPI tracking, DAU/WAU/MAU, and single-metric analysis. Good default when unsure.
funnels: Multi-step conversion analysis. Measures how many users complete step A then step B (then step C...). Essential for onboarding, checkout, and signup flows.
retention: Cohort return analysis. Measures what percentage of users who did event A on day 0 return to do event B on day N. Use for stickiness and habit formation.
dataTableV2: Tabular breakdown across multiple metrics and dimensions. Use when the user wants to compare many metrics side-by-side in table form.
customerJourney: Path exploration. Shows what users do before and after a key event. Use when exploring unknown drop-off points or discovery patterns.
sessions: Session-level analysis — duration, frequency, depth. Use when the question is about how deeply users engage per visit rather than over time.
MCP Tools
mcp__Amplitude__get_context — get organization and project context (call first, always)
mcp__Amplitude__get_event_properties — discover valid event and property names for the project
mcp__Amplitude__get_charts — search for existing charts to use as templates or to avoid duplication
mcp__Amplitude__query_chart — execute a chart query to preview data before saving
mcp__Amplitude__save_chart_edits — persist the final chart definition
Key Concepts
projectId / appId: The numeric identifier for an Amplitude project. Required by all data tools. Get it from get_context.
eventsSegmentation: The default chart type for time-series trend analysis.
Sample Ratio Mismatch (SRM): An imbalance in traffic allocation that can invalidate results.
Grouping: Breaking a metric down by a dimension (e.g., by platform, country, plan).
Filter: Narrowing the dataset to a specific subset before computing the metric.
Cohort: A group of users who share a common attribute or behavior in a defined time window.
Event property: A key-value pair attached to an event at the time it fires (e.g., plan_type = "pro").
User property: A persistent attribute on a user profile that can change over time.
Output Format
The output includes:
A brief explanation of which chart type was chosen and why
The events selected and the rationale for each selection
Any filters or groupings applied, with reasoning
A link to the saved chart in Amplitude
A 2-3 sentence interpretation of the data returned — what the chart shows at a high level
If the chart could not be built (e.g., no matching events found), the output explains what was searched, what was found, and what the user should do next (e.g., verify event names with their analytics team).