create_chart_monitor
ChatGPTCreate a chart alert monitor on a saved chart that does not already have one. WHEN TO USE: - The user wants to start alerting on a chart. - get_config returned hasMonitor=false for this chartId. INSTRUCTIONS: - Provide chartId. Defaults to a smart/automatic monitor (99% confidence interval, above or below). - Optional name, frequency (daily or hourly), conditions, and emailRecipients. Emails default to the current user. - Only chart owners and project managers can create a monitor. - If a monitor already exists, do not create another — use get_config, then subscribe or update. EXAMPLES: - {"chartId":"abc123"} - {"chartId":"abc123","frequency":"hourly","name":"Hourly active users"} - {"chartId":"abc123","conditions":[{"type":"automatic","confidence_interval":95,"direction":"below"}]} NOTES: - This does not query chart data. Use get_amplitude_charts or query_amplitude_data for that. - After create, use subscribe_chart_alert (or action=subscribe) to add Slack/Teams, and update_chart_monitor to enable/disable.
create_dashboard
ChatGPTCreate 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_dashboard
ChatGPTCreate 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_amplitude_data — this tool cannot persist them. Call save_chart_edits first, or create via use_amp_dashboards which saves edit IDs automatically - The typical workflow is: query_amplitude_data (returns editId) → save_chart_edits (converts editId to permanent chartId) → create_dashboard (uses chartId) - If you use an editId instead of a saved chartId, this tool fails with "NotFoundError: No chart" INSTRUCTIONS: - Provide a descriptive name for the dashboard - Saves unpublished to your personal space by default. To put it somewhere the team can see, pass destination {"kind":"space","spaceId":"..."} using a space id from the user or a shared-space URL. To create a space or move an existing dashboard, use manage_amp_entities. The response echoes where it landed in savedTo - Shared-space creates always notify members. DashboardService.createDashboard has no quiet flag, so destination.notify is ignored here - 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)
get_amp_session_replay_info
ChatGPTUnified entry point for session replay data: find replays and inspect what happened in them. Replaces get_session_replays, list_session_replays, get_session_replay_events, and get_session_replay_timeline. ACTIONS: - search (default): find replays by event / user-property / cohort filters, by Amplitude user (userId), by ID (sessionReplayIds), or sample recent sessions with no filters (random slice from the last 24 hours). - list: simple paginated time-range listing via the public Session Replay API (start_time/end_time/page_size/page_token). Use search instead when filtering by events or user properties. - events: processed rrweb interaction timeline for one replay (sessionReplayId) — page navigations, clicks, inputs, scrolls. - timeline: full analytics event timeline for one replay (sessionReplayId) — every event the user fired during and around the session. PREFER THIS over user-timeline tools when you have a replay ID. REQUIRED FOLLOW-UP — render_amp_session_replay: - After search/list return replay IDs, you MUST call render_amp_session_replay in the SAME turn whenever the user's request implies viewing the replays ("show me", "let me see", "pull up", "watch", "play", "open", or any phrasing where seeing the replays is the deliverable). A list of IDs alone is not the answer the user wants. - ONLY skip the render call for raw data extraction ("just count them", "export the IDs"). When in doubt, render. INSTRUCTIONS: - Provide projectId for every action. - Replay IDs use the "<device_id>/<session_id>" format — pass them verbatim between actions. - search: filters are ANDed; reference real event names (call get_events first if unsure). userId and sessionReplayIds are mutually exclusive with each other and with filters. - list: use the returned next_page_token to fetch subsequent pages; keep sort_order consistent across pages. The list response's start/end times describe the analytics session window, NOT the recorded replay length. - events vs timeline: events shows what the user DID in the recording (clicks/inputs/navigation from rrweb); timeline shows which analytics EVENTS fired (with properties). For "walk me through this session" prefer timeline. EXAMPLES: - Sample recent sessions: { "projectId": "12345" } - Users who hit checkout errors: { "action": "search", "projectId": "12345", "events": [{ "name": "Checkout", "withProperty": { "name": "error_type", "exists": true } }] } - Replays for a user yesterday: { "action": "search", "projectId": "12345", "userId": "98765", "since": "yesterday" } - Paginated listing: { "action": "list", "projectId": "12345", "page_size": 50, "sort_order": "desc" } - What the user did in a replay: { "action": "events", "projectId": "12345", "sessionReplayId": "device-abc/1773235450374" } - Events fired during a replay: { "action": "timeline", "projectId": "12345", "sessionReplayId": "device-abc/1773235450374", "includeEventProperties": true } NOTES: - search defaults: 10 results; 30-day window for filtered queries, 24 hours otherwise. If a filtered search is empty, widen the window or relax filters instead of retrying unchanged. - list defaults to the last 48 hours when no time range is provided. - Cohort filters take numeric IDs only — resolve names with get_cohorts first.
get_amplitude_agent_analytics_info
ChatGPTSingle read entry point for Amplitude Agent Analytics (AI/LLM session investigation). NOT FOR: Customer product feedback (use use_amplitude_ai_feedback) or browser Session Replay. Set view to choose the read route (each view has its own parameters in the tool schema): - schema — fields, rubrics, taxonomy, filter_options. Use only when an exact filter identifier is not already known; request only the needed filterOptionTypes. - sessions — filtered session lists and groupBy aggregations (replaces metrics/timeseries tools). - conversation — full transcript; sessionId is required. - spans — per-operation trace; sessionId or traceId is required (no org-wide scans). - tool_reliability — metrics enum is only tool_stats | tool_definitions. REMOVED (use sessions filters instead): - search_agent_analytics_conversations (ILIKE scans) - query_agent_analytics_metrics quality/cost/topics/timeseries enums EXAMPLES: - Agent names: { "view": "schema", "projectId": "12345", "include": ["filter_options"], "filterOptionTypes": ["agent_names"] } - Failed sessions: { "view": "sessions", "projectId": "12345", "hasTechnicalFailure": true, "agentNames": ["global-chat"] } - Transcript: { "view": "conversation", "projectId": "12345", "sessionId": "abc-123" } - Tool reliability: { "view": "tool_reliability", "projectId": "12345", "metrics": ["tool_stats","tool_definitions"], "agentNames": ["global-chat"] }
get_amplitude_context
ChatGPTUnified 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'.
get_amplitude_context
ChatGPTUnified 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, project-level AI context, and data view definition when applicable. WHEN TO USE: - Session start, "what projects do I have access to?", "show me my org details", "what is my role?" → call with no arguments. - "what timezone / currency / session settings does project X use?", "describe project X" → pass projectId. CONTEXT DOCUMENTS (uploaded files): - org.aiContext / project aiContext are short text fields only. Customers also upload context files (CSV data dictionaries, PDFs, process docs) in Settings → AI Controls; those are indexed for search and never returned in full — only titles (opt-in) or search snippets. - listContextDocuments: true adds contextDocuments — document titles and ids only, no file contents. Use it when aiContext references an uploaded file by name (e.g. "always check <file> before answering"). - searchContextDocuments runs semantic search over the uploaded documents' contents and adds contextDocumentSearch with matching text snippets. Use specific terms from the user's question (event names, property names, column names). - Scope for both: without projectId, org-level documents only; with projectId, org-level plus that project's documents. EXAMPLES: - Session start: {} - Project settings: {"projectId": 12345} - aiContext says "check the event dictionary file" → {"projectId": 12345, "listContextDocuments": true} - Look up a term from uploaded docs: {"projectId": 12345, "searchContextDocuments": "envelope_event_type_id"} NOTES: - projectId is optional on purpose. Omit it to get the project list first, then call again with a real id from that list — do NOT guess project ids. - The two layers are meant to be loaded together: call once without projectId at session start for org context, then with a projectId to drill into a project. On conflict, project-level context overrides org-level. - Omit listContextDocuments and searchContextDocuments at session start — they add latency and are only useful once you know what to look for. - A data view is a governed, filtered subset of a source project. Use its projectId for analysis to preserve its filters. The returned dataView.sourceAppId describes lineage, not a replacement query target. DO NOT USE FOR: - Running analytics queries → use 'query_dataset'. - Finding charts/dashboards/cohorts → use 'search'.
get_chart_alerts
ChatGPTRetrieve chart alert anomalies for a project or for one specific chart. WHEN TO USE: - The user wants recent chart alerts, anomalies, or alert notifications. - Use chartId to scope to one chart. - Use get_chart_monitor when the user wants monitor configuration or subscribers instead of alert history. INSTRUCTIONS: - chartId is optional. If provided, projectId is not needed. - For project-wide alerts, projectId is optional only when the user has access to exactly one project. If multiple projects are accessible, provide projectId. - includeUnseen filters to alerts the current user has not marked as seen. - limit defaults to 20 and is capped at 100. EXAMPLES: - {"projectId":"12345"} - {"chartId":"abc123","limit":10} - {"projectId":"12345","includeUnseen":true} NOTES: - This tool returns alert anomalies, not monitor configuration. - Alerts are returned newest first.
get_chart_alerts
ChatGPTRetrieve chart alert anomalies for a project or for one specific chart. WHEN TO USE: - The user wants recent chart alerts, anomalies, or alert notifications. - Use chartId to scope to one chart. - Use get_chart_monitor when the user wants monitor configuration or subscribers instead of alert history. INSTRUCTIONS: - chartId is optional. If provided, projectId is not needed. - For project-wide alerts, projectId is optional only when the user has access to exactly one project. If multiple projects are accessible, provide projectId. - includeUnseen filters to alerts the current user has not marked as seen. - limit defaults to 20 and is capped at 100. EXAMPLES: - {"projectId":"12345"} - {"chartId":"abc123","limit":10} - {"projectId":"12345","includeUnseen":true} NOTES: - This tool returns alert anomalies, not monitor configuration. - Alerts are returned newest first.
get_chart_definition_params
ChatGPTGet 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
get_chart_definition_params
ChatGPTGet the parameter schema, valid enum values, and a working example for a specific chart type. WHEN TO USE: - Before calling query_dataset, to understand the correct parameter schema for a chart type. - When you need to know valid enum values (e.g., funnel modes, segmentation metrics). - When you need a working example definition to use as a template. INSTRUCTIONS: - Call this tool with the chart type you want to build a definition for. - Use the returned schema to construct a valid definition object. - Pass the constructed definition to query_dataset. - If the chart type is not yet supported, construct the definition based on existing chart examples from search/get_charts. SUPPORTED CHART TYPES: eventsSegmentation, funnels, metricExplorer, retention, revenueLtv, sessions, stickiness
get_chart_monitor
ChatGPTRetrieve 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.
get_chart_monitor
ChatGPTRetrieve chart monitor configuration, or list monitors you created or are subscribed to. WHEN TO USE: - The user asks what chart alerts or monitors they have — omit chartId to list. - The user wants to inspect one chart's monitor before changing it — pass chartId. - 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: - Omit chartId to list custom chart monitors you created or are subscribed to (email / Slack / Teams), split into createdByYou and createdByOthers. Each row includes chart name, a short condition summary, and alertsLast30Days. - Optional projectId scopes the list to one project. Optional limit caps each group (default 50, max 100). - Provide chartId to read that chart's full monitor (ID, enabled state, conditions, email recipients, channel subscriptions). - Charts with no monitor return hasMonitor=false and nextStep (not an error). Then use create_chart_monitor (or use_amplitude_chart_monitors action=create). EXAMPLES: - {} - {"projectId":"12345","limit":20} - {"chartId":"abc123"} NOTES: - List does not include automatic event-level monitors — only custom chart monitors. - If a listed chart has no monitor details you need, call again with that chartId. After a monitor exists, subscribe or update can manage it.
get_charts
ChatGPTRetrieve full chart objects by their IDs using the chart service directly WHEN TO USE: - You want to retrieve a full chart definition. - Useful if you want to base an ad hoc query dataset analysis on an exsiting chart. INSTRUCTIONS: - Use the search tool to find the IDs of charts you want to retrieve, then call this tool with the IDs.
get_charts
ChatGPTRetrieve full chart objects by their IDs using the chart service directly WHEN TO USE: - You want to retrieve a full chart definition. - Useful if you want to base an ad hoc query dataset analysis on an exsiting chart. INSTRUCTIONS: - Use the search tool to find the IDs of charts you want to retrieve, then call this tool with the IDs.
get_cohorts
ChatGPTGet 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_cohorts
ChatGPTGet 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_dashboard
ChatGPTGet 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.
get_dashboard
ChatGPTGet 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 (or search_amp_entities / search) to find the IDs of dashboards you want to retrieve, then call this tool with the IDs. - Pass 1 to 3 dashboard IDs in the dashboardIds array (e.g. ["abc1234"] or ["dash_1", "dash_2"]). - Very commonly you will want to query the charts after retrieving a dashboard. - When a dashboard has activeFilters (saved Replace Property entries, dashboard filters, or a date range), pass the dashboard's id as dashboardId to query_charts so those params are applied — and mention the replaced/filtered view when reporting numbers. EXAMPLES: - Retrieve a single dashboard: { "dashboardIds": ["abc1234"] } - Retrieve multiple dashboards (up to 3): { "dashboardIds": ["abc1234", "xyz5678"] }
get_events
ChatGPTRetrieve 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).
get_events
ChatGPTRetrieve events from a project with strict filtering by event types, limit, and cursor pagination. WHEN TO USE: - You can generally rely on the search tool to find the event you are looking for. - Use this tool to get full event objects, including metadata like category, activity, visiblity, and more. - Use this tool to paginate through ALL events when the search tool may not return the event you are looking for. INSTRUCTIONS: - Get the project ID from the context tool. - Use the search tool first to try to find the event you're looking for. - If the search tool does not return the event you are looking for, use this tool without specifying eventTypes to paginate through all events. - If you know the event types you want to get, use this tool with the eventTypes parameter to get more information about the event. - To inspect or analyze a screenshot embedded in an event description, pass includeDescriptionImages=true. This resolves ampl:// image references all the way to attached image bytes; it is off by default. - For ingested volume or query counts, include volume and/or queries in fields. Set lookbackWindow to change the window. - By default, returns events from the project's default branch. Pass branchId or branchName to fetch events from a specific tracking-plan branch — use get_branches first to find the branch. NOTES: - Event types are equivalent to the ingested name. Always use "ingested name" instead of "event type" when responding to the user. - Each event has a "status" field: "planned" (in tracking plan, not yet ingested), "live" (in tracking plan and ingested), "unexpected" (ingested, not in tracking plan), "blocked" (ingestion blocked by an admin), or "deleted" (marked as deleted; only returned when includeDeleted is true). Merge targets omit status — the tracking-plan UI does not show a status on transformed events. "live" and "unexpected" events have been ingested and are queryable; "planned" is not. Unplanned ("unexpected") status alone never stops an event from charting. - Amplitude system events (e.g. "[Amplitude] Page Viewed", "session_start", "_active") are flagged with "isAmplitudeEvent: true". The tracking-plan UI special-cases these as "live" in its status filter regardless of actual ingestion state — keep that in mind when reasoning about why a system event might show as "unexpected" or "planned" here. - Source events of enabled merge transformations are hidden — only the merged target is returned, with a "mergedFrom" field listing the source event names. mergedFrom is always included for merge targets even when fields omits it (otherwise source-hiding would drop context). Merge targets never include status, even if fields requests it. - "firstSeen"/"lastSeen" are lifetime ingestion timestamps (not scoped to a lookback window). "createdAt"/"updatedAt" are tracking-plan edit times and are only present for events in the plan — unexpected events omit them. "updatedBy" is the last editor; Amplitude does not record who originally created an event. - Some ingested names cannot be retyped safely — they contain U+FFFD, control characters, or JSON-significant glyphs (quotes, braces, backslashes). Those events carry an "encodedName" field: an ASCII-only encoding of the exact name. When it is present, copy it verbatim and pass it instead of "name" to this tool's eventTypes and to every event write tool. Never retype the raw name into tool arguments. Events without the field have ordinary names — use "name" as usual. - Valid requested fields: name, encodedName, displayName, description, category, tags, status, isActiveAction, isOfficial, isAmplitudeEvent, hiddenFrom, sources, mergedFrom, owner, createdAt, updatedAt, updatedBy, firstSeen, lastSeen, volume, queries. - Automatically returned when fields is provided: name, encodedName (plus mergedFrom when the event is a merge target). - When fields is omitted, the full event row is returned without volume or queries. Required fields are automatic, and [] is invalid. - volume and queries are per project (not per branch) and 0 when unknown…
get_experiments
ChatGPTRetrieve 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.
get_experiments
ChatGPTRetrieve 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.
get_flags
ChatGPTRetrieve 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.
get_flags
ChatGPTRetrieve 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.
get_from_url
ChatGPTRetrieve 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
get_from_url
ChatGPTRetrieve objects from Amplitude URLs WHEN TO USE: - CRITICAL: Only use this tool for full Amplitude app URLs on supported hosts (app.amplitude.com, app.eu.amplitude.com, apps.stag2.amplitude.com, local.amplitude.com) - You have an Amplitude URL and want to get the full object definition - User shares a link to a dashboard, chart, notebook, experiment, etc. INSTRUCTIONS: - Provide the full Amplitude URL (e.g., https://app.amplitude.com/analytics/myorg/chart/456 or https://app.eu.amplitude.com/analytics/myorg/chart/456) - The tool will parse the URL, validate the organization, and return the full object - Works with charts, dashboards, notebooks, experiments, flags, cohorts, metrics, and opportunities - /chart/new/{id} URLs may refer to a chart draft or a temporary chart edit (from query tools); both are resolved automatically - Agent session URLs (/agents/session/{id}) are not resolvable here — use get_agent_results with the session_id instead
get_metrics
ChatGPTGet 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.
get_monitor_history
ChatGPTRetrieve the audit history for a chart monitor. WHEN TO USE: - The user wants to know who changed a chart monitor and when. - Use get_chart_monitor first if you need to discover the monitorId from a chart. INSTRUCTIONS: - Provide monitorId. - Returns the history entries in reverse chronological order. EXAMPLES: - {"monitorId":"mon_123"} NOTES: - This is monitor change history, not alert anomaly history.
get_monitor_history
ChatGPTRetrieve the audit history for a chart monitor. WHEN TO USE: - The user wants to know who changed a chart monitor and when. - Use get_chart_monitor first if you need to discover the monitorId from a chart. INSTRUCTIONS: - Provide monitorId. - Returns the history entries in reverse chronological order. EXAMPLES: - {"monitorId":"mon_123"} NOTES: - This is monitor change history, not alert anomaly history.
get_properties
ChatGPTRetrieve 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"] }
get_properties
ChatGPTList the properties that exist in a project's taxonomy — the direct way to answer "which/what properties exist on <event>?" and to discover valid property names before querying or filtering. WHEN TO USE — answer questions like: - "Which properties exist on the checkout event?" → { propertyType: "event", eventType: "checkout", projectId } - "What properties are on the Purchase event?" → { propertyType: "event", eventType: "Purchase", projectId } - "What user properties are in my project?" → { propertyType: "user", projectId } - "What group / derived / channel / lookup properties are tracked?" → set propertyType accordingly - Discovering valid event-property names before building a query_dataset filter or group_by This is a fast, direct lookup. Do NOT run query_dataset to discover which properties an event has — that is a schema lookup, not a metric query, and belongs here. DO NOT USE FOR: - Metrics, counts, trends, funnels, retention → use 'query_dataset' - Finding which EVENTS exist (not their properties) → use 'get_events' or 'search' PROPERTY TYPES: | propertyType | What it returns | Key params | |---|---|---| | event | Event properties, via one of four paths: eventType for one event's properties, names for selected properties project-wide with the events that use them, both for selected properties on one event (with a missing list for names not on it), or neither for all event properties (paginated). Transformations are included by default. Pass includeDeleted to add deleted states, or includeHidden/includeBlocked false to drop those states. Request firstSeen/lastSeen via fields. For query counts, include queries in fields and set lookbackWindow to change the window. | eventType, names, includeDeleted, includeHidden, includeBlocked, includeTransformations, fields, lookbackWindow, branchId/branchName | | user | User-level properties with transformations included by default. Request firstSeen/lastSeen via fields. For query counts, include queries in fields and set lookbackWindow to change the window. | names, sources, includeDeleted, includeHidden, includeBlocked, includeTransformations, fields, lookbackWindow, branchId/branchName | | derived | Computed/formula properties | derivedPropertyType, names | | group | Group properties, one row per property. groupTypes lists attached group types. | names, groupTypes, includeDeleted, includeHidden, includeBlocked, branchId/branchName | | lookup | CSV lookup table properties | names, configurationFilter, lookupTableName | | channel | Traffic source channel classifiers (derived formula properties) | names | | persisted | Event-to-user persisted properties | names | CHART QUERY PROP TYPES (query_dataset / chart definitions): - Derived and channel classifier properties must use prop_type / group_by.type / subprop_type of "derivedV2" — not legacy "derived" or other invented types. - get_properties returns chartPropType: "derivedV2" for derived and channel properties. propertyType "event"/"user" is display scope only, not the chart API type. GLOBAL VS. EVENT-SCOPED EVENT PROPERTIES: Event properties in Amplitude have two scopes: - Global (plan-wide): a property definition shared across the project's tracking plan, not tied to a single event. - Event-scoped (local): a definition attached to one specific event type (e.g., "Button Clicked.button_name"). When the user looks for event properties without specifying a scope (global or event-scoped), prompt for clarification. INSTRUCTIONS: - Use the search tool or get_events first to find exact event/property names before calling this tool. - names works the same on every propertyType: exact, case-sensitive, 1-100 names; names that match nothing come back in a "missing" list, spelled as you sent them. - All property types support limit/cursor pagination. For 'event', pagination applies only when eventType and names are omitted (event-scoped returns all properties for that event). - Event, user, and group property rows carry an "encodedName" field when the raw name cannot be retyped safely (U+FFFD, control characters, quotes/braces/back…
query_charts
ChatGPTQuery up to 3 charts concurrently given their IDs. RULES: - Users want to know references for analyses in order to validate the data. - ALWAYS REFERENCE CHARTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES. WHEN TO USE: - You want to query multiple charts to get their data efficiently. - Maximum of 3 charts can be queried in a single request. PREREQUISITES (required): - You MUST have at least one concrete chartIds or chartEditIds entry before calling this tool. Do not call it speculatively. - If you do not already have any, resolve them FIRST via: - search with entityTypes: ["CHART"] to find saved charts by name. - get_from_url when the user has shared Amplitude chart URLs. - query_dataset if the user wants an ad-hoc analysis rather than an existing chart. - If the user has not provided chart references and none of the above apply, STOP and ask the user which charts to query. INSTRUCTIONS: - Provide saved charts via chartIds and chart edits (links ending in /chart/new/<edit_id> or /chart/<chart_id>/edit/<edit_id>) via chartEditIds. - Chart edit IDs take precedence over chart IDs when both are available for a given chart. - Use this tool to query up to 3 charts + chart edits (combined total). - Results will include data for each successfully queried chart and errors for any failed charts. RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. Check the isCsvResponse flag to determine which response format to parse CRITICAL — NON-ADDITIVE METRICS (uniques, pct_dau): - These metrics cannot be summed across intervals. The chart UI plots per-interval values, not a running total. - Additive metrics (totals, sums) CAN be summed across intervals. How to read the JSON response, by metric type: 1. COUNT metrics ("uniques"): - Use "overallSeries" — it is the TRUE deduped unique count across the full date range. - Do NOT sum "timeSeries" values — that overstates the count due to user overlap across intervals. 2. RATIO metrics ("pct_dau" only): - Use "timeSeriesAverage" (mean of per-interval values) — this matches what the chart UI displays. For "current" reporting, also consider the most recent N intervals from "timeSeries". - Do NOT use "overallSeries" for pct_dau over multi-interval ranges. For pct_dau, "overallSeries" is a long-range aggregate (deduped numerator over the full range / deduped denominator over the full range). Over many intervals the denominator dedupes a much larger pool than the numerator, which compresses the ratio — typically reporting roughly half of the per-interval values the chart shows. This is mathematically valid as a long-range aggregate but is NOT what users see in the chart. - Do NOT sum "timeSeries" values — ratios cannot be summed. CSV Response Structure (when isCsvResponse is true): - Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details - Data header row: A single row containing column labels for the data points below (typically includes dates or time periods) - Data rows: Each row contains: Label columns: First few columns contain row labels identifying the data series Value columns: Numerical data organized under the corresponding date/time columns from the data header row - Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns - Cells in the CSV response are delimited by commas and may be prepended with a character Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. IMPORTANT: The overall unique users is 5642 (NOT 614+1769+4132=6515), because users overlap across days. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'" " Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "par…
query_charts
ChatGPTQuery 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. When jsonResponse is present, "seriesNames" (string[]) gives the human-readable name of each timeSeries entry in order — use it instead of the numeric seriesLabels for ungrouped segments. "seriesKeys" (string[], same order) gives each series' customSerieLabels key; use it verbatim to rename a legend. 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…
query_dataset_chatgpt
ChatGPTRun 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. Check the isCsvResponse flag to determine which response format to parse CRITICAL — NON-ADDITIVE METRICS (uni…
query_dataset_chatgpt
ChatGPTRun 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: - Heatmaps and zoning for a page URL (click map, scroll depth, zone metrics such as click rate or rage clicks per zone) → use 'run_amp' (heatmaps click-map, heatmaps scroll-map, zoning zone-metrics). Dataset queries cannot serve them. - Listing or checking which properties exist on an event (e.g. "what/which properties are on the checkout event?") → use 'get_properties' (propertyType="event", pass eventType). Do NOT run queries to discover a schema. - Finding existing charts/dashboards → use 'search' instead - Getting valid chart definition structure → use 'get_chart_definition_params' (or fix from chartTypeSchema in a validation-error response) - If you need more information about existing charts in the project as an example → use 'get_charts' instead - Project settings (timezone, currency) → use 'get_project_context' instead STRATEGIES 1. Use 'get_events' to discover the exact event name, then query directly. Do not page the project-wide property catalogue unless the requested analysis needs a property. 2. Use 'get_chart_definition_params' when you need the full schema before building a definition (optional — validation errors also return chartTypeSchema). 3. Use the 'get_charts' tool to find examples of existing charts in the project to understand the events, properties, and dataset schema generally. 4. Optionally use the 'search' tool again to find additional events, user properties, etc. needed for the query. 5. Optionally use the 'get_properties' tool (propertyType="event", pass eventType) to get properties on individual events. 6. Use this tool to query the ad hoc analysis — definitions are validated and auto-corrected inline. GENERAL GUIDELINES - Read saved metric definitions with get_metrics or use_amplitude_metrics action="get_metrics" before building a chart from them. - 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 "d…
query_experiment
ChatGPTQuery an experiment analysis. CRITICAL: Do NOT pass metricIds unless user explicitly requests specific metrics or requests analysis on secondary metrics. Omit metricIds for primary metric only (cleaner, focused results). RULES: - Users want to know references for analyses in order to validate the data. - ALWAYS REFERENCE EXPERIMENTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES. WHEN TO USE: - You want to query a experiment for analysis. INSTRUCTIONS: - Use the search tool to find the ID of the experiment you want to query. - You may want to use the get_experiments tool to get more context about the experiment (i.e. state, variants, etc.) - Use this tool to query the experiment analysis. EXAMPLE: groupBy: [{"type": "user", "value": "device type", "group_type": "User"}]
query_experiment
ChatGPTQuery an experiment analysis. CRITICAL: Do NOT pass metricIds unless user explicitly requests specific metrics or requests analysis on secondary metrics. Omit metricIds for primary metric only (cleaner, focused results). RULES: - Users want to know references for analyses in order to validate the data. - ALWAYS REFERENCE EXPERIMENTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES. WHEN TO USE: - You want to query a experiment for analysis. INSTRUCTIONS: - Use the search tool to find the ID of the experiment you want to query. - You may want to use the get_experiments tool to get more context about the experiment (i.e. state, variants, etc.) - Use this tool to query the experiment analysis. EXAMPLE: groupBy: [{"type": "user", "value": "device type", "group_type": "User"}]
query_metric
ChatGPTQuery metric data using the dataset endpoint with metric references RULES: - Users want to know references for analyses in order to validate the data. - ALWAYS REFERENCE METRICS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES. WHEN TO USE: - You want to query a metric to get its data. INSTRUCTIONS: - Use the search tool to find the ID of the metric you want to query. - Use this tool to query the metric. RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. Check the isCsvResponse flag to determine which response format to parse CRITICAL — NON-ADDITIVE METRICS (uniques, pct_dau): - These metrics cannot be summed across intervals. The chart UI plots per-interval values, not a running total. - Additive metrics (totals, sums) CAN be summed across intervals. How to read the JSON response, by metric type: 1. COUNT metrics ("uniques"): - Use "overallSeries" — it is the TRUE deduped unique count across the full date range. - Do NOT sum "timeSeries" values — that overstates the count due to user overlap across intervals. 2. RATIO metrics ("pct_dau" only): - Use "timeSeriesAverage" (mean of per-interval values) — this matches what the chart UI displays. For "current" reporting, also consider the most recent N intervals from "timeSeries". - Do NOT use "overallSeries" for pct_dau over multi-interval ranges. For pct_dau, "overallSeries" is a long-range aggregate (deduped numerator over the full range / deduped denominator over the full range). Over many intervals the denominator dedupes a much larger pool than the numerator, which compresses the ratio — typically reporting roughly half of the per-interval values the chart shows. This is mathematically valid as a long-range aggregate but is NOT what users see in the chart. - Do NOT sum "timeSeries" values — ratios cannot be summed. CSV Response Structure (when isCsvResponse is true): - Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details - Data header row: A single row containing column labels for the data points below (typically includes dates or time periods) - Data rows: Each row contains: Label columns: First few columns contain row labels identifying the data series Value columns: Numerical data organized under the corresponding date/time columns from the data header row - Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns - Cells in the CSV response are delimited by commas and may be prepended with a character Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. IMPORTANT: The overall unique users is 5642 (NOT 614+1769+4132=6515), because users overlap across days. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'" " Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "eventsSegmentation", } JSON Response Structure (when isCsvResponse is false): - Parse using the following structure: - timeSeries: Array of arrays, each containing data points for a given time period with a "value" property - overallSeries: Array of arrays, each containing the overall data point across the entire range under the "value" property. IMPORTANT — interpretation depends on the metric: For "uniques" (count): this is the TRUE deduped unique count over the full date range. Use this. For "pct_dau" (ratio): this is a long-range aggregate ratio (deduped numerator over range / deduped denominator over range). It does NOT match the per-interval values the chart UI plots …
query_metric
ChatGPTQuery metric data using the dataset endpoint with metric references RULES: - Users want to know references for analyses in order to validate the data. - ALWAYS REFERENCE METRICS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES. WHEN TO USE: - You want to query a metric to get its data. INSTRUCTIONS: - If the metric ID is already known, query it directly; search only when you need to discover the ID. - Preserve the requested date window and grouping. For a day-based window grouped weekly, use query_dataset with explicit start/end and interval=7, or query_amplitude_data with the same raw definition when query_dataset is unavailable. - For saved AmpSQL metrics with declared-column filters or breakdowns, use query_dataset (or query_amplitude_data) with a raw chart definition instead. RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. When jsonResponse is present, "seriesNames" (string[]) gives the human-readable name of each timeSeries entry in order — use it instead of the numeric seriesLabels for ungrouped segments. "seriesKeys" (string[], same order) gives each series' customSerieLabels key; use it verbatim to rename a legend. Check the isCsvResponse flag to determine which response format to parse CRITICAL — NON-ADDITIVE METRICS (uniques, pct_dau): - These metrics cannot be summed across intervals. The chart UI plots per-interval values, not a running total. - Additive metrics (totals, sums) CAN be summed across intervals. How to read the JSON response, by metric type: 1. COUNT metrics ("uniques"): - Use "overallSeries" — it is the TRUE deduped unique count across the full date range. - Do NOT sum "timeSeries" values — that overstates the count due to user overlap across intervals. 2. RATIO metrics ("pct_dau" only): - Use "timeSeriesAverage" (mean of per-interval values) — this matches what the chart UI displays. For "current" reporting, also consider the most recent N intervals from "timeSeries". - Do NOT use "overallSeries" for pct_dau over multi-interval ranges. For pct_dau, "overallSeries" is a long-range aggregate (deduped numerator over the full range / deduped denominator over the full range). Over many intervals the denominator dedupes a much larger pool than the numerator, which compresses the ratio — typically reporting roughly half of the per-interval values the chart shows. This is mathematically valid as a long-range aggregate but is NOT what users see in the chart. - Do NOT sum "timeSeries" values — ratios cannot be summed. CSV Response Structure (when isCsvResponse is true): - Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details - Data header row: A single row containing column labels for the data points below (typically includes dates or time periods) - Data rows: Each row contains: Label columns: First few columns contain row labels identifying the data series Value columns: Numerical data organized under the corresponding date/time columns from the data header row - Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns - Cells in the CSV response are delimited by commas and may be prepended with a character Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. IMPORTANT: The overall unique users is 5642 (NOT 614+1769+4132=6515), because users overlap across days. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'" " Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "e…
save_chart_edits
ChatGPTSave 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
save_chart_edits
ChatGPTPromote chart edits to saved charts — Save as (new chartId) or Save in place (same chartId). WHEN TO USE: - You have a chartEditId from query_amplitude_data and need a permanent chartId - The user asked to update an existing chart and keep the same chartId / links MODES (per item in charts[]): - Save as (default): omit chartId → creates a new unpublished chart in personal space - Save in place: chartId + expectedLastModified → overwrites that chart (same chartId; updates all dashboards/notebooks referencing it) → ONLY when the user explicitly asked to update the existing chart — never infer from context → Requires a two-step confirm flow (probe, then confirm) — see workflow below WORKFLOW — save as new: 1. query_amplitude_data → chartEditId 2. save_chart_edits({ charts: [{ editId, name }] }) 3. Use returned chartId in dashboards/notebooks WORKFLOW — update existing chart (two-step — always confirm with the user): 1. get_amplitude_charts({ chartIds, include: "definition" }) → lastModified 2. query_amplitude_data({ chart, chartId }) → chartEditId 3. Probe (no confirm flags): save_chart_edits({ charts: [{ editId, name, chartId, expectedLastModified }] }) → returns overwriteImpact (chart name, URL, dashboards, published status) → present this to the user and ask whether to update in place or save as new 4. Confirm (only if user explicitly wants in-place): re-call with confirmOverwrite: true → if requiresSharedChartConfirmation, also add confirmSharedImpact: true after user reviews sharedChartImpact IMPORTANT: - Never set confirmOverwrite on the first in-place call — the probe response exists so you can double-check with the user - Default to save-as-new unless the user clearly wants the same chartId updated - Having chartId from a URL or prior query does NOT mean in-place save is allowed - Save-as-new charts default to unpublished in your personal space until a human publishes - To collaborate on save-as-new, pass destination {"kind":"space","spaceId":"..."} using a space id from the user or a shared-space URL. You must have permission to add to that space. To create a space or move already-saved charts, use manage_amp_entities - The response echoes where charts landed in savedTo (kind, spaceName, published, notified). Report that to the user rather than assuming the requested destination was used - In-place save requires edit access, matching edit provenance, and a fresh expectedLastModified (409 conflict if stale) - Prefer save in place when the user explicitly asks to update a chart others reference; use save as for new analyses
search
ChatGPTSearch 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.
search
ChatGPTSearch for dashboards, charts, notebooks, experiments, and other content in Amplitude. INSTRUCTIONS: - Use this as your primary tool to discover and explore available analytics content before diving into specific analyses. - If you are not sure what to search for, use the default search query. - Do not specify appIds/projectIds in the input unless the user explicitly asks to search within a specific app/project. - When searching for taxonomy entities like events, properties, etc. use higher limits (e.g. 100-200) to get more results as there are more important entities to search through. - When searching for events, use the get_properties tool (propertyType="event") to get event properties on an individual event. - To search Amplitude's official product documentation (SDK setup guides, API reference, help articles), include 'AMPLITUDE_DOCS' in entityTypes. This searches the public docs corpus — NOT your org's content — and returns doc pages with browsable URLs. Pair it with a natural-language query (e.g. "how to track revenue in the browser SDK"). DO NOT USE FOR: - AI agent results, agent analyses, or agent runs → use 'get_agent_results' instead - Getting full dashboard definitions with chart details → use 'get_dashboard' with the IDs from search results - Running queries or analysis → use 'query_dataset' or 'query_charts' ADDITIONAL INFORMATION: - Results are personalized to the user you are making the request on behalf of. - Results do not include the full object definition. You will need to use other tools to get the full object definition when needed. - Best practice is to query for a single entity type, unless the user's request is open ended. - The response includes an isOfficial flag in contentMeta to identify content that has been marked as official by the organization.
search_entity_relationships
ChatGPTFind relationships for any Amplitude entity - shows what charts, experiments, cohorts, and other entities are connected to or use the specified source entity. WHEN TO USE: - You want to understand dependencies and relationships for a specific Amplitude entity. - You need to see what content references a specific entity before making changes. - You're analyzing the impact of modifying or archiving an entity. - You want to find all entities that use a particular event, property, cohort, chart, etc. INSTRUCTIONS: - Provide the app ID and specify a source entity with its type and name. - The tool searches for relationships to a fixed set of target entity types (metrics, segments, cohorts, connections, predictions, experiments, flags, custom events, derived properties, lookup properties). - Results are split into separate searches for charts vs other entities to prevent charts from crowding out other entity types. - The response shows all entities that reference or are related to the specified source entity, organized by entity type. - Use this to understand entity adoption and potential impact of changes. SUPPORTED ENTITY TYPES: - event - custom_event - event_property - user_property - derived_property - lookup_property - channel_classifier - cohort - prediction - metric RESPONSE FORMAT: - results: Combined list of all related entities - resultsByType: Results organized by entity type (charts, cohorts, metrics, etc.) - counts: Count of results for each entity type - totalHits: Total number of matching entities across both searches - chartHits/nonChartHits: Separate hit counts for chart vs non-chart searches EXAMPLES: - Find all charts using event "Login" in app 187520 - Analyze which experiments are targeting a specific cohort id in an app - Understand what content uses a particular custom event before archiving it - Find all entities that reference a specific event_property
search_entity_relationships
ChatGPTFind relationships for any Amplitude entity - shows what charts, experiments, cohorts, and other entities are connected to or use the specified source entity. WHEN TO USE: - You want to understand dependencies and relationships for a specific Amplitude entity. - You need to see what content references a specific entity before making changes. - You're analyzing the impact of modifying or archiving an entity. - You want to find all entities that use a particular event, property, cohort, chart, etc. INSTRUCTIONS: - Provide the app ID and specify a source entity with its type and name. - The tool searches for relationships to a fixed set of target entity types (metrics, segments, cohorts, connections, predictions, experiments, flags, custom events, derived properties, lookup properties). - Results are split into separate searches for charts vs other entities to prevent charts from crowding out other entity types. - The response shows all entities that reference or are related to the specified source entity, organized by entity type. - Use this to understand entity adoption and potential impact of changes. SUPPORTED ENTITY TYPES: - event - custom_event - event_property - user_property - derived_property - lookup_property - channel_classifier - cohort - prediction - metric RESPONSE FORMAT: - results: Combined list of all related entities - resultsByType: Results organized by entity type (charts, cohorts, metrics, etc.) - counts: Count of results for each entity type - totalHits: Total number of matching entities across both searches - chartHits/nonChartHits: Separate hit counts for chart vs non-chart searches EXAMPLES: - Find all charts using event "Login" in app 187520 - Analyze which experiments are targeting a specific cohort id in an app - Understand what content uses a particular custom event before archiving it - Find all entities that reference a specific event_property
subscribe_chart_alert
ChatGPTSubscribe or unsubscribe the current user or a channel to chart alerts for a monitor. WHEN TO USE: - The user wants to subscribe or unsubscribe from chart alerts. - Use get_chart_monitor first if you need the monitorId or want to inspect existing subscribers. INSTRUCTIONS: - Provide monitorId, action, and deliveryMethod. - For email delivery, this tool only manages the current user's own email subscription. - For Slack or Teams delivery, provide deliveryChannel. - deliveryWorkspaceId is optional workspace context for Slack or Teams channels when needed. - If adding the first subscriber to a disabled monitor, this tool re-enables the monitor automatically. - If removing the last subscriber, this tool disables the monitor automatically. EXAMPLES: - {"monitorId":"mon_123","action":"subscribe","deliveryMethod":"email"} - {"monitorId":"mon_123","action":"subscribe","deliveryMethod":"slack","deliveryChannel":"C024BE91L"} - {"monitorId":"mon_123","action":"unsubscribe","deliveryMethod":"teams","deliveryChannel":"19:channel-id@thread.tacv2","deliveryWorkspaceId":"tenant-id:team-id"} NOTES: - Do not use this to edit thresholds or other monitor settings. Use update_chart_monitor for that.
subscribe_chart_alert
ChatGPTSubscribe or unsubscribe the current user or a channel to chart alerts for a monitor. WHEN TO USE: - The user wants to subscribe or unsubscribe from chart alerts. - Use get_chart_monitor first if you need the monitorId or want to inspect existing subscribers. INSTRUCTIONS: - Provide monitorId, action, and deliveryMethod. - For email delivery, this tool only manages the current user's own email subscription. - For Slack or Teams delivery, provide deliveryChannel. - deliveryWorkspaceId is optional workspace context for Slack or Teams channels when needed. - If adding the first subscriber to a disabled monitor, this tool re-enables the monitor automatically. - If removing the last subscriber, this tool disables the monitor automatically. EXAMPLES: - {"monitorId":"mon_123","action":"subscribe","deliveryMethod":"email"} - {"monitorId":"mon_123","action":"subscribe","deliveryMethod":"slack","deliveryChannel":"C024BE91L"} - {"monitorId":"mon_123","action":"unsubscribe","deliveryMethod":"teams","deliveryChannel":"19:channel-id@thread.tacv2","deliveryWorkspaceId":"tenant-id:team-id"} NOTES: - Do not use this to edit thresholds or other monitor settings. Use update_chart_monitor for that.
update_chart_monitor
ChatGPTEnable 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.
update_chart_monitor
ChatGPTEnable 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.
use_amplitude_metrics
ChatGPTUnified entry point for metric definitions, goals, and goal alerts in a project. Replaces get_metrics, create_metric, update_metric, delete_metric, get_metric_goals, the five goal write tools, and the four goal-alert CRUD tools. WHEN TO USE: - Anything about defining metrics, setting targets on metrics, listing goals/pacing, or configuring goal alerts. - NOT for querying metric values over time — use query_metric or query_dataset instead. INSTRUCTIONS: - Select the operation with action. - Metric defs: resolve metricIds with search first; create_metric needs projectId, name, and metricType plus type-specific fields (same rules as the legacy create_metric tool). - Goals: use get_goals to discover goalIds before update / archive / restore / delete / alert actions. - update_metric may be two-step when changing a metric definition with dependents; delete_metric and delete_goal may also be two-step when dependents exist. For any of these operations, first call without confirmed, show the returned dependency payload to the user, then retry with confirmed: true only after user confirmation. - get_goals accepts either metricId OR projectId, not both. DO NOT USE FOR: - Chart or experiment metric values → query_metric / query_dataset. - Experiments and flags → get_experiments / get_flags / create_experiment.
verify_chart_definition
ChatGPTValidate 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.
verify_chart_definition
ChatGPTValidate and auto-correct a chart definition before passing it to query_dataset. WHEN TO USE: - After constructing a chart definition, to verify it is valid before querying. - When you want to catch and auto-fix common mistakes (wrong enum values, wrong field names). - The tool will auto-coerce known LLM mistakes and return the corrected definition. - Validates event types and properties exist in the project taxonomy. WHAT IT DOES: - Validates required fields (type, app, params) and chart-type-specific parameters. - Auto-coerces known mistakes: wrong funnel mode names (this_order → ordered), conversionWindow objects → conversionSeconds, ISO date strings → Unix timestamps, string events → {event_type, filters, group_by}. - Validates that referenced event types exist in the project. - Validates that referenced properties exist on their event types. - Validates user and derived properties in segments/group_by: hidden properties are rejected, and derived formula properties must use prop_type/group_by type derivedV2 (not user or legacy derived). - Returns the corrected definition ready to pass to query_dataset. SUPPORTED CHART TYPES: eventsSegmentation, funnels, metricExplorer, retention, revenueLtv, sessions, stickiness Unsupported types pass through with a warning (not an error) — you can still send them to query_dataset.
