Amplitude

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.

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 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.

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:[email protected]","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.

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.

Read saved Amplitude charts by ID, or look up the chart-type schema. One tool with four output modes selected by `include` (default `link`). OUTPUT MODES: - `link` (default) → 'get_chart_link': validates each id exists, then returns the chart's URL(s). Does not run the chart — cheap id lookup only. - `definition` → 'get_charts': returns the full chart definition object(s). Use when you need the chart's configuration (events, segments, params). - `data` → 'query_charts': runs the chart(s) and returns the result data. Use when you need the numbers. - `guide` → 'get_chart_definition_params': no ids needed. Pass `chartType` to get that type's parameter schema, valid enum values, and a working example definition — use BEFORE calling `query_amplitude_data` if you are unsure of the shape, or to look up valid enum values (e.g. funnel modes, segmentation metrics). Omit `chartType` to list all supported chart types. NOTE: This schema describes chart STRUCTURE only (params, enums, example) — it does NOT validate event or property names against your project's taxonomy. An unrecognized event/property key will NOT error; it silently returns a chart with empty data. Before building, confirm exact spelling via 'search', 'get_event_properties', or get_amplitude_charts include='definition' on a similar existing chart — never guess a key name. PREREQUISITES (required): - For `link` / `definition` / `data`: you MUST have at least one concrete `chartIds` or `chartEditIds` entry. Do not call speculatively. Resolve ids FIRST via `search` (by name), `get_from_url` (from a chart link), or `query_dataset` (for ad-hoc analysis, which returns a chart edit id). - For `guide`: no ids required; `chartType` is optional (omit to list all supported types). INSTRUCTIONS: - Saved charts → `chartIds`. Chart edits (links ending in /chart/new/<edit_id> or /chart/<chart_id>/edit/<edit_id>) → `chartEditIds`. - `definition` mode supports `chartIds` only. For a chart edit's data use `data` mode. - `data` mode accepts up to 3 ids/edits combined. - The data params (`groupByLimit`, `excludeIncompleteDatapoints`, `timeSeriesLimit`) only apply when `include = 'data'`. `chartType` only applies when `include = 'guide'`. DO NOT USE FOR: - Ad-hoc analysis without a saved chart → use 'query_dataset'. - Finding charts by name → use 'search'.

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

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 cohort sync history (execution logs) for a specific cohort ID. Returns detailed sync execution records including success/failure status, timing, and error information. WHEN TO USE: - Troubleshooting cohort sync issues and failures - Analyzing sync performance and execution patterns - Auditing cohort sync activity and success rates - Understanding sync execution details for a specific cohort - Use AFTER get_cohort_syncs to get detailed execution history for specific sync jobs INSTRUCTIONS: - Provide a cohortId to get sync execution history for that cohort - Specify appId to scope the results to a specific project - Specify target parameter for the sync destination (e.g., 'salesforce', 's3', 'braze') - Optional targetId for specific destination instances - Use pageNumber and pageSize for pagination (defaults: pageNumber=1, pageSize=20) - Set errorOnly=true to only return failed sync executions EXAMPLES: - Get recent sync history: {"cohortId": "12345", "appId": "67890", "target": "salesforce"} - Get failed syncs only: {"cohortId": "12345", "appId": "67890", "target": "salesforce", "errorOnly": true} - Paginated results: {"cohortId": "12345", "appId": "67890", "target": "s3", "pageNumber": 2, "pageSize": 50} NOTES: - Returns sync logs from the last 14 days only - Results are ordered by execution time (most recent first) - Each log entry includes execution details, timing, success status, and error information if applicable - Use this tool to investigate specific sync execution issues after identifying problematic syncs with get_cohort_syncs

Get configured cohort sync destinations for a project. Returns all available integration configurations that can be used as destinations for cohort syncing. WHEN TO USE: - You need to see what destinations are configured for cohort syncing in a specific project - You want to understand available integration targets before setting up cohort syncs - You're troubleshooting cohort sync configuration issues - You need to audit configured integrations for a project INSTRUCTIONS: - Provide the projectId for the project you want to check - The tool returns all generic integration app configurations including partner names and target details - Use this BEFORE setting up cohort syncs to see available destinations - Use this to understand what integrations are already configured - Results are grouped by partner; each target has a targetId. To sync a cohort to one of these classic destinations with sync_cohort, pass BOTH the partner and that targetId — a targetId is only unique within a partner EXAMPLES: - {"projectId": "12345"} - Get all configured destinations for project 12345 NOTES: - Requires the Manage Syncs permission (Member role) on the project — the same permission needed to sync a cohort - customParameters objects are completely removed for security (contain API keys and credentials) - Other fields like displayName, targetId, and mappingParameters are preserved - Only shows active (non-deleted) configurations

Trigger a one-time cohort sync to a destination immediately, without waiting for the next scheduled sync. WHEN TO USE: - You need to force an immediate cohort export to a downstream destination (e.g. Braze, Salesforce, S3) - Useful for unblocking a stalled integration or testing a new sync configuration REQUIRED PREPARATION — always call these first: 1. Call get_cohorts to find and confirm the cohortId you want to sync 2. Call get_cohort_sync_destinations (it takes a projectId) to list configured destinations — each entry has a partner and a targetId 3. Identify the destination you want to sync to INSTRUCTIONS: - Always provide cohortId. - For a classic integration (e.g. Braze, Iterable, S3): provide BOTH partner and targetId from get_cohort_sync_destinations. A targetId is only unique within a partner — the same id can exist under two partners (e.g. Iterable and Segment) — so partner is required to identify the destination unambiguously. - For a Connector Manager (beam) destination: provide only the numeric targetId and omit partner; the partner is resolved automatically. - If a cohort has been synced to this destination before, only the diff (added/removed users) is sent; the first sync performs a full export. - This is a confirmed write. The first call (without confirmed) returns a confirmation_required preview — cohort, member count, and resolved destination — and performs NO sync. Show that to the user, then re-call with confirmed: true to run it. NOTES: - Only supported for cohorts with fewer than 10,000 members - Runs synchronously: the response reflects whether the export ran. Call get_cohort_sync_history afterwards for delivery details (member counts, skips) - Subject to the org's monthly manual export limit - If a sync job is already in progress for the same cohort + destination, the request will be rejected

Create a new cohort with the provided definition and configuration. WHEN TO USE: - You need to create a new audience segment based on user behavior or properties - You want to save a cohort definition for reuse in charts, experiments, or other analyses - You need to create a cohort from specific conditions like events, user properties, or funnels LEARNING FROM EXISTING COHORTS: - Before creating a cohort, use the "search" MCP tool to find relevant cohorts by name/description, then use get_cohorts with those IDs to analyze existing cohort definitions and structure - Study the structure and patterns of existing cohort definitions to understand the correct payload format - Pay attention to how different condition types (event, user_property, other_cohort, etc.) are structured - Learn from the andClauses/orClauses patterns and how they combine different conditions - Use existing cohorts as templates for similar use cases to ensure proper schema compliance EXAMPLES: - Create an event-based cohort (users who performed a specific event >= 1 time in the past 30 days): { "app_id": "365742", "name": "xuan-simple-event-cohort", "definition": { "version": 3, "andClauses": [{ "negated": false, "orClauses": [{ "type": "event", // Condition type: event-based "metric": null, // No specific metric aggregation "offset": 0, // No time offset from the base time range "group_by": [], // No grouping/segmentation by event properties "interval": 1, // Time granularity: 1 = DAY (daily buckets) "operator": ">=", // Event count operator: greater than or equal "time_type": "rolling", // Rolling time window (last N days from now) "time_value": 30, // Time range: 30 units of the interval (30 days) "type_value": "xuan-test-httpapi-event-type", // The specific event name to match "operator_value": 1, // Minimum event count threshold: >= 1 occurrence "exclude_current_interval": false // Include events from the current day }] }], "cohortType": "UNIQUES", // Count unique users (not event occurrences) "countGroup": {"name": "User", "is_computed": false}, // Group by User entities "referenceFrameTimeParams": {} // No additional time frame parameters }, "type": "redshift", // Cohort computation engine type (optional - defaults to "redshift") "published": true // Make cohort discoverable to others } // EXPLANATION: This creates a cohort of users who performed the event "xuan-test-httpapi-event-type" // at least once in the last 30 days. The interval=1 means we evaluate this on a daily basis, // so the system looks at each day in the past 30 days to see if the user performed the event. - Create a complex cohort with multiple conditions (organizations in another cohort OR new active, AND performed an event): { "app_id": "365742", "name": "xuan-test", "definition": { "version": 3, "andClauses": [{ // First AND condition group "negated": false, "orClauses": [{ // First OR condition: existing cohort membership "type": "other_cohort", // Condition type: reference to another cohort "offset": 0, // No time offset "interval": 1, // Time granularity: 1 = DAY (daily evalua…

List all projects (apps) for a customer organization by orgId. Amplitude-employee only. Requires an adminv2 grant on the target org. Use this tool to discover projectIds for a customer organization so you can then call read tools (get_events, get_charts, etc.) with those projectIds. INSTRUCTIONS: - You must be an Amplitude employee (@amplitude.com login) to call this tool. - You must have adminv2 access granted for the target org. - Use the returned projectIds with other read tools to explore the customer org. EXAMPLES: - {"orgId": 12345} NOTES: - orgId is the customer's organization ID, not a project/app ID. - Returns all projects in the org, not filtered by your personal access.

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?" → omit `projectId`. - "what timezone / currency / session settings does project X use?", "describe project X" → pass `projectId`. 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. DO NOT USE FOR: - Running analytics queries → use 'query_dataset'. - Finding charts/dashboards/cohorts → use 'search'.

Set or update the organization-level AI context. This context helps AI tools understand your organization's business, terminology, and conventions. WHEN TO USE: - "Set the org context to describe our business" - "Update the organization context" - "Add context about our company for AI tools" REQUIRES: Org admin permissions NOTES: - Context maximum length is 10000 characters - This overwrites any existing org-level context

Set or update the project-level AI context. This context helps AI tools understand the specific project's purpose, data model, and conventions. WHEN TO USE: - "Set the project context for project 12345" - "Update the AI context for my project" - "Add context about this project for AI tools" REQUIRES: projectId parameter and project manager/admin permissions NOTES: - Context maximum length is 10000 characters - This overwrites any existing project-level context - Use 'get_context' first to get project IDs

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.

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)

Create a recurring dashboard subscription for email, Slack, or Teams delivery. WHEN TO USE: - The user wants a dashboard delivered on a recurring cadence. - Use get_dashboard first if you need to confirm the dashboardId or editId. INSTRUCTIONS: - Provide the dashboardId for the saved dashboard. - Use editId only when subscribing to a specific dashboard edit instead of the base dashboard. - schedule.sendHourUtc must be an integer from 0-23 and is stored in UTC. - schedule.sendDay is also interpreted in UTC, not in the user's local timezone. - The dashboard UI may display the subscription on the previous or next local weekday after timezone conversion. - Use schedule.sendWeek="every" and schedule.sendDay="every" for daily delivery. - Use schedule.sendWeek="every" and a weekday for weekly delivery. - Use schedule.sendWeek="first"|"second"|"third"|"last" with a weekday for monthly delivery. - For email subscriptions, only create subscriptions for the current user's own email address. - Use get_context to fetch the current user's email instead of guessing or using another person's email. - attachCsv only applies to email subscriptions. - For Slack or Teams subscriptions, provide the recipientId and recipientType. Teams subscriptions also require recipientTeamId. - Slack channel subscriptions automatically invite the Amplitude bot when needed. EXAMPLES: - Daily email subscription: {"dashboardId":"12345","delivery":{"notificationType":"email","email":"[email protected]","attachCsv":true},"schedule":{"sendWeek":"every","sendDay":"every","sendHourUtc":15}} - Weekly Slack channel subscription: {"dashboardId":"12345","delivery":{"notificationType":"slack","recipientType":"channel","recipientId":"C024BE91L"},"schedule":{"sendWeek":"every","sendDay":"monday","sendHourUtc":17}} - Monthly Teams channel subscription for a dashboard edit: {"dashboardId":"12345","editId":"edit-987","delivery":{"notificationType":"teams","recipientType":"channel","recipientId":"19:[email protected]","recipientTeamId":"team-123"},"schedule":{"sendWeek":"first","sendDay":"wednesday","sendHourUtc":16}} NOTES: - Duplicate subscriptions for the same dashboard/edit and recipient are rejected. - Email subscriptions should never be created for a different user's email address. - The stored schedule is UTC. For example, Wednesday at 06:00 UTC may appear as Tuesday at 11:00 PM in America/Vancouver. - The response includes the created subscription when it is visible to the caller.

Edit an existing dashboard subscription's delivery cadence and email CSV setting. WHEN TO USE: - The user wants to change when an existing dashboard subscription is delivered. - The user wants to toggle CSV attachment for an email dashboard subscription. INSTRUCTIONS: - Provide the existing subscriptionId. - This tool only edits supported fields: sendWeek, sendDay, sendHourUtc, and attachCsv for email subscriptions. - It does not change the recipient, notification type, or dashboard target. - schedule.sendDay and schedule.sendHourUtc are interpreted in UTC, not in the user's local timezone. - The dashboard UI may display the subscription on the previous or next local weekday after timezone conversion. - For email subscriptions, only edit subscriptions that belong to the current user's own email address. - Use get_context to fetch the current user's email if you need to verify which email subscription should be edited. - Use schedule.sendWeek="every" and schedule.sendDay="every" for daily delivery. - Use schedule.sendWeek="every" and a weekday for weekly delivery. - Use schedule.sendWeek="first"|"second"|"third"|"last" with a weekday for monthly delivery. - attachCsv is only valid for email subscriptions. EXAMPLES: - Change an email subscription to daily at 15:00 UTC: {"subscriptionId":"sub_123","schedule":{"sendWeek":"every","sendDay":"every","sendHourUtc":15}} - Turn off CSV for an email subscription: {"subscriptionId":"sub_123","attachCsv":false} - Move a Slack subscription to Fridays at 20:00 UTC: {"subscriptionId":"sub_123","schedule":{"sendWeek":"every","sendDay":"friday","sendHourUtc":20}} NOTES: - At least one editable field must be provided. - Email subscription edits should target the current user's own email subscription, not another user's. - The stored schedule is UTC. For example, Wednesday at 06:00 UTC may appear as Tuesday at 11:00 PM in America/Vancouver. - The updated subscription is returned when it is visible to the caller.

Edit a dashboard's metadata and layout with optimistic concurrency protection. WHEN TO USE: - You already have a dashboard ID and want to update its name/description and/or content rows. INSTRUCTIONS: - Always call get_dashboard first to retrieve the dashboard's current lastModified and rows. - Pass the retrieved lastModified in expectedLastModified. - Metadata fields are only updated when values are not null/undefined. - Use one structural edit at a time via edit. EXAMPLES: - Metadata only: {"dashboardId":"123","expectedLastModified":1700000000,"metadata":{"name":"Q1 Dashboard"}} - Replace all rows: {"dashboardId":"123","expectedLastModified":1700000000,"edit":{"type":"set_rows","rows":[{"height":500,"items":[{"type":"chart","chartId":"abc","width":12}]}]}} - Update a row: {"dashboardId":"123","expectedLastModified":1700000000,"edit":{"type":"update_row","rowIndex":0,"row":{"height":500,"items":[{"type":"rich_text","content":"# Notes","width":12}]}}} - Insert a row: {"dashboardId":"123","expectedLastModified":1700000000,"edit":{"type":"insert_row","index":1,"row":{"height":375,"items":[{"type":"chart","chartId":"def","width":12}]}}} - Remove a row: {"dashboardId":"123","expectedLastModified":1700000000,"edit":{"type":"remove_row","rowIndex":2}} NOTES: - The request fails with a conflict if expectedLastModified is stale. - Response is intentionally compact to minimize context usage.

Discover replaceable properties across all charts on a dashboard and optionally apply bulk find-and-replace. WHEN TO USE: - You need to replace a property filter (e.g. country, platform, device_type) across every chart on a dashboard in one step. - You want to see which properties are used across a dashboard's charts before deciding what to replace. INSTRUCTIONS: - Call with only dashboardId to discover replaceable properties. The response lists each unique property filter with its key and affectedChartIds. - Call with dashboardId + replacements to apply find-and-replace. Each replacement references a sourcePropertyKey from the discovery response and specifies target property attributes. - Target attributes default to the source values when omitted, so you only need to specify what changes. - Set dryRun=true with replacements to validate inputs and preview replacement impact without saving chart edits. - If dryRun reports cross-dashboard shared chart impacts, rerun with confirmSharedChartImpact=true to apply changes. - Use get_dashboard first if you need the dashboard ID. SAFETY: - This tool updates chart definitions and saves changes. It does not delete dashboards or charts, but it can modify many charts at once. - Replacements can cause partial updates if some chart saves fail. Always review the response for chartsFailed and errors. - Use precise sourcePropertyKey values from discovery mode. Unknown keys are rejected. - Chart edits apply globally to that chart. If a chart is reused on other dashboards, those dashboards will also reflect the property changes. RECOMMENDED WORKFLOW: - Step 1: Run discovery mode (dashboardId only) and inspect properties + affectedChartIds. - Step 2: Start with a small, targeted replacement. - Step 3: Verify chart outputs. - Step 4: Apply broader replacements only after validation. EXAMPLES: - Discover: {"dashboardId":"abc123"} - Dry run: {"dashboardId":"abc123","dryRun":true,"replacements":[{"sourcePropertyKey":"property-event-undefined-country-is-US-undefined","target":{"elementType":"region"}}]} - Replace: {"dashboardId":"abc123","confirmSharedChartImpact":true,"replacements":[{"sourcePropertyKey":"property-event-undefined-country-is-US-undefined","target":{"elementType":"region"}}]}

Add a plain-text comment to a chart, dashboard, or notebook. WHEN TO USE: - Document why a chart/dashboard/notebook was changed, or capture an interpretation of an unusual data point - Leave context, decisions, or open questions for collaborators - Persist insight from analysis directly on the object so the next viewer sees it INSTRUCTIONS: - Use get_comments FIRST to read existing context and avoid duplicates - Comments are automatically attributed to the AI tool making the request - Comments are plain-text only (no rich formatting, mentions, or reactions) EXAMPLES: - {"source": "DASHBOARD", "id": "<dashboard-uuid>", "projectId": "123456", "content": "Spike on 2026-04-20 lines up with the marketing email — see thread in #growth."} - {"source": "CHART", "id": "<chart-uuid>", "projectId": "123456", "content": "Switched primary metric to Active Users (DAU) per the analytics review."} - {"source": "NOTEBOOK", "id": "<notebook-uuid>", "projectId": "123456", "content": "Section 3 holds — the activation lift on Variant B replicates across both segments."}

Read all comments on a chart, dashboard, or notebook. WHEN TO USE: - Before adding a comment, to read existing context and avoid duplicating points - To summarize discussion, decisions, or open questions left on an object - To find what blockers or follow-ups have been raised by collaborators INSTRUCTIONS: - For dashboards and notebooks, this also returns comments rolled up from charts inside them - Comments authored by AI tools are prefixed "[via <client-name>]" in plainText - Comments are returned newest-last; deleted comments are excluded EXAMPLES: - {"source": "DASHBOARD", "id": "<dashboard-uuid>", "projectId": "123456"} - {"source": "CHART", "id": "<chart-uuid>", "projectId": "123456"}

Retrieve all deployments for the current project. Deployments are api keys for flags and experiments.

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.

Create a new experiment across one or more projects. INSTRUCTIONS: - If the user has not specified projects, prompt them to decide which projects to use - Creates a feature A/B test with control and treatment variants - Creates the same experiment in each specified project - Returns the experiment IDs and URLs for viewing in Amplitude EXAMPLES: - Basic A/B test: Provide projectIds, key, and name - Multiple projects: Provide array of projectIds to create experiment in each - With custom variants: Provide projectIds, key, name, and variants array - With links: Provide links array with url and title for each link (e.g., PRs, tickets, docs) - With deployments: Provide deploymentIds array to associate specific deployments (API keys) NOTES: - Experiment keys must be unique within each project - Variants default to 'control' and 'treatment' if not specified - Use get_deployments to retrieve available deployment IDs

Create multiple feature flags in batch. INSTRUCTIONS: - Use get_context to get available project IDs - Always prompt the user if they haven't specified a project - Use get_deployments to find deployment IDs to associate with the flag EXAMPLES: - {"flags": [{"projectId": "123456", "key": "new-feature", "name": "New Feature"}]} NOTES: - Flag keys must be unique within each project - Flags are disabled by default - If a flag is enabled, it does not mean that all users will see the flag.

Update a feature flag or experiment with comprehensive options including metadata, variants, testers, and deployments. Works for both feature flags and experiments — all experiments are also flags and share the same flag ID. INSTRUCTIONS: - Use the search tool with entityTypes: ['FLAG'] or entityTypes: ['EXPERIMENT'] to find IDs first - Use get_deployments to find deployment IDs if modifying deployments - Only include sections you want to update (flagConfig, variants, testers, deployments) - To update experiment-specific settings (metrics), use update_experiment instead EXAMPLES: - Update name: {"flagId": "abc123", "flagConfig": {"name": "New Name"}} - Enable flag/experiment: {"flagId": "abc123", "flagConfig": {"enabled": true}} - Add variant: {"flagId": "abc123", "variants": {"create": [{"key": "variant-c"}]}} - Add tester: {"flagId": "abc123", "testers": {"add": [{"variantKey": "control", "userOrDeviceIds": ["user123"]}]}} - Add link: {"flagId": "abc123", "links": {"add": [{"url": "https://jira.example.com/PROJ-123", "title": "JIRA Ticket"}]}} NOTES: - At least one variant must remain after deletions - For testers to receive a variant the flag must be enabled - All experiments are also flags and have an associated flag ID — use this tool for metadata, variants, testers, and deployments on experiments

Set metrics on an experiment. For other changes (name, description, enabled, variants, testers, deployments, links), use update_flag — it works for both flags and experiments. INSTRUCTIONS: - Use the search tool with entityTypes: ['EXPERIMENT'] to find experiment IDs first - Use create_metric to create metrics before attaching them here - Metrics are replaced entirely — include all metrics you want on the experiment - Only one metric can have recommendation=true (the primary metric) EXAMPLES: - Set primary + guardrail: {"experimentId": "abc123", "metrics": [{"metricId": "met1", "metricIndex": 0, "recommendation": true, "analysisParams": {"metricGoalType": "success", "testDirection": "larger", "minDetectableEffect": 0.02}}, {"metricId": "met2", "metricIndex": 1, "analysisParams": {"metricGoalType": "guardrail", "testDirection": "smaller", "minDetectableEffect": 0.02}}]} - Replace all metrics: {"experimentId": "abc123", "metrics": [{"metricId": "met3", "metricIndex": 0, "recommendation": true, "analysisParams": {"metricGoalType": "success", "testDirection": "larger", "minDetectableEffect": 0.02}}]} - Clear all metrics: {"experimentId": "abc123", "metrics": []} NOTES: - This tool only works on experiments (not feature flags). - Use get_experiments to see current metrics before updating.

Create a new metric in a project. WHEN TO USE: - You need to create a metric for use in experiments or dashboards. - You want to define a reusable KPI like "Daily Active Users" or "Error Rate". - The user wants a success or guardrail metric for an A/B test. INSTRUCTIONS: - Provide the projectId and a descriptive name. - Choose a metricType: "UNIQUES" (unique users), "TOTALS" (total event count), "FORMULA" (custom formula), "PROPSUM"/"PROPAVG" (property aggregation), "RETENTION" (retention metrics), or "CONVERSION" (funnel / multi-step conversion metrics). - For UNIQUES or TOTALS: provide a single event with optional filters. - For FORMULA: provide multiple events (max 6) and a formula string. Each event is referenced by letter (A, B, C...). Available formula functions: UNIQUES(A), TOTALS(A), PROPSUM(A), PROPAVG(A), PROPMIN(A), PROPMAX(A), PROPCOUNT(A), PROPCOUNTAVG(A), REVENUETOTAL(A). - For FORMULA with property aggregation functions (PROPSUM, PROPAVG, etc.): the event must include a group_by specifying which property to aggregate. Example: events=[{event_type: "Purchase", group_by: [{type: "event", value: "revenue"}]}], formula="PROPSUM(A)". - For PROPSUM/PROPAVG: provide a single event AND an aggregationProperty specifying which numeric property to aggregate. - For property min/max/count operations, use a FORMULA metric with PROPMIN(A), PROPMAX(A), PROPCOUNT(A), or PROPCOUNTAVG(A). - For RETENTION: provide a startEvent and returnEvent, and returnOn and returnOnInterval. If you want one day retention, set returnOn=1 and returnOnInterval=1. If you want one week retention, set returnOn=1 and returnOnInterval=7. If you want one month retention, set returnOn=1 and returnOnInterval=30. - For RETENTION: if you see the word "day", set returnOnInterval=1. If you see the word "week", set returnOnInterval=7. If you see the word "month", set returnOnInterval=30. - For CONVERSION (funnel): provide funnelEvents (at least 2 ordered steps), funnelMode ("ordered" = this order, "unordered" = any order, "sequential" = exact order), conversionSeconds (max time to complete funnel, e.g. 86400 for 1 day), and funnelPathsToCollect ("UNIQUES" for unique users completing the funnel, "TOTALS" for total funnel conversion counts). Optional funnelConstantProperties holds properties constant across steps (holding constant). Optional funnelComputeProperty + funnelComputePropFunction ("SUM" or "AVG") aggregate a numeric property on the last funnel step (e.g. sum revenue on the final purchase step). - For CONVERSION (funnel): if funnelComputeProperty is provided, funnelComputePropFunction must also be provided. - For CONVERSION (funnel): if funnelConstantProperties is provided, make sure that event property or user property exists for every event in the funnel. - Set isExperimentMetric=true when the metric is intended for use in an experiment. This enables experiment-specific formula validation. - ALWAYS use the search or get_events tool first to discover valid event names before calling this tool. Do not guess event names. EXAMPLES: - Unique users for an event: metricType="UNIQUES", event={event_type: "Button Clicked"} - Error rate formula: metricType="FORMULA", events=[{event_type: "API Call"}, {event_type: "API Error"}], formula="TOTALS(B)/TOTALS(A)" - Revenue per user formula: metricType="FORMULA", events=[{event_type: "Purchase", group_by: [{type: "event", value: "revenue"}]}, {event_type: "_active"}], formula="PROPSUM(A)/UNIQUES(B)" - Total event count: metricType="TOTALS", event={event_type: "Purchase Completed"} - Sum of a property: metricType="PROPSUM", event={event_type: "Purchase Completed"}, aggregationProperty={type: "event", value: "revenue"} - Average of a property: metricType="PROPAVG", event={event_type: "Page Viewed"}, aggregationProperty={type: "event", value: "load_time"} - Count of a property: metricType="FORMULA", events=[{event_type: "Purchase", group_by: [{type: "event", value: "item_id"}]}], formula="PROPCOUNT(A)" - Retention met…

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.

Create a new notebook WHEN TO USE: - The user wants to create a new notebook - The user wants to generate an interactive report with specific content from amplitude data specifically 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 notebooks - 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_notebook (uses chartId) - If you use an editId instead of a saved chartId, the notebook creation will fail with "NotFoundError: No chart" INSTRUCTIONS: - Provide a name for the notebook - 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 - Total width of items in a row must not exceed 12 columns - Max 4 items per row (ensures minimum 3-column width per item) - The tool will create the notebook and return the new notebook ID and details - Return a link to the new notebook in the response 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: "# Analysis Summary\n\nKey findings show **significant growth** in user engagement." LAYOUT EXAMPLES: - Full-width item: { items: [{ type: 'chart', chartId: '123', width: 12 }] } - Two side-by-side: { items: [{ type: 'chart', chartId: '1', width: 6 }, { type: 'rich_text', content: '# Notes', width: 6 }] } - Three columns: { items: [{ width: 4 }, { width: 4 }, { width: 4 }] } - Auto-fill: { items: [{ type: 'chart', chartId: '1' }, { type: 'chart', chartId: '2' }] } (each gets 6 columns)

Edit a notebook's metadata and layout with optimistic concurrency protection. WHEN TO USE: - You already have a notebook ID and want to update its name and/or content rows. INSTRUCTIONS: - Always call get_notebook first to retrieve the notebook's current lastModifiedAt and rows. - Pass the retrieved lastModifiedAt in expectedLastModifiedAt. - Metadata fields are only updated when values are not null/undefined. - Use one structural edit at a time via edit. EXAMPLES: - Metadata only: {"notebookId":"123","expectedLastModifiedAt":1700000000,"metadata":{"name":"Q1 Notebook"}} - Replace all rows: {"notebookId":"123","expectedLastModifiedAt":1700000000,"edit":{"type":"set_rows","rows":[{"items":[{"type":"chart","chartId":"abc","width":12}]}]}} - Update a row: {"notebookId":"123","expectedLastModifiedAt":1700000000,"edit":{"type":"update_row","rowIndex":0,"row":{"items":[{"type":"rich_text","content":"# Notes","width":12}]}}} - Insert a row: {"notebookId":"123","expectedLastModifiedAt":1700000000,"edit":{"type":"insert_row","index":1,"row":{"items":[{"type":"chart","chartId":"def","width":12}]}}} - Remove a row: {"notebookId":"123","expectedLastModifiedAt":1700000000,"edit":{"type":"remove_row","rowIndex":2}} NOTES: - The request fails with a conflict if expectedLastModifiedAt is stale. - Response is intentionally compact to minimize context usage.

Invite users to the current Amplitude organization by email. WHEN TO USE: - Invite one or more people to the org from MCP - Grant chart access to invitees as part of the invite INSTRUCTIONS: - Provide explicit invitee email addresses; this tool does not create reusable shared invite links - Only CHART object permissions are currently supported for invite-time object access EXAMPLES: - Email invite: {"emails":["[email protected]"],"orgRole":"VIEWER"} - Email invite with chart access: {"emails":["[email protected]"],"initialObjectPermissions":[{"objectType":"CHART","objectId":"abc123","shareRole":"CAN_VIEW"}]} NOTES: - Email invite permissions are enforced by Thunder; callers need invite/user-management permission - Existing org members, already-pending users, invalid emails, and self-invites are filtered by Thunder - Use get_org_users and update_org_users for user/role inspection or follow-up role changes

Get the current sharing information for an Amplitude object (chart, dashboard, notebook, or cohort), including its owners (editors) and viewers. WHEN TO USE: - You want to see who has access to a specific object - You need to check a user's current role before updating it - You want to list all editors and viewers of an object INSTRUCTIONS: - Use the search tool to find the object ID first - The objectType must be one of: CHART, DASHBOARD, NOTEBOOK, COHORT EXAMPLES: - {"objectId": "abc123", "objectType": "CHART"} - {"objectId": "def456", "objectType": "DASHBOARD"}

Share an Amplitude object (chart, dashboard, notebook, or cohort) with one or more users by adding them as viewers. INSTRUCTIONS: - Use the search tool to find the object ID first - Use get_org_users to find user login IDs to share with - The objectType must be one of: CHART, DASHBOARD, NOTEBOOK, COHORT - Users who are already editors will not be downgraded to viewers - Users who are already viewers will not be re-added EXAMPLES: - Share a chart: {"objectId": "abc123", "objectType": "CHART", "userIds": ["[email protected]", "[email protected]"]} - Share a dashboard with a message: {"objectId": "def456", "objectType": "DASHBOARD", "userIds": ["[email protected]"], "message": "Check out this dashboard!"} NOTES: - Only editors/owners of the object (or org admins) can share it - Sharing adds users as viewers; to add editors, use update_share_role with CAN_EDIT

Update a user's share role on an Amplitude object (chart, dashboard, notebook, or cohort). INSTRUCTIONS: - Use the search tool to find the object ID first - Use get_org_users to find the user's login ID - To make someone an editor: set shareRole to CAN_EDIT - To make someone a viewer: set shareRole to CAN_VIEW - To remove someone's access: set shareRole to NOT_ADDED EXAMPLES: - Make editor: {"objectId": "abc123", "objectType": "CHART", "userId": "[email protected]", "shareRole": "CAN_EDIT"} - Remove access: {"objectId": "def456", "objectType": "DASHBOARD", "userId": "[email protected]", "shareRole": "NOT_ADDED"} NOTES: - Only editors/owners (or org admins) can update share roles - Setting CAN_EDIT promotes a viewer to editor - Setting NOT_ADDED removes a user from both editors and viewers

Render an interactive Amplitude chart UI for a saved chart or a chart edit by ID. This is the way to SHOW a chart to the user — it spins up the chart widget; the widget fetches the chart's data itself and draws it. ## SUPPORTED CHART TYPES eventsSegmentation, funnels, retention, composition, metricExplorer. - dataTableV2 CANNOT be rendered as a chart. Present its data as a table instead (get the data via query_dataset). ## WHEN TO USE - The user wants to SEE a chart and you already have a `chartId` (saved chart) or `chartEditId` (ad-hoc chart edit). - Right after `query_dataset` returns a `chartEditId` for a non-empty result — pass that `chartEditId` here to render it. - Right after `search` / `get_from_url` resolves a saved `chartId` the user asked to see. ## WHEN NOT TO USE — DO NOT CALL WITHOUT AN ID - You do NOT have a `chartId` or `chartEditId` yet. Resolve one FIRST: - `query_dataset` (returns a `chartEditId` for an ad-hoc definition) - `search` with `entityTypes: ["CHART"]` (finds a saved `chartId`) - `get_from_url` (parses an id out of an Amplitude chart URL) - The query you ran returned empty / all-zero data — tell the user, do NOT render an empty chart. ## INSTRUCTIONS - Provide exactly one of `chartId` (saved chart) or `chartEditId` (chart edit). If you have both, prefer `chartEditId`. - This tool does NOT return chart data to you — it only renders the widget. To reason about the numbers, call `get_amplitude_charts` (include='data') / `query_dataset` for the data.

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: - 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_event_properties' tool 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 search/get_charts/get_properties/get_event_properties before querying Supported chart types: composition, eventsSegmentation, funnels, metricExplorer, retention, revenueLtv, sessions, stickiness RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. C…

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: composition, eventsSegmentation, funnels, metricExplorer, retention, revenueLtv, sessions, stickiness

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: composition, 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.

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:"," [Cust…

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"}]

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_event_properties tool 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.

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, opportunities, and orchestration workflows - Agent session URLs (/agents/session/{id}) are not resolvable here — use get_agent_results with the session_id instead

Search session replays for a project. REQUIRED FOLLOW-UP — render_session_replay: - After this tool returns sessionReplayIds, you MUST call `render_session_replay` in the SAME turn whenever the user's request implies viewing the replays. This includes nearly every conversational ask: "show me", "let me see", "pull up", "find", "get me", "any sessions", "what's happening", "watch", "play", "view", "open", or any phrasing where the user is looking at session replays as the deliverable. - Pass the returned sessionReplayIds (max 20) to `render_session_replay` along with the same `projectId`. Do not stop after the search — a list of IDs alone is not the answer the user wants. - ONLY skip the render call when the user is plainly asking for raw data extraction (e.g. "give me a CSV of replay IDs", "just count them", "export to JSON"). When in doubt, render. WHEN TO USE: - Find session replays matching event / user-property / cohort filters. - Fetch replays for a specific Amplitude user (`userId`), or by replay ID (`sessionReplayIds`). - Sample recent sessions when the user wants a quick look ("show me what's happening", "any sessions today?") — call with no filters and the tool returns a random slice from the last 24 hours. INSTRUCTIONS: - Provide `projectId`. Add filters incrementally; each is ANDed. - Reference real event names — call `get_events` (or `get_custom_or_labeled_events` for labeled events) first if unsure. - `sessionReplayId` format is "device_id/session_id" — pass it directly to `get_session_replay_events` for the rrweb stream, or to `render_session_replay` for the player UI. - `userId` and `sessionReplayIds` are mutually exclusive with each other and with all filter fields. EXAMPLES: - Replays for an Amplitude user yesterday: { "projectId": "12345", "userId": "98765", "since": "yesterday" } - Users who viewed the pricing page 3+ times: { "projectId": "12345", "events": [{ "name": "Page Viewed", "minCount": 3, "withProperty": { "name": "page", "is": "pricing" } }] } - Sessions where the Checkout event recorded an error: { "projectId": "12345", "events": [{ "name": "Checkout", "withProperty": { "name": "error_type", "exists": true } }] } - Enterprise users who completed checkout: { "projectId": "12345", "userProperties": [{ "name": "gp:plan", "is": "enterprise2" }], "events": [{ "name": "Checkout Completed" }] } - Replays from a cohort (pass the numeric ID; use get_cohorts to resolve a name): { "projectId": "12345", "cohorts": [556677] } - Specific replays by ID: { "projectId": "12345", "sessionReplayIds": ["device-abc/111", "device-def/222"] } - Quick sample from the last day: { "projectId": "12345" } NOTES: - Defaults: 10 results, time window depends on intent (30 days for filtered queries, 24 hours otherwise). - Cohorts are filtered by numeric ID only; call get_cohorts to resolve a cohort name to its ID first. - If results are empty for a filtered query, do not retry with the same parameters — widen the window or relax filters.

List session replays for a project using the Amplitude public Session Replay API. WHEN TO USE: - You want a paginated list of session replays within a time window without complex event-count filtering. - Use get_session_replays for event-count or user-property filtering; use this tool for simple time-range listing or when you need a replay_id to pass to get_session_replay_events. - Use amplitude_id to fetch replays for a specific user. - Use replay_id to fetch one or more specific replays by device_id/session_id. CHAIN INTO render_session_replay: - If the user's request implies they want to SEE the replays (verbs like "show", "render", "play", "watch", "let me see", "pull up", "open", "display", "view", or implicit references like "the session for X", "those recordings"), call this tool to find replay_id values and then IMMEDIATELY call render_session_replay with those IDs in the same turn. Do not stop at listing replay_id values in text — the user wants to watch. - For "random" requests (e.g. "show me 5 random replays"), fetch a larger page (page_size 100–200), sample the requested count of replay_id values client-side, then call render_session_replay once with the sampled IDs. - Only skip render_session_replay when the user explicitly asked for a count, summary, pagination cursor, or raw list to inspect. INSTRUCTIONS: - Provide projectId. Optionally narrow results with start_time, end_time, page_size, and sort_order. - Use the returned next_page_token to fetch subsequent pages. - replay_id format is "device_id/session_id" — pass it directly to get_session_replay_events to retrieve rrweb events. - For random replay requests, fetch a larger page (for example page_size 100–200), sample the requested number of replay_id values client-side, then call render_session_replay once with the sampled IDs. DURATION FIELDS — IMPORTANT: - The bare list response's start_time/end_time describe the analytics session window, NOT the recorded replay. They can diverge significantly (a session can be open for an hour with only 10s of recording, or vice versa). - If you need to rank by replay length, call get_session_replay_duration per candidate. NOTES: - If no start_time/end_time is provided, the last 48 hours is used automatically (end_time = now, start_time = 48 hours ago). - Keep sort_order consistent across paginated requests for the same query. - Replays older than their retention period will not appear. - amplitude_id and replay_id are mutually exclusive. - replay_id and page_token are mutually exclusive. - Max 100 replay_id values per request. - When replay_id is used, next_page_token is always null.

Retrieve and process rrweb events from a session replay recording. WHEN TO USE: - You have a replay_id (from list_session_replays or get_session_replays) and want to understand what the user did during that session. - Useful for debugging user issues, understanding UX flows, or analyzing error reproduction steps. INSTRUCTIONS: - Provide projectId and replay_id in "device_id/session_id" format (as returned by list_session_replays). - Returns a processed interaction timeline: page navigations, clicks, text inputs, and significant scrolls. - Use event_limit to cap the number of events returned (default 500; reduce if context is tight). OUTPUT: - interactions: ordered list of user actions with timestamps (ms since Unix epoch) - navigation: { url, viewport } - click / double_click: { nodeId, x, y } - input: { nodeId, value } — text inputs and checkbox state changes - scroll: { nodeId, x, y, delta_y } — only large position jumps (≥200px) - viewport_resize: { width, height } NOTES: - rrweb nodeId values reference DOM nodes from the session's full snapshot; without the snapshot they cannot be resolved to CSS selectors or element text. - Large or long sessions may be truncated at event_limit; the response indicates if truncation occurred.

Retrieve the full user timeline for a session replay, showing all events the user fired during and around the replay session. WHEN TO USE: - PREFER THIS over get_user_timeline whenever you have a session replay ID and want to see what a user did - You want to understand what a user did during a specific session replay - You need to see the sequence of events, page views, and interactions during a replay - You're investigating user behavior or debugging an issue observed in a replay - You want context around what happened before and after the captured replay segment INSTRUCTIONS: - Provide the projectId and sessionReplayId (format: "<device_id>/<session_id>", e.g. "0c650142-4a68-4f82-ad6a-4f154fee5265/1773235450374") - The sessionReplayId can be obtained from get_session_replays - Experiment assignment events are excluded by default — enable includeExperimentEvents if needed OUTPUT: - events: chronological list of shaped events, each with: - eventType, eventTime, eventTimeMs, sessionId, amplitudeId, userId - eventTimeMs: epoch ms timestamp (numeric companion to eventTime — useful for offset math against the recorded replay start) - msFromSessionStart: milliseconds elapsed since the analytics session began (NOT the replay's start; the replay can begin partway into the session) - replayUrl: direct link to the replay at this event's position - matchedFilter: whether this event was the anchor for the replay - platform, deviceFamily, osName - eventProperties (if includeEventProperties is true) - hasMoreBefore/hasMoreAfter: whether sessions exist outside the returned window - totalEventsReturned: count after filtering and limiting - redactedPropertyKeys (only present if non-empty): names of event-property keys that were hidden due to data-access controls (DAC). If a user asks about a specific property that is restricted let them know that the property is restricted and they can request access to it from their org admin. EXAMPLES: - Get timeline: { "projectId": "187520", "sessionReplayId": "0c650142-4a68-4f82-ad6a-4f154fee5265/1773235450374" } - With event properties: { "projectId": "187520", "sessionReplayId": "...", "includeEventProperties": true }

Render an interactive session replay player UI for one or more session replays. This is the ONLY way to actually show a session replay to the user — text descriptions are not a substitute. WHEN TO USE (call this tool whenever the user wants to SEE a replay): - Any user request with a viewing verb: "show me", "render", "play", "watch", "let me see", "pull up", "open", "display", "view", "I want to see", "can I see" + "session replay(s)" / "session(s)" / "recording(s)" / "the replay" / "those sessions". - Any time the user asks to look at, observe, or visually inspect session activity, even without an explicit verb (e.g. "the session for [email protected]", "that recording", "those replays from yesterday"). - Immediately after get_session_replays / list_session_replays / get_session_replay_timeline returns session replay IDs in response to such a request — chain directly into render_session_replay with the returned IDs. Do NOT stop at listing IDs in text when the user asked to see the replays. - If the user asks to see replays but you don't have IDs yet, FIRST call get_session_replays (or list_session_replays) to find them, THEN call this tool with the results — in the same turn. - Call ONCE with a list of IDs to render multiple replays the user can switch between — do NOT call this tool separately per replay. WHEN NOT TO USE: - The user is asking for a count, summary, or analysis of replay events without wanting to watch them ("how many replays…", "what did the user do in…", "summarize…"). Use the timeline / events tools instead. INSTRUCTIONS: - Provide projectId and one or more sessionReplayIds. - sessionReplayId format is "<device_id>/<session_id>" (e.g. "0c650142-4a68-4f82-ad6a-4f154fee5265/1773235450374") — use the ids returned from the search/list tools verbatim. - Maximum 20 IDs per call. The UI hydrates the rrweb player on demand for each replay. - Set `title` to a short, human-readable summary of WHY you're rendering these replays based on the user's request (3–8 words). This is shown as the heading above the player. Examples: "Recent web sessions for nvidia.com", "Sessions where users hit checkout errors", "Top 3 longest sessions yesterday". Do NOT echo IDs or device info — that lives in the player itself. If the user gave no specific framing, omit `title`. EXAMPLES: - Single replay: { "projectId": "187520", "sessionReplayIds": ["0c650142-4a68-4f82-ad6a-4f154fee5265/1773235450374"], "title": "Most recent session for [email protected]" } - Multiple replays: { "projectId": "187520", "sessionReplayIds": ["abc/111", "def/222"], "title": "Sessions where users abandoned checkout" } - No framing context: { "projectId": "187520", "sessionReplayIds": ["abc/111"] } NOTES: - The UI plays the replay inline (rrweb-based) with a tree-style event list — the model does NOT need to summarize that data in text. - This tool is UI-only. Do not rely on its response for reasoning about the replays.

APP SUPPORT ONLY. Do not call this tool from the LLM or agent. The session replay app calls this tool to stream rrweb events for inline playback. The response is base64-encoded gzipped NDJSON and is not useful for text reasoning. If you need to understand what happened in a replay, use get_session_replay_events instead. APP INSTRUCTIONS: - First call: pass projectId + sessionReplayId. Response includes durationMs, events (file 0), and nextCursor. - Continue with nextCursor until it is null. - For duration-only hydration, pass metadataOnly: true.

APP SUPPORT ONLY. Do not call this tool from the LLM or agent. The session replay app calls this tool to hydrate replay duration metadata without downloading the full replay. Prefer list_session_replays, get_session_replays, get_session_replay_events, or render_session_replay for user-facing tasks. APP INSTRUCTIONS: - Provide projectId and sessionReplayId in "<device_id>/<session_id>" format (as returned by list_session_replays / get_session_replays). - Returns durationMs: last event timestamp minus first event timestamp. - Returns null durationMs for empty or single-frame recordings.

Retrieve properties from a project's taxonomy. Use propertyType to select which kind of properties to fetch. 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 properties | names | | persisted | Event-to-user persisted properties | names | 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"] }

Create one or more properties in a project's tracking plan. Use propertyType to select which kind of properties to create. PROPERTY TYPES: | propertyType | What it creates | Key params | |---|---|---| | event | Event properties (global or event-scoped) | properties[].eventType (omit for global) | | user | User-level properties | properties[].type, regex, enumValues | | group | Group properties (e.g., company_name, plan_tier) for a group type | groupType, properties[] | INSTRUCTIONS: - If a user says "create a property" without specifying a type, ask them to clarify which type they mean: event, user, or group. - If a user says "create a property on an event," assume they mean an event property — propertyType "event" is the default for that phrasing. - Derived properties, profile properties, lookup properties, computed properties, and persisted properties are NOT supported via MCP tools. If the user asks to create one of these, let them know that this property type is not currently supported through MCP tools. - If the user has not specified a project, prompt them to decide. Don't decide for them. PERMISSIONS: - This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. # Workspace warnings Be sure you have information on the workspace settings and environments from get_workspace_context before using this tool. If the workspace has more than one environment, warn the user that the change will apply across multiple environments. If the main branch is protected (workspace setting approvalWF is "Required"), let the user know that changes cannot be made on the default branch and they will have to first create a new branch and make changes on that. NOTES BY PROPERTY TYPE: - group: Group properties describe attributes of a group type (e.g., company name, plan tier). Accepts a group type name (e.g., "org id", "Company") — the tool resolves it to the correct ID internally. If no branch is specified, defaults to the main branch. EXAMPLES: - Event property (global): { "propertyType": "event", "projectId": "123", "properties": [{ "name": "page_url", "type": "string" }] } - Event property (event-scoped): { "propertyType": "event", "projectId": "123", "properties": [{ "name": "button_name", "eventType": "Button Clicked", "type": "string" }] } - Event properties (mixed: one fresh, one add-to-plan, on a feature branch): { "propertyType": "event", "projectId": "123", "branchName": "marketing-edits", "properties": [{ "name": "page_url", "type": "string" }, { "name": "button_name", "eventType": "Button Clicked", "isUnexpected": true }] } - User property: { "propertyType": "user", "projectId": "123", "properties": [{ "name": "plan_type", "type": "string" }] } - Group properties: { "propertyType": "group", "projectId": "123", "groupType": "Company", "properties": [{ "name": "plan_tier", "type": "string" }] } USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Refer to the default branch as "main", not "default branch". - Say "event property", "user property", or "group property" not "propertyType". - Say "unexpected" or "unplanned" not "isUnexpected" when describing properties not yet in the plan. - Say "array type" not "isArrayType", "hidden" not "isHidden", "enum values" not "enumValues", and "classification" not "classifications". - Say "branch approval setting" not "approvalWF". - Do not mention "mutations", "versionId", "stagingVersionId", branch IDs, or GraphQL details to the user.

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 which include the event category and whether or not the event is active. - 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. NOTES: - Event types are equivalent to the ingested name. Always use "ingested name" instead of "event type" when responding to the user. - Plan membership is reported via "isInSchema" (true = the event is part of the tracking plan). Ingestion/queryability is reported via "isQueryable" (true = the event has been seen in data).

Create one or more events in a project, OR add already-ingested events with status "unexpected" to the tracking plan. Create events or add events with an unexpected status to plan with this tool. When a user says "create an event" without further qualification or 'add to plan' for unexpected events, use this tool. Use the create_custom_event tool when the user wants to create a custom event. To add unexpected events to plan, specify whether an event is unexpected or not with isUnexpected. If isUnexpected is true, the event will be added to the tracking plan and be in the live state. If false, the event will be created as a new event and will be in the planned state. Events may only be added to the tracking plan if they have been ingested (observed) in the project and have the unexpected status. # Caveats Attempting to add an unexpected event that has already been ingested but not in the plan with isUnexpected set to false will result in an error saying the event with that name already exists. This error does not necessarily mean that the event is already in the plan, as it also includes events that have been ingested. # Response - Brand-new events appear in `createdEvents`. - Events added to plan appear in `eventsAddedToPlan`. # Optional metadata (brand-new events only) For brand-new events (isUnexpected: false) you may also set description, category, and/or isOfficial in the same call. These fields are NOT supported when isUnexpected is true — you must first add the event to plan and then make an additional call to the update_event tool to update the metadata. # Branch targeting Unless specified, the default branch is used. To apply changes to a non-default branch, pass either branchId or branchName. If the user references a branch by name (e.g. "my-edits-branch"), use branchName. Pass only one. # Permissions This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. # Workspace warnings Be sure you have information on the workspace settings and environments from get_workspace_context before using this tool. If the workspace has more than one environment, warn the user that the change will apply across multiple environments. If the main branch is protected (workspace setting approvalWF is "Required"), let the user know that changes cannot be made on the default branch and they will have to first create a new branch and make changes on that. USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Refer to the default branch as "main", not "default branch". - Say "official" not "isOfficial" when describing event status. - Say "unexpected events" not "isUnexpected events" when describing events not yet in the plan. - Say "created" or "added to the tracking plan" rather than using field names like "createdEvents" or "eventsAddedToPlan". - Say "branch approval setting" not "approvalWF". - Do not mention "mutations", "versionId", "stagingVersionId", branch IDs, or GraphQL details to the user.

Create one or more group types in a project, OR add already-ingested group types with status "unexpected" to the tracking plan. A group type is a category of group that users can belong to (for example "Company", "Account", "Team", "Workspace", "Organization"). The Amplitude Accounts add-on lets you analyse product usage at the group level rather than per individual user. NOTE: group TYPES are the categories themselves — use create_properties with propertyType "group" to add attributes (e.g. company name, plan tier) to an existing group type. When a user says "create a group type" without further qualification, or "add to plan" for an unexpected group type, use this tool. Specify whether each item is unexpected with `isUnexpected`. If `isUnexpected` is true, the group type must already exist in the project as observed-but-unexpected and will be added to the tracking plan. If false (default), a brand-new entry is created. INSTRUCTIONS: - Use get_context to get available project IDs first. - Use get_group_types to check which group types already exist before creating new ones. - If the user has not specified a project, prompt the user to decide. Don't decide for them. EXAMPLES: - Minimal: {"projectId": "123456", "groupTypes": [{"name": "Company"}]} - With description: {"projectId": "123456", "groupTypes": [{"name": "Team", "description": "Engineering teams within a company"}]} - Mixed batch (one fresh, one add-to-plan, on a feature branch): {"projectId": "123456", "branchName": "marketing-edits", "groupTypes": [{"name": "Account"}, {"name": "Workspace", "isUnexpected": true}]} # Response Each input item is reported individually in `groupTypes[]` with a `result` of `"created"`, `"addedToPlan"`, or `"failed"` (with a `reason`). Partial successes are preserved: a failure on one item never discards the results of others in the same batch. PERMISSIONS: - This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. # Workspace warnings Be sure you have information on the workspace settings and environments from get_workspace_context before using this tool. If the workspace has more than one environment, warn the user that the change will apply across multiple environments. If the main branch is protected (workspace setting approvalWF is "Required"), let the user know that changes cannot be made on the default branch and they will have to first create a new branch and make changes on that. NOTES: - A group type with the same name cannot already exist on the targeted branch — that item will be marked as failed. - Branch targeting: unless specified, the default branch is used. Pass either branchId or branchName, not both. - `description` is only allowed on brand-new group types (isUnexpected: false). Unexpected items added to the plan cannot include metadata at the same time — add them first, then use a follow-up tool call to set the description. USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Refer to the default branch as "main", not "default branch". - Say "unexpected group types" not "isUnexpected group types". - Say "added to the tracking plan" rather than using field names like "addedToPlan". - Say "branch approval setting" not "approvalWF". - Do not mention "mutations", "versionId", "stagingVersionId", "propertyPath", branch IDs, or GraphQL details to the user.

Create a custom event in a project. IMPORTANT: Only use this tool when the user explicitly asks to create a "custom event." If they just say "create an event," use create_events instead. A custom event is a virtual event composed of one or more source events with optional property filters. INSTRUCTIONS: - Use get_context to get available project IDs first. - Use get_events to find the raw event types to use as source events. - COPYING / RECREATING AN EXISTING CUSTOM EVENT (e.g. from another project, or one referenced in a chart): first call get_custom_or_labeled_events on the SOURCE project with customEventNames=[<exact name>] to fetch the existing custom event's definition, then call this tool with the destination projectId and the same name + definition. Do NOT fall back to global search to look up a custom event by name — taxonomy tools (get_custom_or_labeled_events) are the source of truth for custom event definitions across projects. EXAMPLES: - Simple alias: {"projectId": "123456", "name": "User Engaged", "definition": [{"event_type": "Button Clicked"}, {"event_type": "Link Clicked"}]} - With filter: {"projectId": "123456", "name": "Checkout Started", "definition": [{"event_type": "Add to Cart", "filters": [{"group_type": "User", "subprop_key": "page_type", "subprop_op": "is", "subprop_value": ["checkout"], "subprop_type": "event"}]}]} - With metadata: {"projectId": "123456", "name": "Purchase", "description": "Any purchase event across platforms", "category": "Revenue", "definition": [{"event_type": "app_purchase"}, {"event_type": "web_purchase"}]} FILTER FIELD GUIDE: - group_type: Use "User" for user/event properties, or the group type name (e.g. "org id") for group properties. - subprop_type: Use "event" for event properties, "user" for user properties, "group" for group properties. - subprop_key: The property name to filter on. - subprop_op: The operator (e.g., "is", "is not", "contains", "does not contain"). - subprop_value: Array of string values to match. PERMISSIONS: - This tool requires the "Manage Data Enrichments" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. NOTES: - Do NOT use for labeled events (isAutotrack); this tool always creates non-autotrack custom events. - The definition requires at least one source event. - You can optionally set a description and category to help organize and document the custom event. USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Say "labeled event" not "isAutotrack event". - Say "composed of" or "source events" not "definition" when describing what a custom event is made up of. - Say "property filter" or "filter" not "subprop_key", "subprop_op", "subprop_value", "subprop_type", or "group_type" when describing filters. - Do not mention "mutations", "customEventId", or GraphQL details to the user.

Retrieve custom events, labeled (autotrack) events, or both from a project, with optional filtering by event IDs or names, limit, and cursor pagination. Labeled events share the same underlying resource as custom events but have isAutotrack=true. Use eventKind to choose which subset to return. WHEN TO USE: - eventKind "_all": both custom and labeled events in one list (default). - eventKind "custom": non-autotrack custom events only. - eventKind "labeled": labeled/autotrack events only. - Find events by IDs or names (value field), or paginate through results. - Fetch a known custom event's full definition (e.g. one shown in a chart or referenced by name) so it can be inspected, duplicated, or recreated in another project. Prefer this over the generic search tool when you already know the exact event name — search indexes content broadly and may not surface custom events that this tool returns directly from the taxonomy service. RESPONSE: - eventKind echoes your filter (custom, labeled, or _all). - events: each item includes isAutotrack (false for custom, true for labeled), plus definition and flattenedDefinition (source event lists from TMS). INSTRUCTIONS: - Get the project ID from the context tool. When filtering by customEventNames, pass the full event name including any brackets, year prefixes, or punctuation exactly as shown in the UI (e.g. "[2026] User Signed Up"). - Omit eventKind or use "_all" to return custom and labeled events together (default). Use "custom" or "labeled" when the user only wants one kind. - Optionally filter by customEventIds or customEventNames (same fields for all kinds). - Use pagination to retrieve large lists.

Update descriptions, categories, names, isOfficial, and/or eventDefinitions on custom events (virtual events) or labeled events (autotrack). For plain events use update_event. INSTRUCTIONS: - Fetch current state with get_custom_or_labeled_events first. - Confirm changes with the user; no speculative or broad-batch edits. - eventDefinitions replaces in full — pass the complete source-event list. - Descriptions: append, don't overwrite, unless the user asks to replace. - Renaming breaks chart references — warn the user. - Per-app scope only; don't warn about multi-env effects. - Follow project naming/category/description conventions; don't invent patterns. - Requires "Update Tracking Plan" permission; on 403, surface error noting admin may need to grant, don't pre-warn. EXAMPLES: - Multi-field: {"projectId":"123","eventKind":"custom","newNames":{"ce-abc":"Checkout"},"descriptions":{"ce-abc":"Buy flow"},"eventDefinitions":{"ce-abc":[{"event_type":"app_purchase"},{"event_type":"web_purchase"}]}} - Labeled w/ filter: {"projectId":"123","eventKind":"labeled","eventDefinitions":{"CTA":[{"event_type":"[Amplitude] Element Clicked","filters":[{"group_type":"User","subprop_key":"[Amplitude] Element Selector","subprop_op":"autotrack css match","subprop_value":["button.cta"],"subprop_type":"event"}]}]}} Filter shape: { group_type, subprop_key, subprop_op (is | is not | contains | glob match | autotrack css match | ...), subprop_value: string[], subprop_type: "event"|"user"|"group" }. group_type="User" unless filtering on a group property. LABELED EVENT CONSTRAINTS: - event_type: "[Amplitude] Element Clicked" or "[Amplitude] Element Changed" - subprop_key: "[Amplitude] Element Hierarchy" | "Element Text" | "Page URL" - subprop_op: "autotrack css match" | "is" | "glob match" NOTES: - At least one of descriptions, categories, newNames, isOfficial, or eventDefinitions required. - eventKind scopes lookups — "custom" will not match labeled events. - Duplicate definitions in the same scope return a conflict.

Set descriptions, official status, category, sources, tags, visibility, activity, and/or rename one or more events in a project. To add sources to an event, first call get_tracking_plan_sources to look up source IDs, then pass them in the sources map. Use removeSources to detach a source from an event, and removeTags to remove a tag. Adding via sources/tags is additive — existing entries not listed in a remove map are preserved. # Safety and Usage Rules - This tool loads the latest metadata for only the event types you pass in before applying changes. Event type keys must match event "name" exactly (case-sensitive). Make sure you are not using the displayName. Resolve that to the get_events "name" first if necessary. - If you have previously changed the name of an event (not displayName), use the new name from get_events as the eventType on the next call. Ingested events only change display name; while non-ingested events change the event name. - Make sure you have used the get_workspace_context tool to get information on workspace settings and environments for specified projectId. If there is more than one environment in the workspace, warn the user that the change will apply across multiple environments. If the workspace has main branch protected (indicated by approvalWF being "Required"), let the user know that changes cannot be made on the default branch and they will have to first create a new branch and make changes on that. ## Non-destructive updates - Do not overwrite existing descriptions; append additional context instead (for example by adding an "Additional context" section). ## Explicit overwrite / removal when requested - If the user clearly asks to remove or replace existing descriptions for specific events/properties, you may apply those changes after confirming the exact updates with the user. - Names and categories are expected to be overwritten rather than appended, but only after the user has confirmed the new values. ## Explicit user approval required - Call this tool only after the user has explicitly confirmed the exact events to update and the exact new descriptions/names/official status/categories/sources/removeSources/tags/removeTags/visibility/isActiveAction values. - Do not auto-apply speculative or inferred changes. ## Protected event types - Never use this tool on events that begin with brackets or vendor prefixes ([Amplitude], [Experiment], [Guides - Surveys], [Agent], [AI Feedback]). ## Minimal, convention-aligned changes - Only update the specific events the user has asked about (or explicitly selected), not broad pattern-based batches. - Follow the project's existing naming conventions instead of inventing new patterns. ## Branch targeting - Unless specified, the default branch is used. To apply changes to a non-default branch, pass either branchId or branchName. If the user references a branch by name (e.g. "my-edits-branch"), use branchName. Pass only one. ## Permissions - This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. NOTES: - Event types are equivalent to the ingested name. Always use "ingested name" instead of "event type" when responding to the user.

Update property description, isOfficial, category, and/or name in a project's tracking plan. Use propertyType to select which kind of properties to update. This tool CANNOT be used to update property visibility or type. It can also NOT be used to set event properties to required. PROPERTY TYPES: | propertyType | What it updates | Key params | |---|---|---| | event | Event property metadata (global or event-scoped) | metadataScope, eventType (when scope is "event") | | user | User property metadata | descriptions, isOfficial, categories, newNames | INSTRUCTIONS: - Use get_properties first to verify property names and status before updating. - Call this tool only after the user has explicitly confirmed the properties to change and the exact new values. - Do not auto-apply speculative or inferred changes. - If the user has not specified a project, prompt them to decide. Don't decide for them. - This tool requires the "Update Tracking Plan" permission. If it fails with 403, note that an admin may need to grant access. - Make sure you have used the get_workspace_context tool to get information on workspace settings and environments for specified projectId. If there is more than one environment in the workspace, warn the user that the change will apply across multiple environments. If the workspace has main branch protected (indicated by approvalWF being "Required"), let the user know that changes cannot be made on the default branch and they will have to first create a new branch and make changes on that. - This tool only updates properties that are already in the tracking plan (status: planned, live, blocked). Unexpected properties (auto-detected from ingested data, isPlanned: false) are skipped. To edit an unexpected property's metadata, first add it to the plan with create_properties by setting properties[].isUnexpected: true on that item, then call update_properties. WHEN UPDATING EVENT PROPERTIES: - Do not try to update the properties globally if it failed on the event-scoped update, or vice-versa. Always confirm with the user whether the event property should be updated on a global or event-scoped basis. WHEN UPDATING USER PROPERTIES: - Remove the gp: prefix, if present, from user property names when requesting updates with this tool. EXAMPLES: - Event properties (global): { "propertyType": "event", "projectId": "123", "metadataScope": "global", "descriptions": { "revenue": "USD amount" } } - Event properties (event-scoped): { "propertyType": "event", "projectId": "123", "metadataScope": "event", "eventType": "Purchase", "descriptions": { "line_items": "JSON array" } } - User properties: { "propertyType": "user", "projectId": "123", "descriptions": { "plan_tier": "Customer subscription tier" } }

Retrieve data transformations from a project. Transformations are data cleaning operations that merge events, merge properties, or map property values. WHEN TO USE: - Use this tool to see what transformations are configured for a project. - Use this tool to understand how events or properties are being merged or remapped. - Use this tool to audit data cleaning rules applied to a project. WHAT IT RETURNS: - A list of transformations with their type, name, description, and configuration details. - Transform types include: merge (merge events), merge_events_derived_prop (merge events with derived property), merge_event_properties, merge_user_properties, map_event_property_values, map_user_property_values. INSTRUCTIONS: - Get the project ID from the context tool. - Optionally filter by transform type to narrow results. - Use pagination to retrieve large lists of transformations.

List the sources configured on a project's tracking plan (e.g. iOS, Android, Web, Server). WHEN TO USE: - You need source IDs before adding sources to an event in the tracking plan. - The user asks what sources are configured on their tracking plan. INSTRUCTIONS: - Pass projectId. - Returns each source's id and name. Use the id when modifying event sources. NOTES: - The Sources UI merges tracking-plan labels with pipeline connections, but this tool returns only the tracking-plan catalog (id + name) for assigning sources to events. Use get_data_ingestion_sources for ingestion status, volumes, and warehouse/import connections.

Internal telemetry tool used by MCP UI components to report render latency and errors. NOT FOR DIRECT MODEL USE.

Read Amplitude AI Feedback (customer VoC) for a project — surveys, support tickets, app reviews, and grouped themes. This is CUSTOMER product feedback (what users said in connected sources). NOT for: - AI/LLM agent session quality, transcripts, or agent analytics → use get_amplitude_agent_analytics_info - Reporting that you (the agent) are stuck → use report_agent_feedback (requires user approval) Set `facet` to choose what to read: - `sources` → connected feedback integrations + sourceIds (call first when you need sourceIds for filters) - `comments` → raw feedback comments with search, categories, pagination - `insights` → grouped themes (requests, complaints, loved features, …) sorted by popularity - `mentions` → drill into comments behind ONE insightId or trendId (do not call for every insight) - `trends` → saved themes tracked over time TYPICAL WORKFLOWS: 1. Bootstrap: facet=sources → facet=comments or facet=insights 2. Themes: facet=insights → facet=mentions with insightId when user asks for examples 3. Tracked themes: facet=trends → facet=mentions with trendId EXAMPLES: - Connected sources: {"facet": "sources", "projectId": "123456"} - Complaints this month: {"facet": "insights", "projectId": "123456", "types": ["complaint"], "dateStart": "2026-06-01", "dateEnd": "2026-06-30"} - What are customers saying about pricing: {"facet": "comments", "projectId": "123456", "search": ["pricing", "price"]} - Show comments behind insight 42: {"facet": "mentions", "projectId": "123456", "insightId": 42}

List all brands tracked by this organization in Amplitude AI Visibility. AI Visibility monitors how your brand appears in responses from consumer LLMs (ChatGPT, Google AI Overview, Claude, Gemini). It sends predefined prompts to those models and records which brands get mentioned, at what position, and in what sentiment. An "org brand" is a brand this organization has set up to monitor — it links to the canonical brand record and stores region/language preferences. Every other AI Visibility tool requires an orgBrandId, which you get from this tool. INSTRUCTIONS: - Always call this first when the user asks about AI visibility — you need the orgBrandId to call any other AI Visibility tool. - If multiple org brands are returned, ask the user which one they want to analyze. - Use limit and cursor to page through the list. EXAMPLES: - List org brands: {} - Paginate: {"limit": 25, "cursor": "25"}

Read Amplitude AI Visibility data for a tracked brand. AI Visibility measures how a brand appears in answers from consumer LLMs (ChatGPT, Google AI Overview, Claude, Gemini): which brands get mentioned, at what rank, with what sentiment, and which sources are cited. Call list_ai_visibility_org_brands FIRST to get the orgBrandId — every view here requires it. Set "view" to choose what to read: - scores: top-line visibility score for one brand in one report (visibility %, avgRank, coverage, citations). Start here for "how are we doing". - scores_over_time: visibility trend for a brand across reports over time. - reports: list the monitoring runs (reports); use to find a specific reportId. - topics: per-topic visibility breakdown — where the brand is strong/weak by subject area. - prompts: per-prompt visibility breakdown. - prompt_responses: the raw LLM responses for prompts (verbatim text snippets). - competitors: competitor visibility comparison using the same prompts. - aliases: alternate brand names/spellings detected in responses. - models: visibility broken down by LLM/model family (ChatGPT vs Gemini, etc.). - pages: the brand's own web pages cited by LLMs. - sentiment: sentiment of brand mentions, optionally by theme. - sources: citation source domains rolled up (which sites LLMs cite). Use sourceKeyword to filter to a domain/URL/title. All views accept orgBrandId plus view-specific filters (reportId, topicId, promptIds, modelFamilies, date ranges, sortBy, limit/cursor). Omit reportId to use the latest completed report. EXAMPLES: - Overall score: {"view": "scores", "orgBrandId": 123} - Strongest topics: {"view": "topics", "orgBrandId": 123, "sortBy": "visibility"} - Competitor comparison: {"view": "competitors", "orgBrandId": 123} - Where we're cited: {"view": "sources", "orgBrandId": 123} - Visibility on ChatGPT only: {"view": "models", "orgBrandId": 123, "modelFamilies": ["openai"]}

Update the AI Visibility page view configuration for one project. This sets the app-level page viewed event, referrer property, and URL property used by AI Visibility traffic reporting. INSTRUCTIONS: - Use get_context first to understand available projects, then look for the project containing events that represent people visiting the website. - If the project is unclear, search for SEO, website traffic, web analytics, or traffic dashboards/charts to identify the right project. - Once you have the project, find the page view event with get_events or charts/dashboards that use website visit events. - Use get_properties for that event to find the referrer property and the URL/page URL property. - Do not guess when multiple plausible projects, events, or properties remain. Ask the user to confirm. EXAMPLES: - {"projectId": "123456", "pageViewedEventType": "Page Viewed", "referrerProperty": "referrer", "pageUrlProperty": "page_url"} - {"projectId": "123456", "pageViewedEventType": "[Amplitude] Page Viewed", "referrerProperty": "[Amplitude] Page Domain", "pageUrlProperty": "[Amplitude] Page URL"}

List available group types for a project. Group types are the categories of groups (e.g., "Company", "Team", "Account") — NOT the properties/attributes of those groups. WHEN TO USE: - Use this tool to discover what group types exist (e.g., "Company", "Team"). - Use get_properties with propertyType "group" instead if the user is generally asking for group properties (e.g., company_name, plan_tier). NOTES: - Returns group types from the latest staging version of the default branch.

Retrieve Data workspace settings and environments for a project. These settings control governance and data quality configuration; the environments list shows every environment that shares this workspace's tracking plan. Do not use this to determine general Amplitude settings or context information. Use the get_context tool instead. AVAILABLE SETTINGS: - eventNC: Event naming convention (e.g., camelCase, snake_case, custom regex) - propertyNC: Property naming convention - approvalWF: Approval workflow (None, Required). Used to indicate whether main (default) branches are protected. If required, the user will need to create a new branch to make changes. - descriptionRequired: Whether descriptions are required for events/properties - drsDefaultRole: Default role for data role overrides - snowplowVendorName: Custom Snowplow vendor name - copyToProjects: Cross-project copy configuration - sessionReplayEventGIFsDisabled: Whether session replay GIFs are disabled ENVIRONMENTS: - Returned as `environments: [{ id, name, rank, appId }]`, sorted by rank ascending. - A workspace can have one or many environments. Each environment is mapped to an app via `appId`; the input `projectId` is one of those apps. - When more than one environment is returned, tracking-plan changes apply to every environment in the list — not just the input project. WHEN TO USE: - When you need to understand governance settings for a project. - When checking naming conventions before creating events or properties. - When checking whether main branch protection is enabled - when enabled, the approvalWF setting will be "Required", and the user will not be able to directly make changes to the main branch (the default). - Before any tracking-plan update, to learn how many environments share this workspace so you can warn the user about the scope of changes when there is more than one. INSTRUCTIONS: - Get the project ID from the context tool. - Returns all configured settings. Settings not yet configured will not appear in the response.

List all branches in a project's tracking plan. INSTRUCTIONS: - Use get_context to get available project IDs first. - Call this tool before update_branch or delete_branch to discover branch names and IDs. EXAMPLES: - {"projectId": "123456"} NOTES: - Always includes the default (main) branch, indicated by the isDefault field. - Use the returned branchId or name when calling update_branch or delete_branch. USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Say "main" not "default branch". - Refer to branches by name, not by ID. - Do not mention "pull requests", "PRs", "mutations", branch IDs, version IDs, or GraphQL details to the user.

Create a new branch in a project's tracking plan. INSTRUCTIONS: - Use get_context to get available project IDs first. - Branches are always created off the default (main) branch. - Branch names must be unique within the project. Use the get_branches tool to find existing branches. EXAMPLES: - Simple: {"projectId": "123456", "name": "feature/new-events"} - With description: {"projectId": "123456", "name": "Q3-cleanup", "description": "Cleaning up deprecated events for Q3"} PERMISSIONS: - This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. NOTES: - New branches always fork from the default branch — branching off a feature branch is not supported. - Branch names are validated server-side. USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Say "main" not "default branch". - Refer to branches by name, not by ID. - Do not mention "pull requests", "PRs", "mutations", branch IDs, version IDs, or GraphQL details to the user.

Delete a branch from a project's tracking plan. INSTRUCTIONS: - Use get_context to get available project IDs first. - Provide either branchId or branchName to identify the branch — not both. - This is a destructive operation. Pass confirmed: true only after the user has explicitly acknowledged the deletion. - The default (main) branch cannot be deleted. EXAMPLES: - First call (show confirmation): {"projectId": "123456", "branchName": "feature/old"} - Second call (confirmed): {"projectId": "123456", "branchName": "feature/old", "confirmed": true} PERMISSIONS: - This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. NOTES: - Deleted branches cannot be recovered. - Any tracking plan changes on the branch will be permanently lost. USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Say "main" not "default branch". - Refer to branches by name, not by ID. - Do not mention "pull requests", "PRs", "mutations", branch IDs, version IDs, or GraphQL details to the user.

Update the description of a branch in a project's tracking plan. INSTRUCTIONS: - Use get_context to get available project IDs first. - Provide either branchId or branchName to identify the branch — not both. - The default (main) branch cannot be modified. EXAMPLES: - Update description: {"projectId": "123456", "branchId": "abc123", "description": "Updated description"} - Clear description: {"projectId": "123456", "branchName": "feature/v2", "description": ""} PERMISSIONS: - This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. NOTES: - Branch names cannot be changed through this tool. USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Say "main" not "default branch". - Refer to branches by name, not by ID. - Do not mention "pull requests", "PRs", "mutations", branch IDs, version IDs, or GraphQL details to the user.

Merge a feature branch into the default (main) branch. INSTRUCTIONS: - Use get_context to get available project IDs first. - Use get_branches to find the branch name or ID you want to merge. - This operation requires explicit confirmation before proceeding. - If the workspace requires approval before merging, this tool will surface the current approval status instead of merging. APPROVAL WORKFLOW: - Some workspaces require one or more approvals from team members before a branch can be merged. If this workspace has that requirement enabled and there aren't sufficient approvals, this tool will report the current approval count and block the merge. - Once all required approvals are in place, call this tool again to proceed with the merge. CONFLICT BEHAVIOUR — READ CAREFULLY BEFORE CONFIRMING: Merging applies all changes from the feature branch onto main. If there are unresolved conflicts (changes on both the branch and main to the same item), the merge may fail. Run refresh_branch first to bring the branch up to date with main before merging. EXAMPLES: - First call (show what will happen): {"projectId": "123456", "branchName": "feature/v2"} - Second call (confirmed): {"projectId": "123456", "branchName": "feature/v2", "confirmed": true} PERMISSIONS: - This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. NOTES: - The default (main) branch cannot be merged into itself. - Merging is permanent and cannot be undone. USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Say "main" not "default branch". - Say "approvals" not "reviews". - Refer to branches by name, not by ID. - Do not mention "pull requests", "PRs", "mutations", branch IDs, version IDs, or GraphQL details to the user.

Approve or unapprove a branch so it can be merged into main. INSTRUCTIONS: - Use get_context to get available project IDs first. - Use get_branches to find the branch name or ID. - Set action to "approve" to add your approval, or "unapprove" to withdraw your approval. - Approvals are only meaningful in workspaces that require approval before merging. Check get_workspace_context for approval settings. Where approval is not required, use merge_branch instead. EXAMPLES: - Approve: {"projectId": "123456", "branchName": "feature/v2", "action": "approve"} - Unapprove: {"projectId": "123456", "branchName": "feature/v2", "action": "unapprove"} USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics (pull requests, reviews, mutations) to customers. - Use "approving" / "unapproving a branch", not "creating a pull request review". - On approve success: "Branch approved." - On unapprove success: "Branch unapproved." - When the caller lacks the role for approving branches, say "Insufficient permission to approve a branch." rather than naming internal permission strings. - When more approvals are still needed, say: "One approval is needed for the branch before it can be merged." (singular) or "<number of approvals> approvals are needed for the branch before it can be merged." (plural). - Do not mention "pull requests", "PRs", "reviews", "declined", or GraphQL details to the user. PERMISSIONS: - This tool requires the "Manage Tracking Plans" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. NOTES: - The default (main) branch cannot be approved or unapproved. - Approve requires pending changes on the branch. - An approval counts toward the workspace required-approvals threshold; call merge_branch once enough approvers have approved. - A user can only contribute one approval per branch.

Refresh a branch by pulling in the latest changes from the default (main) branch. INSTRUCTIONS: - Use get_context to get available project IDs first. - Use get_branches to find the branch name or ID you want to refresh. - This operation requires explicit confirmation before proceeding. READ AND RELAY TO USER BEFORE RUNNING THE TOOL: - If the same event or property was changed on both the feature branch and on main after the branch was created, the main version will win and all changes made to that item on the feature branch will be permanently overwritten. There is no way to recover overwritten changes. TWO-STEP PROCESS: - On the first call to this tool (no confirmed flag), this tool returns the list of incoming changes from main and, if any, the specific items that will be overwritten in a `conflicts` field. Show the user the changes and highlight the conflicts to the user. - Show the user the changes and highlight the conflicts to the user. Get their explicit approval before running the tool again to proceed with the refresh. Previous approvals do not count. - If the user previously cancelled the confirmation, running the tool again RESTARTS this process. Show them the diff again and get their explicit approval before running the tool again. EXAMPLES: - First call (show what will happen): {"projectId": "123456", "branchName": "feature/v2"} - Second call (confirmed): {"projectId": "123456", "branchName": "feature/v2", "confirmed": true} PERMISSIONS: - This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. NOTES: - The default (main) branch cannot be refreshed — it is already up to date. USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Say "main" not "default branch". - Refer to branches by name, not by ID. - Do not mention "pull requests", "PRs", "mutations", branch IDs, version IDs, or GraphQL details to the user.

Unified entry point for everything to do with a project's data connections — ingestion sources, import/export job history, Snowflake credentials, live Snowflake warehouse browsing, and Amplitude import-config recommendations. Replaces 9 previously separate tools (get_data_ingestion_sources, get_data_source_details, get_data_warehouse_jobs, get_falcon_integrations, get_snowflake_warehouse_databases/_schemas/_tables/_columns/_rows, recommend_falcon_import_config). ROUTES (action='read', selected by `view`): - omit `dataSourceId` and `view` → list every configured source for the project ('data_connections.list (get_data_ingestion_sources)'). Start here. - `dataSourceId` set, `view` omitted or 'summary' → detail for that one source ('data_connections.summary (get_data_source_details)'). - `view: 'connections'` → list the project's Snowflake credentials/integrations ('data_connections.connections (get_falcon_integrations)'). Use this to find an `integrationId` for the browsing views below. - `view: 'jobs'` → import/export batch job history for one connection ('data_connections.jobs (get_data_warehouse_jobs)'). Requires `dataSourceId` in `vacuum:{id}` / `falcon:{id}` form (as returned by the list route); auto-resolved when the project has exactly one configured source. - `view: 'databases' | 'schemas' | 'tables' | 'columns' | 'rows'` → live Snowflake warehouse browsing, one drill-down level at a time ('data_connections.databases (get_snowflake_warehouse_databases)' etc.). Needs a connection reference (`integrationId` or `sourceDestinationId`) — auto-resolved via 'connections' when the project has exactly one Snowflake credential. Snowflake-only today; other warehouse types will extend this enum, not rename the tool. ROUTES (action='recommend_import'): - Generates a heuristic Amplitude import config + ready-to-run SQL for one or more warehouse tables ('data_connections.recommend_import (recommend_falcon_import_config)'). This is the ONLY correct way to produce warehouse-import SQL — never hand-write it. WHEN TO USE: - Anything about "what's sending data into my project", "did this import/export succeed", "what Snowflake credentials/connections exist", "what's in my Snowflake warehouse", or "generate an import config/SQL for this table". INSTRUCTIONS: - Always provide `projectId`. - Prefer omitting `dataSourceId`/connection refs on the first call in a session — this tool auto-resolves the connection when there's exactly one, and only asks you to disambiguate when there are several. - For 'jobs', pass the prefixed `dataSourceId` from the list route (e.g. `vacuum:42`, `falcon:abc-123`) — not a bare numeric id. - For browsing views, drill down one level per call: 'databases' → 'schemas' (needs `database`) → 'tables' (needs `database`+`schema`) → 'columns'/'rows' (needs a read-only `sql` SELECT). - For 'recommend_import', provide `tables` (fully qualified dotted names) and either `sourceDestinationId` (preferred — lets Amplitude introspect the warehouse; NOT the same id as `integrationId` from 'connections') or `warehouseKind` for a dry run with caller-supplied `columns`/`sampleRows`. EXAMPLES: - List sources: { "projectId": "123456" } - Job history: { "projectId": "123456", "view": "jobs", "dataSourceId": "vacuum:42" } - Browse tables: { "projectId": "123456", "view": "tables", "database": "ANALYTICS", "schema": "PUBLIC" } - Recommend import: { "projectId": "123456", "action": "recommend_import", "sourceDestinationId": "789", "tables": [{"fullyQualifiedName": "ANALYTICS.PUBLIC.EVENTS"}] } NOTES: - Sensitive credential fields are never returned; empty strings stand in for secrets. - Databricks/BigQuery/GA4 warehouse-native browsing isn't implemented yet — only classic Snowflake. `recommend_import` returns a `WAREHOUSE_NOT_SUPPORTED_YET` error for other kinds; surface it without retrying.

Retrieve user profile information for a specific Amplitude user. WHEN TO USE: - You want to view comprehensive information about a specific user - You need to see user properties, device IDs, and group associations - You're investigating user behavior or debugging user-specific issues INSTRUCTIONS: 1. Provide EITHER the amplitudeId OR the userId, along with the projectId 2. Using userId is recommended when you know the customer's user identifier but not their Amplitude ID OUTPUT: - User identity: user ID, amplitude ID, device IDs - Amplitude properties: platform, device, OS, location (city, country, region), language, etc. - Custom user properties and profile properties - Group associations - Usage statistics: event count, session count, purchases, revenue, usage time - First seen and last seen timestamps - By default, experiment properties (prefixed with [Experiment]) are excluded from custom and profile properties - If any user / profile properties were hidden due to data-access controls (DAC) restricted-property rules, the names of those restricted property keys are returned in profile.redactedPropertyKeys. Surface this to the user (e.g. "N restricted user properties were hidden") and route them to their org admin to request access. NEVER claim to have hidden values. LIMITATIONS: - Very large user property objects may be truncated in summary

Retrieve user event timeline for a specific Amplitude user. WHEN TO USE: - You want to examine a user's recent event activity across their full history - You're investigating deep dives into user behavior or debugging user-specific issues - You want to analyze a user's event sequence over time - NOTE: If you have a session replay ID, use get_session_replay_timeline instead — it's scoped to the session and includes richer replay context INSTRUCTIONS: 1. Provide EITHER the amplitudeId OR the userId, along with the projectId 2. Using userId is recommended when you know the customer's user identifier but not their Amplitude ID 3. Optionally specify whether to include full event properties (default false for concise output). When asked to analyze, deep dive, or debug user timelines, enable event properties. 4. Optionally provide an array of event types to filter the timeline to only include those specific events. 5. Optionally specify the number of events to return (default 50, max 1000) 6. Optionally specify a timestamp (ISO 8601 format) to get events from a specific time (default: current time) 7. By default, experiment assignment events (prefixed with [Experiment]) are excluded. If you're debugging experiment related issues, you may want to include them. OUTPUT: - Recent event timeline with event types, timestamps, and properties - Session information for each event. Out-of-session events have session ID of -1. These events are generally sent from the server-side. - Device and platform information - If any event properties were hidden due to data-access controls (DAC) restricted-property rules, the names of those restricted property keys are returned in timeline.redactedPropertyKeys. Surface this to the user so they know the response is incomplete (e.g. "N restricted property values were hidden from this timeline"). NEVER claim to have hidden values; just acknowledge the keys exist and route them to their org admin to request access. EXAMPLES: - Basic timeline lookup by amplitudeId: { "amplitudeId": "12345", "projectId": "67890" } - Basic timeline lookup by userId: { "userId": "[email protected]", "projectId": "67890" } - Timeline with more events: { "amplitudeId": "12345", "projectId": "67890", "eventLimit": 100 } - Timeline from specific time: { "amplitudeId": "12345", "projectId": "67890", "timestamp": "2022-01-01T00:00:00Z" } - Timeline with full event properties: { "amplitudeId": "12345", "projectId": "67890", "includeEventProperties": true } - Include experiment events: { "amplitudeId": "12345", "projectId": "67890", "includeExperimentEvents": true } - Filter to specific event types: { "amplitudeId": "12345", "projectId": "67890", "filterEvents": ["Page Viewed", "Button Clicked"] } LIMITATIONS: - If multiple users match the userId, use amplitudeId for exact lookup

Retrieve user-level data and associated session replays for users who performed a specific event. WHEN TO USE: - You want to inspect individual users who performed a specific event - You need amplitude user IDs to use with get_user_profile or get_user_timeline tools - You want session replays correlated to specific users who performed an event INSTRUCTIONS: - IMPORTANT: Call get_events first to confirm the exact event name exists in the project. Do not guess event names. - Use the search tool to search for events, charts, properties to build the necessary event filter. - Provide projectId, event type, and optional event filters - Use limits to control how many users and session replays to return - Session replays are automatically fetched for returned users when available FILTER FORMAT: Each filter object MUST include all four fields: - subprop_type: "event" (event property) or "user" (user property) - subprop_key: property key name (e.g., "button_name", "gp:plan") - subprop_op: operator (e.g., "is", "is not", "contains", "does not contain", "greater", "less") - subprop_value: array of string values (e.g., ["Submit"]) Do NOT pass empty objects ({}) as filters — either pass a complete filter object or an empty array []. TIME RANGE FORMAT: - Use ISO 8601 format: "2025-01-15T00:00:00Z" - The start date must be before the end date COMMON EXAMPLES: - Active users (default time range): {"projectId": "12345", "event": {"event_type": "_active", "filters": []}} - Button clicks with filters: {"projectId": "12345", "event": {"event_type": "Button Clicked", "filters": [{"subprop_type": "event", "subprop_key": "button_name", "subprop_op": "is", "subprop_value": ["Submit"]}]}} - With explicit time range: {"projectId": "12345", "event": {"event_type": "Page Viewed", "filters": []}, "timeRange": {"start": "2025-01-01T00:00:00Z", "end": "2025-01-31T23:59:59Z"}} - Custom limits: {"projectId": "12345", "event": {"event_type": "Purchase", "filters": []}, "limits": {"users": 20, "sessionReplays": 5}} NOTES: - Time range defaults to "Last 30 Days" if not specified - The amplitude user IDs returned can be used with other tools like get_user_profile or get_user_timeline - Session replays are fetched per-user via the session-replay-lookup API and included in the response - If session replay lookup fails, the error is surfaced in metadata and user data is still returned

Retrieve results from AI agents that have analyzed your dashboards or session replays. This is NOT for searching dashboards, charts, or notebooks — use 'search' for that. This is specifically for retrieving the AI-generated insights and analyses that agents produced. This tool handles both searching for agent analyses and fetching full results in a single call. MODES: 1. **Search mode** (no session_id): Search agent analyses with filters. Returns preview summaries. 2. **Direct fetch mode** (session_id provided): Fetch full artifact data for a specific session. 3. **Auto-expand**: If search returns exactly 1 session, full artifacts are included automatically. SEARCH STRATEGY (important — follow this order): 1. If you have a specific session_id, use direct fetch mode. 2. For dashboard analyses, pass agent_params with dashboard_id (cheap exact-match). 3. For session replay insights, use agent_params with category and/or impact (cheap exact-match). 4. Use "query" ONLY for natural language / fuzzy search when exact filters aren't sufficient. WHEN TO USE: - "What are my dashboard agents?" → agent_type: dashboard_explorer - "Show my agent results" → agent_type: dashboard_explorer (or session_replay_explorer) - "What agents have I run?" → agent_type: dashboard_explorer - "What analyses exist for dashboard xyz?" → agent_type: dashboard_explorer, agent_params: { dashboard_id: "xyz" } - "Show me high-impact session replay insights" → agent_type: session_replay_explorer, agent_params: { impact: "High" } - "Friction hotspots in the checkout flow" → agent_type: session_replay_explorer, agent_params: { category: "Friction Hotspots" }, query: "checkout flow" - "What did the AI find about rage clicks?" → agent_type: session_replay_explorer, query: "rage clicks" - "Any dashboard insights about revenue?" → agent_type: dashboard_explorer, query: "revenue" - "Show me insights from last week" → agent_type: session_replay_explorer, created_after: "2026-03-16T00:00:00Z" - "What did I analyze recently?" → agent_type: dashboard_explorer DO NOT USE FOR: - Finding or listing dashboards, charts, or notebooks → use 'search' instead - Running new analyses or queries → use 'query_dataset' or 'query_charts' instead - Creating dashboards → use 'create_dashboard' instead RETURNS: - Search mode: List of analysis sessions with preview summaries, URLs, and pagination info - Direct fetch mode: Full artifact data for the session - Links to view each session in the Amplitude UI are included

List Guides and Surveys ("nudges") in a project, with filters and derived rollout status. WHEN TO USE: - Discovery and summaries across multiple nudges ("What surveys are live?", "Which guides target the dashboard page?"). - Compare rollout states across nudges ("Which guides are scheduled or in experiments?"). - Provide links or ownership context at a list level ("Give me links to the current onboarding nudges"). INSTRUCTIONS: - If the user says "surveys", pass `types: ["SURVEY"]`; if they say "guides", pass `types: ["GUIDE"]`. - If the user asks for a platform (ios, react-native, etc.), set `platform` and filter the list accordingly. - Use `pageTargetSegments` to answer "what pages are targeted" (URL patterns + match types). If missing/empty, treat as globally eligible. - Use `status` / `statusDescription` to describe rollout: published, testing, scheduled-active, experiment-running, archived, etc. - Use `priority` to explain trigger precedence (4=urgent → 1=low). - Use `createdAt` / `modifiedAt` / `createdBy` / `lastModifiedBy` for recency / ownership questions. - If the user wants full content or detailed configuration for one item, suggest `get_guide_or_survey` with that id — same rollout fields plus full content / targeting / triggering detail. Variants and step content are NOT returned by this tool. OUTPUT FORMAT: - Always render results as a single markdown table, one row per nudge — never as bullets or inline prose. - Always include a `Title` column whose cell wraps the title in a markdown link: `[<title>](<url>)`. Never emit a bare URL anywhere in the response. - Choose 2-4 additional columns from the returned fields based on the user's question. Common picks: `Type`, `Status`, `Platform`, `Priority`, `Last Modified`, `Created By`. Keep the table tightly scoped to what the user asked. Example response for the prompt "What guides are running?": | Title | Type | Status | |---|---|---| | [Welcome tour](https://app.amplitude.com/guides-surveys/amplitude/guides/574019/15731) | GUIDE | published | | [iOS onboarding](https://app.amplitude.com/guides-surveys/amplitude/guides/574019/15728) | GUIDE | experiment-running | EXAMPLES: - All non-archived guides and surveys: { "projectId": "574019" } - Only surveys: { "projectId": "574019", "types": ["SURVEY"] } - iOS guides created in a window: { "projectId": "574019", "types": ["GUIDE"], "platform": "ios", "createdAfter": "2025-01-01T00:00:00Z", "createdBefore": "2025-04-01T00:00:00Z" } - Created by a specific user: { "projectId": "574019", "createdBy": "[email protected]" } - Include archived: { "projectId": "574019", "includeArchived": true } - Next page: { "projectId": "574019", "cursor": "<nextCursor from previous response>" } NOTES: - Terminology: internally these items are called "nudges"; users refer to them as guides or surveys. - `platform: "web"` matches both `web` rows and rows with no platform set. - Results are sorted newest first by id, capped at `limit` (default 50, max 200). When `hasMore` is true, pass `nextCursor` back as `cursor` for the next page. - The current authenticated user must have access to the project.

Get a single guide or survey ("nudge") by id, including variants and step content. WHEN TO USE: - Deep dive on one nudge after discovery via list_guides_surveys: "Show details for guide 123", "Tell me about the onboarding survey". - Questions about rollout / targeting for a specific nudge: "Is it live or scheduled?", "Which pages is it on?", "Is it in an experiment?". - Content / configuration reviews: "What steps does this tour include?", "Can users snooze or dismiss it?", "What triggers it?". INSTRUCTIONS: - Always include `status` / `statusDescription` (derived rollout state) and `url` so the user can navigate to the nudge. - Use `pageTargetSegments` to describe eligible pages; if empty, treat as global. Call out `temporarilyHidePageTargetSegments` as suppressions. - Summarize `triggerConfig.type` (`immediately`, `smart_delay`, `rage_click`, etc.) and any data to explain when it fires. - Summarize `variants[].steps` (title / content / formFactor) to describe the user experience; mention `templateSource` if relevant. - Note `dismissible` / `snoozable`, `lifecycle` rules, `snoozeDuration` / `snoozeLabel` / `snoozableOnAllSteps`, and `priority` for trigger ordering. - `flagVariants` lists the experiment variant keys for experiment-backed nudges (empty otherwise). - Include `platform` when asked for iOS / Android / React Native-specific guidance. - If the user actually wants multiple nudges, suggest `list_guides_surveys` with filters instead. - When you reference the nudge in your response, render its URL as a markdown link with the title as the link text: `[<title>](url)`. Bare URLs without link text render as title-less cards. EXAMPLES: - { "projectId": "574019", "nudgeId": "101" } NOTES: - Terminology: internally these items are called "nudges"; users refer to them as guides or surveys.