The OpenReplay MCP Server enables AI models to query and analyze OpenReplay user session data, providing comprehensive insights into user behavior, performance, and errors through both API key and JWT authentication.
Core Capabilities:
Project Management: List all projects in your organization
Session Analysis: Get user sessions by ID with date range filters, search and filter sessions (full capabilities require JWT authentication), and access detailed session information including events, errors, network requests, console logs, and performance metrics
Event Tracking: Retrieve session events with optional filtering by event type
Data Aggregation: Aggregate session data with metrics like count, average duration, and error rate, grouped by time, device, or custom fields
User Journey Mapping: Track complete user journeys across multiple sessions with detailed event inclusion
Error Analysis: Identify errors and issues with impact analysis, filtering by type and grouping by message, stack, or URL
Funnel Analysis: Analyze user conversion paths with custom step definitions
Performance Monitoring: Measure key metrics like load time, largest contentful paint (LCP), and time to interactive (TTI) with percentile calculations
Advanced Querying: Execute custom SQL-like queries using ClickHouse syntax for sophisticated data analysis
Enables execution of custom SQL-like queries for advanced session analytics through OpenReplay's ClickHouse backend
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OpenReplay MCP Server show me the most common JavaScript errors from the last 7 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that provides AI-powered analytics for OpenReplay sessions. This server enables LLMs to query and analyze user sessions through OpenReplay's API.
The server currently uses API key authentication which provides access to:
List all projects
Get user sessions by user ID
Get session events
User details
Note: API key authentication has limited access. For full functionality (session search, metrics, funnels, etc.), JWT authentication is required.
Full access to all OpenReplay features including:
Complete session search with filters
Performance metrics and analytics
Funnel analysis
Error tracking and aggregation
Custom dashboards and metrics
Related MCP server: KrystalView MCP Server
npm install
npm run buildCopy .env.example to .env:
cp .env.example .envConfigure your OpenReplay credentials:
# OpenReplay API URL
# For cloud: https://api.openreplay.com (default)
# For self-hosted: Your instance URL
OPENREPLAY_API_URL=https://api.openreplay.com
# Organization API Key (find in Preferences > Account > Organization API Key)
OPENREPLAY_API_KEY=your_organization_api_key
# Project key from your project settings
OPENREPLAY_PROJECT_KEY=your_project_keyAdd to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"openreplay": {
"command": "node",
"args": ["/path/to/openreplay-mcp/dist/index.js"],
"env": {
"OPENREPLAY_API_URL": "https://api.openreplay.com",
"OPENREPLAY_API_KEY": "your_organization_api_key",
"OPENREPLAY_PROJECT_KEY": "your_project_key"
}
}
}
}Search and filter sessions with various criteria like date range, user properties, errors, performance metrics.
Get detailed information about a specific session including all events, errors, network requests, console logs.
Get all events from a session with optional filtering by event type.
Aggregate session data with various metrics and groupings (count, avg_duration, error_rate, bounce_rate, etc.).
Get the complete journey of a user across multiple sessions.
Get errors and issues with their impact and affected sessions.
Analyze user funnels and conversion paths with custom step definitions.
Get performance metrics like page load times, LCP, TTI with percentiles.
Execute custom queries for advanced analysis (SQL-like syntax for ClickHouse).
Once connected, you can ask the LLM questions like:
"What are the most common drop-off points in our checkout flow?"
"Show me the longest user sessions from the last week"
"What JavaScript errors are affecting the most users?"
"Analyze the user journey for users who converted vs those who didn't"
"What pages have the worst performance metrics?"
"Find patterns in sessions that resulted in errors"
"Show me the bounce rate by device type and country"
# Run in development mode
npm run dev
# Build for production
npm run build
# Start production server
npm startMIT
Aggregate session data with various metrics and groupings
| Name | Required | Description | Default |
|---|---|---|---|
| startDate | No | Start date in ISO format | |
| endDate | No | End date in ISO format | |
| metrics | Yes | Metrics to calculate | |
| groupBy | No | Fields to group by | |
| filters | No | Same filter format as search_sessions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states the tool aggregates data but doesn't mention whether this is a read-only operation, if it requires specific permissions, how results are returned (e.g., pagination, format), or any rate limits. For an aggregation tool with multiple parameters and no annotations, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part ('aggregate session data,' 'various metrics and groupings') contributes directly to understanding the tool's function. There's no redundancy or fluff, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, aggregation functionality) and lack of annotations and output schema, the description is minimally adequate. It covers the basic purpose but misses behavioral details, usage context, and output expectations. For a tool that likely returns aggregated data sets, more information on result format or limitations would improve completeness, but the schema provides good parameter coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by implying the tool handles 'various metrics and groupings,' which aligns with the metrics and groupBy parameters. However, it doesn't provide additional context like examples of common groupings or how filters relate to search_sessions. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as aggregating session data with metrics and groupings, using specific verbs ('aggregate') and resources ('session data'). It distinguishes from siblings like get_session_details or get_session_events by focusing on aggregation rather than retrieval of individual records. However, it doesn't explicitly differentiate from get_performance_metrics which might also involve aggregated data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_performance_metrics, search_sessions, or execute_custom_query. It mentions 'various metrics and groupings' but doesn't specify contexts, prerequisites, or exclusions. Without this, an agent might struggle to choose between this and other analytical tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a custom query on the session data (supports SQL-like syntax for ClickHouse)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Custom query to execute | |
| parameters | No | Query parameters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'SQL-like syntax for ClickHouse' which gives some technical context, but doesn't disclose important behavioral traits like whether this is read-only or can modify data, what permissions are required, rate limits, error handling, or what format results are returned in. The description is insufficient for a tool that executes arbitrary queries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality. It's appropriately sized for what it does cover, though it could be more comprehensive given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that executes arbitrary queries with no annotations and no output schema, the description is inadequate. It doesn't explain what data can be queried, what SQL-like syntax is supported, what happens on execution errors, or what the return format looks like. The complexity of the tool demands more complete documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters fully. The description doesn't add any meaningful parameter semantics beyond what's in the schema - it doesn't explain query syntax examples, parameter binding mechanisms, or provide guidance on constructing valid queries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a custom query on session data using SQL-like syntax for ClickHouse. It specifies the verb ('execute'), resource ('custom query on session data'), and technology context ('ClickHouse'), but doesn't explicitly differentiate from sibling tools like aggregate_sessions or search_sessions that might also query session data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With multiple sibling tools for querying session data (aggregate_sessions, get_session_details, search_sessions, etc.), there's no indication of when this custom query approach is preferred over the more specialized tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get errors and issues with their impact and affected sessions
| Name | Required | Description | Default |
|---|---|---|---|
| startDate | No | Start date in ISO format | |
| endDate | No | End date in ISO format | |
| errorTypes | No | Filter by error types (js_exception, missing_resource, etc.) | |
| minOccurrences | No | Minimum number of occurrences | |
| groupBy | No | How to group errors |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions retrieving errors with 'impact and affected sessions', but does not specify whether this is a read-only operation, if it requires permissions, how results are paginated, or the format of returned data. This leaves significant gaps for a tool with multiple parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. It directly states what the tool does, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no annotations, and no output schema, the description is incomplete. It does not explain the return format, error impact details, or session linkage, leaving the agent with insufficient context to understand the full behavior and output of this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description adds no additional semantic meaning beyond implying filtering by date and error types, which is already covered in the schema. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('errors and issues'), specifying what information is retrieved. However, it does not differentiate this tool from sibling tools like 'get_session_events' or 'get_performance_metrics', which might also involve error-related data, leaving some ambiguity about its unique scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get_session_details' or 'search_sessions' that might overlap in error reporting, there is no explicit context, exclusions, or named alternatives to help an agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze user funnels and conversion paths
| Name | Required | Description | Default |
|---|---|---|---|
| steps | Yes | Funnel steps in order | |
| startDate | No | Start date in ISO format | |
| endDate | No | End date in ISO format | |
| filters | No | Additional filters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Analyze' suggests a read operation, but the description doesn't specify whether this is a heavy computation, has rate limits, requires specific permissions, or what the output format looks like. For a tool with 4 parameters and no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized and front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of funnel analysis with 4 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what the analysis returns, how results are structured, or any behavioral aspects like performance characteristics or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional meaning about parameters beyond what's in the schema. The baseline score of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as analyzing user funnels and conversion paths, which is a specific verb (analyze) and resource (user funnels/conversion paths). However, it doesn't distinguish this tool from sibling tools like get_user_journey or get_session_events, which might also analyze user paths.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like get_user_journey and get_session_events that might overlap in analyzing user paths, there's no indication of what makes this tool distinct or when it's the appropriate choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get performance metrics like page load times, largest contentful paint, time to interactive, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| startDate | No | Start date in ISO format | |
| endDate | No | End date in ISO format | |
| metrics | Yes | ||
| groupBy | No | ||
| percentiles | No | Percentiles to calculate (e.g., [50, 75, 90, 95, 99]) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only mentions what metrics can be retrieved but doesn't disclose any behavioral traits like whether this is a read-only operation, potential rate limits, authentication requirements, data freshness, or what the output format looks like. For a tool with 5 parameters and no annotations, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for the tool's complexity and front-loads the core purpose immediately. Every word earns its place by specifying the type of metrics retrieved.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain the behavioral context (read-only vs. mutation, rate limits, etc.), doesn't clarify when to use it versus sibling tools, and provides minimal parameter guidance beyond what's in the schema. For a data retrieval tool with multiple parameters and siblings, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'performance metrics like page load times, largest contentful paint, time to interactive, etc.' which partially maps to the 'metrics' parameter. However, with 60% schema description coverage (3 out of 5 parameters have descriptions), the description doesn't add meaningful semantics beyond what the schema already provides for startDate, endDate, groupBy, and percentiles. The baseline is 3 since schema coverage is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'performance metrics', with specific examples like page load times and largest contentful paint. It distinguishes from siblings by focusing on performance metrics rather than sessions, errors, or user journeys. However, it doesn't explicitly differentiate from all siblings (e.g., execute_custom_query could potentially retrieve similar data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With multiple sibling tools like get_session_details, get_errors_issues, and execute_custom_query, there's no indication of the specific context or scenarios where this tool is appropriate versus those alternatives. The description only states what it does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific session including all events, errors, network requests, console logs, custom events, and performance metrics
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | The session ID to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what information is retrieved but lacks details on permissions needed, rate limits, pagination, error handling, or the format of returned data. For a tool that fetches comprehensive session details, this omission is significant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and lists included information without unnecessary words. It could be slightly improved by structuring the list more clearly, but it avoids redundancy and is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (retrieving multiple data types) and lack of annotations or output schema, the description is incomplete. It doesn't explain the structure of returned data, potential limitations, or how to interpret the detailed information, leaving gaps for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'sessionId' clearly documented. The description adds no additional semantic context about the parameter, such as format examples or validation rules, but the schema's completeness justifies the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('detailed information about a specific session'), and it enumerates the types of information included (events, errors, network requests, etc.). However, it doesn't explicitly distinguish this tool from similar siblings like 'get_session_events' or 'get_performance_metrics', which reduces clarity about its unique scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get_session_events' and 'get_performance_metrics' available, it fails to specify scenarios where this comprehensive tool is preferred over more focused ones, or any prerequisites for its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all events from a session with optional filtering by event type
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | The session ID | |
| eventTypes | No | Filter by specific event types (CLICK, INPUT, LOCATION, CUSTOM, ERROR, etc.) | |
| startTime | No | Start timestamp (ms) | |
| endTime | No | End timestamp (ms) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves events but doesn't mention whether this is a read-only operation, if there are rate limits, authentication requirements, or what the return format looks like (e.g., pagination, structure). This leaves significant gaps for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose and key feature (filtering). It's front-loaded with the main action and avoids unnecessary words, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of retrieving events with filtering, no annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like safety, performance, or return values, leaving the agent with insufficient context to use the tool effectively beyond basic parameter passing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters thoroughly. The description adds minimal value by mentioning 'optional filtering by event type', which aligns with the 'eventTypes' parameter but doesn't provide additional semantic context beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('events from a session'), making the purpose understandable. However, it doesn't distinguish this tool from potential siblings like 'get_session_details' or 'get_user_journey' which might also retrieve session-related data, so it lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'optional filtering by event type', which implies some usage context, but it doesn't provide explicit guidance on when to use this tool versus alternatives like 'get_session_details' or 'get_user_sessions'. No when-not-to-use or prerequisite information is included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete journey of a user across multiple sessions
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | User ID or anonymous ID | |
| startDate | No | Start date in ISO format | |
| endDate | No | End date in ISO format | |
| includeEvents | No | Include detailed events (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions retrieving a 'complete journey' but doesn't specify if this is a read-only operation, what permissions are needed, how data is returned (e.g., pagination, format), or any rate limits. This leaves significant gaps for a tool that likely queries user data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without any fluff or redundancy. It's appropriately sized and front-loaded, making it easy to understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of retrieving user journeys across sessions, no annotations, and no output schema, the description is insufficient. It doesn't explain the return format, potential data volume, or how it differs from sibling tools, leaving the agent with incomplete context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so parameters like 'userId', 'startDate', 'endDate', and 'includeEvents' are well-documented in the schema. The description adds no additional meaning beyond implying a user journey retrieval, which the schema already supports, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('complete journey of a user across multiple sessions'), making the purpose understandable. However, it doesn't explicitly differentiate from siblings like 'get_user_sessions' or 'get_session_details', which might offer similar user-focused data, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'get_user_sessions' or 'get_session_details', nor does it mention prerequisites or exclusions. It only states what the tool does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get sessions for a specific user ID (API key authentication supported)
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | The user ID to get sessions for | |
| startDate | No | Start date in ISO format | |
| endDate | No | End date in ISO format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It adds value by specifying 'API key authentication supported', which is useful behavioral context not in the schema. However, it lacks details on rate limits, pagination, error handling, or what 'sessions' entail, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It front-loads the core purpose and includes authentication details concisely, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is minimal but covers the basic purpose and authentication. For a tool with three parameters and session data retrieval, it should ideally explain return values or data scope, but it's adequate as a starting point.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no additional parameter semantics beyond what's in the schema, such as format examples or constraints, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'sessions for a specific user ID', making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'get_session_details' or 'search_sessions', which likely retrieve similar session-related data, so it misses the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'get_session_details' or 'search_sessions'. It mentions API key authentication, but this is more about behavioral context than usage timing, leaving the agent without clear selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get list of all projects in the organization
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Get list') but doesn't describe key traits such as whether this is a read-only operation, if it requires authentication, what the return format looks like (e.g., pagination, fields included), or any rate limits. This leaves significant gaps for a tool with no structured safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly states the tool's purpose without any fluff or redundancy. It's front-loaded with the essential information, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a tool that likely returns a list of projects. It doesn't explain what data is returned (e.g., project names, IDs, statuses), how results are structured, or any limitations (e.g., maximum number of projects). This leaves the agent with insufficient context to use the tool effectively beyond its basic purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, meaning there are no parameters to document. The description appropriately doesn't add parameter details, which is correct for this case. It gets a baseline 4 because there's nothing to compensate for, and it doesn't introduce unnecessary complexity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get list') and resource ('projects in the organization'), making the purpose immediately understandable. However, it doesn't distinguish this tool from potential sibling tools that might also retrieve project data, such as a filtered search tool, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_sessions' or 'execute_custom_query' from the sibling list. It lacks any mention of prerequisites, exclusions, or specific contexts, leaving the agent to infer usage based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[Requires userId with API key auth] Search and filter sessions. Full search requires JWT authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| userId | No | Required: User ID to search sessions for | |
| startDate | No | Start date in ISO format | |
| endDate | No | End date in ISO format | |
| filters | No | Filters (limited with API key auth) | |
| limit | No | Number of sessions to return | |
| offset | No | Offset for pagination | |
| sort | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively adds context about authentication requirements (API key vs JWT) and functional limitations ('filters (limited with API key auth)'), which are crucial behavioral traits. However, it doesn't mention rate limits, pagination behavior beyond parameters, or what happens with missing parameters, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences that are front-loaded with essential information. Every sentence earns its place by covering authentication requirements and functional scope. There's zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, nested objects) and lack of both annotations and output schema, the description is incomplete. It covers authentication needs but doesn't explain return values, error conditions, or how parameters interact (e.g., what happens if startDate is missing). For a search tool with rich parameters, more context about results and behavior would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high at 86%, so the baseline is 3 even though the description adds no parameter-specific information beyond what's in the schema. The description mentions authentication constraints that affect parameters (e.g., filters being limited with API key auth), but this is more about behavioral context than parameter semantics. The schema already documents all parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'Search and filter sessions' which is a specific verb+resource combination. However, it doesn't distinguish this from sibling tools like 'get_user_sessions' or 'get_session_details', which likely have overlapping functionality. The description is clear but lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context by mentioning authentication requirements ('Requires userId with API key auth' and 'Full search requires JWT authentication'), which implies when certain features are available. However, it doesn't explicitly state when to use this tool versus alternatives like 'get_user_sessions' or 'aggregate_sessions', nor does it provide clear exclusions or prerequisites beyond authentication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0aggregate_sessionsexecute_custom_queryget_errors_issuesget_funnel_analysisget_performance_metricsget_session_detailsget_session_eventsget_user_journeyget_user_sessionslist_projectssearch_sessionsaggregate_sessionsexecute_custom_queryget_errors_issuesget_funnel_analysisget_performance_metricsget_session_detailsget_session_eventsget_user_journeyget_user_sessionslist_projectssearch_sessionsaggregate_sessionsexecute_custom_queryget_errors_issuesget_funnel_analysisget_performance_metricsget_session_detailsget_session_eventsget_user_journeyget_user_sessionslist_projectssearch_sessionsScored across 11 tools
Most tools have distinct purposes, such as aggregate_sessions for metrics, get_session_details for comprehensive data, and get_funnel_analysis for user paths. However, get_session_events and get_session_details could be confused as both retrieve session data, though their scopes differ (events only vs. all details).
All tool names follow a consistent verb_noun pattern using snake_case, such as aggregate_sessions, get_session_details, and list_projects. This uniformity makes the tool set predictable and easy to navigate for an agent.
With 11 tools, the count is well-suited for a session analytics domain, covering key operations like querying, analyzing, and managing sessions and projects. Each tool appears purposeful without being overwhelming or insufficient.
The tool set provides strong coverage for session analytics, including data retrieval, aggregation, error analysis, and user journey tracking. A minor gap exists in management operations, such as creating or deleting sessions or projects, but core analytical workflows are well-supported.
Session replays, JS errors, funnel drop-offs and revenue-loss diagnostics.
Query real user session replay data: tapes, transcripts, error/rage-click filters, alerts.
Query your Betterlytics web analytics from AI agents: traffic, funnels, journeys, errors, uptime.
AI access to Hitsteps analytics, live visitors, uptime, goals, alerts, and chats.
