Amplitude

Create a comprehensive dashboard with charts, rich text, and custom layout

WHEN TO USE:

• After the user has searched existing content or explored some analysis in Amplitude
• The user has explicitly requested to create a dashboard

CRITICAL

• CHART IDs MUST BE FROM SAVED CHARTS:
• Only use chartIds from SAVED/PERMANENT charts - these are returned by save_chart_edits (in the chartId field) or create_chart
• DO NOT use editIds from query_dataset - these are temporary IDs that cannot be added to dashboards
• DO NOT use the editId from query_dataset responses - you must first call save_chart_edits to get a permanent chartId
• The typical workflow is: query_dataset (returns editId) → save_chart_edits (converts editId to permanent chartId) → create_dashboard (uses chartId)
• If you use an editId instead of a saved chartId, the dashboard creation will fail with "NotFoundError: No chart"

INSTRUCTIONS:

• Provide a descriptive name for the dashboard
• Use rows array where each row contains items in left-to-right order
• Each item specifies width (3-12 columns). If width is omitted, items auto-fill remaining space
• Each row must specify height in pixels. Only heights of 375, 500, 625, 750 are allowed
• Total width of items in a row must not exceed 12 columns
• Max 4 items per row (ensures minimum 3-column width per item)
• Use chartMetas to configure chart display options (view type, annotations, etc.)
• Return a link to the new dashboard in the response
• DO NOT include static analysis in dashboard text content. Dashboards are meant to be long-lived and thus a point in time insight does not help
• DO group similar charts together and include a header and some text describing how to interpret the charts effectively

MARKDOWN FORMAT:

• Rich text content uses standard markdown syntax
• Supported: headers (

#

###), bold (text), italic (*text*), lists (- or 1.), links ([text](url)), code blocks (

), inline code (`code`)
- Example: "

Overview\n\nThis dashboard shows key metrics for user engagement."

LAYOUT EXAMPLES:

• Full-width item: { height: 6, items: [{ type: 'chart', chartId: '123', width: 12 }] }
• Two side-by-side: { height: 4, items: [{ type: 'chart', chartId: '1', width: 6 }, { type: 'rich_text', content: '

Notes', width: 6 }] }

• Three columns: { height: 5, items: [{ width: 4 }, { width: 4 }, { width: 4 }] }
• Auto-fill: { height: 4, items: [{ type: 'chart', chartId: '1' }, { type: 'chart', chartId: '2' }] } (each gets 6 columns)

Unified entry point for Amplitude context. Routes to one of two underlying tools based on whether a projectId is provided.

ROUTES:

• No projectId → 'get_context' route: returns the current user, organization (including org-level AI context), and the LIST of accessible projects as { appId, appName }. Use this to discover which projects exist and their ids.
• projectId provided → 'get_project_context' route: returns that single project's details — description, timezone, currency, session definition, source projects, and project-level AI context.

WHEN TO USE:

• Session start, "what projects do I have access to?", "show me my org details", "what is my role?" → call with no arguments.
• "what timezone / currency / session settings does project X use?", "describe project X" → pass projectId.

CONTEXT DOCUMENTS (uploaded files):

• org.aiContext / project aiContext are short text fields only. Customers also upload context files (CSV data dictionaries, PDFs, process docs) in Settings → AI Controls; those are indexed for search and never returned in full — only titles (opt-in) or search snippets.
• listContextDocuments: true adds contextDocuments — document titles and ids only, no file contents. Use it when aiContext references an uploaded file by name (e.g. "always check <file> before answering").
• searchContextDocuments runs semantic search over the uploaded documents' contents and adds contextDocumentSearch with matching text snippets. Use specific terms from the user's question (event names, property names, column names).
• Scope for both: without projectId, org-level documents only; with projectId, org-level plus that project's documents.

EXAMPLES:

• Session start: {}
• Project settings: {"projectId": 12345}
• aiContext says "check the event dictionary file" → {"projectId": 12345, "listContextDocuments": true}
• Look up a term from uploaded docs: {"projectId": 12345, "searchContextDocuments": "envelope_event_type_id"}

NOTES:

• projectId is optional on purpose. Omit it to get the project list first, then call again with a real id from that list — do NOT guess project ids.
• The two layers are meant to be loaded together: call once without projectId at session start for org context, then with a projectId to drill into a project. On conflict, project-level context overrides org-level.
• Omit listContextDocuments and searchContextDocuments at session start — they add latency and are only useful once you know what to look for.

DO NOT USE FOR:

• Running analytics queries → use 'query_dataset'.
• Finding charts/dashboards/cohorts → use 'search'.

Retrieve chart alert anomalies for a project or for one specific chart.

WHEN TO USE:

• The user wants recent chart alerts, anomalies, or alert notifications.
• Use chartId to scope to one chart.
• Use get_chart_monitor when the user wants monitor configuration or subscribers instead of alert history.

INSTRUCTIONS:

• chartId is optional. If provided, projectId is not needed.
• For project-wide alerts, projectId is optional only when the user has access to exactly one project. If multiple projects are accessible, provide projectId.
• includeUnseen filters to alerts the current user has not marked as seen.
• limit defaults to 20 and is capped at 100.

EXAMPLES:

• {"projectId":"12345"}
• {"chartId":"abc123","limit":10}
• {"projectId":"12345","includeUnseen":true}

NOTES:

• This tool returns alert anomalies, not monitor configuration.
• Alerts are returned newest first.

Get the parameter schema, valid enum values, and a working example for a specific chart type.

WHEN TO USE:

• Before calling query_dataset, to understand the correct parameter schema for a chart type.
• When you need to know valid enum values (e.g., funnel modes, segmentation metrics).
• When you need a working example definition to use as a template.

INSTRUCTIONS:

• Call this tool with the chart type you want to build a definition for.
• Use the returned schema to construct a valid definition object.
• Pass the constructed definition to query_dataset.
• If the chart type is not yet supported, construct the definition based on existing chart examples from search/get_charts.

SUPPORTED CHART TYPES: eventsSegmentation, funnels, metricExplorer, retention, revenueLtv, sessions, stickiness

Retrieve the current monitor configuration and subscribers for a chart.

WHEN TO USE:

• The user wants to inspect a chart alert monitor before changing it.
• Use this before subscribe_chart_alert if you need the monitorId or current subscriber list.
• Use get_chart_alerts if the user wants alert anomalies instead of monitor settings.

INSTRUCTIONS:

• Provide chartId.
• Returns the monitor ID, enabled state, conditions, email recipients, and channel subscriptions.

EXAMPLES:

• {"chartId":"abc123"}

NOTES:

• This only works for charts that already have a monitor.

Retrieve full chart objects by their IDs using the chart service directly

WHEN TO USE:

• You want to retrieve a full chart definition.
• Useful if you want to base an ad hoc query dataset analysis on an exsiting chart.

INSTRUCTIONS:

• Use the search tool to find the IDs of charts you want to retrieve, then call this tool with the IDs.

Get detailed information about specific cohorts by their IDs.

WHEN TO USE:

• You want to retrieve full cohort definitions after finding them via search.
• You need detailed cohort information including definition, metadata, and audience details.

INSTRUCTIONS:

• Use the search tool to find the IDs of cohorts you want to retrieve, then call this tool with the IDs.
• This returns full cohort objects with all details, unlike the search tool which returns summary information.

Get information about the current user, organization, and list of accessible projects.

WHEN TO USE:

• "What projects do I have access to?"
• "Show me my organization details"
• "What is my user role?"
• Any session start, before drilling into a specific project — load the org layer first.

RETURNS:

• User details (email, name, role)
• Organization info: name, plan, quota, and org.aiContext — org-level AI context (company-wide business definitions, glossary terms, KPI rules, behavior guidelines). Canonical source for org-scoped guidance.
• List of accessible projects (just names and IDs)

CONTEXT LAYERING:

• org.aiContext here is the org-level layer of customer AI context.
• For project-specific guidance — including project-level AI context, timezone, currency, source projects, and session settings — call 'get_project_context' with a projectId.
• The two layers are intended to be loaded together. On conflict, project-level context supplements or overrides org-level context.

DO NOT USE FOR:

• Project-specific settings (timezone, currency, sessions) → use 'get_project_context' instead
• Running analytics queries → use 'query_dataset' or 'query_amplitude_data' instead
• Finding charts/dashboards/cohorts → use 'search' instead

Get specific dashboards and all their charts

WHEN TO USE:

• You want to retrieve full dashboard definitions including chart IDs that you can query and analyze individually.

INSTRUCTIONS:

• Use the search tool to find the IDs of dashboards you want to retrieve, then call this tool with the IDs.
• Very commonly you will want to query the charts after retrieving a dashboard.
• When a dashboard has activeFilters (saved Replace Property entries, dashboard filters, or a date range), pass the dashboard's id as dashboardId to query_charts so those params are applied — and mention the replaced/filtered view when reporting numbers.

Retrieve event properties for a specific event type from a project. This tool provides a concise way to get all properties associated with a particular event.

WHEN TO USE:

• You want to get all properties associated with a particular event with the EXACT event type.

INSTRUCTIONS:

• Search for the exact event type you want to get properties for using the search tool or the get_events tool.
• Use this tool to get all event properties associated with a particular event.

Retrieve events from a project with strict filtering by event types, limit, and cursor pagination.

WHEN TO USE:

• You can generally rely on the search tool to find the event you are looking for.
• Use this tool to get full event objects, including metadata like category, activity, visiblity, and more.
• Use this tool to paginate through ALL events when the search tool may not return the event you are looking for.

INSTRUCTIONS:

• Get the project ID from the context tool.
• Use the search tool first to try to find the event you're looking for.
• If the search tool does not return the event you are looking for, use this tool without specifying eventTypes to paginate through all events.
• If you know the event types you want to get, use this tool with the eventTypes parameter to get more information about the event.
• By default, returns events from the project's default branch. Pass branchId or branchName to fetch events from a specific tracking-plan branch — use get_branches first to find the branch.

NOTES:

• Event types are equivalent to the ingested name. Always use "ingested name" instead of "event type" when responding to the user.
• Each event has a "status" field: "planned" (in tracking plan, not yet ingested), "live" (in tracking plan and ingested), "unexpected" (ingested, not in tracking plan), "blocked" (ingestion blocked by an admin), or "deleted" (soft-deleted; only returned when includeDeleted is true).
• Amplitude system events (e.g. "[Amplitude] Page Viewed", "session_start", "_active") are flagged with "isAmplitudeEvent: true". The tracking-plan UI special-cases these as "live" in its status filter regardless of actual ingestion state — keep that in mind when reasoning about why a system event might show as "unexpected" or "planned" here.
• Source events of enabled merge transformations are hidden — only the merged target is returned, with a "mergedFrom" field listing the source event names. mergedFrom is always included for merge targets even when fields omits it (otherwise source-hiding would drop context).
• "firstSeen"/"lastSeen" are lifetime ingestion timestamps (not scoped to a lookback window). "createdAt"/"updatedAt" are tracking-plan edit times and are only present for events in the plan — unexpected events omit them. "updatedBy" is the last editor; Amplitude does not record who originally created an event.
• Valid requested fields: name, displayName, description, category, tags, status, isActiveAction, isOfficial, isAmplitudeEvent, hiddenFrom, sources, mergedFrom, owner, createdAt, updatedAt, updatedBy, firstSeen, lastSeen.
• Automatically returned when fields is provided: name (plus mergedFrom when the event is a merge target).
• When fields is omitted, the full event row is returned. Required fields are automatic, and [] is invalid.

Retrieve specific experiments by their IDs.

WHEN TO USE:

• You want to retrieve addition information for experiments like state, decisions, etc.

INSTRUCTIONS:

• Use the search tool to find the IDs of experiments you want to retrieve, then call this tool with the IDs.

Retrieve specific feature flags by their IDs or flag key.

WHEN TO USE:

• You want to retrieve full flag definitions including variants, metadata, and configuration details.

INSTRUCTIONS:

• Use the search tool to find the IDs of flags you want to retrieve, then call this tool with the IDs.
• You can also pass in flag key instead and this can return multiple flags since the same flag key can be in multiple projects.

Retrieve objects from Amplitude URLs

WHEN TO USE:

• CRITICAL: Only use this tool for full Amplitude app URLs on supported hosts (app.amplitude.com, app.eu.amplitude.com, apps.stag2.amplitude.com, local.amplitude.com)
• You have an Amplitude URL and want to get the full object definition
• User shares a link to a dashboard, chart, notebook, experiment, etc.

INSTRUCTIONS:

• Provide the full Amplitude URL (e.g., https://app.amplitude.com/analytics/myorg/chart/456 or https://app.eu.amplitude.com/analytics/myorg/chart/456)
• The tool will parse the URL, validate the organization, and return the full object
• Works with charts, dashboards, notebooks, experiments, flags, cohorts, metrics, and opportunities
• /chart/new/{id} URLs may refer to a chart draft or a temporary chart edit (from query tools); both are resolved automatically
• Agent session URLs (/agents/session/{id}) are not resolvable here — use get_agent_results with the session_id instead

Get detailed information about specific metrics by their IDs.

WHEN TO USE:

• You want to retrieve full metric definitions after finding them via search.
• You need detailed metric information including params, key properties, and metadata.

INSTRUCTIONS:

• Use the search tool to find the IDs of metrics you want to retrieve, then call this tool with the IDs.
• This returns full metric objects with all details, unlike the search tool which returns summary information.
• If you already have the metric ID, you can not use this tool and instead query the metric directly using query_metric if that is what the user wants.

Retrieve the audit history for a chart monitor.

WHEN TO USE:

• The user wants to know who changed a chart monitor and when.
• Use get_chart_monitor first if you need to discover the monitorId from a chart.

INSTRUCTIONS:

• Provide monitorId.
• Returns the history entries in reverse chronological order.

EXAMPLES:

• {"monitorId":"mon_123"}

NOTES:

• This is monitor change history, not alert anomaly history.

Get specific notebooks and all their charts

WHEN TO USE:

• You want to retrieve full notebook definitions including chart IDs that you can query and analyze individually.

INSTRUCTIONS:

• Use the search tool to find the IDs of notebooks you want to retrieve, then call this tool with the IDs.
• Very commonly you will want to query the charts after retrieving a notebook.
• The returned notebook rows have markdown content and use the same schema as create_notebook, so you can directly copy and modify them to create new notebooks.

Get project-specific settings and configuration for a specific project.

WHEN TO USE:

• "What timezone is this project using?"
• "What are the currency settings?"
• "How are sessions defined?"
• "What is the week start day?"

RETURNS:

• Timezone and date settings (timezone, week start, quarter start)
• Currency settings (locale, target currency)
• Session definition (timeout, custom property)
• Source projects (data lineage)
• Project-level AI context (project-specific business guidelines)

CONTEXT LAYERING:

• This tool returns the project-level layer of customer AI context only.
• For org-level AI context (company-wide business definitions, glossary, KPI rules, behavior guidelines), call 'get_context' — it carries org.aiContext and is the canonical source for org-scoped guidance.
• Call 'get_context' once per session before drilling into specific projects so you have both layers loaded. On conflict, project-level context supplements or overrides org-level context.

REQUIRES: projectId parameter

DO NOT USE FOR:

• Listing all projects → use 'get_context' instead
• User/org info → use 'get_context' instead

List the properties that exist in a project's taxonomy — the direct way to answer "which/what properties exist on <event>?" and to discover valid property names before querying or filtering.

WHEN TO USE — answer questions like:

• "Which properties exist on the checkout event?" → { propertyType: "event", eventType: "checkout", projectId }
• "What properties are on the Purchase event?" → { propertyType: "event", eventType: "Purchase", projectId }
• "What user properties are in my project?" → { propertyType: "user", projectId }
• "What group / derived / channel / lookup properties are tracked?" → set propertyType accordingly
• Discovering valid event-property names before building a query_dataset filter or group_by

This is a fast, direct lookup. Do NOT run query_dataset to discover which properties an event has — that is a schema lookup, not a metric query, and belongs here.

DO NOT USE FOR:

• Metrics, counts, trends, funnels, retention → use 'query_dataset'
• Finding which EVENTS exist (not their properties) → use 'get_events' or 'search'

PROPERTY TYPES: | propertyType | What it returns | Key params | |---|---|---| | event | Event properties. Pass eventType to scope to one event; omit it to list project-wide. Pass includeDeleted to include deleted properties. | eventType, includeDeleted | | user | User-level properties | sources, name | | derived | Computed/formula properties | derivedPropertyType, names | | group | Group properties (e.g., company_name, plan_tier) | groupTypes | | lookup | CSV lookup table properties | configurationFilter, lookupTableName | | channel | Traffic source channel classifiers (derived formula properties) | names | | persisted | Event-to-user persisted properties | names |

CHART QUERY PROP TYPES (query_dataset / chart definitions):

• Derived and channel classifier properties must use prop_type / group_by.type / subprop_type of "derivedV2" — not legacy "derived" or other invented types.
• get_properties returns chartPropType: "derivedV2" for derived and channel properties. propertyType "event"/"user" is display scope only, not the chart API type.

GLOBAL VS. EVENT-SCOPED EVENT PROPERTIES: Event properties in Amplitude have two scopes:

• Global (plan-wide): a property definition shared across the project's tracking plan, not tied to a single event.
• Event-scoped (local): a definition attached to one specific event type (e.g., "Button Clicked.button_name").

When the user looks for event properties without specifying a scope (global or event-scoped), prompt for clarification.

INSTRUCTIONS:

• Use the search tool or get_events first to find exact event/property names before calling this tool.
• All property types support limit/cursor pagination. For 'event', pagination applies only when eventType is omitted (event-scoped returns all properties for that event).
• If the user has not specified a project, prompt them to decide. Don't decide for them.

EXAMPLES:

• Event properties for one event: { "propertyType": "event", "projectId": "123", "eventType": "Button Clicked" }
• All event properties in a project: { "propertyType": "event", "projectId": "123" }
• Including deleted: { "propertyType": "event", "projectId": "123", "includeDeleted": true }
• User properties: { "propertyType": "user", "projectId": "123", "sources": ["CUSTOMER"] }
• Derived properties: { "propertyType": "derived", "projectId": "123", "derivedPropertyType": "event" }
• Group properties: { "propertyType": "group", "projectId": "123", "groupTypes": ["company"] }

Search session replays for a project using segment filters.

WHEN TO USE:

• You want to find session replays that match user segments or conditions (e.g., variant membership, cohorts, user properties).

INSTRUCTIONS:

• Provide the projectId and one or more segments with conditions.
• Searches the last 30 days with a limit of 10 replays by default.
• Optionally include eventCountFilters, groupBys, and limit.

IMPORTANT: ALWAYS provide the clickable replay links to users. Each session replay result includes a direct URL that users can click to view the full replay in Amplitude's Session Replay interface. These links are essential for users to actually watch and analyze the sessions. Simply providing raw session data without the viewing links is not helpful.

EXAMPLES:

• Segments: All users

segmentFilters: [{ "conditions": [] }]

• Segments: Experiment variant membership

segmentFilters: [ { "conditions": [ { "type": "property", "group_type": "User", "prop_type": "user", "prop": "gp:[Experiment] My Flag", "op": "is", "values": ["treatment"] } ] } ]

• Segments: Country = US and plan in {Pro, Enterprise}

segmentFilters: [ { "conditions": [ {"type":"property","group_type":"User","prop_type":"user","prop":"country","op":"is","values":["US"]}, {"type":"property","group_type":"User","prop_type":"user","prop":"plan","op":"is","values":["Pro","Enterprise"]} ] } ]

• Event counter: at least 1 Purchase event

eventCountFilters: [ { "count": "1", "operator": "greater or equal", "event": {"event_type": "Purchase", "filters": [], "group_by": []} } ]

• Event counter: >= 3 Page Viewed on pricing page

eventCountFilters: [ { "count": "3", "operator": "greater or equal", "event": { "event_type": "Page Viewed", "filters": [ { "group_type": "User", "subprop_key": "page", "subprop_op": "is", "subprop_type": "event", "subprop_value": ["pricing"] } ], "group_by": [] } } ]

NOTES:

• Prefer property-based segment conditions for attributes; prefer eventCountFilters for behavioral criteria.

Query a single chart given its ID.

RULES:

• Users want to know references for analyses in order to validate the data.
• ALWAYS REFERENCE CHARTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES.

WHEN TO USE:

• You want to query a chart to get its data.
• Only one chart or chart edit can be queried in a single request.

PREREQUISITES (required):

• You MUST have a concrete chartId or chartEditId before calling this tool. Do not call it speculatively.
• If you do not already have one, resolve it FIRST via:
• search with entityTypes: ["CHART"] to find a saved chart by name.
• get_from_url when the user has shared an Amplitude chart URL.
• query_amplitude_data if the user wants an ad-hoc analysis rather than an existing chart.
• If the user has not provided a chart reference and none of the above apply, STOP and ask the user which chart to query.

INSTRUCTIONS:

• Provide saved charts via chartId and chart edits (links ending in /chart/new/<edit_id> or /chart/<chart_id>/edit/<edit_id>) via chartEditId.
• Only one chart or chart edit ID is allowed per request; if you have both, prefer chartEditId.
• Results will include data for the chart and errors if it fails.

RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. Check the isCsvResponse flag to determine which response format to parse

CRITICAL — NON-ADDITIVE METRICS (uniques, pct_dau):

• These metrics cannot be summed across intervals. The chart UI plots per-interval values, not a running total.
• Additive metrics (totals, sums) CAN be summed across intervals.

How to read the JSON response, by metric type:

1. COUNT metrics ("uniques"):

• Use "overallSeries" — it is the TRUE deduped unique count across the full date range.
• Do NOT sum "timeSeries" values — that overstates the count due to user overlap across intervals.

2. RATIO metrics ("pct_dau" only):

• Use "timeSeriesAverage" (mean of per-interval values) — this matches what the chart UI displays.

For "current" reporting, also consider the most recent N intervals from "timeSeries".

• Do NOT use "overallSeries" for pct_dau over multi-interval ranges. For pct_dau, "overallSeries"

is a long-range aggregate (deduped numerator over the full range / deduped denominator over the full range). Over many intervals the denominator dedupes a much larger pool than the numerator, which compresses the ratio — typically reporting roughly half of the per-interval values the chart shows. This is mathematically valid as a long-range aggregate but is NOT what users see in the chart.

• Do NOT sum "timeSeries" values — ratios cannot be summed.

CSV Response Structure (when isCsvResponse is true):

• Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details
• Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)
• Data rows: Each row contains:
• Label columns: First few columns contain row labels identifying the data series
• Value columns: Numerical data organized under the corresponding date/time columns from the data header row
• Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns
• Cells in the CSV response are delimited by commas and may be prepended with a character

Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. IMPORTANT: The overall unique users is 5642 (NOT 614+1769+4132=6515), because users overlap across days. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'"

" Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "eventsSegmentation", }

JSON Response Structure (when isCsvResponse is false):

• Parse using the following structure:
• timeSeries: Array of arrays, each containing data points for a given time period with a "value" property
• overallSeries: Array of arrays, each containing the overall data point across the entire range under the "value" property.

IMPORTANT — interpretation depends on the metric:

• For "uniques" (count): this is the TRUE deduped unique count over the full date range. Use this.
• For "pct_dau" (ratio): this is a long-range aggregate ratio (deduped numerator

over range / deduped denominator over range). It does NOT match the per-interval values the chart UI plots and is typically much smaller. Do NOT report it as the headline number — use "timeSeriesAverage" instead.

• timeSeriesAverage: Present only for "pct_dau". Array of arrays, one per series, each

containing a single {value} that is the mean of "timeSeries" values for that series. Use this as the headline ratio when the chart spans multiple intervals — it matches what users see in the chart UI.

• seriesMetadata: Array of objects containing metadata for each series
• xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series
• Use the dataset definition to be able to parse referenced events, properties, and segments.

Example below is a JSON response is for the same query as the CSV example above. { "timeSeries": [[{"value": 614}, {"value": 1769}, {"value": 4132}]], "overallSeries": [[{"value": 5642}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "UNIQUES(A)"}], "xValuesForTimeSeries": ["2025-08-23T00:00:00", "2025-08-24T00:00:00", "2025-08-25T00:00:00"] } Note: 614+1769+4132=6515, but overallSeries shows 5642. This is because unique users overlap across days. For "uniques", always use overallSeries for the total.

Example below is a "pct_dau" query over 3 weeks (a ratio metric): { "timeSeries": [[{"value": 0.1402}, {"value": 0.1421}, {"value": 0.1444}]], "overallSeries": [[{"value": 0.0712}]], "timeSeriesAverage": [[{"value": 0.1422}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "PCT_DAU(A)"}], "xValuesForTimeSeries": ["2026-04-06T00:00:00", "2026-04-13T00:00:00", "2026-04-20T00:00:00"] } Note: the chart UI shows ~14% per week. timeSeriesAverage (14.22%) matches that. overallSeries (7.12%) is the deduped 3-week aggregate ratio and would HALVE the reported value if used as the headline — never report it as "the number" for "pct_dau". Always use timeSeriesAverage for "pct_dau".

Query up to 3 charts concurrently given their IDs.

RULES:

• Users want to know references for analyses in order to validate the data.
• ALWAYS REFERENCE CHARTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES.

WHEN TO USE:

• You want to query multiple charts to get their data efficiently.
• Maximum of 3 charts can be queried in a single request.

PREREQUISITES (required):

• You MUST have at least one concrete chartIds or chartEditIds entry before calling this tool. Do not call it speculatively.
• If you do not already have any, resolve them FIRST via:
• search with entityTypes: ["CHART"] to find saved charts by name.
• get_from_url when the user has shared Amplitude chart URLs.
• query_dataset if the user wants an ad-hoc analysis rather than an existing chart.
• If the user has not provided chart references and none of the above apply, STOP and ask the user which charts to query.

INSTRUCTIONS:

• Provide saved charts via chartIds and chart edits (links ending in /chart/new/<edit_id> or /chart/<chart_id>/edit/<edit_id>) via chartEditIds.
• Chart edit IDs take precedence over chart IDs when both are available for a given chart.
• Use this tool to query up to 3 charts + chart edits (combined total).
• Results will include data for each successfully queried chart and errors for any failed charts.

RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. Check the isCsvResponse flag to determine which response format to parse

CRITICAL — NON-ADDITIVE METRICS (uniques, pct_dau):

• These metrics cannot be summed across intervals. The chart UI plots per-interval values, not a running total.
• Additive metrics (totals, sums) CAN be summed across intervals.

How to read the JSON response, by metric type:

1. COUNT metrics ("uniques"):

• Use "overallSeries" — it is the TRUE deduped unique count across the full date range.
• Do NOT sum "timeSeries" values — that overstates the count due to user overlap across intervals.

2. RATIO metrics ("pct_dau" only):

• Use "timeSeriesAverage" (mean of per-interval values) — this matches what the chart UI displays.

For "current" reporting, also consider the most recent N intervals from "timeSeries".

• Do NOT use "overallSeries" for pct_dau over multi-interval ranges. For pct_dau, "overallSeries"

is a long-range aggregate (deduped numerator over the full range / deduped denominator over the full range). Over many intervals the denominator dedupes a much larger pool than the numerator, which compresses the ratio — typically reporting roughly half of the per-interval values the chart shows. This is mathematically valid as a long-range aggregate but is NOT what users see in the chart.

• Do NOT sum "timeSeries" values — ratios cannot be summed.

CSV Response Structure (when isCsvResponse is true):

• Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details
• Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)
• Data rows: Each row contains:
• Label columns: First few columns contain row labels identifying the data series
• Value columns: Numerical data organized under the corresponding date/time columns from the data header row
• Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns
• Cells in the CSV response are delimited by commas and may be prepended with a character

Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. IMPORTANT: The overall unique users is 5642 (NOT 614+1769+4132=6515), because users overlap across days. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'"

" Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "eventsSegmentation", }

JSON Response Structure (when isCsvResponse is false):

• Parse using the following structure:
• timeSeries: Array of arrays, each containing data points for a given time period with a "value" property
• overallSeries: Array of arrays, each containing the overall data point across the entire range under the "value" property.

IMPORTANT — interpretation depends on the metric:

• For "uniques" (count): this is the TRUE deduped unique count over the full date range. Use this.
• For "pct_dau" (ratio): this is a long-range aggregate ratio (deduped numerator

over range / deduped denominator over range). It does NOT match the per-interval values the chart UI plots and is typically much smaller. Do NOT report it as the headline number — use "timeSeriesAverage" instead.

• timeSeriesAverage: Present only for "pct_dau". Array of arrays, one per series, each

containing a single {value} that is the mean of "timeSeries" values for that series. Use this as the headline ratio when the chart spans multiple intervals — it matches what users see in the chart UI.

• seriesMetadata: Array of objects containing metadata for each series
• xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series
• Use the dataset definition to be able to parse referenced events, properties, and segments.

Example below is a JSON response is for the same query as the CSV example above. { "timeSeries": [[{"value": 614}, {"value": 1769}, {"value": 4132}]], "overallSeries": [[{"value": 5642}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "UNIQUES(A)"}], "xValuesForTimeSeries": ["2025-08-23T00:00:00", "2025-08-24T00:00:00", "2025-08-25T00:00:00"] } Note: 614+1769+4132=6515, but overallSeries shows 5642. This is because unique users overlap across days. For "uniques", always use overallSeries for the total.

Example below is a "pct_dau" query over 3 weeks (a ratio metric): { "timeSeries": [[{"value": 0.1402}, {"value": 0.1421}, {"value": 0.1444}]], "overallSeries": [[{"value": 0.0712}]], "timeSeriesAverage": [[{"value": 0.1422}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "PCT_DAU(A)"}], "xValuesForTimeSeries": ["2026-04-06T00:00:00", "2026-04-13T00:00:00", "2026-04-20T00:00:00"] } Note: the chart UI shows ~14% per week. timeSeriesAverage (14.22%) matches that. overallSeries (7.12%) is the deduped 3-week aggregate ratio and would HALVE the reported value if used as the headline — never report it as "the number" for "pct_dau". Always use timeSeriesAverage for "pct_dau".

Event Segmentation with Insights (anomaly detection / confidence intervals):

• When params.insights.isOn is true, Event Segmentation charts queried via query_charts or query_dataset

return BOTH chartConfig (Highcharts) AND jsonResponse with joinable band data.

• jsonResponse.seriesIntervals maps stringified seriesMetadata keys to { low, high, yhat } arrays

(parallel to xValuesForTimeSeries). Use seriesMetadata + xValuesForTimeSeries to join bands to series.

• Metric Explorer charts with Insights return seriesIntervals inside each data[] entry instead.

Execute a data query using the dataset endpoint for more complex queries.

WHEN TO USE

• You want to query data to form an ad hoc analysis within a project that does not already exist as a chart, metric, or experiment.
• You want to tweak an existing chart to glean more information from it (e.g. add a group by, change the time range, etc.)

STRATEGIES

1. Use the 'search' tool to find existing charts that relate to the data you want to query. 2. Use the 'get_charts' tool to understand the events, properties, and dataset schema generally. 3. Optionally use the 'search' tool again to find additional events, user properties, etc. needed for the query. 4. Optionally use the 'get_event_properties' tool to get properties on individual events. 3. Use this tool to query the ad hoc analysis.

GENERAL GUIDELINES

• Don't assume or guess properties, events, or schema. Use the tools provided to you to understand the data before running a dataset query.
• When running into query failures, try searching for existing charts to understand the data taxonomy and dataset schema.
• When you receive a 400 error response the schema is likely incorrect or the events/properties do not exist.

AMPLITUDE WIDE META EVENTS TYPES

Special system events available for analysis. Events are passed in the "event_type" field:

• "_active": Any active event useful for tracking 'active users' like DAU, MAU(events not marked as inactive)
• "_all": Any event being tracked in Amplitude
• "_new": Events triggered by new users within the time interval. Useful for tracking 'new users'.
• "_any_revenue_event": Any revenue-generating event. Useful for tracking 'revenue'.
• "$popularEvents": Top events by volume (dynamically computed). Useful for more meta taxonomy analyses like 'what are the most common events'.

PROPERTY TYPES:

• AMPLITUDE CORE PROPERTIES: Built-in properties automatically tracked by Amplitude
• Have source: "AMPLITUDE"
• Use standard naming (lowercase, underscores)
• Available for all events and users
• CUSTOM PROPERTIES: Organization-defined properties
• Have source: "CUSTOMER"
• ALWAYS prefixed with "gp:" (e.g., "gp:email", "gp:full name")
• Include experiment flags like "gp:[Experiment] feature-name"

COMPLETE LIST OF AMPLITUDE CORE PROPERTIES:

User & Session Identification:

• user_id: Primary user identifier
• amplitude_id: Amplitude's internal user ID
• device_id: Unique device identifier
• session_id: Session identifier
• event_id: Unique event identifier

Geographic Properties:

• ip_address: User's IP address
• country: Country (from GeoIP)
• city: City (from GeoIP)
• region: State/region (from GeoIP)
• dma: Designated Market Area
• $postal_code: Postal/ZIP code
• location_lat: Latitude coordinate
• location_lng: Longitude coordinate

Device & Platform Properties:

• platform: Device platform (iOS, Android, Web, etc.)
• device: Device family name
• device_type: Type of device (mobile, tablet, desktop)
• os: Operating system
• language: Device language setting
• carrier: Mobile carrier

Application Properties:

• version: Current app version
• start_version: Version when user first used the app
• library: SDK library used to send data
• server_upload_time: When data was received by Amplitude

Business Properties:

• paying: Whether user is a paying customer

RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. Check the isCsvResponse flag to determine which response format to parse

CSV Response Structure (when isCsvResponse is true):

• Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details
• Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)
• Data rows: Each row contains:
• Label columns: First few columns contain row labels identifying the data series
• Value columns: Numerical data organized under the corresponding date/time columns from the data header row
• Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns
• Cells in the CSV response are delimited by commas and may be prepended with a character

Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'"

" Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "eventsSegmentation", }

JSON Response Structure (when isCsvResponse is false):

• Parse using the following structure:
• timeSeries: Array of arrays, each containing data point for a given time period with a "value" property
• overallSeries: Array of arrays, each containing data the overall data point (across the entire range) under the "value" property
• seriesMetadata: Array of objects containing metadata for each series
• xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series
• Use the dataset definition to be able to parse referenced events, properties, and segments.

Example below is a JSON response is for the same query as the CSV example above. { "timeSeries": [[{"value": 614}, {"value": 1769}, {"value": 4132}]], "overallSeries": [[{"value": 5642}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "UNIQUES(A)"}], "xValuesForTimeSeries": ["2025-08-23T00:00:00", "2025-08-24T00:00:00", "2025-08-25T00:00:00"] }

Run analytics queries to answer data questions about users, events, funnels, and retention.

Chart definitions are validated inline before querying. When validation fails, the response includes chartTypeSchema (parameter schema, valid enums, working example, coercion rules) so you can fix the definition and retry.

Optional: call verify_chart_definition first for a dry-run validation without executing a query.

WHEN TO USE

• Answer questions like:
• "How many active users did we have last week?"
• "Show me a funnel from sign up to purchase"
• "What is the retention rate for new users?"
• "How many users completed checkout yesterday?"
• Any question asking for metrics, counts, trends, funnels, or retention analysis

DO NOT USE FOR:

• Listing or checking which properties exist on an event (e.g. "what/which properties are on the checkout event?") → use 'get_properties' (propertyType="event", pass eventType). Do NOT run queries to discover a schema.
• Finding existing charts/dashboards → use 'search' instead
• Getting valid chart definition structure → use 'get_chart_definition_params' (or fix from chartTypeSchema in a validation-error response)
• If you need more information about existing charts in the project as an example → use 'get_charts' instead
• Project settings (timezone, currency) → use 'get_project_context' instead

STRATEGIES

1. Use the 'search' tool to find if there are charts with properties that relate to the data you want to query. 2. Use 'get_chart_definition_params' when you need the full schema before building a definition (optional — validation errors also return chartTypeSchema). 3. Use the 'get_charts' tool to find examples of existing charts in the project to understand the events, properties, and dataset schema generally. 4. Optionally use the 'search' tool again to find additional events, user properties, etc. needed for the query. 5. Optionally use the 'get_properties' tool (propertyType="event", pass eventType) to get properties on individual events. 6. Use this tool to query the ad hoc analysis — definitions are validated and auto-corrected inline.

GENERAL GUIDELINES

• Don't assume or guess properties, events, or schema. Use the tools provided to you to understand the data before running a dataset query.
• When running into query failures, try searching for existing charts to understand the data taxonomy and dataset schema.
• When you receive a validation error, use the returned chartTypeSchema to fix the definition.
• ALWAYS include a descriptive "name" field in the definition object. This name will be displayed as the chart title. Examples: "Active Users Last 7 Days", "Sign Up to Purchase Funnel", "New User Retention".

AMPLITUDE WIDE META EVENTS TYPES

Special system events available for analysis. Events are passed in the "event_type" field:

• "_active": Any active event useful for tracking 'active users' like DAU, MAU(events not marked as inactive)
• "_all": Any event being tracked in Amplitude
• "_new": Events triggered by new users within the time interval. Useful for tracking 'new users'.
• "_any_revenue_event": Any revenue-generating event. Useful for tracking 'revenue'.
• "$popularEvents": Top events by volume (dynamically computed). Useful for more meta taxonomy analyses like 'what are the most common events'.

PROPERTY TYPES:

• Amplitude core properties are built-in and use standard names like "country", "platform", "device_id", "user_id"
• Custom properties are organization-defined and are typically prefixed with "gp:"
• Derived/formula properties (from TMS) must use prop_type and group_by.type of "derivedV2" in segments and group_by — not "user" or legacy "derived". Use get_properties with propertyType "derived" to list them.
• Hidden properties are intentionally excluded from get_properties; do not use them. Prefer derived replacements named in project context.
• If you are unsure which properties exist, use get_properties (propertyType="event", pass eventType) first — this is the direct way to list an event's properties. search/get_charts are fallbacks for discovering related events or example charts.

Supported chart types: eventsSegmentation, funnels, metricExplorer, retention, revenueLtv, sessions, stickiness

RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. Check the isCsvResponse flag to determine which response format to parse

CRITICAL — NON-ADDITIVE METRICS (uniques, pct_dau):

• These metrics cannot be summed across intervals. The chart UI plots per-interval values, not a running total.
• Additive metrics (totals, sums) CAN be summed across intervals.

How to read the JSON response, by metric type:

1. COUNT metrics ("uniques"):

• Use "overallSeries" — it is the TRUE deduped unique count across the full date range.
• Do NOT sum "timeSeries" values — that overstates the count due to user overlap across intervals.

2. RATIO metrics ("pct_dau" only):

• Use "timeSeriesAverage" (mean of per-interval values) — this matches what the chart UI displays.

For "current" reporting, also consider the most recent N intervals from "timeSeries".

• Do NOT use "overallSeries" for pct_dau over multi-interval ranges. For pct_dau, "overallSeries"

is a long-range aggregate (deduped numerator over the full range / deduped denominator over the full range). Over many intervals the denominator dedupes a much larger pool than the numerator, which compresses the ratio — typically reporting roughly half of the per-interval values the chart shows. This is mathematically valid as a long-range aggregate but is NOT what users see in the chart.

• Do NOT sum "timeSeries" values — ratios cannot be summed.

CSV Response Structure (when isCsvResponse is true):

• Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details
• Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)
• Data rows: Each row contains:
• Label columns: First few columns contain row labels identifying the data series
• Value columns: Numerical data organized under the corresponding date/time columns from the data header row
• Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns
• Cells in the CSV response are delimited by commas and may be prepended with a character

Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. IMPORTANT: The overall unique users is 5642 (NOT 614+1769+4132=6515), because users overlap across days. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'"

" Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "eventsSegmentation", }

JSON Response Structure (when isCsvResponse is false):

• Parse using the following structure:
• timeSeries: Array of arrays, each containing data points for a given time period with a "value" property
• overallSeries: Array of arrays, each containing the overall data point across the entire range under the "value" property.

IMPORTANT — interpretation depends on the metric:

• For "uniques" (count): this is the TRUE deduped unique count over the full date range. Use this.
• For "pct_dau" (ratio): this is a long-range aggregate ratio (deduped numerator

over range / deduped denominator over range). It does NOT match the per-interval values the chart UI plots and is typically much smaller. Do NOT report it as the headline number — use "timeSeriesAverage" instead.

• timeSeriesAverage: Present only for "pct_dau". Array of arrays, one per series, each

containing a single {value} that is the mean of "timeSeries" values for that series. Use this as the headline ratio when the chart spans multiple intervals — it matches what users see in the chart UI.

• seriesMetadata: Array of objects containing metadata for each series
• xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series
• Use the dataset definition to be able to parse referenced events, properties, and segments.

Example below is a JSON response is for the same query as the CSV example above. { "timeSeries": [[{"value": 614}, {"value": 1769}, {"value": 4132}]], "overallSeries": [[{"value": 5642}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "UNIQUES(A)"}], "xValuesForTimeSeries": ["2025-08-23T00:00:00", "2025-08-24T00:00:00", "2025-08-25T00:00:00"] } Note: 614+1769+4132=6515, but overallSeries shows 5642. This is because unique users overlap across days. For "uniques", always use overallSeries for the total.

Example below is a "pct_dau" query over 3 weeks (a ratio metric): { "timeSeries": [[{"value": 0.1402}, {"value": 0.1421}, {"value": 0.1444}]], "overallSeries": [[{"value": 0.0712}]], "timeSeriesAverage": [[{"value": 0.1422}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "PCT_DAU(A)"}], "xValuesForTimeSeries": ["2026-04-06T00:00:00", "2026-04-13T00:00:00", "2026-04-20T00:00:00"] } Note: the chart UI shows ~14% per week. timeSeriesAverage (14.22%) matches that. overallSeries (7.12%) is the deduped 3-week aggregate ratio and would HALVE the reported value if used as the headline — never report it as "the number" for "pct_dau". Always use timeSeriesAverage for "pct_dau".

Event Segmentation with Insights (anomaly detection / confidence intervals):

• When params.insights.isOn is true, Event Segmentation charts queried via query_charts or query_dataset

return BOTH chartConfig (Highcharts) AND jsonResponse with joinable band data.

• jsonResponse.seriesIntervals maps stringified seriesMetadata keys to { low, high, yhat } arrays

(parallel to xValuesForTimeSeries). Use seriesMetadata + xValuesForTimeSeries to join bands to series.

• Metric Explorer charts with Insights return seriesIntervals inside each data[] entry instead.

Query an experiment analysis.

CRITICAL: Do NOT pass metricIds unless user explicitly requests specific metrics or requests analysis on secondary metrics. Omit metricIds for primary metric only (cleaner, focused results).

RULES:

• Users want to know references for analyses in order to validate the data.
• ALWAYS REFERENCE EXPERIMENTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES.

WHEN TO USE:

• You want to query a experiment for analysis.

INSTRUCTIONS:

• Use the search tool to find the ID of the experiment you want to query.
• You may want to use the get_experiments tool to get more context about the experiment (i.e. state, variants, etc.)
• Use this tool to query the experiment analysis.

EXAMPLE: groupBy: [{"type": "user", "value": "device type", "group_type": "User"}]

Query metric data using the dataset endpoint with metric references

RULES:

• Users want to know references for analyses in order to validate the data.
• ALWAYS REFERENCE METRICS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES.

WHEN TO USE:

• You want to query a metric to get its data.

INSTRUCTIONS:

• Use the search tool to find the ID of the metric you want to query.
• Use this tool to query the metric.

RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. Check the isCsvResponse flag to determine which response format to parse

CRITICAL — NON-ADDITIVE METRICS (uniques, pct_dau):

• These metrics cannot be summed across intervals. The chart UI plots per-interval values, not a running total.
• Additive metrics (totals, sums) CAN be summed across intervals.

How to read the JSON response, by metric type:

1. COUNT metrics ("uniques"):

• Use "overallSeries" — it is the TRUE deduped unique count across the full date range.
• Do NOT sum "timeSeries" values — that overstates the count due to user overlap across intervals.

2. RATIO metrics ("pct_dau" only):

• Use "timeSeriesAverage" (mean of per-interval values) — this matches what the chart UI displays.

For "current" reporting, also consider the most recent N intervals from "timeSeries".

• Do NOT use "overallSeries" for pct_dau over multi-interval ranges. For pct_dau, "overallSeries"

is a long-range aggregate (deduped numerator over the full range / deduped denominator over the full range). Over many intervals the denominator dedupes a much larger pool than the numerator, which compresses the ratio — typically reporting roughly half of the per-interval values the chart shows. This is mathematically valid as a long-range aggregate but is NOT what users see in the chart.

• Do NOT sum "timeSeries" values — ratios cannot be summed.

CSV Response Structure (when isCsvResponse is true):

• Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details
• Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)
• Data rows: Each row contains:
• Label columns: First few columns contain row labels identifying the data series
• Value columns: Numerical data organized under the corresponding date/time columns from the data header row
• Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns
• Cells in the CSV response are delimited by commas and may be prepended with a character

Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. IMPORTANT: The overall unique users is 5642 (NOT 614+1769+4132=6515), because users overlap across days. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'"

" Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "eventsSegmentation", }

JSON Response Structure (when isCsvResponse is false):

• Parse using the following structure:
• timeSeries: Array of arrays, each containing data points for a given time period with a "value" property
• overallSeries: Array of arrays, each containing the overall data point across the entire range under the "value" property.

IMPORTANT — interpretation depends on the metric:

• For "uniques" (count): this is the TRUE deduped unique count over the full date range. Use this.
• For "pct_dau" (ratio): this is a long-range aggregate ratio (deduped numerator

over range / deduped denominator over range). It does NOT match the per-interval values the chart UI plots and is typically much smaller. Do NOT report it as the headline number — use "timeSeriesAverage" instead.

• timeSeriesAverage: Present only for "pct_dau". Array of arrays, one per series, each

containing a single {value} that is the mean of "timeSeries" values for that series. Use this as the headline ratio when the chart spans multiple intervals — it matches what users see in the chart UI.

• seriesMetadata: Array of objects containing metadata for each series
• xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series
• Use the dataset definition to be able to parse referenced events, properties, and segments.

Example below is a JSON response is for the same query as the CSV example above. { "timeSeries": [[{"value": 614}, {"value": 1769}, {"value": 4132}]], "overallSeries": [[{"value": 5642}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "UNIQUES(A)"}], "xValuesForTimeSeries": ["2025-08-23T00:00:00", "2025-08-24T00:00:00", "2025-08-25T00:00:00"] } Note: 614+1769+4132=6515, but overallSeries shows 5642. This is because unique users overlap across days. For "uniques", always use overallSeries for the total.

Example below is a "pct_dau" query over 3 weeks (a ratio metric): { "timeSeries": [[{"value": 0.1402}, {"value": 0.1421}, {"value": 0.1444}]], "overallSeries": [[{"value": 0.0712}]], "timeSeriesAverage": [[{"value": 0.1422}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "PCT_DAU(A)"}], "xValuesForTimeSeries": ["2026-04-06T00:00:00", "2026-04-13T00:00:00", "2026-04-20T00:00:00"] } Note: the chart UI shows ~14% per week. timeSeriesAverage (14.22%) matches that. overallSeries (7.12%) is the deduped 3-week aggregate ratio and would HALVE the reported value if used as the headline — never report it as "the number" for "pct_dau". Always use timeSeriesAverage for "pct_dau".

Event Segmentation with Insights (anomaly detection / confidence intervals):

• When params.insights.isOn is true, Event Segmentation charts queried via query_charts or query_dataset

return BOTH chartConfig (Highcharts) AND jsonResponse with joinable band data.

• jsonResponse.seriesIntervals maps stringified seriesMetadata keys to { low, high, yhat } arrays

(parallel to xValuesForTimeSeries). Use seriesMetadata + xValuesForTimeSeries to join bands to series.

• Metric Explorer charts with Insights return seriesIntervals inside each data[] entry instead.

Save temporary chart edits as permanent charts

WHEN TO USE:

• You have chart edit IDs from query_dataset and want to save them as permanent charts
• You need to add charts to dashboards or notebooks (which require saved chart IDs)

WORKFLOW: 1. Use query_dataset to create ad-hoc analyses (returns editId) 2. Use save_chart_edits to convert editIds into permanent chartIds 3. Use chartIds in create_dashboard or create_notebook

IMPORTANT:

• All AI-generated charts are saved as unpublished in your personal space
• Charts require human review before publishing to shared spaces
• Use bulk saving to reduce tool calls when creating multiple charts

Search for dashboards, charts, notebooks, experiments, and other content in Amplitude.

INSTRUCTIONS:

• Use this as your primary tool to discover and explore available analytics content before diving into specific analyses.
• If you are not sure what to search for, use the default search query.
• Do not specify appIds/projectIds in the input unless the user explicitly asks to search within a specific app/project.
• When searching for taxonomy entities like events, properties, etc. use higher limits (e.g. 100-200) to get more results as there are more important entities to search through.
• When searching for events, use the get_properties tool (propertyType="event") to get event properties on an individual event.
• To search Amplitude's official product documentation (SDK setup guides, API reference, help articles), include 'AMPLITUDE_DOCS' in entityTypes. This searches the public docs corpus — NOT your org's content — and returns doc pages with browsable URLs. Pair it with a natural-language query (e.g. "how to track revenue in the browser SDK").

DO NOT USE FOR:

• AI agent results, agent analyses, or agent runs → use 'get_agent_results' instead
• Getting full dashboard definitions with chart details → use 'get_dashboard' with the IDs from search results
• Running queries or analysis → use 'query_dataset' or 'query_charts'

ADDITIONAL INFORMATION:

• Results are personalized to the user you are making the request on behalf of.
• Results do not include the full object definition. You will need to use other tools to get the full object definition when needed.
• Best practice is to query for a single entity type, unless the user's request is open ended.
• The response includes an isOfficial flag in contentMeta to identify content that has been marked as official by the organization.

Find relationships for any Amplitude entity - shows what charts, experiments, cohorts, and other entities are connected to or use the specified source entity.

WHEN TO USE:

• You want to understand dependencies and relationships for a specific Amplitude entity.
• You need to see what content references a specific entity before making changes.
• You're analyzing the impact of modifying or archiving an entity.
• You want to find all entities that use a particular event, property, cohort, chart, etc.

INSTRUCTIONS:

• Provide the app ID and specify a source entity with its type and name.
• The tool searches for relationships to a fixed set of target entity types (metrics, segments, cohorts, connections, predictions, experiments, flags, custom events, derived properties, lookup properties).
• Results are split into separate searches for charts vs other entities to prevent charts from crowding out other entity types.
• The response shows all entities that reference or are related to the specified source entity, organized by entity type.
• Use this to understand entity adoption and potential impact of changes.

SUPPORTED ENTITY TYPES:

• event
• custom_event
• event_property
• user_property
• derived_property
• lookup_property
• channel_classifier
• cohort
• prediction
• metric

RESPONSE FORMAT:

• results: Combined list of all related entities
• resultsByType: Results organized by entity type (charts, cohorts, metrics, etc.)
• counts: Count of results for each entity type
• totalHits: Total number of matching entities across both searches
• chartHits/nonChartHits: Separate hit counts for chart vs non-chart searches

EXAMPLES:

• Find all charts using event "Login" in app 187520
• Analyze which experiments are targeting a specific cohort id in an app
• Understand what content uses a particular custom event before archiving it
• Find all entities that reference a specific event_property

Subscribe or unsubscribe the current user or a channel to chart alerts for a monitor.

WHEN TO USE:

• The user wants to subscribe or unsubscribe from chart alerts.
• Use get_chart_monitor first if you need the monitorId or want to inspect existing subscribers.

INSTRUCTIONS:

• Provide monitorId, action, and deliveryMethod.
• For email delivery, this tool only manages the current user's own email subscription.
• For Slack or Teams delivery, provide deliveryChannel.
• deliveryWorkspaceId is optional workspace context for Slack or Teams channels when needed.
• If adding the first subscriber to a disabled monitor, this tool re-enables the monitor automatically.
• If removing the last subscriber, this tool disables the monitor automatically.

EXAMPLES:

• {"monitorId":"mon_123","action":"subscribe","deliveryMethod":"email"}
• {"monitorId":"mon_123","action":"subscribe","deliveryMethod":"slack","deliveryChannel":"C024BE91L"}
• {"monitorId":"mon_123","action":"unsubscribe","deliveryMethod":"teams","deliveryChannel":"19:channel-id@thread.tacv2","deliveryWorkspaceId":"tenant-id:team-id"}

NOTES:

• Do not use this to edit thresholds or other monitor settings. Use update_chart_monitor for that.

Enable or disable an existing chart monitor.

WHEN TO USE:

• The user wants to turn a chart alert monitor on or off.
• Use get_chart_monitor first if you need to inspect the current monitor state.

INSTRUCTIONS:

• Provide monitorId.
• enabled=true turns the monitor on.
• enabled=false turns the monitor off.

EXAMPLES:

• {"monitorId":"mon_123","enabled":true}
• {"monitorId":"mon_123","enabled":false}

NOTES:

• This tool only changes the enabled state.
• Use subscribe_chart_alert to manage recipients and get_chart_monitor to inspect thresholds and subscribers.

Unified entry point for metric definitions, goals, and goal alerts in a project. Replaces get_metrics, create_metric, update_metric, delete_metric, get_metric_goals, the five goal write tools, and the four goal-alert CRUD tools.

WHEN TO USE:

• Anything about defining metrics, setting targets on metrics, listing goals/pacing, or configuring goal alerts.
• NOT for querying metric *values* over time — use query_metric or query_dataset instead.

INSTRUCTIONS:

• Select the operation with action.
• Metric defs: resolve metricIds with search first; create_metric needs projectId, name, and metricType plus type-specific fields (same rules as the legacy create_metric tool).
• Goals: use get_goals to discover goalIds before update / archive / restore / delete / alert actions.
• update_metric may be two-step when changing a metric definition with dependents; delete_metric and delete_goal may also be two-step when dependents exist. For any of these operations, first call without confirmed, show the returned dependency payload to the user, then retry with confirmed: true only after user confirmation.
• get_goals accepts either metricId OR projectId, not both.

DO NOT USE FOR:

• Chart or experiment metric *values* → query_metric / query_dataset.
• Experiments and flags → get_experiments / get_flags / create_experiment.

Validate and auto-correct a chart definition before passing it to query_dataset.

WHEN TO USE:

• After constructing a chart definition, to verify it is valid before querying.
• When you want to catch and auto-fix common mistakes (wrong enum values, wrong field names).
• The tool will auto-coerce known LLM mistakes and return the corrected definition.
• Validates event types and properties exist in the project taxonomy.

WHAT IT DOES:

• Validates required fields (type, app, params) and chart-type-specific parameters.
• Auto-coerces known mistakes: wrong funnel mode names (this_order → ordered), conversionWindow objects → conversionSeconds, ISO date strings → Unix timestamps, string events → {event_type, filters, group_by}.
• Validates that referenced event types exist in the project.
• Validates that referenced properties exist on their event types.
• Validates user and derived properties in segments/group_by: hidden properties are rejected, and derived formula properties must use prop_type/group_by type derivedV2 (not user or legacy derived).
• Returns the corrected definition ready to pass to query_dataset.

SUPPORTED CHART TYPES: eventsSegmentation, funnels, metricExplorer, retention, revenueLtv, sessions, stickiness Unsupported types pass through with a warning (not an error) — you can still send them to query_dataset.