Skip to content

Instantly share code, notes, and snippets.

@bgrainger

bgrainger/tools.json

Created April 9, 2026 18:31
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save bgrainger/82cc04fe5b2a56f65fee43f4e2e21716 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save bgrainger/82cc04fe5b2a56f65fee43f4e2e21716 to your computer and use it in GitHub Desktop.
Download ZIP
Amplitude MCP Tools
Raw
tools.json
{
"result": {
"tools": [
{
"name": "get_charts",
"title": "Reading chart data",
"description": "Retrieve full chart objects by their IDs using the chart service directly\n\nWHEN TO USE:\n- You want to retrieve a full chart definition.\n- Useful if you want to base an ad hoc query dataset analysis on an exsiting chart.\n\nINSTRUCTIONS:\n- Use the search tool to find the IDs of charts you want to retrieve, then call this tool with the IDs.\n",
"inputSchema": {
"type": "object",
"properties": {
"chartIds": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Array of chart IDs to retrieve (required)"
}
},
"required": [
"chartIds"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Reading chart data",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"chart",
"analytics",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "save_chart_edits",
"title": "Saving chart edits",
"description": "Save temporary chart edits as permanent charts\n\nWHEN TO USE:\n- You have chart edit IDs from query_dataset and want to save them as permanent charts\n- You need to add charts to dashboards or notebooks (which require saved chart IDs)\n\nWORKFLOW:\n1. Use query_dataset to create ad-hoc analyses (returns editId)\n2. Use save_chart_edits to convert editIds into permanent chartIds\n3. Use chartIds in create_dashboard or create_notebook\n\nIMPORTANT:\n- All AI-generated charts are saved as unpublished in your personal space\n- Charts require human review before publishing to shared spaces\n- Use bulk saving to reduce tool calls when creating multiple charts",
"inputSchema": {
"type": "object",
"properties": {
"charts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"editId": {
"type": "string",
"description": "Chart edit ID to save"
},
"name": {
"type": "string",
"description": "Name for the saved chart"
},
"description": {
"type": "string",
"description": "Description for the saved chart"
}
},
"required": [
"editId",
"name",
"description"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Array of chart edits to save with name and description for each"
}
},
"required": [
"charts"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Saving chart edits",
"destructiveHint": false,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"chart",
"analytics",
"default"
],
"amplitude/accessLevels": [
"create"
]
}
},
{
"name": "get_cohorts",
"title": "Finding cohorts",
"description": "Get detailed information about specific cohorts by their IDs.\n\nWHEN TO USE:\n- You want to retrieve full cohort definitions after finding them via search.\n- You need detailed cohort information including definition, metadata, and audience details.\n\nINSTRUCTIONS:\n- Use the search tool to find the IDs of cohorts you want to retrieve, then call this tool with the IDs.\n- This returns full cohort objects with all details, unlike the search tool which returns summary information.",
"inputSchema": {
"type": "object",
"properties": {
"cohortIds": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 50,
"description": "Array of cohort IDs to retrieve (required)"
}
},
"required": [
"cohortIds"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Finding cohorts",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"cohort",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "create_cohort",
"title": "Create Cohort",
"description": "Create a new cohort with the provided definition and configuration.\n\nWHEN TO USE:\n- You need to create a new audience segment based on user behavior or properties\n- You want to save a cohort definition for reuse in charts, experiments, or other analyses\n- You need to create a cohort from specific conditions like events, user properties, or funnels\n\nLEARNING FROM EXISTING COHORTS:\n- 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\n- Study the structure and patterns of existing cohort definitions to understand the correct payload format\n- Pay attention to how different condition types (event, user_property, other_cohort, etc.) are structured\n- Learn from the andClauses/orClauses patterns and how they combine different conditions\n- Use existing cohorts as templates for similar use cases to ensure proper schema compliance\n\nEXAMPLES:\n- Create an event-based cohort (users who performed a specific event >= 1 time in the past 30 days):\n {\n \"app_id\": \"365742\",\n \"name\": \"xuan-simple-event-cohort\",\n \"definition\": {\n \"version\": 3,\n \"andClauses\": [{\n \"negated\": false,\n \"orClauses\": [{\n \"type\": \"event\", // Condition type: event-based\n \"metric\": null, // No specific metric aggregation\n \"offset\": 0, // No time offset from the base time range\n \"group_by\": [], // No grouping/segmentation by event properties\n \"interval\": 1, // Time granularity: 1 = DAY (daily buckets)\n \"operator\": \">=\", // Event count operator: greater than or equal\n \"time_type\": \"rolling\", // Rolling time window (last N days from now)\n \"time_value\": 30, // Time range: 30 units of the interval (30 days)\n \"type_value\": \"xuan-test-httpapi-event-type\", // The specific event name to match\n \"operator_value\": 1, // Minimum event count threshold: >= 1 occurrence\n \"exclude_current_interval\": false // Include events from the current day\n }]\n }],\n \"cohortType\": \"UNIQUES\", // Count unique users (not event occurrences)\n \"countGroup\": {\"name\": \"User\", \"is_computed\": false}, // Group by User entities\n \"referenceFrameTimeParams\": {} // No additional time frame parameters\n },\n \"type\": \"redshift\", // Cohort computation engine type (optional - defaults to \"redshift\")\n \"published\": true // Make cohort discoverable to others\n }\n // EXPLANATION: This creates a cohort of users who performed the event \"xuan-test-httpapi-event-type\"\n // at least once in the last 30 days. The interval=1 means we evaluate this on a daily basis,\n // so the system looks at each day in the past 30 days to see if the user performed the event.\n\n\n- Create a complex cohort with multiple conditions (organizations in another cohort OR new active, AND performed an event):\n {\n \"app_id\": \"365742\",\n \"name\": \"xuan-test\",\n \"definition\": {\n \"version\": 3,\n \"andClauses\": [{ // First AND condition group\n \"negated\": false,\n \"orClauses\": [{ // First OR condition: existing cohort membership\n \"type\": \"other_cohort\", // Condition type: reference to another cohort\n \"offset\": 0, // No time offset\n \"interval\": 1, // Time granularity: 1 = DAY (daily evaluation)\n \"time_type\": \"rolling\", // Rolling time window (last N days)\n \"time_value\": 365, // Time range: 365 days (1 year lookback)\n \"cohort_keys\": [\"rs4d2xg5\"], // Reference to cohort ID \"rs4d2xg5\"\n \"exclude_current_interval\": false // Include current day in evaluation\n }, { // Second OR condition: new/active users\n \"type\": \"new_active\", // Condition type: new or active user status\n \"offset\": 0, // No time offset\n \"interval\": 1, // Time granularity: 1 = DAY (daily buckets)\n \"time_type\": \"absolute\", // Absolute time range (specific dates)\n \"time_value\": [1760572800, 1761955199], // Unix timestamps: specific date range\n \"type_value\": \"new\", // Filter for \"new\" users (vs \"active\")\n \"exclude_current_interval\": false // Include current day\n }]\n }, { // Second AND condition group\n \"negated\": false,\n \"orClauses\": [{ // Event-based condition\n \"type\": \"event\", // Condition type: event-based\n \"metric\": null, // No specific metric aggregation\n \"offset\": 0, // No time offset\n \"group_by\": [], // No event property grouping\n \"interval\": 1, // Time granularity: 1 = DAY (daily buckets)\n \"operator\": \">=\", // Event count operator: greater than or equal\n \"time_type\": \"rolling\", // Rolling time window (last N days)\n \"time_value\": 30, // Time range: 30 days\n \"type_value\": \"test event\", // Event name to match\n \"operator_value\": 1, // Minimum event count: >= 1 occurrence\n \"exclude_current_interval\": false // Include current day\n }]\n }],\n \"cohortType\": \"UNIQUES\", // Count unique organizations (not occurrences)\n \"countGroup\": {\"name\": \"org id\", \"is_computed\": false}, // Group by Organization entities\n \"referenceFrameTimeParams\": {} // No additional time frame parameters\n },\n \"type\": \"redshift\", // Cohort computation engine type (optional - defaults to \"redshift\")\n \"published\": true // Make cohort discoverable to others\n }\n // EXPLANATION: This creates a complex cohort using boolean logic:\n // (Organizations in cohort \"rs4d2xg5\" in the last 365 days OR new users in the specified date range)\n // AND (Organizations that performed \"test event\" >= 1 time in the last 30 days)\n //\n // The interval=1 in all conditions means daily granularity:\n // - Cohort membership is checked daily over 365 days\n // - New user status is evaluated daily within the absolute date range\n // - Event occurrences are counted daily over the last 30 days\n //\n // Note: This cohort counts organizations (org id) rather than individual users.",
"inputSchema": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "The application/project ID where the cohort should be created (required)"
},
"name": {
"type": "string",
"minLength": 1,
"description": "Name of the cohort (required)"
},
"definition": {
"type": "object",
"properties": {
"orClauses": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"orClauses": {
"type": "array",
"items": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"offset": {
"type": "number",
"description": "Time offset from base time range"
},
"interval": {
"type": "number",
"description": "Time granularity: 1 = DAY"
},
"time_type": {
"type": "string",
"enum": [
"rolling",
"absolute",
"since"
],
"description": "Time window type"
},
"time_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "number"
}
}
],
"description": "Time range: number for rolling (days), [start, end] unix timestamps for absolute"
},
"exclude_current_interval": {
"type": "boolean",
"description": "Whether to exclude current interval"
},
"type": {
"type": "string",
"const": "event"
},
"type_value": {
"type": "string",
"description": "Event name to match"
},
"operator": {
"type": "string",
"enum": [
">=",
"<=",
">",
"<",
"==",
"!="
],
"description": "Comparison operator for event count"
},
"operator_value": {
"type": "number",
"description": "Event count threshold"
},
"metric": {
"description": "Metric aggregation (null for count)"
},
"group_by": {
"type": "array",
"items": {},
"description": "Group by event properties"
}
},
"required": [
"type",
"type_value",
"operator",
"operator_value"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"offset": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/offset"
},
"interval": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/interval"
},
"time_type": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/time_type"
},
"time_value": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/time_value"
},
"exclude_current_interval": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/exclude_current_interval"
},
"type": {
"type": "string",
"const": "other_cohort"
},
"cohort_keys": {
"type": "array",
"items": {
"type": "string"
},
"description": "Referenced cohort IDs"
}
},
"required": [
"type",
"cohort_keys"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"offset": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/offset"
},
"interval": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/interval"
},
"time_type": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/time_type"
},
"time_value": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/time_value"
},
"exclude_current_interval": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/exclude_current_interval"
},
"type": {
"type": "string",
"const": "new_active"
},
"type_value": {
"type": "string",
"enum": [
"new",
"active"
],
"description": "Filter for new or active users"
}
},
"required": [
"type",
"type_value"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"offset": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/offset"
},
"interval": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/interval"
},
"time_type": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/time_type"
},
"time_value": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/time_value"
},
"exclude_current_interval": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/exclude_current_interval"
},
"type": {
"type": "string",
"const": "user_property"
},
"type_value": {
"type": "string",
"description": "User property name"
},
"operator": {
"type": "string",
"description": "Comparison operator (e.g. \"equals\", \"contains\")"
},
"operator_value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {}
}
],
"description": "Value to compare against"
}
},
"required": [
"type",
"type_value",
"operator"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"offset": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/offset"
},
"interval": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/interval"
},
"time_type": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/time_type"
},
"time_value": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/time_value"
},
"exclude_current_interval": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/exclude_current_interval"
},
"type": {
"type": "string",
"const": "nova_property"
},
"type_value": {
"type": "string",
"description": "Computed property name"
}
},
"required": [
"type",
"type_value"
],
"additionalProperties": true
}
]
},
{
"type": "object",
"properties": {
"offset": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/offset"
},
"interval": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/interval"
},
"time_type": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/time_type"
},
"time_value": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/time_value"
},
"exclude_current_interval": {
"$ref": "#/properties/definition/properties/orClauses/items/items/properties/orClauses/items/anyOf/0/anyOf/0/properties/exclude_current_interval"
},
"type": {
"type": "string",
"description": "Condition type"
}
},
"required": [
"type"
],
"additionalProperties": true
}
]
},
"description": "Array of conditions in OR relationship"
},
"negated": {
"type": "boolean",
"description": "Whether this condition set is negated"
},
"viewDefinition": {
"type": "object",
"properties": {
"isHidden": {
"type": "boolean"
},
"linkedConditionIdentifier": {
"type": "number"
},
"isNotPerformEvent": {
"type": "boolean"
}
},
"additionalProperties": false,
"description": "UI-specific view definition properties"
}
},
"required": [
"orClauses",
"negated"
],
"additionalProperties": false
}
},
"description": "Array of OR clause groups"
},
"andClauses": {
"type": "array",
"items": {
"$ref": "#/properties/definition/properties/orClauses/items/items"
},
"description": "Array of AND conditions"
},
"countGroup": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the count group (e.g., \"User\", \"Event\")"
},
"is_computed": {
"type": "boolean",
"description": "Whether this is a computed count group"
}
},
"required": [
"name",
"is_computed"
],
"additionalProperties": true,
"description": "What this cohort counts (users, events, etc.)"
},
"version": {
"type": "number",
"description": "Definition version number"
},
"reverseOrAnd": {
"type": "boolean",
"description": "Whether to reverse OR/AND logic"
},
"querySource": {
"type": "string",
"description": "Source of the query"
},
"isDACRestricted": {
"type": "boolean",
"description": "Whether cohort is DAC restricted"
}
},
"required": [
"andClauses",
"countGroup",
"version"
],
"additionalProperties": false,
"description": "Cohort definition object containing conditions and configuration (required)"
},
"type": {
"type": "string",
"enum": [
"redshift",
"clause_based_fine_grained_time",
"cluster",
"funnels",
"sessions"
],
"description": "Type of cohort computation engine (optional, defaults to \"redshift\" for standard dynamic cohorts). Only specify other types (\"cluster\", \"funnels\", \"sessions\", \"clause_based_fine_grained_time\") for specialized cohort types.",
"default": "redshift"
},
"is_predictive_cohort": {
"type": "boolean",
"default": false,
"description": "Whether this is a predictive cohort (optional, defaults to false)"
},
"owner": {
"type": "string",
"description": "Owner of the cohort (optional, defaults to current user)"
}
},
"required": [
"app_id",
"name",
"definition"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Create Cohort",
"destructiveHint": false,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"cohort",
"default"
],
"amplitude/accessLevels": [
"create"
]
}
},
{
"name": "get_context",
"title": "Getting project context",
"description": "Get information about the current user, organization, and list of accessible projects.\n\nWHEN TO USE:\n- \"What projects do I have access to?\"\n- \"Show me my organization details\"\n- \"What is my user role?\"\n\nRETURNS:\n- User details (email, name, role)\n- Organization info (name, plan, quota)\n- List of accessible projects (just names and IDs)\n\nDO NOT USE FOR:\n- Project-specific settings (timezone, currency, sessions) → use 'get_project_context' instead\n- Running analytics queries → use 'query_dataset' or 'query_amplitude_data' instead\n- Finding charts/dashboards/cohorts → use 'search' instead",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {}
},
"annotations": {
"title": "Getting project context",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"context",
"developer",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_project_context",
"title": "Getting comprehensive project context",
"description": "Get project-specific settings and configuration for a specific project.\n\nWHEN TO USE:\n- \"What timezone is this project using?\"\n- \"What are the currency settings?\"\n- \"How are sessions defined?\"\n- \"What is the week start day?\"\n\nRETURNS:\n- Timezone and date settings (timezone, week start, quarter start)\n- Currency settings (locale, target currency)\n- Session definition (timeout, custom property)\n- Source projects (data lineage)\n- Project AI context (business guidelines)\n\nREQUIRES: projectId parameter\n\nDO NOT USE FOR:\n- Listing all projects → use 'get_context' instead\n- User/org info → use 'get_context' instead",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "number",
"exclusiveMinimum": 0,
"description": "The project/app ID to get context for"
}
},
"required": [
"projectId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Getting comprehensive project context",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"context",
"project",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_dashboard",
"title": "Getting dashboard data",
"description": "Get specific dashboards and all their charts\n\nWHEN TO USE:\n- You want to retrieve full dashboard definitions including chart IDs that you can query and analyze individually.\n\nINSTRUCTIONS:\n- Use the search tool to find the IDs of dashboards you want to retrieve, then call this tool with the IDs.\n- Very commonly you will want to query the charts after retrieving a dashboard.",
"inputSchema": {
"type": "object",
"properties": {
"dashboardIds": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 3,
"description": "Array of dashboard IDs to retrieve (required)"
}
},
"required": [
"dashboardIds"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Getting dashboard data",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"dashboard",
"analytics",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "create_dashboard",
"title": "Creating dashboard",
"description": "Create a comprehensive dashboard with charts, rich text, and custom layout\n\nWHEN TO USE:\n- After the user has searched existing content or explored some analysis in Amplitude\n- The user has explicitly requested to create a dashboard\n\nCRITICAL - CHART IDs MUST BE FROM SAVED CHARTS:\n- Only use chartIds from SAVED/PERMANENT charts - these are returned by save_chart_edits (in the chartId field) or create_chart\n- DO NOT use editIds from query_dataset - these are temporary IDs that cannot be added to dashboards\n- DO NOT use the editId from query_dataset responses - you must first call save_chart_edits to get a permanent chartId\n- The typical workflow is: query_dataset (returns editId) → save_chart_edits (converts editId to permanent chartId) → create_dashboard (uses chartId)\n- If you use an editId instead of a saved chartId, the dashboard creation will fail with \"NotFoundError: No chart\"\n\nINSTRUCTIONS:\n- Provide a descriptive name for the dashboard\n- Use rows array where each row contains items in left-to-right order\n- Each item specifies width (3-12 columns). If width is omitted, items auto-fill remaining space\n- Each row must specify height in pixels. Only heights of 375, 500, 625, 750 are allowed\n- Total width of items in a row must not exceed 12 columns\n- Max 4 items per row (ensures minimum 3-column width per item)\n- Use chartMetas to configure chart display options (view type, annotations, etc.)\n- Return a link to the new dashboard in the response\n- 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\n- DO group similar charts together and include a header and some text describing how to interpret the charts effectively\n\nMARKDOWN FORMAT:\n- Rich text content uses standard markdown syntax\n- Supported: headers (# ## ###), bold (**text**), italic (*text*), lists (- or 1.), links ([text](url)), code blocks (```), inline code (`code`)\n- Example: \"# Overview\\n\\nThis dashboard shows **key metrics** for user engagement.\"\n\nLAYOUT EXAMPLES:\n- Full-width item: { height: 6, items: [{ type: 'chart', chartId: '123', width: 12 }] }\n- Two side-by-side: { height: 4, items: [{ type: 'chart', chartId: '1', width: 6 }, { type: 'rich_text', content: '# Notes', width: 6 }] }\n- Three columns: { height: 5, items: [{ width: 4 }, { width: 4 }, { width: 4 }] }\n- Auto-fill: { height: 4, items: [{ type: 'chart', chartId: '1' }, { type: 'chart', chartId: '2' }] } (each gets 6 columns)",
"inputSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Descriptive name for the dashboard (e.g., \"User Engagement Overview\", \"Revenue Analytics\")"
},
"description": {
"type": "string",
"description": "Optional description for the dashboard to provide context and details about its purpose"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"height": {
"type": "integer",
"description": "Row height in pixels. Must be one of: 375, 500, 625, or 750"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"number"
],
"description": "Item ID (returned from get operations, useful for future updates)"
},
"type": {
"type": "string",
"enum": [
"chart",
"rich_text",
"session_replay",
"video",
"image",
"cohort"
],
"description": "Content type"
},
"width": {
"type": "number",
"minimum": 3,
"maximum": 12,
"description": "Width in columns (3-12). If omitted, item auto-fills remaining space equally with other auto-width items."
},
"content": {
"type": "string",
"description": "Rich text content as markdown (for rich_text type)"
},
"chartId": {
"type": "string",
"description": "Saved chart ID (required when type is \"chart\"). IMPORTANT: Must be a permanent chartId from save_chart_edits or create_chart, NOT an editId from query_dataset. Using an editId will cause \"NotFoundError: No chart\"."
},
"sessionReplayIdentifier": {
"type": "string",
"description": "Session replay identifier (for session_replay type)"
},
"note": {
"type": "string",
"description": "Optional note (for session_replay type)"
},
"videoUrl": {
"type": "string",
"description": "Video URL (for video type)"
},
"imageS3Key": {
"type": "string",
"description": "S3 key for image (for image type)"
},
"title": {
"type": "string",
"description": "Title (for video/image types)"
},
"cohortId": {
"type": "string",
"description": "Cohort ID (for cohort type)"
},
"hideChart": {
"type": "boolean",
"description": "Whether to hide visualization (defaults to false)"
}
},
"required": [
"type"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 4,
"description": "Items in this row (left-to-right order, max 4 items)"
}
},
"required": [
"height",
"items"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Array of rows, each containing items in left-to-right order with height specification"
},
"chartMetas": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": [
"series",
"table",
"headline",
"converted",
"dropoff",
"sequences",
"metric_only",
"metrics_with_previous_data",
"table_metrics",
"target_metrics"
],
"description": "Chart display view: \"series\" for line/bar charts, \"table\" for data tables, \"headline\" for key metrics, \"converted\" for conversion funnels"
},
"annotation": {
"type": "string",
"description": "Optional annotation text to display on the chart"
},
"selectedSerieIndex": {
"type": "number",
"description": "Index of the selected data series (0-based) for multi-series charts"
}
},
"additionalProperties": false
},
"description": "Display configuration for charts. Key is chartId, value contains view type, annotations, and other display options."
}
},
"required": [
"name",
"rows"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Creating dashboard",
"destructiveHint": false,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"dashboard",
"default"
],
"amplitude/accessLevels": [
"create"
]
}
},
{
"name": "edit_dashboard",
"title": "Editing dashboard",
"description": "Edit a dashboard's metadata and layout with optimistic concurrency protection.\n\nWHEN TO USE:\n- You already have a dashboard ID and want to update its name/description and/or content rows.\n\nINSTRUCTIONS:\n- Always call get_dashboard first to retrieve the dashboard's current lastModified and rows.\n- Pass the retrieved lastModified in expectedLastModified.\n- Metadata fields are only updated when values are not null/undefined.\n- Use one structural edit at a time via edit.\n\nEXAMPLES:\n- Metadata only:\n {\"dashboardId\":\"123\",\"expectedLastModified\":1700000000,\"metadata\":{\"name\":\"Q1 Dashboard\"}}\n- Replace all rows:\n {\"dashboardId\":\"123\",\"expectedLastModified\":1700000000,\"edit\":{\"type\":\"set_rows\",\"rows\":[{\"height\":500,\"items\":[{\"type\":\"chart\",\"chartId\":\"abc\",\"width\":12}]}]}}\n- Update a row:\n {\"dashboardId\":\"123\",\"expectedLastModified\":1700000000,\"edit\":{\"type\":\"update_row\",\"rowIndex\":0,\"row\":{\"height\":500,\"items\":[{\"type\":\"rich_text\",\"content\":\"# Notes\",\"width\":12}]}}}\n- Insert a row:\n {\"dashboardId\":\"123\",\"expectedLastModified\":1700000000,\"edit\":{\"type\":\"insert_row\",\"index\":1,\"row\":{\"height\":375,\"items\":[{\"type\":\"chart\",\"chartId\":\"def\",\"width\":12}]}}}\n- Remove a row:\n {\"dashboardId\":\"123\",\"expectedLastModified\":1700000000,\"edit\":{\"type\":\"remove_row\",\"rowIndex\":2}}\n\nNOTES:\n- The request fails with a conflict if expectedLastModified is stale.\n- Response is intentionally compact to minimize context usage.",
"inputSchema": {
"type": "object",
"properties": {
"dashboardId": {
"type": "string",
"minLength": 1,
"description": "Dashboard ID to edit (required)."
},
"expectedLastModified": {
"type": "integer",
"description": "Required optimistic concurrency value. Request fails on mismatch."
},
"metadata": {
"type": "object",
"properties": {
"name": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 255
},
{
"type": "null"
}
],
"description": "Optional dashboard name update. Applied only when not null/undefined."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
],
"description": "Optional dashboard description update. Applied only when not null/undefined."
}
},
"additionalProperties": false,
"description": "Optional metadata updates. Fields are applied only when not null/undefined."
},
"edit": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "set_rows"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"height": {
"type": "integer",
"description": "Row height in pixels. Must be one of: 375, 500, 625, or 750"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"number"
],
"description": "Item ID (returned from get operations, useful for future updates)"
},
"type": {
"type": "string",
"enum": [
"chart",
"rich_text",
"session_replay",
"video",
"image",
"cohort"
],
"description": "Content type"
},
"width": {
"type": "number",
"minimum": 3,
"maximum": 12,
"description": "Width in columns (3-12). If omitted, item auto-fills remaining space equally with other auto-width items."
},
"content": {
"type": "string",
"description": "Rich text content as markdown (for rich_text type)"
},
"chartId": {
"type": "string",
"description": "Saved chart ID (required when type is \"chart\"). IMPORTANT: Must be a permanent chartId from save_chart_edits or create_chart, NOT an editId from query_dataset. Using an editId will cause \"NotFoundError: No chart\"."
},
"sessionReplayIdentifier": {
"type": "string",
"description": "Session replay identifier (for session_replay type)"
},
"note": {
"type": "string",
"description": "Optional note (for session_replay type)"
},
"videoUrl": {
"type": "string",
"description": "Video URL (for video type)"
},
"imageS3Key": {
"type": "string",
"description": "S3 key for image (for image type)"
},
"title": {
"type": "string",
"description": "Title (for video/image types)"
},
"cohortId": {
"type": "string",
"description": "Cohort ID (for cohort type)"
},
"hideChart": {
"type": "boolean",
"description": "Whether to hide visualization (defaults to false)"
}
},
"required": [
"type"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 4,
"description": "Items in this row (left-to-right order, max 4 items)"
}
},
"required": [
"height",
"items"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Replace all dashboard rows with this full rows array."
}
},
"required": [
"type",
"rows"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "update_row"
},
"rowIndex": {
"type": "integer",
"minimum": 0,
"description": "Zero-based index of row to replace."
},
"row": {
"$ref": "#/properties/edit/anyOf/0/properties/rows/items",
"description": "Full replacement row (height + items)."
}
},
"required": [
"type",
"rowIndex",
"row"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "insert_row"
},
"index": {
"type": "integer",
"minimum": 0,
"description": "Zero-based insertion index. May equal current row count to append."
},
"row": {
"$ref": "#/properties/edit/anyOf/0/properties/rows/items",
"description": "Row to insert."
}
},
"required": [
"type",
"index",
"row"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "remove_row"
},
"rowIndex": {
"type": "integer",
"minimum": 0,
"description": "Zero-based index of row to remove."
}
},
"required": [
"type",
"rowIndex"
],
"additionalProperties": false
}
],
"description": "Optional single structural layout edit."
}
},
"required": [
"dashboardId",
"expectedLastModified"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Editing dashboard",
"destructiveHint": true,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"dashboard",
"default"
],
"amplitude/accessLevels": [
"update"
]
}
},
{
"name": "create_experiment",
"title": "Creating experiment",
"description": "Create a new experiment across one or more projects.\n\nINSTRUCTIONS:\n- If the user has not specified projects, prompt them to decide which projects to use\n- Creates a feature A/B test with control and treatment variants\n- Creates the same experiment in each specified project\n- Returns the experiment IDs and URLs for viewing in Amplitude\n\nEXAMPLES:\n- Basic A/B test: Provide projectIds, key, and name\n- Multiple projects: Provide array of projectIds to create experiment in each\n- With custom variants: Provide projectIds, key, name, and variants array\n- With links: Provide links array with url and title for each link (e.g., PRs, tickets, docs)\n- With deployments: Provide deploymentIds array to associate specific deployments (API keys)\n\nNOTES:\n- Experiment keys must be unique within each project\n- Variants default to 'control' and 'treatment' if not specified\n- Use get_deployments to retrieve available deployment IDs",
"inputSchema": {
"type": "object",
"properties": {
"projectIds": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 5,
"description": "Array of project IDs where the experiment will be created. If the user has not specified projects, prompt the user to decide. Do not decide for them."
},
"key": {
"type": "string",
"minLength": 1,
"pattern": "^[a-z0-9-_]+$",
"description": "Unique experiment key (e.g., \"homepage-redesign\"). Must be unique within each project."
},
"name": {
"type": "string",
"description": "Human-readable experiment name"
},
"description": {
"type": "string",
"description": "Experiment description explaining what is being tested"
},
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"pattern": "^[a-zA-Z0-9-_]+$",
"description": "Variant key (e.g., \"control\", \"treatment\"). Must contain only letters, numbers, hyphens, and underscores. Cannot be \"off\"."
},
"name": {
"type": "string",
"description": "Human-readable variant name"
},
"payload": {
"description": "Variant payload (JSON)"
},
"description": {
"type": "string",
"description": "Variant description"
}
},
"required": [
"key"
],
"additionalProperties": false
},
"description": "Experiment variants. Defaults to control and treatment variants if not specified."
},
"evaluationMode": {
"type": "string",
"enum": [
"local",
"remote"
],
"default": "remote",
"description": "Defaults to \"remote\". Set to \"local\" if specified by the user"
},
"bucketingKey": {
"type": "string",
"description": "The user property used to bucket users into variants. Defaults to \"amplitude_id\" if not specified. Common values: \"amplitude_id\", \"user_id\", \"device_id\"."
},
"projectMetrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"metricId": {
"type": "string",
"description": "Metric ID"
},
"analysisParams": {
"type": "object",
"properties": {
"metricGoalType": {
"type": "string",
"enum": [
"success",
"guardrail"
],
"default": "success",
"description": "Goal type of metric. \"success\" metrics measure experiment success. \"guardrail\" metrics ensure the experiment does not harm other important metrics."
},
"testDirection": {
"type": "string",
"enum": [
"larger",
"smaller"
],
"default": "larger",
"description": "Direction of expected change. \"larger\" means you expect the metric to increase; \"smaller\" means you expect it to decrease."
},
"minDetectableEffect": {
"type": "number",
"default": 0.02,
"description": "Minimum detectable effect as a percentage (MDE). Used for statistical power calculations."
},
"maxWinsorization": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Maximum winsorization percentage for outlier capping."
},
"isLogTransformed": {
"type": "boolean",
"description": "Whether log transformation is applied to the metric."
},
"useExposures": {
"type": "boolean",
"description": "Whether to normalize the metric by exposures. Defaults to true. Set to false to normalize by step 1 exposures instead."
}
},
"additionalProperties": false,
"default": {},
"description": "Analysis parameters for this metric. Defines how the metric should be analyzed in the experiment."
},
"metricIndex": {
"type": "integer",
"minimum": 0,
"description": "Order index for the metric. Index 0 should be the primary metric if recommendation is true."
},
"recommendation": {
"type": "boolean",
"default": false,
"description": "Whether this is a recommendation metric. The recommendation metric is the metric that is used to determine the winner of the experiment. Only one metric can be a recommendation metric."
}
},
"required": [
"metricId",
"metricIndex"
],
"additionalProperties": false
},
"description": "Metrics to attach to the experiment for analysis"
},
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Link URL"
},
"title": {
"type": "string",
"description": "Link title (e.g., \"Design Doc\", \"JIRA Ticket\")"
}
},
"required": [
"url",
"title"
],
"additionalProperties": false
},
"description": "Links to associate with the experiment (e.g., design docs, tickets, PRs). Each link requires a url and title."
},
"deploymentIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "IDs of deployments (API keys) to associate with the experiment. Use get_deployments to retrieve available deployment IDs. Can only be used when creating experiments in a single project."
}
},
"required": [
"projectIds",
"key",
"name"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Creating experiment",
"destructiveHint": false,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"experiment",
"default"
],
"amplitude/accessLevels": [
"create"
]
}
},
{
"name": "get_deployments",
"title": "Getting deployments",
"description": "Retrieve all deployments for the current project. Deployments are api keys for flags and experiments.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {}
},
"annotations": {
"title": "Getting deployments",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"experiment",
"deployments",
"developer",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_experiments",
"title": "Getting experiments",
"description": "Retrieve specific experiments by their IDs.\n\nWHEN TO USE:\n- You want to retrieve addition information for experiments like state, decisions, etc.\n\nINSTRUCTIONS:\n- Use the search tool to find the IDs of experiments you want to retrieve, then call this tool with the IDs.",
"inputSchema": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Array of IDs to retrieve experiments by."
}
},
"required": [
"ids"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Getting experiments",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"experiments",
"analytics",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_flags",
"title": "Getting feature flags",
"description": "Retrieve specific feature flags by their IDs.\n\nWHEN TO USE:\n- You want to retrieve full flag definitions including variants, metadata, and configuration details.\n\nINSTRUCTIONS:\n- Use the search tool to find the IDs of flags you want to retrieve, then call this tool with the IDs.",
"inputSchema": {
"type": "object",
"properties": {
"flagIds": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Array of flag IDs to retrieve"
}
},
"required": [
"flagIds"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Getting feature flags",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"experiment",
"flags",
"developer",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "create_flags",
"title": "Creating flags",
"description": "Create multiple feature flags in batch.\n\nINSTRUCTIONS:\n- Use get_context to get available project IDs\n- Always prompt the user if they haven't specified a project\n- Use get_deployments to find deployment IDs to associate with the flag\n\nEXAMPLES:\n- {\"flags\": [{\"projectId\": \"123456\", \"key\": \"new-feature\", \"name\": \"New Feature\"}]}\n\nNOTES:\n- Flag keys must be unique within each project\n- Flags are disabled by default\n- If a flag is enabled, it does not mean that all users will see the flag.",
"inputSchema": {
"type": "object",
"properties": {
"flags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project ID where the flag will be created"
},
"key": {
"type": "string",
"description": "Unique flag key"
},
"name": {
"type": "string",
"description": "Flag name"
},
"description": {
"type": "string",
"description": "Flag description"
},
"enabled": {
"type": "boolean",
"default": false,
"description": "Initial enabled state"
},
"evaluationMode": {
"type": "string",
"enum": [
"local",
"remote"
],
"description": "Defaults to \"remote\". Set to \"local\" if specified by the user."
},
"bucketingKey": {
"type": "string",
"description": "The user property used to bucket users into variants. Defaults to \"amplitude_id\" if not specified. Common values: \"amplitude_id\", \"user_id\", \"device_id\"."
},
"deploymentIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Deployment IDs to associate with the flag"
},
"percentage": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Default rollout percentage for \"All Other Users\" (0-100). Set to 100 to enable for everyone."
},
"rolloutWeights": {
"type": "object",
"additionalProperties": {
"type": "number"
},
"description": "Default variant weight distribution for \"All Other Users\" (e.g., {\"on\": 1} for 100% to \"on\" variant)."
},
"testers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"variantKey": {
"type": "string",
"description": "Variant key to add testers to"
},
"userOrDeviceIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of user or device IDs to add as testers"
}
},
"required": [
"variantKey",
"userOrDeviceIds"
],
"additionalProperties": false
},
"description": "Testers to add to specific variants"
},
"targetSegments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Segment name"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"prop": {
"type": "string",
"description": "Property name to target (e.g., \"user_id\", \"country\")"
},
"prop_type": {
"type": "string",
"description": "Property type (e.g., \"user\")"
},
"op": {
"type": "string",
"description": "Operator (e.g., \"contains\", \"is\", \"is not\", \"glob match\")"
},
"type": {
"type": "string",
"description": "Condition type (e.g., \"property\", \"cohort\")"
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values to match against"
}
},
"required": [
"op",
"type",
"values"
],
"additionalProperties": false
}
},
"percentage": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Rollout percentage for this segment (0-100)"
},
"bucketingKey": {
"type": "string",
"description": "Bucketing key override for this segment"
},
"rolloutWeights": {
"type": "object",
"additionalProperties": {
"type": "number"
},
"description": "Variant weight distribution (e.g., {\"on\": 1} for 100% to \"on\")"
}
},
"required": [
"conditions"
],
"additionalProperties": false
},
"description": "Target segments for conditional rollout. Each segment has conditions and a rollout percentage/weights."
}
},
"required": [
"key",
"name"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 10,
"description": "Array of flags to create"
}
},
"required": [
"flags"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Creating flags",
"destructiveHint": false,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"experiment",
"flags",
"developer",
"create",
"default"
],
"amplitude/accessLevels": [
"create"
]
}
},
{
"name": "update_flag",
"title": "Updating flag",
"description": "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.\n\nINSTRUCTIONS:\n- Use the search tool with entityTypes: ['FLAG'] or entityTypes: ['EXPERIMENT'] to find IDs first\n- Use get_deployments to find deployment IDs if modifying deployments\n- Only include sections you want to update (flagConfig, variants, testers, deployments)\n- To update experiment-specific settings (metrics), use update_experiment instead\n\nEXAMPLES:\n- Update name: {\"flagId\": \"abc123\", \"flagConfig\": {\"name\": \"New Name\"}}\n- Enable flag/experiment: {\"flagId\": \"abc123\", \"flagConfig\": {\"enabled\": true}}\n- Add variant: {\"flagId\": \"abc123\", \"variants\": {\"create\": [{\"variantKey\": \"variant-c\"}]}}\n- Add tester: {\"flagId\": \"abc123\", \"testers\": {\"add\": [{\"variantKey\": \"control\", \"userOrDeviceIds\": [\"user123\"]}]}}\n- Add link: {\"flagId\": \"abc123\", \"links\": {\"add\": [{\"url\": \"https://jira.example.com/PROJ-123\", \"title\": \"JIRA Ticket\"}]}}\n\nNOTES:\n- At least one variant must remain after deletions\n- For testers to receive a variant the flag must be enabled\n- All experiments are also flags and have an associated flag ID — use this tool for metadata, variants, testers, and deployments on experiments",
"inputSchema": {
"type": "object",
"properties": {
"flagId": {
"type": "string",
"description": "ID of the flag or experiment to update"
},
"flagConfig": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Flag name"
},
"description": {
"type": "string",
"description": "Flag description"
},
"enabled": {
"type": "boolean",
"description": "Flag enabled state"
}
},
"additionalProperties": false,
"description": "Flag configuration updates"
},
"variants": {
"type": "object",
"properties": {
"create": {
"type": "array",
"items": {
"type": "object",
"properties": {
"variantKey": {
"type": "string",
"description": "Unique key for the new variant"
},
"variantName": {
"type": "string",
"description": "Name for the new variant"
},
"variantDescription": {
"type": "string",
"description": "Description for the new variant"
},
"variantPayload": {
"description": "Payload for the new variant"
}
},
"required": [
"variantKey"
],
"additionalProperties": false
},
"description": "Variants to create"
},
"update": {
"type": "array",
"items": {
"type": "object",
"properties": {
"variantKey": {
"type": "string",
"description": "Key of the variant to update"
},
"variantName": {
"type": "string",
"description": "New name for the variant"
},
"variantDescription": {
"type": "string",
"description": "New description for the variant"
},
"variantPayload": {
"description": "New payload for the variant"
}
},
"required": [
"variantKey"
],
"additionalProperties": false
},
"description": "Variants to update"
},
"delete": {
"type": "array",
"items": {
"type": "string"
},
"description": "Variant keys to delete"
}
},
"additionalProperties": false,
"description": "Variant operations"
},
"testers": {
"type": "object",
"properties": {
"add": {
"type": "array",
"items": {
"type": "object",
"properties": {
"variantKey": {
"type": "string",
"description": "Variant key to add testers to"
},
"userOrDeviceIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of user or device IDs to add as testers"
}
},
"required": [
"variantKey",
"userOrDeviceIds"
],
"additionalProperties": false
},
"description": "Testers to add"
},
"remove": {
"type": "array",
"items": {
"type": "object",
"properties": {
"variantKey": {
"type": "string",
"description": "Variant key to remove testers from"
},
"userOrDeviceIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of user or device IDs to remove as testers"
}
},
"required": [
"variantKey",
"userOrDeviceIds"
],
"additionalProperties": false
},
"description": "Testers to remove"
}
},
"additionalProperties": false,
"description": "Tester operations"
},
"deployments": {
"type": "object",
"properties": {
"add": {
"type": "array",
"items": {
"type": "string"
},
"description": "Deployment IDs to add to the flag"
},
"remove": {
"type": "array",
"items": {
"type": "string"
},
"description": "Deployment IDs to remove from the flag"
}
},
"additionalProperties": false,
"description": "Deployment operations"
},
"links": {
"type": "object",
"properties": {
"add": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Link URL"
},
"title": {
"type": "string",
"description": "Link title (e.g., \"Design Doc\", \"JIRA Ticket\", \"Pull Request\")"
}
},
"required": [
"url",
"title"
],
"additionalProperties": false
},
"description": "Links to add"
}
},
"additionalProperties": false,
"description": "Link operations"
}
},
"required": [
"flagId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Updating flag",
"destructiveHint": true,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"experiment",
"flags",
"developer",
"default"
],
"amplitude/accessLevels": [
"update"
]
}
},
{
"name": "update_experiment",
"title": "Updating experiment metrics",
"description": "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.\n\nINSTRUCTIONS:\n- Use the search tool with entityTypes: ['EXPERIMENT'] to find experiment IDs first\n- Use create_metric to create metrics before attaching them here\n- Metrics are replaced entirely — include all metrics you want on the experiment\n- Only one metric can have recommendation=true (the primary metric)\n\nEXAMPLES:\n- 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}}]}\n- Replace all metrics: {\"experimentId\": \"abc123\", \"metrics\": [{\"metricId\": \"met3\", \"metricIndex\": 0, \"recommendation\": true, \"analysisParams\": {\"metricGoalType\": \"success\", \"testDirection\": \"larger\", \"minDetectableEffect\": 0.02}}]}\n- Clear all metrics: {\"experimentId\": \"abc123\", \"metrics\": []}\n\nNOTES:\n- This tool only works on experiments (not feature flags).\n- Use get_experiments to see current metrics before updating.",
"inputSchema": {
"type": "object",
"properties": {
"experimentId": {
"type": "string",
"description": "ID of the experiment to update"
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"metricId": {
"type": "string",
"description": "Metric ID"
},
"analysisParams": {
"type": "object",
"properties": {
"metricGoalType": {
"type": "string",
"enum": [
"success",
"guardrail"
],
"default": "success",
"description": "Goal type of metric. \"success\" metrics measure experiment success. \"guardrail\" metrics ensure the experiment does not harm other important metrics."
},
"testDirection": {
"type": "string",
"enum": [
"larger",
"smaller"
],
"default": "larger",
"description": "Direction of expected change. \"larger\" means you expect the metric to increase; \"smaller\" means you expect it to decrease."
},
"minDetectableEffect": {
"type": "number",
"default": 0.02,
"description": "Minimum detectable effect as a percentage (MDE). Used for statistical power calculations."
},
"maxWinsorization": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Maximum winsorization percentage for outlier capping."
},
"isLogTransformed": {
"type": "boolean",
"description": "Whether log transformation is applied to the metric."
},
"useExposures": {
"type": "boolean",
"description": "Whether to normalize the metric by exposures. Defaults to true. Set to false to normalize by step 1 exposures instead."
}
},
"additionalProperties": false,
"default": {},
"description": "Analysis parameters for this metric. Defines how the metric should be analyzed in the experiment."
},
"metricIndex": {
"type": "integer",
"minimum": 0,
"description": "Order index for the metric. Index 0 should be the primary metric if recommendation is true."
},
"recommendation": {
"type": "boolean",
"default": false,
"description": "Whether this is a recommendation metric. The recommendation metric is the metric that is used to determine the winner of the experiment. Only one metric can be a recommendation metric."
}
},
"required": [
"metricId",
"metricIndex"
],
"additionalProperties": false
},
"description": "Metrics to set on the experiment. Replaces all existing metrics. Use create_metric first to create metrics, then attach them here. The metric with recommendation=true is the primary metric used to determine the experiment winner."
}
},
"required": [
"experimentId",
"metrics"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Updating experiment metrics",
"destructiveHint": true,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"experiment",
"default"
],
"amplitude/accessLevels": [
"update"
]
}
},
{
"name": "create_metric",
"title": "Creating metric",
"description": "Create a new metric in a project.\n\nWHEN TO USE:\n- You need to create a metric for use in experiments or dashboards.\n- You want to define a reusable KPI like \"Daily Active Users\" or \"Error Rate\".\n- The user wants a success or guardrail metric for an A/B test.\n\nINSTRUCTIONS:\n- Provide the projectId and a descriptive name.\n- 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).\n- For UNIQUES or TOTALS: provide a single event with optional filters.\n- 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).\n- 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)\".\n- For PROPSUM/PROPAVG: provide a single event AND an aggregationProperty specifying which numeric property to aggregate.\n- For property min/max/count operations, use a FORMULA metric with PROPMIN(A), PROPMAX(A), PROPCOUNT(A), or PROPCOUNTAVG(A).\n- 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.\n- 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.\n- 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).\n- For CONVERSION (funnel): if funnelComputeProperty is provided, funnelComputePropFunction must also be provided.\n- For CONVERSION (funnel): if funnelConstantProperties is provided, make sure that event property or user property exists for every event in the funnel.\n- Set isExperimentMetric=true when the metric is intended for use in an experiment. This enables experiment-specific formula validation.\n- ALWAYS use the search or get_events tool first to discover valid event names before calling this tool. Do not guess event names.\n\nEXAMPLES:\n- Unique users for an event: metricType=\"UNIQUES\", event={event_type: \"Button Clicked\"}\n- Error rate formula: metricType=\"FORMULA\", events=[{event_type: \"API Call\"}, {event_type: \"API Error\"}], formula=\"TOTALS(B)/TOTALS(A)\"\n- Revenue per user formula: metricType=\"FORMULA\", events=[{event_type: \"Purchase\", group_by: [{type: \"event\", value: \"revenue\"}]}, {event_type: \"_active\"}], formula=\"PROPSUM(A)/UNIQUES(B)\"\n- Total event count: metricType=\"TOTALS\", event={event_type: \"Purchase Completed\"}\n- Sum of a property: metricType=\"PROPSUM\", event={event_type: \"Purchase Completed\"}, aggregationProperty={type: \"event\", value: \"revenue\"}\n- Average of a property: metricType=\"PROPAVG\", event={event_type: \"Page Viewed\"}, aggregationProperty={type: \"event\", value: \"load_time\"}\n- Count of a property: metricType=\"FORMULA\", events=[{event_type: \"Purchase\", group_by: [{type: \"event\", value: \"item_id\"}]}], formula=\"PROPCOUNT(A)\"\n- Retention metrics: metricType=\"RETENTION\", startEvent={event_type: \"Purchase\"}, returnEvent={event_type: \"Purchase\"}, returnOn=7, returnOnInterval=7\n- Funnel conversion (unique users): metricType=\"CONVERSION\", funnelEvents=[{event_type: \"View Item\"}, {event_type: \"Add to Cart\"}, {event_type: \"Purchase\"}], funnelMode=\"ordered\", conversionSeconds=604800, funnelPathsToCollect=\"UNIQUES\"\n- Funnel conversion (totals): same as above with funnelPathsToCollect=\"TOTALS\"\n- Funnel with holding constant: add funnelConstantProperties=[{type: \"event\", value: \"country\", group_type: \"\"}]\n- Funnel with sum of last-step property: add funnelComputeProperty={type: \"event\", value: \"revenue\", group_type: \"\"}, funnelComputePropFunction=\"SUM\"\n\nNOTES:\n- The returned metric ID can be used with create_experiment's projectMetrics parameter.\n- Metrics with duplicate names or identical definitions within the same project will be rejected.\n- FORMULA metrics are validated against the backend before creation. The validation checks formula syntax, event references, and metric compatibility.\n- PROPSUM/PROPAVG aggregation properties must be numeric.",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project ID to create the metric in"
},
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name for the metric"
},
"description": {
"type": "string",
"default": "",
"description": "Description of what this metric measures"
},
"metricType": {
"type": "string",
"enum": [
"UNIQUES",
"TOTALS",
"FORMULA",
"PROPSUM",
"PROPAVG",
"RETENTION",
"CONVERSION"
],
"description": "Type of metric. UNIQUES: unique users who performed the event. TOTALS: total event count. FORMULA: custom formula combining multiple events (supports PROPCOUNT, PROPMIN, PROPMAX, etc. as formula terms). PROPSUM: sum of a numeric property. PROPAVG: average of a numeric property. RETENTION: retention metrics. CONVERSION: funnel / multi-step conversion metrics."
},
"event": {
"type": "object",
"properties": {
"event_type": {
"type": "string",
"description": "Event name (e.g., \"Page View\", \"_active\")"
},
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"subprop_key": {
"type": "string",
"description": "Property key to filter on"
},
"subprop_op": {
"type": "string",
"enum": [
"is",
"is not",
"contains",
"does not contain",
"less",
"less or equal",
"greater",
"greater or equal",
"set is",
"set is not",
"set contains",
"set does not contain",
"glob match",
"glob does not match",
"has prefix",
"does not have prefix",
"ends with",
"version less than",
"version less than or equal to",
"version greater than",
"version greater than or equal to",
"css match"
],
"description": "Filter operator"
},
"subprop_value": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Values to match against"
},
"subprop_type": {
"type": "string",
"default": "event",
"description": "Property type: \"event\", \"user\", \"group\", etc. Defaults to \"event\"."
},
"group_type": {
"type": "string",
"default": "",
"description": "Group type for group properties. Empty string for non-group."
}
},
"required": [
"subprop_key",
"subprop_op"
],
"additionalProperties": false
},
"default": [],
"description": "Filters to apply to the event"
},
"group_by": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Property type: \"event\", \"user\", or \"group\"."
},
"value": {
"type": "string",
"description": "Property name to group by (e.g., \"revenue\", \"price\")."
},
"group_type": {
"type": "string",
"default": "",
"description": "Group type for group properties. Empty string for non-group."
}
},
"required": [
"type",
"value"
],
"additionalProperties": false
},
"description": "Properties to group by. Required for FORMULA metrics that use property aggregation functions like PROPSUM(A) or PROPAVG(A) -- the first group_by property on the event is used as the aggregation property."
}
},
"required": [
"event_type"
],
"additionalProperties": false,
"description": "Event definition for single-event metrics (UNIQUES, TOTALS, PROPSUM, etc.). Required for non-FORMULA types."
},
"aggregationProperty": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Property type: \"event\" for event properties, \"user\" for user properties, \"group\" for group properties."
},
"value": {
"type": "string",
"description": "Property name to aggregate (e.g., \"revenue\", \"duration\", \"price\")."
},
"group_type": {
"type": "string",
"default": "",
"description": "Group type for group properties. Empty string for non-group."
}
},
"required": [
"type",
"value"
],
"additionalProperties": false,
"description": "Property to aggregate for PROPSUM and PROPAVG metrics. Specifies which numeric event/user/group property to compute the aggregation on. Required for PROPSUM/PROPAVG metric types."
},
"events": {
"type": "array",
"items": {
"$ref": "#/properties/event"
},
"description": "Array of event definitions for FORMULA metrics. Each event is referenced by letter (A, B, C...) in the formula."
},
"formula": {
"type": "string",
"description": "Formula string for FORMULA metrics. Reference events by letter: A, B, C... Available functions: UNIQUES(A), TOTALS(A), PROPSUM(A), PROPAVG(A), PROPMIN(A), PROPMAX(A), PROPCOUNT(A), PROPCOUNTAVG(A), REVENUETOTAL(A). Example: \"TOTALS(B)/TOTALS(A)\""
},
"startEvent": {
"$ref": "#/properties/event",
"description": "Event definition for retention metrics. Required for RETENTION metric type."
},
"returnEvent": {
"$ref": "#/properties/event",
"description": "Event definition for retention metrics. Required for RETENTION metric type."
},
"returnOn": {
"type": "integer",
"minimum": 0,
"maximum": 30,
"description": "Number of days to return on for retention metrics (0–30). Required for RETENTION metric type."
},
"returnOnInterval": {
"type": "integer",
"minimum": 1,
"maximum": 30,
"description": "1 is for daily retention, 7 is for weekly retention, 30 is for monthly retention. Required for RETENTION metric type."
},
"funnelEvents": {
"type": "array",
"items": {
"$ref": "#/properties/event"
},
"description": "Ordered funnel steps for CONVERSION metrics (minimum 2 events). Each step is an event with optional filters. Not used for FORMULA — use \"events\" for formula metrics."
},
"funnelMode": {
"type": "string",
"enum": [
"ordered",
"unordered",
"sequential"
],
"description": "How funnel steps relate: \"ordered\" (this order), \"unordered\" (any order), \"sequential\" (exact order). Required for CONVERSION."
},
"conversionSeconds": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Maximum time window to complete the funnel, in seconds (e.g. 86400 = 1 day, 604800 = 7 days). Required for CONVERSION."
},
"funnelPathsToCollect": {
"type": "string",
"enum": [
"UNIQUES",
"TOTALS"
],
"description": "CONVERSION only: \"UNIQUES\" measures unique users who complete the funnel; \"TOTALS\" measures total conversion path counts."
},
"funnelConstantProperties": {
"type": "array",
"items": {
"$ref": "#/properties/aggregationProperty"
},
"description": "CONVERSION only: properties held constant across funnel steps (same as funnel \"holding constant\" in the UI)."
},
"funnelComputeProperty": {
"$ref": "#/properties/aggregationProperty",
"description": "CONVERSION only: numeric property on the last funnel step to aggregate (e.g. revenue). Use with funnelComputePropFunction."
},
"funnelComputePropFunction": {
"type": "string",
"enum": [
"SUM",
"AVG"
],
"description": "CONVERSION only: how to aggregate funnelComputeProperty on the last step — \"SUM\" (default when property set) or \"AVG\"."
},
"isExperimentMetric": {
"type": "boolean",
"default": false,
"description": "Set to true when this metric is intended for use in an experiment. Enables experiment-specific formula validation rules."
},
"countGroup": {
"type": "string",
"default": "User",
"description": "What to count. \"User\" for unique users (default), \"Event\" for event totals."
},
"isOfficial": {
"type": "boolean",
"default": false,
"description": "Whether to mark this metric as official. Requires elevated permissions."
}
},
"required": [
"projectId",
"name",
"metricType"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Creating metric",
"destructiveHint": false,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"metrics",
"analytics",
"experiment",
"default"
],
"amplitude/accessLevels": [
"create"
]
}
},
{
"name": "create_notebook",
"title": "Creating notebook",
"description": "Create a new notebook\n\nWHEN TO USE:\n- The user wants to create a new notebook\n- The user wants to generate an interactive report with specific content from amplitude data specifically\n\nCRITICAL - CHART IDs MUST BE FROM SAVED CHARTS:\n- Only use chartIds from SAVED/PERMANENT charts - these are returned by save_chart_edits (in the chartId field) or create_chart\n- DO NOT use editIds from query_dataset - these are temporary IDs that cannot be added to notebooks\n- DO NOT use the editId from query_dataset responses - you must first call save_chart_edits to get a permanent chartId\n- The typical workflow is: query_dataset (returns editId) → save_chart_edits (converts editId to permanent chartId) → create_notebook (uses chartId)\n- If you use an editId instead of a saved chartId, the notebook creation will fail with \"NotFoundError: No chart\"\n\nINSTRUCTIONS:\n- Provide a name for the notebook\n- Use rows array where each row contains items in left-to-right order\n- Each item specifies width (3-12 columns). If width is omitted, items auto-fill remaining space\n- Total width of items in a row must not exceed 12 columns\n- Max 4 items per row (ensures minimum 3-column width per item)\n- The tool will create the notebook and return the new notebook ID and details\n- Return a link to the new notebook in the response\n\nMARKDOWN FORMAT:\n- Rich text content uses standard markdown syntax\n- Supported: headers (# ## ###), bold (**text**), italic (*text*), lists (- or 1.), links ([text](url)), code blocks (```), inline code (`code`)\n- Example: \"# Analysis Summary\\n\\nKey findings show **significant growth** in user engagement.\"\n\nLAYOUT EXAMPLES:\n- Full-width item: { items: [{ type: 'chart', chartId: '123', width: 12 }] }\n- Two side-by-side: { items: [{ type: 'chart', chartId: '1', width: 6 }, { type: 'rich_text', content: '# Notes', width: 6 }] }\n- Three columns: { items: [{ width: 4 }, { width: 4 }, { width: 4 }] }\n- Auto-fill: { items: [{ type: 'chart', chartId: '1' }, { type: 'chart', chartId: '2' }] } (each gets 6 columns)",
"inputSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Name for the new notebook"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"number"
],
"description": "Optional row ID for backend ordering (string for grid layout IDs, number for legacy)"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"number"
],
"description": "Item ID (returned from get operations, useful for future updates)"
},
"type": {
"type": "string",
"enum": [
"chart",
"rich_text",
"session_replay",
"video",
"image",
"cohort"
],
"description": "Content type"
},
"width": {
"type": "number",
"minimum": 3,
"maximum": 12,
"description": "Width in columns (3-12). If omitted, item auto-fills remaining space equally with other auto-width items."
},
"content": {
"type": "string",
"description": "Rich text content as markdown (for rich_text type)"
},
"chartId": {
"type": "string",
"description": "Saved chart ID (required when type is \"chart\"). IMPORTANT: Must be a permanent chartId from save_chart_edits or create_chart, NOT an editId from query_dataset. Using an editId will cause \"NotFoundError: No chart\"."
},
"sessionReplayIdentifier": {
"type": "string",
"description": "Session replay identifier (for session_replay type)"
},
"note": {
"type": "string",
"description": "Optional note (for session_replay type)"
},
"videoUrl": {
"type": "string",
"description": "Video URL (for video type)"
},
"imageS3Key": {
"type": "string",
"description": "S3 key for image (for image type)"
},
"title": {
"type": "string",
"description": "Title (for video/image types)"
},
"cohortId": {
"type": "string",
"description": "Cohort ID (for cohort type)"
},
"hideChart": {
"type": "boolean",
"description": "Whether to hide visualization (defaults to false)"
}
},
"required": [
"type"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 4,
"description": "Items in this row (left-to-right order, max 4 items)"
}
},
"required": [
"items"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Array of rows, each containing items in left-to-right order"
}
},
"required": [
"name",
"rows"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Creating notebook",
"destructiveHint": false,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"notebook",
"default"
],
"amplitude/accessLevels": [
"create"
]
}
},
{
"name": "edit_notebook",
"title": "Editing notebook",
"description": "Edit a notebook's metadata and layout with optimistic concurrency protection.\n\nWHEN TO USE:\n- You already have a notebook ID and want to update its name and/or content rows.\n\nINSTRUCTIONS:\n- Always call get_notebook first to retrieve the notebook's current lastModifiedAt and rows.\n- Pass the retrieved lastModifiedAt in expectedLastModifiedAt.\n- Metadata fields are only updated when values are not null/undefined.\n- Use one structural edit at a time via edit.\n\nEXAMPLES:\n- Metadata only:\n {\"notebookId\":\"123\",\"expectedLastModifiedAt\":1700000000,\"metadata\":{\"name\":\"Q1 Notebook\"}}\n- Replace all rows:\n {\"notebookId\":\"123\",\"expectedLastModifiedAt\":1700000000,\"edit\":{\"type\":\"set_rows\",\"rows\":[{\"items\":[{\"type\":\"chart\",\"chartId\":\"abc\",\"width\":12}]}]}}\n- Update a row:\n {\"notebookId\":\"123\",\"expectedLastModifiedAt\":1700000000,\"edit\":{\"type\":\"update_row\",\"rowIndex\":0,\"row\":{\"items\":[{\"type\":\"rich_text\",\"content\":\"# Notes\",\"width\":12}]}}}\n- Insert a row:\n {\"notebookId\":\"123\",\"expectedLastModifiedAt\":1700000000,\"edit\":{\"type\":\"insert_row\",\"index\":1,\"row\":{\"items\":[{\"type\":\"chart\",\"chartId\":\"def\",\"width\":12}]}}}\n- Remove a row:\n {\"notebookId\":\"123\",\"expectedLastModifiedAt\":1700000000,\"edit\":{\"type\":\"remove_row\",\"rowIndex\":2}}\n\nNOTES:\n- The request fails with a conflict if expectedLastModifiedAt is stale.\n- Response is intentionally compact to minimize context usage.",
"inputSchema": {
"type": "object",
"properties": {
"notebookId": {
"type": "string",
"minLength": 1,
"description": "Notebook ID to edit (required)."
},
"expectedLastModifiedAt": {
"type": "integer",
"description": "Required optimistic concurrency value. Request fails on mismatch."
},
"metadata": {
"type": "object",
"properties": {
"name": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 255
},
{
"type": "null"
}
],
"description": "Optional notebook name update. Applied only when not null/undefined."
}
},
"additionalProperties": false,
"description": "Optional metadata updates. Fields are applied only when not null/undefined."
},
"edit": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "set_rows"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"number"
],
"description": "Optional row ID for backend ordering (string for grid layout IDs, number for legacy)"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"number"
],
"description": "Item ID (returned from get operations, useful for future updates)"
},
"type": {
"type": "string",
"enum": [
"chart",
"rich_text",
"session_replay",
"video",
"image",
"cohort"
],
"description": "Content type"
},
"width": {
"type": "number",
"minimum": 3,
"maximum": 12,
"description": "Width in columns (3-12). If omitted, item auto-fills remaining space equally with other auto-width items."
},
"content": {
"type": "string",
"description": "Rich text content as markdown (for rich_text type)"
},
"chartId": {
"type": "string",
"description": "Saved chart ID (required when type is \"chart\"). IMPORTANT: Must be a permanent chartId from save_chart_edits or create_chart, NOT an editId from query_dataset. Using an editId will cause \"NotFoundError: No chart\"."
},
"sessionReplayIdentifier": {
"type": "string",
"description": "Session replay identifier (for session_replay type)"
},
"note": {
"type": "string",
"description": "Optional note (for session_replay type)"
},
"videoUrl": {
"type": "string",
"description": "Video URL (for video type)"
},
"imageS3Key": {
"type": "string",
"description": "S3 key for image (for image type)"
},
"title": {
"type": "string",
"description": "Title (for video/image types)"
},
"cohortId": {
"type": "string",
"description": "Cohort ID (for cohort type)"
},
"hideChart": {
"type": "boolean",
"description": "Whether to hide visualization (defaults to false)"
}
},
"required": [
"type"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 4,
"description": "Items in this row (left-to-right order, max 4 items)"
}
},
"required": [
"items"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Replace all notebook rows with this full rows array."
}
},
"required": [
"type",
"rows"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "update_row"
},
"rowIndex": {
"type": "integer",
"minimum": 0,
"description": "Zero-based index of row to replace."
},
"row": {
"$ref": "#/properties/edit/anyOf/0/properties/rows/items",
"description": "Full replacement row."
}
},
"required": [
"type",
"rowIndex",
"row"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "insert_row"
},
"index": {
"type": "integer",
"minimum": 0,
"description": "Zero-based insertion index. May equal current row count to append."
},
"row": {
"$ref": "#/properties/edit/anyOf/0/properties/rows/items",
"description": "Row to insert."
}
},
"required": [
"type",
"index",
"row"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "remove_row"
},
"rowIndex": {
"type": "integer",
"minimum": 0,
"description": "Zero-based index of row to remove."
}
},
"required": [
"type",
"rowIndex"
],
"additionalProperties": false
}
],
"description": "Optional single structural layout edit."
}
},
"required": [
"notebookId",
"expectedLastModifiedAt"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Editing notebook",
"destructiveHint": true,
"readOnlyHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"notebook",
"default"
],
"amplitude/accessLevels": [
"update"
]
}
},
{
"name": "query_dataset",
"title": "Analyzing chart",
"description": "Run analytics queries to answer data questions about users, events, funnels, and retention.\n\n# WHEN TO USE - Answer questions like:\n- \"How many active users did we have last week?\"\n- \"Show me a funnel from sign up to purchase\"\n- \"What is the retention rate for new users?\"\n- \"How many users completed checkout yesterday?\"\n- Any question asking for metrics, counts, trends, funnels, or retention analysis\n\n# DO NOT USE FOR:\n- Finding existing charts/dashboards → use 'search' instead\n- To get the valid chart definition to pass -> use 'get_chart_definition_params' instead\n- To validate the chart definition before passing it to query_dataset -> use 'verify_chart_definition' instead\n- BOTH THESE TOOLS SHOULD BE USED AND ARE INEXPENSIVE TO USE BEFORE PASSING THE CHART DEFINITION TO query_dataset\n- If you need more information about existing charts in the project as an example → use 'get_charts' instead\n- Project settings (timezone, currency) → use 'get_project_context' instead\n\n# STRATEGIES\n1. Use the 'search' tool to find if there are charts with properties that relate to the data you want to query.\n2. If you are unsure about the properties or schema please don't modify existing properties and use the two tools below to get detailed information:\n3. Use the 'get_chart_definition_params' tool to understand the valid chart definition to pass.\n4. Use the 'verify_chart_definition' tool to validate the chart definition before passing it to query_dataset.\n5. Use the 'get_charts' tool to find examples of existing charts in the project to understand the events, properties, and dataset schema generally.\n6. Optionally use the 'search' tool again to find additional events, user properties, etc. needed for the query.\n7. Optionally use the 'get_event_properties' tool to get properties on individual events.\n8. Use this tool to query the ad hoc analysis.\n\n# GENERAL GUIDELINES\n- Don't assume or guess properties, events, or schema. Use the tools provided to you to understand the data before running a dataset query.\n- When running into query failures, try searching for existing charts to understand the data taxonomy and dataset schema.\n- When you receive a 400 error response the schema is likely incorrect or the events/properties do not exist.\n- 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\".\n\n# AMPLITUDE WIDE META EVENTS TYPES\nSpecial system events available for analysis. Events are passed in the \"event_type\" field:\n- \"_active\": Any active event useful for tracking 'active users' like DAU, MAU(events not marked as inactive)\n- \"_all\": Any event being tracked in Amplitude\n- \"_new\": Events triggered by new users within the time interval. Useful for tracking 'new users'.\n- \"_any_revenue_event\": Any revenue-generating event. Useful for tracking 'revenue'.\n- \"$popularEvents\": Top events by volume (dynamically computed). Useful for more meta taxonomy analyses like 'what are the most common events'.\n\n# PROPERTY TYPES:\n- Amplitude core properties are built-in and use standard names like \"country\", \"platform\", \"device_id\", \"user_id\"\n- Custom properties are organization-defined and are typically prefixed with \"gp:\"\n- If you are unsure which properties exist, use search/get_charts/get_event_properties before querying\n\n\n\nRESPONSE FORMAT:\nReturns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present.\nCheck the isCsvResponse flag to determine which response format to parse\n\nCSV Response Structure (when isCsvResponse is true):\n- Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details\n- Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)\n- Data rows: Each row contains:\n * Label columns: First few columns contain row labels identifying the data series\n * Value columns: Numerical data organized under the corresponding date/time columns from the data header row\n- Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns\n- Cells in the CSV response are delimited by commas and may be prepended with a \t character\nExample below measures uniques of custom event \"Valuable Tweaking\" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users.\nThe data points are 614, 1769, and 4132 for the 3 days respectively.\ndata:\n\"\tExample chart name\"\n\"\tFormula\",\"\tUNIQUES(A)\"\n\"\tA:\",\"\t[Custom] 'Valuable Tweaking'\"\n\n\"\tSegment\",\"\t2025-08-23\",\"\t2025-08-24\",\"\t2025-08-25\"\n\"\tAll Non-Amplitude Users\",\"614\",\"1769\",\"4132\"\ndefinition: {\n \"app\": \"APP_ID\",\n \"params\": {\n \"countGroup\": \"User\",\n \"end\": 1756166399,\n \"events\": [\n {\n \"event_type\": \"ce:'Valuable Tweaking'\",\n \"filters\": [],\n \"group_by\": []\n }\n ],\n \"groupBy\": [],\n \"interval\": 1,\n \"metric\": \"uniques\",\n \"segments\": [],\n \"start\": 1755907200,\n },\n \"type\": \"eventsSegmentation\",\n}\n\nJSON Response Structure (when isCsvResponse is false):\n- Parse using the following structure:\n - timeSeries: Array of arrays, each containing data point for a given time period with a \"value\" property\n - overallSeries: Array of arrays, each containing data the overall data point (across the entire range) under the \"value\" property\n - seriesMetadata: Array of objects containing metadata for each series\n - xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series\n- Use the dataset definition to be able to parse referenced events, properties, and segments.\n\nExample below is a JSON response is for the same query as the CSV example above.\n{\n \"timeSeries\": [[{\"value\": 614}, {\"value\": 1769}, {\"value\": 4132}]],\n \"overallSeries\": [[{\"value\": 5642}]],\n \"seriesMetadata\": [{\"segmentIndex\": 0, \"formulaIndex\": 0, \"formula\": \"UNIQUES(A)\"}],\n \"xValuesForTimeSeries\": [\"2025-08-23T00:00:00\", \"2025-08-24T00:00:00\", \"2025-08-25T00:00:00\"]\n}\n",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project ID to query data from"
},
"definition": {
"type": "object",
"properties": {
"app": {
"type": "string",
"description": "Project ID (required)"
},
"type": {
"type": "string",
"description": "Query type (e.g., \"eventsSegmentation\", \"funnel\", \"retention\")"
},
"name": {
"type": "string",
"description": "Query name"
},
"params": {
"type": "object",
"additionalProperties": {},
"description": "Query parameters"
},
"version": {
"type": "number",
"default": 40,
"description": "API version (optional, defaults to 40)"
}
},
"required": [
"app",
"type",
"params"
],
"additionalProperties": true,
"description": "Use 'get_chart_definition_params' to get the valid chart definition to pass. Use 'verify_chart_definition' to validate the chart definition before passing it to query_dataset.\n\nUse canonical chart types only:\n- \"eventsSegmentation\"\n- \"funnels\"\n- \"retention\"\n- \"sessions\"\n- \"dataTableV2\"\n\nDo not use aliases like:\n- \"segmentation\"\n- \"event_segmentation\"\n- \"events\"\n- \"funnel\"\n\nTIME RANGE:\n- Use either \"range\" OR \"start\"/\"end\", never both\n- Valid range examples: \"Last 30 Days\", \"Last 12 Weeks\", \"This Month\", \"Yesterday\"\n- Use \"start\"/\"end\" for custom ranges with Unix timestamps, ISO 8601 strings, or relative strings like \"now-7d\" / \"now\"\n- Do not use invalid placeholders like \"Custom\", \"Daily\", or \"All Time\"\n\nCOMMON GUARDRAILS:\n- \"dataTableV2\" requires \"params.table\"\n- \"sessions\" requires \"params.sessions\"\n- event lists should use canonical event objects with \"event_type\", \"filters\", and \"group_by\"\n- include a descriptive top-level \"name\" whenever possible\n\nMINIMAL EXAMPLES:\n- eventsSegmentation:\n {\"type\":\"eventsSegmentation\",\"app\":\"123\",\"name\":\"Active Users Last 30 Days\",\"params\":{\"range\":\"Last 30 Days\",\"events\":[{\"event_type\":\"_active\",\"filters\":[],\"group_by\":[]}],\"metric\":\"uniques\",\"countGroup\":\"User\",\"groupBy\":[],\"interval\":1,\"segments\":[{\"conditions\":[]}]}}\n- funnels:\n {\"type\":\"funnels\",\"app\":\"123\",\"name\":\"Signup Funnel\",\"params\":{\"range\":\"Last 30 Days\",\"events\":[{\"event_type\":\"View Signup\",\"filters\":[],\"group_by\":[]},{\"event_type\":\"Complete Signup\",\"filters\":[],\"group_by\":[]}],\"countGroup\":\"User\",\"segments\":[{\"conditions\":[]}]}}"
},
"groupByLimit": {
"type": "number",
"minimum": 1,
"maximum": 1000,
"default": 10,
"description": "Maximum number of group by values to return (1-1000, defaults to 10)"
},
"excludeIncompleteDatapoints": {
"type": "boolean",
"default": false,
"description": "Optional flag to exclude incomplete data points from results. When true, the current time interval will be excluded from the results to avoid incomplete data points. Defaults to false."
},
"chartId": {
"type": "string",
"description": "Optional parent chart ID. When provided, the parent chart's params (segments, filters, countGroup, groupBy, etc.) are used as defaults — only params you explicitly provide will override."
},
"timeSeriesLimit": {
"type": "integer",
"minimum": 0,
"maximum": 1000,
"default": 6,
"description": "Maximum number of group-by values that include per-interval time-series rows in the CSV response. All group-by values always include their aggregate \"Total\" row. Groups beyond this limit only return their Total row, which dramatically reduces response size for charts with many group-by values over long date ranges. Set to 0 for totals-only. Defaults to 3."
}
},
"required": [
"projectId",
"definition"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Analyzing chart",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"query",
"analytics",
"dataset",
"default"
],
"amplitude/accessLevels": [
"read"
],
"openai/outputTemplate": "ui://amplitude/chart.html",
"ui/resourceUri": "ui://amplitude/chart.html",
"ui": {
"resourceUri": "ui://amplitude/chart.html"
}
}
},
{
"name": "get_chart_definition_params",
"title": "Getting chart definition params",
"description": "Get the parameter schema, valid enum values, and a working example for a specific chart type.\n\nWHEN TO USE:\n- Before calling query_dataset, to understand the correct parameter schema for a chart type.\n- When you need to know valid enum values (e.g., funnel modes, segmentation metrics).\n- When you need a working example definition to use as a template.\n\nINSTRUCTIONS:\n- Call this tool with the chart type you want to build a definition for.\n- Use the returned schema to construct a valid definition object.\n- Pass the constructed definition to query_dataset.\n- If the chart type is not yet supported, construct the definition based on existing chart examples from search/get_charts.\n\nSUPPORTED CHART TYPES: composition, eventsSegmentation, funnels, retention, sessions, stickiness",
"inputSchema": {
"type": "object",
"properties": {
"chartType": {
"type": "string",
"description": "The chart type to get parameter documentation for. Supported: composition, eventsSegmentation, funnels, retention, sessions, stickiness"
}
},
"required": [
"chartType"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Getting chart definition params",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "verify_chart_definition",
"title": "Verifying chart definition",
"description": "Validate and auto-correct a chart definition before passing it to query_dataset.\n\nWHEN TO USE:\n- After constructing a chart definition, to verify it is valid before querying.\n- When you want to catch and auto-fix common mistakes (wrong enum values, wrong field names).\n- The tool will auto-coerce known LLM mistakes and return the corrected definition.\n- Validates event types and properties exist in the project taxonomy.\n\nWHAT IT DOES:\n- Validates required fields (type, app, params) and chart-type-specific parameters.\n- 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}.\n- Validates that referenced event types exist in the project.\n- Validates that referenced properties exist on their event types.\n- Returns the corrected definition ready to pass to query_dataset.\n\nSUPPORTED CHART TYPES: composition, eventsSegmentation, funnels, retention, sessions, stickiness\nUnsupported types pass through with a warning (not an error) — you can still send them to query_dataset.",
"inputSchema": {
"type": "object",
"properties": {
"definition": {
"type": "object",
"properties": {
"app": {
"type": "string",
"description": "Project ID (required)"
},
"type": {
"type": "string",
"description": "Chart type (e.g., \"eventsSegmentation\", \"funnels\")"
},
"params": {
"type": "object",
"additionalProperties": {},
"description": "Chart parameters"
}
},
"required": [
"app",
"type",
"params"
],
"additionalProperties": true,
"description": "The chart definition object to validate. Can be a JSON object or a JSON string."
}
},
"required": [
"definition"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Verifying chart definition",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "query_chart",
"title": "Analyzing chart",
"description": "Query a single chart given its ID.\n\nRULES:\n- Users want to know references for analyses in order to validate the data.\n- ALWAYS REFERENCE CHARTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES.\n\nWHEN TO USE:\n- You want to query a chart to get its data.\n- Only one chart or chart edit can be queried in a single request.\n\nINSTRUCTIONS:\n- Identify the IDs of the charts you want to query from the conversation context (e.g., from URLs) or use the search tool to find them.\n- Provide saved charts via `chartId` parameter and chart edits (links ending in `/chart/new/<edit_id>` or `/chart/<chart_id>/edit/<edit_id>`) via the `chartEditId` parameter.\n- Only one chart or chart edit ID is allowed per request; if you have both, prefer the chart edit ID.\n- Use this tool to query one chart or chart edit.\n- Results will include data for the chart and errors if it fails.\n\n\n\nRESPONSE FORMAT:\nReturns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present.\nCheck the isCsvResponse flag to determine which response format to parse\n\nCSV Response Structure (when isCsvResponse is true):\n- Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details\n- Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)\n- Data rows: Each row contains:\n * Label columns: First few columns contain row labels identifying the data series\n * Value columns: Numerical data organized under the corresponding date/time columns from the data header row\n- Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns\n- Cells in the CSV response are delimited by commas and may be prepended with a \t character\nExample below measures uniques of custom event \"Valuable Tweaking\" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users.\nThe data points are 614, 1769, and 4132 for the 3 days respectively.\ndata:\n\"\tExample chart name\"\n\"\tFormula\",\"\tUNIQUES(A)\"\n\"\tA:\",\"\t[Custom] 'Valuable Tweaking'\"\n\n\"\tSegment\",\"\t2025-08-23\",\"\t2025-08-24\",\"\t2025-08-25\"\n\"\tAll Non-Amplitude Users\",\"614\",\"1769\",\"4132\"\ndefinition: {\n \"app\": \"APP_ID\",\n \"params\": {\n \"countGroup\": \"User\",\n \"end\": 1756166399,\n \"events\": [\n {\n \"event_type\": \"ce:'Valuable Tweaking'\",\n \"filters\": [],\n \"group_by\": []\n }\n ],\n \"groupBy\": [],\n \"interval\": 1,\n \"metric\": \"uniques\",\n \"segments\": [],\n \"start\": 1755907200,\n },\n \"type\": \"eventsSegmentation\",\n}\n\nJSON Response Structure (when isCsvResponse is false):\n- Parse using the following structure:\n - timeSeries: Array of arrays, each containing data point for a given time period with a \"value\" property\n - overallSeries: Array of arrays, each containing data the overall data point (across the entire range) under the \"value\" property\n - seriesMetadata: Array of objects containing metadata for each series\n - xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series\n- Use the dataset definition to be able to parse referenced events, properties, and segments.\n\nExample below is a JSON response is for the same query as the CSV example above.\n{\n \"timeSeries\": [[{\"value\": 614}, {\"value\": 1769}, {\"value\": 4132}]],\n \"overallSeries\": [[{\"value\": 5642}]],\n \"seriesMetadata\": [{\"segmentIndex\": 0, \"formulaIndex\": 0, \"formula\": \"UNIQUES(A)\"}],\n \"xValuesForTimeSeries\": [\"2025-08-23T00:00:00\", \"2025-08-24T00:00:00\", \"2025-08-25T00:00:00\"]\n}\n",
"inputSchema": {
"type": "object",
"properties": {
"chartId": {
"type": "string",
"minLength": 1,
"description": "Saved chart ID to query data for"
},
"chartEditId": {
"type": "string",
"minLength": 1,
"description": "Chart edit ID to query data for"
},
"groupByLimit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 10,
"description": "Maximum number of group by values to return (1-1000, defaults to 10)"
},
"excludeIncompleteDatapoints": {
"type": "boolean",
"default": false,
"description": "Optional flag to exclude incomplete data points from results. When true, the current time interval will be excluded from the results to avoid incomplete data points. Defaults to false."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Analyzing chart",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"query",
"analytics",
"chart",
"default"
],
"amplitude/accessLevels": [
"read"
],
"openai/outputTemplate": "ui://amplitude/chart.html",
"ui/resourceUri": "ui://amplitude/chart.html",
"ui": {
"resourceUri": "ui://amplitude/chart.html"
}
}
},
{
"name": "query_charts",
"title": "Analyzing chart",
"description": "Query up to 3 charts concurrently given their IDs.\n\nRULES:\n- Users want to know references for analyses in order to validate the data.\n- ALWAYS REFERENCE CHARTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES.\n\nWHEN TO USE:\n- You want to query multiple charts to get their data efficiently.\n- Maximum of 3 charts can be queried in a single request.\n\nINSTRUCTIONS:\n- Identify the IDs of the charts you want to query from the conversation context (e.g., from URLs) or use the search tool to find them.\n- Provide saved charts via `chartIds` parameter and chart edits (links ending in `/chart/new/<edit_id>` or `/chart/<chart_id>/edit/<edit_id>`) via the `chartEditIds` parameter.\n- Chart edit IDs take precedence over chart IDs when both are available for a given chart.\n- Use this tool to query up to 3 charts + chart edits (combined total).\n- Results will include data for each successfully queried chart and errors for any failed charts.\n\n\n\nRESPONSE FORMAT:\nReturns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present.\nCheck the isCsvResponse flag to determine which response format to parse\n\nCSV Response Structure (when isCsvResponse is true):\n- Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details\n- Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)\n- Data rows: Each row contains:\n * Label columns: First few columns contain row labels identifying the data series\n * Value columns: Numerical data organized under the corresponding date/time columns from the data header row\n- Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns\n- Cells in the CSV response are delimited by commas and may be prepended with a \t character\nExample below measures uniques of custom event \"Valuable Tweaking\" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users.\nThe data points are 614, 1769, and 4132 for the 3 days respectively.\ndata:\n\"\tExample chart name\"\n\"\tFormula\",\"\tUNIQUES(A)\"\n\"\tA:\",\"\t[Custom] 'Valuable Tweaking'\"\n\n\"\tSegment\",\"\t2025-08-23\",\"\t2025-08-24\",\"\t2025-08-25\"\n\"\tAll Non-Amplitude Users\",\"614\",\"1769\",\"4132\"\ndefinition: {\n \"app\": \"APP_ID\",\n \"params\": {\n \"countGroup\": \"User\",\n \"end\": 1756166399,\n \"events\": [\n {\n \"event_type\": \"ce:'Valuable Tweaking'\",\n \"filters\": [],\n \"group_by\": []\n }\n ],\n \"groupBy\": [],\n \"interval\": 1,\n \"metric\": \"uniques\",\n \"segments\": [],\n \"start\": 1755907200,\n },\n \"type\": \"eventsSegmentation\",\n}\n\nJSON Response Structure (when isCsvResponse is false):\n- Parse using the following structure:\n - timeSeries: Array of arrays, each containing data point for a given time period with a \"value\" property\n - overallSeries: Array of arrays, each containing data the overall data point (across the entire range) under the \"value\" property\n - seriesMetadata: Array of objects containing metadata for each series\n - xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series\n- Use the dataset definition to be able to parse referenced events, properties, and segments.\n\nExample below is a JSON response is for the same query as the CSV example above.\n{\n \"timeSeries\": [[{\"value\": 614}, {\"value\": 1769}, {\"value\": 4132}]],\n \"overallSeries\": [[{\"value\": 5642}]],\n \"seriesMetadata\": [{\"segmentIndex\": 0, \"formulaIndex\": 0, \"formula\": \"UNIQUES(A)\"}],\n \"xValuesForTimeSeries\": [\"2025-08-23T00:00:00\", \"2025-08-24T00:00:00\", \"2025-08-25T00:00:00\"]\n}\n",
"inputSchema": {
"type": "object",
"properties": {
"chartIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3,
"description": "Array of saved chart IDs to query data for (max 3)"
},
"chartEditIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3,
"description": "Array of chart edit IDs to query data for (max 3)"
},
"groupByLimit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 10,
"description": "Maximum number of group by values to return (1-1000, defaults to 10)"
},
"excludeIncompleteDatapoints": {
"type": "boolean",
"default": false,
"description": "Optional flag to exclude incomplete data points from results. When true, the current time interval will be excluded from the results to avoid incomplete data points. Defaults to false."
},
"timeSeriesLimit": {
"type": "integer",
"minimum": 0,
"maximum": 1000,
"default": 6,
"description": "Maximum number of group-by values that include per-interval time-series rows in the CSV response. All group-by values always include their aggregate \"Total\" row. Groups beyond this limit only return their Total row, which dramatically reduces response size for charts with many group-by values over long date ranges. Defaults to 6 to prevent excessively large responses, but we recommend setting to 0 (totals-only) unless you specifically need time-series breakdowns for trend analysis."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Analyzing chart",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"query",
"analytics",
"chart",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "query_experiment",
"title": "Analyzing experiment",
"description": "Query an experiment analysis.\n\nCRITICAL: 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).\n\nRULES:\n- Users want to know references for analyses in order to validate the data.\n- ALWAYS REFERENCE EXPERIMENTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES.\n\nWHEN TO USE:\n- You want to query a experiment for analysis.\n\nINSTRUCTIONS:\n- Use the search tool to find the ID of the experiment you want to query.\n- You may want to use the get_experiments tool to get more context about the experiment (i.e. state, variants, etc.)\n- Use this tool to query the experiment analysis.\n\n\nEXAMPLE:\ngroupBy: [{\"type\": \"user\", \"value\": \"device type\", \"group_type\": \"User\"}]",
"inputSchema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^\\d+$",
"description": "ID of the experiment to query"
},
"metricIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"description": "ONLY provide if user explicitly requests specific metrics or all metrics. If omitted, returns primary/recommended metric only for cleaner, focused results. Default behavior is preferred."
},
"groupBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"group_type": {
"type": "string"
}
},
"required": [
"type",
"value",
"group_type"
],
"additionalProperties": false
},
"maxItems": 1,
"default": [],
"description": "Group by user (optional) - Example: [{\"type\": \"user\", \"value\": \"device type\", \"group_type\": \"User\"}]"
},
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"group_type": {
"type": "string"
},
"subprop_key": {
"type": "string"
},
"subprop_op": {
"type": "string"
},
"subprop_value": {
"type": "array",
"items": {
"type": "string"
}
},
"subprop_type": {
"type": "string"
}
},
"required": [
"group_type",
"subprop_key",
"subprop_op",
"subprop_value",
"subprop_type"
],
"additionalProperties": false
},
"default": [],
"description": "Filters to apply to the metric (optional)"
},
"groupByLimit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 10,
"description": "Maximum number of group by values to return (1-1000, defaults to 10)"
}
},
"required": [
"id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Analyzing experiment",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"query",
"analytics",
"experiment",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "search",
"title": "Searching for content",
"description": "Search for dashboards, charts, notebooks, experiments, and other content in Amplitude.\n\nINSTRUCTIONS:\n- Use this as your primary tool to discover and explore available analytics content before diving into specific analyses.\n- If you are not sure what to search for, use the default search query.\n- Do not specify appIds/projectIds in the input unless the user explicitly asks to search within a specific app/project.\n- 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.\n- When searching for events, use the get_event_properties tool to get event properties on an individual event.\n\nDO NOT USE FOR:\n- AI agent results, agent analyses, or agent runs → use 'get_agent_results' instead\n- Getting full dashboard definitions with chart details → use 'get_dashboard' with the IDs from search results\n- Running queries or analysis → use 'query_dataset' or 'query_chart'\n\nADDITIONAL INFORMATION:\n- Results are personalized to the user you are making the request on behalf of.\n- Results do not include the full object definition. You will need to use other tools to get the full object definition when needed.\n- Best practice is to query for a single entity type, unless the user's request is open ended.\n- The response includes an isOfficial flag in contentMeta to identify content that has been marked as official by the organization.",
"inputSchema": {
"type": "object",
"properties": {
"appIds": {
"type": "array",
"items": {
"type": "number"
},
"description": "Array of app/project IDs to search within. If not provided, search will be for all apps the user has access to."
},
"queries": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Array of search query strings. If not provided or empty, search will return results based on relevance to the user. Multiple queries are executed in parallel and results are deduplicated using Reciprocal Rank Fusion (RRF)."
},
"entityTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"EVENT",
"EVENT_PROPERTY",
"USER_PROPERTY",
"GROUP_PROPERTY",
"DERIVED_PROPERTY",
"LOOKUP_PROPERTY",
"PERSISTED_PROPERTY",
"CUSTOM_EVENT",
"SAVED_SEGMENT",
"METRIC",
"CHART",
"DASHBOARD",
"NOTEBOOK",
"COHORT",
"SPACE",
"FLAG",
"EXPERIMENT",
"GUIDE",
"SURVEY"
]
},
"default": [
"CHART",
"DASHBOARD",
"NOTEBOOK",
"EXPERIMENT"
],
"description": "Types of entities to search for. Will be converted to camelCase internally for entityRef field access."
},
"includeArchived": {
"type": "boolean",
"default": false,
"description": "Whether to include archived entities"
},
"includeGenerated": {
"type": "boolean",
"default": false,
"description": "Whether to include AI-generated entites"
},
"owners": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter by owners (array of login IDs)"
},
"excludeOwners": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter out content by specific owners (array of login IDs)"
},
"sortOrder": {
"type": "string",
"enum": [
"relevance",
"lastModified",
"viewCount",
"name"
],
"description": "Sort order for results"
},
"isOfficial": {
"type": "boolean",
"description": "Filter by official content only"
},
"limitPerQuery": {
"type": "number",
"default": 50,
"description": "Maximum number of results to return per query. Results from multiple queries are deduplicated before being returned. We recommend starting with the default of 50, even if you are using multiple queries."
},
"sortDirection": {
"type": "string",
"enum": [
"ASC",
"DESC"
],
"default": "DESC",
"description": "Sort direction for results"
},
"lastModifiedAfter": {
"type": "number",
"description": "Filter to entities modified after this epoch timestamp (in seconds). Useful for finding recently active content, e.g. charts modified in the last 7 days."
},
"lastViewedBefore": {
"type": "number",
"description": "Filter to entities last viewed before this epoch timestamp (in seconds). Useful for finding stale or unused content."
},
"semanticSearch": {
"type": "boolean",
"default": false,
"description": "Whether to use semantic search in addition to keyword search"
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Searching for content",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"search",
"default"
],
"amplitude/accessLevels": [
"read"
]
},
"outputSchema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"score": {
"type": "number",
"description": "Relevance score for this search result (higher = more relevant)"
},
"entity": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the entity"
},
"orgId": {
"type": "string",
"description": "Organization ID where this entity belongs"
},
"type": {
"type": "string",
"description": "Entity type (e.g., CHART, DASHBOARD, NOTEBOOK)"
},
"name": {
"type": "string",
"description": "Display name of the entity"
},
"description": {
"type": "string",
"description": "Description of the entity"
},
"definition": {
"type": "string",
"description": "JSON definition of the entity (contains the configuration/setup data)"
},
"entityRef": {
"description": "Specific entity reference data"
},
"owners": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of owner user IDs"
},
"lastModified": {
"type": "string",
"description": "Last modified timestamp in ISO 8601 format"
},
"contentMeta": {
"type": "object",
"properties": {
"location": {
"type": "object",
"properties": {
"locationId": {
"type": [
"string",
"null"
],
"description": "Location identifier"
},
"shortcutIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Associated shortcut IDs"
}
},
"required": [
"shortcutIds"
],
"additionalProperties": false,
"description": "Optional Location information"
},
"isArchived": {
"type": "boolean",
"description": "Whether the content is archived"
},
"isGenerated": {
"type": "boolean",
"description": "Whether the content is AI-generated"
},
"isOfficial": {
"type": "boolean",
"description": "Whether the content is marked as official"
},
"isTemplate": {
"type": "boolean",
"description": "Whether the content is a template"
},
"chartCount": {
"type": "number",
"description": "Number of charts in the content"
},
"chartType": {
"type": "string",
"description": "Type of chart"
},
"appIds": {
"type": "array",
"items": {
"type": "number"
},
"description": "Associated application IDs"
},
"viewCount": {
"type": "number",
"description": "Number of times viewed"
},
"lastViewed": {
"type": "string",
"description": "Last viewed timestamp in ISO 8601 format"
},
"nudgeType": {
"type": "string",
"description": "Type of nudge/guide (for guide/survey entities)"
}
},
"required": [
"isArchived",
"isOfficial",
"isTemplate",
"chartCount",
"chartType",
"appIds",
"viewCount",
"lastViewed",
"nudgeType"
],
"additionalProperties": false,
"description": "Optional metadata about the content"
},
"url": {
"type": "string",
"description": "Optional URL to access the entity"
}
},
"required": [
"id",
"orgId",
"type",
"name",
"description",
"definition",
"owners",
"lastModified"
],
"additionalProperties": false
},
"scoreComponents": {
"type": "object",
"additionalProperties": {
"type": "number"
},
"description": "Optional breakdown of how the relevance score was calculated"
}
},
"required": [
"score",
"entity"
],
"additionalProperties": false
},
"description": "Array of search results"
},
"totalHits": {
"type": "number",
"description": "Total number of matching results"
}
},
"required": [
"results",
"totalHits"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
},
{
"name": "get_from_url",
"title": "Getting data from URL",
"description": "Retrieve objects from Amplitude URLs\n\nWHEN TO USE:\n- CRITICAL: Only use this tool if the user shares a link to an amplitude URL which starts with https://app.amplitude.com!\n- You have an Amplitude URL and want to get the full object definition\n- User shares a link to a dashboard, chart, notebook, experiment, etc.\n\nINSTRUCTIONS:\n- Provide the full Amplitude URL (e.g., https://app.amplitude.com/analytics/myorg/chart/456)\n- The tool will parse the URL, validate the organization, and return the full object\n- Works with charts, dashboards, notebooks, experiments, flags, cohorts, and metrics",
"inputSchema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Full Amplitude URL to retrieve the object from"
}
},
"required": [
"url"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Getting data from URL",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"navigation",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_session_replays",
"title": "Watching session replays",
"description": "Search session replays for a project using event count filters.\n\nWHEN TO USE:\n- You want to find session replays that match certain event count filters and user properties (e.g., plan type, cohort membership, email).\n\nINSTRUCTIONS:\n- Provide the projectId and one or more eventCountFilters.\n- Searches the last 30 days with a limit of 10 replays by default.\n- Optionally provide startTime and/or endTime to narrow the search window (ISO 8601 string or Unix timestamp in milliseconds). Defaults to the last 30 days if omitted.\n- Optionally include groupBys and limit.\n\nIMPORTANT: Provide clickable replay links when available. Some sessions may not have a URL if identifiers are missing — omit those gracefully.\n\nIMPORTANT: Before specifying any event_type other than \"_all\", first call get_labeled_events or get_events to confirm the event exists in the project. Do not guess or infer event names from context.\n\nEXAMPLES:\n\n- Filter by user property (e.g. plan type):\n eventCountFilters: [\n {\n \"count\": \"1\",\n \"operator\": \"greater or equal\",\n \"event\": {\n \"event_type\": \"_all\",\n \"filters\": [\n {\n \"group_type\": \"User\",\n \"subprop_key\": \"gp:plan\",\n \"subprop_op\": \"is\",\n \"subprop_type\": \"user\",\n \"subprop_value\": [\"enterprise2\", \"growth\"]\n }\n ],\n \"group_by\": []\n }\n }\n ]\n\n- Filter by local project-scoped property (e.g. platform):\n eventCountFilters: [\n {\n \"count\": \"1\",\n \"operator\": \"greater or equal\",\n \"event\": {\n \"event_type\": \"_all\",\n \"filters\": [\n {\n \"group_type\": \"User\",\n \"subprop_key\": \"platform\",\n \"subprop_op\": \"is\",\n \"subprop_type\": \"user\",\n \"subprop_value\": [\"Web\"]\n }\n ],\n \"group_by\": []\n }\n }\n ]\n\n- Exclude internal users by email:\n eventCountFilters: [\n {\n \"count\": \"1\",\n \"operator\": \"greater or equal\",\n \"event\": {\n \"event_type\": \"_all\",\n \"filters\": [\n {\n \"group_type\": \"User\",\n \"subprop_key\": \"gp:email\",\n \"subprop_op\": \"does not contain\",\n \"subprop_type\": \"user\",\n \"subprop_value\": [\"amplitude.com\"]\n }\n ],\n \"group_by\": []\n }\n }\n ]\n\n- Filter by a specific event (>= 1 occurrence):\n eventCountFilters: [\n {\n \"count\": \"1\",\n \"operator\": \"greater or equal\",\n \"event\": {\"event_type\": \"Purchase\", \"filters\": [], \"group_by\": []}\n }\n ]\n\n- Filter by event with property (>= 3 Page Viewed on pricing page):\n eventCountFilters: [\n {\n \"count\": \"3\",\n \"operator\": \"greater or equal\",\n \"event\": {\n \"event_type\": \"Page Viewed\",\n \"filters\": [\n {\n \"group_type\": \"User\",\n \"subprop_key\": \"page\",\n \"subprop_op\": \"is\",\n \"subprop_type\": \"event\",\n \"subprop_value\": [\"pricing\"]\n }\n ],\n \"group_by\": []\n }\n }\n ]\n\n- Combine user property filter with event filter:\n eventCountFilters: [\n {\n \"count\": \"1\",\n \"operator\": \"greater or equal\",\n \"event\": {\n \"event_type\": \"_all\",\n \"filters\": [{\"group_type\":\"User\",\"subprop_key\":\"gp:plan\",\"subprop_op\":\"is\",\"subprop_type\":\"user\",\"subprop_value\":[\"enterprise2\"]}],\n \"group_by\": []\n }\n },\n {\n \"count\": \"1\",\n \"operator\": \"greater or equal\",\n \"event\": {\"event_type\": \"Checkout Started\", \"filters\": [], \"group_by\": []}\n }\n ]\n\nNOTES:\n- Use event_type \"_all\" to filter on user properties (applies across any event).\n- Regular tracked events use just the event name (e.g. \"Purchase\", \"Checkout Started\"). Amplitude built-in events use bracket notation (e.g. \"[Amplitude] Start Session\"). Amplitude custom events created in the UI use the \"ce:\" prefix. Use \"_all\" to match any event.\n- User properties use the \"gp:\" prefix for globally propagated properties (e.g. \"gp:plan\", \"gp:email\") — these are reliably set across the org. Local project-scoped properties use plain keys (e.g. \"platform\" for Web/iOS/Android).\n- This tool returns the complete result in a single call. Do not call it again with the same parameters.\n- If results are empty, there are no matching sessions in the search window. Do not retry.\n- If this tool returns an error, report it to the user and stop.\n",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project ID (appId) to search within"
},
"segmentFilters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "property"
},
"op": {
"type": "string"
},
"values": {
"type": "array",
"items": {
"type": "string"
}
},
"prop": {
"type": "string"
},
"prop_type": {
"type": "string"
},
"group_type": {
"type": "string"
}
},
"required": [
"type",
"op",
"values"
],
"additionalProperties": false
},
"default": []
},
"name": {
"type": "string"
}
},
"additionalProperties": false
},
"default": [
{
"conditions": []
}
],
"description": "Array of segments; each with a conditions array"
},
"eventCountFilters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"count": {
"type": "string"
},
"operator": {
"type": "string"
},
"event": {
"type": "object",
"properties": {
"event_type": {
"type": "string"
},
"filters": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"default": []
},
"group_by": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"default": []
}
},
"required": [
"event_type"
],
"additionalProperties": false
}
},
"required": [
"count",
"operator",
"event"
],
"additionalProperties": false
},
"default": [],
"description": "Optional event count filters to constrain results"
},
"groupBys": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"group_type": {
"type": "string"
}
},
"required": [
"type",
"value",
"group_type"
],
"additionalProperties": false
},
"default": [],
"description": "Optional group by properties to include in metadata"
},
"limit": {
"type": "number",
"default": 10,
"description": "Max number of sessions to return. Defaults to 10."
},
"startTime": {
"type": [
"string",
"number"
],
"description": "Start of the search window. ISO 8601 string (e.g. \"2024-01-15T00:00:00Z\") or Unix timestamp in milliseconds. Defaults to 30 days ago."
},
"endTime": {
"type": [
"string",
"number"
],
"description": "End of the search window. ISO 8601 string or Unix timestamp in milliseconds. Defaults to now."
}
},
"required": [
"projectId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Watching session replays",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"session-replay",
"analytics",
"user-behavior",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "list_session_replays",
"title": "Listing session replays (public API)",
"description": "List session replays for a project using the Amplitude public Session Replay API.\n\nWHEN TO USE:\n- You want a paginated list of session replays within a time window without complex event-count filtering.\n- 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.\n\nINSTRUCTIONS:\n- Provide projectId. Optionally narrow results with start_time, end_time, page_size, and sort_order.\n- Use the returned next_page_token to fetch subsequent pages.\n- replay_id format is \"device_id/session_id\" — pass it directly to get_session_replay_events to retrieve rrweb events.\n\nNOTES:\n- If no start_time/end_time is provided, the last 48 hours is used automatically (end_time = now, start_time = 48 hours ago).\n- Keep sort_order consistent across paginated requests for the same query.\n- Replays older than their retention period will not appear.\n",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project ID (appId) to list replays for"
},
"start_time": {
"type": "string",
"description": "ISO 8601 lower bound for filtering (e.g. \"2024-01-01T00:00:00Z\")"
},
"end_time": {
"type": "string",
"description": "ISO 8601 upper bound for filtering"
},
"page_size": {
"type": "number",
"minimum": 1,
"maximum": 200,
"default": 50,
"description": "Number of results per page (1–200, default 50)"
},
"page_token": {
"type": "string",
"description": "Opaque pagination cursor returned by a previous response"
},
"sort_order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc",
"description": "Sort order: \"asc\" (oldest first) or \"desc\" (newest first, default)"
}
},
"required": [
"projectId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Listing session replays (public API)",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"session-replay",
"analytics",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_session_replay_events",
"title": "Getting session replay events",
"description": "Retrieve and process rrweb events from a session replay recording.\n\nWHEN TO USE:\n- You have a replay_id (from list_session_replays or get_session_replays) and want to understand what the user did during that session.\n- Useful for debugging user issues, understanding UX flows, or analyzing error reproduction steps.\n\nINSTRUCTIONS:\n- Provide projectId and replay_id in \"device_id/session_id\" format (as returned by list_session_replays).\n- Returns a processed interaction timeline: page navigations, clicks, text inputs, and significant scrolls.\n- Use event_limit to cap the number of events returned (default 500; reduce if context is tight).\n\nOUTPUT:\n- interactions: ordered list of user actions with timestamps (ms since Unix epoch)\n - navigation: { url, viewport }\n - click / double_click: { nodeId, x, y }\n - input: { nodeId, value } — text inputs and checkbox state changes\n - scroll: { nodeId, x, y, delta_y } — only large position jumps (≥200px)\n - viewport_resize: { width, height }\n\nNOTES:\n- 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.\n- Large or long sessions may be truncated at event_limit; the response indicates if truncation occurred.\n",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project ID (appId)"
},
"replay_id": {
"type": "string",
"description": "Replay ID in \"device_id/session_id\" format, as returned by list_session_replays"
},
"version": {
"type": "number",
"enum": [
2,
3
],
"default": 3,
"description": "Recording format version: 3 (default, current) or 2 (legacy)"
},
"event_limit": {
"type": "number",
"minimum": 1,
"maximum": 5000,
"default": 500,
"description": "Maximum number of interaction events to return (default 500)"
}
},
"required": [
"projectId",
"replay_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Getting session replay events",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"session-replay",
"analytics",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_event_properties",
"title": "Finding the right event properties",
"description": "Retrieve event properties for a specific event type from a project. This tool provides a concise way to get all properties associated with a particular event.\n\nWHEN TO USE:\n- You want to get all properties associated with a particular event with the EXACT event type.\n\n\nINSTRUCTIONS:\n- Search for the exact event type you want to get properties for using the search tool or the get_events tool.\n- Use this tool to get all event properties associated with a particular event.",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project ID to get event properties from. If the user has not specified a project, prompt the user to decide. Dont decide for them."
},
"eventType": {
"type": "string",
"description": "The specific event type to get properties for."
},
"includeTransformations": {
"type": "boolean",
"default": false,
"description": "When true, includes event property transformations (merges, value mappings) alongside the properties. May increase response time."
}
},
"required": [
"projectId",
"eventType"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Finding the right event properties",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"taxonomy",
"event-properties",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_feedback_comments",
"title": "Getting feedback comments",
"description": "Get raw customer feedback comments for a project with optional filtering and pagination.\n\nWHEN TO USE:\n- You want to retrieve raw feedback comments from various sources (surveys, support tickets, app reviews).\n- You need to see the actual customer feedback text and metadata.\n- You want to analyze comments with optional filters before they are grouped into insights.\n- You need to search for specific feedback or paginate through results.\n\nNOT FOR: AI/LLM agent chat transcripts, conversation logs, agent response quality (use get_agent_analytics_conversation, search_agent_analytics_conversations instead).\n\nTRIGGER PHRASES: \"feedback comments\", \"customer comments\", \"survey responses\", \"support tickets\", \"app reviews\", \"user reviews\", \"customer feedback text\", \"product feedback\", \"what are customers saying\", \"feedback page\", \"AI feedback page\"\n\nINSTRUCTIONS:\n- Provide the projectId (appId) to retrieve comments.\n- To get available sourceId values, first call get_feedback_sources with the projectId.\n- Provide sourceId to filter comments from a specific feedback source.\n- Use search to filter by body text. Pass an array for OR matching across terms.\n- Use page and pageSize parameters for pagination (defaults: page=1, pageSize=20).\n- Returns a list of comments with metadata including totalCount for pagination.\n- Each comment includes the feedback text, source information, and associated metadata.",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "The project ID (appId) to get feedback comments for"
},
"sourceId": {
"type": "number",
"description": "Source ID to filter comments by specific AI feedback source"
},
"page": {
"type": "number",
"default": 1,
"description": "Optional page number for pagination (default: 1)"
},
"pageSize": {
"type": "number",
"maximum": 1000,
"default": 50,
"description": "Optional page size for pagination (default: 50, max: 1000)"
},
"search": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Search term(s) to filter comments by body text. Multiple terms are OR-matched. Pass granular synonyms for better recall."
}
},
"required": [
"projectId",
"sourceId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Getting feedback comments",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"ai-feedback",
"feedback",
"comments",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_feedback_insights",
"title": "Get Feedback Insights",
"description": "Get customer feedback insights (processed and grouped themes) for a project with optional filtering and pagination.\n\nWHEN TO USE:\n- You want to see grouped themes extracted from customer feedback (feature requests, complaints, bugs, etc.).\n- You want to understand what customers are asking for or complaining about.\n- You need to drill into feedback themes before looking at individual comments.\n\nNOT FOR: AI/LLM agent error categories, session topics, agent quality scores (use query_agent_analytics_metrics, query_agent_analytics_sessions instead).\n\nTRIGGER PHRASES: \"feedback insights\", \"feedback themes\", \"feature requests from customers\", \"customer complaints\", \"pain points\", \"loved features\", \"what are users asking for\", \"product feedback\", \"feedback page\", \"AI feedback page\", \"AI feedback insights\"\n\nWHAT ARE INSIGHTS:\n- Insights are derived from mentions in feedback comments. Insights represent processed and grouped themes extracted from feedback comments.\n- The 8 types of insights are: feature requests (request), complaints (complaint), loved features (lovedFeature), brands mentioned (competitor), bugs (bug), feature mentions (mentionedFeature), pain points (painPoint), and key takeaways (takeaway).\n\nSORTING AND FILTERING:\n- Results are sorted by popularity (mention count), NOT by creation date. The tool cannot sort by when insights were created.\n- dateStart and dateEnd filter to insights with feedback comments within the date range.\n\nDRILLING DEEPER:\n- Present the deep dive details to the user to help them understand the insight better.\n- If a user asks for more details on a specific insight, use get_feedback_mentions with the insightId to see the actual user feedback.\n- Do NOT call get_feedback_mentions for every insight - only when explicitly requested.\n\nDIFFERENCE FROM GET_FEEDBACK_COMMENTS TOOL:\n- Insights are processed and grouped themes, while comments are raw individual feedback from a feedback source.\n- Use insights to understand themes and trends, use comments to see individual feedback.",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "The project ID (appId) to get feedback insights for"
},
"sourceIds": {
"type": "array",
"items": {
"type": "number"
},
"description": "Array of source IDs to filter insights by specific feedback sources (not required, all sources included by default)"
},
"types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"request",
"complaint",
"lovedFeature",
"competitor",
"bug",
"mentionedFeature",
"painPoint",
"takeaway"
]
},
"description": "Array of insight types to filter by"
},
"dateStart": {
"type": "string",
"description": "Optional start date for filtering insights (ISO date string)"
},
"dateEnd": {
"type": "string",
"description": "Optional end date for filtering insights (ISO date string)"
},
"page": {
"type": "number",
"default": 1,
"description": "Optional page number for pagination (default: 1)"
},
"pageSize": {
"type": "number",
"maximum": 100,
"default": 20,
"description": "Optional page size for pagination (default: 20, max: 100)"
},
"orderDirection": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Optional sort direction by mention count (default: desc)"
},
"search": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Search term(s) to filter insights by text. Pass an array of granular search terms for better recall."
},
"ampId": {
"type": "string",
"description": "Optional Amplitude user ID to filter insights by specific amplitude user"
}
},
"required": [
"projectId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Get Feedback Insights",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"feedback",
"ai-feedback",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_feedback_mentions",
"title": "Get Feedback Mentions",
"description": "Get customer feedback mentions (individual feedback comments associated with an insight or trend).\n\nWHEN TO USE:\n- ONLY after a user asks for more details or wants to see the actual feedback behind a specific insight or trend.\n- Do NOT call this tool for every insight/trend - only when the user specifically requests to drill down.\n\nNOT FOR: AI/LLM agent session data or conversation turns (use get_agent_analytics_conversation instead).\n\nTRIGGER PHRASES: \"feedback mentions\", \"feedback details\", \"drill into feedback\", \"see the actual feedback\", \"comments behind insight\", \"feedback behind trend\"\n\nPREREQUISITE: You MUST call get_feedback_insights or get_feedback_trends first to obtain an insightId or trendId.\n\nWHAT ARE MENTIONS:\n- Mentions are the individual user feedback comments that contributed to a specific insight or trend.\n- Each mention represents a piece of feedback from a user (survey response, support ticket, app review, etc).\n\nREQUIRED PARAMETERS:\n- Either insightId OR trendId must be provided.\n- insightId: The ID of the insight (from get_feedback_insights response).\n- trendId: The ID of the trend (from get_feedback_trends response).\n- All filter parameters (dateStart, dateEnd, sourceIds, ampId) should match what was used in the original query to ensure consistent results.",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "The project ID (appId) to get feedback mentions for"
},
"insightId": {
"type": "number",
"description": "The insight ID to retrieve mentions for (required if trendId not provided)"
},
"trendId": {
"type": "number",
"description": "The trend ID to retrieve mentions for (required if insightId not provided)"
},
"dateStart": {
"type": "string",
"description": "Start date for filtering mentions (ISO date string) - should match get_feedback_insights query"
},
"dateEnd": {
"type": "string",
"description": "End date for filtering mentions (ISO date string) - should match get_feedback_insights query"
},
"sourceId": {
"type": "number",
"description": "Source ID to filter mentions by - should match get_feedback_insights query"
},
"ampId": {
"type": "string",
"description": "Amplitude user ID to filter mentions by - should match get_feedback_insights query"
}
},
"required": [
"projectId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Get Feedback Mentions",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"feedback",
"mentions",
"ai-feedback",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_feedback_sources",
"title": "Getting feedback sources",
"description": "Get customer feedback sources (connected feedback integrations) for a project.\n\nWHEN TO USE:\n- You want to retrieve the list of feedback sources/integrations configured for a project.\n- You need to understand which feedback channels (e.g., surveys, support tickets, app reviews) are connected.\n- You need sourceId values to filter feedback comments by specific sources.\n- You want to see metadata about feedback sources before analyzing comments.\n\nNOT FOR: AI/LLM agent session data, agent performance, conversation transcripts (use query_agent_analytics_sessions, query_agent_analytics_metrics instead).\n\nTRIGGER PHRASES: \"feedback sources\", \"feedback integrations\", \"survey sources\", \"support ticket sources\", \"app review sources\", \"connected feedback channels\", \"feedback page\", \"AI feedback page\", \"customer feedback\", \"product feedback\", \"user feedback from surveys/reviews\"\n\nINSTRUCTIONS:\n- Provide the projectId (appId) to retrieve all configured feedback sources.\n- Returns a list of sources with their sourceId, sourceType, name, and configuration details.\n- Use the sourceId from results to filter comments in get_feedback_comments.\n- Each source represents a connected integration like surveys, support tickets, or app store reviews.\n\nTYPICAL WORKFLOW:\n1. Call get_feedback_sources to discover available sources and their sourceId values.\n2. Call get_feedback_comments with specific sourceId to retrieve comments from that source.",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "The project ID (appId) to get feedback sources for"
}
},
"required": [
"projectId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Getting feedback sources",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"ai-feedback",
"feedback",
"sources",
"integrations",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_feedback_trends",
"title": "Get Feedback Trends",
"description": "Get saved customer feedback trends for a project. Trends are user-defined groupings of product feedback that are tracked over time.\n\nWHEN TO USE:\n- When the user wants to see what feedback themes are being tracked.\n- When the user asks about tracked trends, saved trends, or monitored themes.\n- Before creating a new trend, to check what already exists.\n\nNOT FOR: AI/LLM agent quality trends, cost trends, session volume trends (use query_agent_analytics_metrics with timeseries metrics instead).\n\nTRIGGER PHRASES: \"feedback trends\", \"tracked feedback themes\", \"saved feedback trends\", \"monitored themes\", \"feedback over time\", \"feedback page\", \"AI feedback page\"\n\nWHAT ARE TRENDS:\n- Trends are saved themes derived from insights that are tracked over time as new feedback comes in.\n- Each trend has a name, category (same types as insights), and associated mentions (feedback comments).\n- Trends provide a mention timeline showing how the volume of feedback changes over time.\n\nTYPICAL WORKFLOW:\n1. Call get_feedback_trends to see existing saved trends.\n2. Call get_feedback_mentions with a trendId to see the feedback behind a specific trend.",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "The project ID (appId) to get feedback trends for"
},
"category": {
"type": "string",
"description": "Optional category filter (e.g., request, complaint, bug)"
},
"page": {
"type": "number",
"default": 1,
"description": "Optional page number for pagination (default: 1)"
},
"pageSize": {
"type": "number",
"maximum": 100,
"default": 20,
"description": "Optional page size for pagination (default: 20, max: 100)"
}
},
"required": [
"projectId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Get Feedback Trends",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"feedback",
"ai-feedback",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_users",
"title": "Get Users",
"description": "Retrieve user-level data and associated session replays for users who performed a specific event.\n\nWHEN TO USE:\n- You want to inspect individual users who performed a specific event\n- You need amplitude user IDs to use with get_user_profile or get_user_timeline tools\n- You want session replays correlated to specific users who performed an event\n\nINSTRUCTIONS:\n- IMPORTANT: Call get_events first to confirm the exact event name exists in the project. Do not guess event names.\n- Use the search tool to search for events, charts, properties to build the necessary event filter.\n- Provide projectId, event type, and optional event filters\n- Use limits to control how many users and session replays to return\n- Session replays are automatically fetched for returned users when available\n\nFILTER FORMAT:\nEach filter object MUST include all four fields:\n - subprop_type: \"event\" (event property) or \"user\" (user property)\n - subprop_key: property key name (e.g., \"button_name\", \"gp:plan\")\n - subprop_op: operator (e.g., \"is\", \"is not\", \"contains\", \"does not contain\", \"greater\", \"less\")\n - subprop_value: array of string values (e.g., [\"Submit\"])\n\nDo NOT pass empty objects ({}) as filters — either pass a complete filter object or an empty array [].\n\nTIME RANGE FORMAT:\n- Use ISO 8601 format: \"2025-01-15T00:00:00Z\"\n- The start date must be before the end date\n\nCOMMON EXAMPLES:\n\n- Active users (default time range): {\"projectId\": \"12345\", \"event\": {\"event_type\": \"_active\", \"filters\": []}}\n- 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\"]}]}}\n- 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\"}}\n- Custom limits: {\"projectId\": \"12345\", \"event\": {\"event_type\": \"Purchase\", \"filters\": []}, \"limits\": {\"users\": 20, \"sessionReplays\": 5}}\n\nNOTES:\n- Time range defaults to \"Last 30 Days\" if not specified\n- The amplitude user IDs returned can be used with other tools like get_user_profile or get_user_timeline\n- Session replays are fetched per-user via the session-replay-lookup API and included in the response\n- If session replay lookup fails, the error is surfaced in metadata and user data is still returned\n",
"inputSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project/App ID"
},
"event": {
"type": "object",
"properties": {
"event_type": {
"type": "string",
"description": "Event type/name (e.g., \"Button Clicked\", \"_active\"). Call get_events first to confirm the exact event name."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"subprop_type": {
"type": "string",
"enum": [
"event",
"user"
],
"description": "Filter scope: \"event\" for event properties, \"user\" for user properties"
},
"subprop_key": {
"type": "string",
"description": "Property key to filter on (e.g., \"button_name\", \"gp:plan\")"
},
"subprop_op": {
"type": "string",
"description": "Comparison operator: \"is\", \"is not\", \"contains\", \"does not contain\", \"greater\", \"less\", etc."
},
"subprop_value": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of values to match against (e.g., [\"Submit\", \"Cancel\"])"
}
},
"required": [
"subprop_type",
"subprop_key",
"subprop_op",
"subprop_value"
],
"additionalProperties": false,
"description": "A single property filter condition"
},
"default": [],
"description": "Optional event/user property filters. Each filter must have subprop_type, subprop_key, subprop_op, and subprop_value."
}
},
"required": [
"event_type"
],
"additionalProperties": false,
"description": "Event with type and filters"
},
"timeRange": {
"type": "object",
"properties": {
"start": {
"type": "string",
"description": "ISO 8601 timestamp for start of time range"
},
"end": {
"type": "string",
"description": "ISO 8601 timestamp for end of time range"
}
},
"required": [
"start",
"end"
],
"additionalProperties": false,
"description": "Optional time range to override default (defaults to Last 30 Days)"
},
"limits": {
"type": "object",
"properties": {
"users": {
"type": "number",
"default": 10,
"description": "Number of users to return (default 10)"
},
"sessionReplays": {
"type": "number",
"default": 10,
"description": "Max number of session replays to return in total (default 10)"
}
},
"additionalProperties": false,
"description": "Optional output limits"
}
},
"required": [
"projectId",
"event"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Get Users",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"users",
"analytics",
"session-replay",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
},
{
"name": "get_agent_results",
"title": "Searching agent analysis results",
"description": "Retrieve results from AI agents that have analyzed your dashboards or session replays.\n\nThis is NOT for searching dashboards, charts, or notebooks — use 'search' for that.\nThis is specifically for retrieving the AI-generated insights and analyses that agents produced.\n\nThis tool handles both searching for agent analyses and fetching full results in a single call.\n\nMODES:\n1. **Search mode** (no session_id): Search agent analyses with filters. Returns preview summaries.\n2. **Direct fetch mode** (session_id provided): Fetch full artifact data for a specific session.\n3. **Auto-expand**: If search returns exactly 1 session, full artifacts are included automatically.\n\nSEARCH STRATEGY (important — follow this order):\n1. If you have a specific session_id, use direct fetch mode.\n2. For dashboard analyses, pass agent_params with dashboard_id (cheap exact-match).\n3. For session replay insights, use agent_params with category and/or impact (cheap exact-match).\n4. Use \"query\" ONLY for natural language / fuzzy search when exact filters aren't sufficient.\n\nWHEN TO USE:\n- \"What are my dashboard agents?\" → agent_type: dashboard_explorer\n- \"Show my agent results\" → agent_type: dashboard_explorer (or session_replay_explorer)\n- \"What agents have I run?\" → agent_type: dashboard_explorer\n- \"What analyses exist for dashboard xyz?\" → agent_type: dashboard_explorer, agent_params: { dashboard_id: \"xyz\" }\n- \"Show me high-impact session replay insights\" → agent_type: session_replay_explorer, agent_params: { impact: \"High\" }\n- \"Friction hotspots in the checkout flow\" → agent_type: session_replay_explorer, agent_params: { category: \"Friction Hotspots\" }, query: \"checkout flow\"\n- \"What did the AI find about rage clicks?\" → agent_type: session_replay_explorer, query: \"rage clicks\"\n- \"Any dashboard insights about revenue?\" → agent_type: dashboard_explorer, query: \"revenue\"\n- \"Show me insights from last week\" → agent_type: session_replay_explorer, created_after: \"2026-03-16T00:00:00Z\"\n- \"What did I analyze recently?\" → agent_type: dashboard_explorer\n\nDO NOT USE FOR:\n- Finding or listing dashboards, charts, or notebooks → use 'search' instead\n- Running new analyses or queries → use 'query_dataset' or 'query_amplitude_data' or 'query_chart' instead\n- Creating dashboards → use 'create_dashboard' instead\n\nRETURNS:\n- Search mode: List of analysis sessions with preview summaries, URLs, and pagination info\n- Direct fetch mode: Full artifact data for the session\n- Links to view each session in the Amplitude UI are included",
"inputSchema": {
"type": "object",
"properties": {
"agent_type": {
"type": "string",
"enum": [
"dashboard_explorer",
"session_replay_explorer"
],
"description": "Type of agent analysis to search for. \"dashboard_explorer\" finds AI-generated dashboard analysis summaries. \"session_replay_explorer\" finds AI-generated UX insights from session replay analysis."
},
"session_id": {
"type": "string",
"description": "Specific session ID to fetch full artifacts for. When provided, returns full artifact data and other filters are ignored. Get session IDs from a previous search."
},
"agent_params": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Agent-type-specific filter parameters as a JSON object. For dashboard_explorer: { \"dashboard_id\": \"xyz\" }. For session_replay_explorer: { \"category\": \"Friction Hotspots\", \"impact\": \"High\" }. Valid categories: Journeys & Navigation, Forms & Input, Content, Conversion, Friction Hotspots, Retention. Valid impacts: Low, Medium, High."
},
"query": {
"type": "string",
"description": "Free-text semantic search query (uses vector embeddings). Best for natural language discovery: \"rage clicks on save button\", \"dashboard showing revenue drop\", \"friction in onboarding flow\". This is EXPENSIVE (generates an embedding) — prefer exact filters when you have specific values."
},
"created_after": {
"type": "string",
"description": "ISO 8601 date string. Only return sessions with analysis artifacts created after this date. Filters by artifact time, not session creation time. Example: \"2025-03-01T00:00:00Z\" for analyses run since March 2025."
},
"created_before": {
"type": "string",
"description": "ISO 8601 date string. Only return sessions with analysis artifacts created before this date. Use with created_after for a date range."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"description": "Maximum number of results to return (default: 10)."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Pagination offset. Use with limit to page through results. Start at 0 (default)."
}
},
"required": [
"agent_type"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
},
"annotations": {
"title": "Searching agent analysis results",
"destructiveHint": false,
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"execution": {
"taskSupport": "forbidden"
},
"_meta": {
"amplitude/tags": [
"agents",
"analytics",
"default"
],
"amplitude/accessLevels": [
"read"
]
}
}
],
"_meta": {
"requestId": "req_1775759308480_onpowhftv"
}
},
"jsonrpc": "2.0",
"id": 1
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment