elasticsearch-mcp-vsee 0.5.5 → 0.5.7

package/README.md

@@ -14,7 +14,7 @@
 - **🔐 Secure by Design**: Input validation, script sanitization, injection prevention
 - **☁️ Elastic Cloud Ready**: Native support for cloud ID and API key authentication  
 - **⚡ High Performance**: Connection pooling, optimized query execution, efficient aggregations
-- **🛠️ Comprehensive Tools**: 11 specialized tools for analytics, summaries, and data exploration
+- **🛠️ Comprehensive Tools**: 9 specialized tools for analytics, summaries, and data exploration
 - **📊 Advanced Querying**: Full Elasticsearch DSL support with aggregations and highlighting
 - **🔍 Smart Validation**: Zod-based schemas with security-first validation
 - **📝 Full TypeScript**: Complete type safety with strict null checks
@@ -48,7 +48,7 @@ The MCP server is configured in `vsee/mcp/config.json`:
 }
 ```
 
-The Open WebUI deployment automatically loads this configuration and starts the MCP server via MCPO, making all 11 tools available to the LLM for querying Elasticsearch data.
+The Open WebUI deployment automatically loads this configuration and starts the MCP server via MCPO, making all 9 tools available to the LLM for querying Elasticsearch data.
 
 ## 🔄 Updating and Publishing
 
@@ -93,15 +93,14 @@ After publishing a new version to npm:
 | Tool | Description | Use Cases |
 |------|-------------|-----------|
 | `search_elasticsearch` | Advanced search with aggregations | Custom queries, data analysis |
-| `get_index_fields` | Discover index fields and types | Schema exploration, field discovery |
+| `get_index_fields` | Discover index fields and types (defaults to stats-*) | Schema exploration, field discovery |
 | `top_change` | Find top accounts or groups with highest visit increase/decrease | Trend analysis, account/group monitoring |
 | `get_subscription_breakdown` | Compare subscription tiers with metrics per tier | Subscription-tier analysis and comparisons |
-| `get_account_summary` | Comprehensive statistics for a specific account | Account analytics, performance review |
-| `get_group_summary` | Group statistics with account breakdown | Group management, resource allocation |
-| `get_platform_breakdown` | Platform or platform version breakdown (provider/patient, platform/version) | Platform adoption, device preferences, version analysis |
+| `get_platform_breakdown` | Platform or platform version breakdown (provider/patient, platform/version) with optional account/group filtering | Platform adoption, device preferences, version analysis |
 | `get_rating_distribution` | Rating histograms with statistics | Satisfaction analysis |
 | `get_visit_trends` | Time series visit trends (daily/weekly/monthly) | Trend visualization |
-| `get_usage_summary` | Comprehensive metrics summary with flexible filtering and grouping | Multi-dimensional analysis and comparisons |
+| `get_usage_summary` | Comprehensive metrics summary with flexible filtering and grouping (replaces get_account_summary and get_group_summary) | Multi-dimensional analysis and comparisons |
+| `find_entities_by_metric` | Find groups or accounts based on metric thresholds | Entity discovery, filtering by performance metrics |
 
 ## 📋 Tool Examples
 
@@ -137,15 +136,16 @@ After publishing a new version to npm:
 }
 ```
 
-### Get Account Summary
+### Get Usage Summary (Account or Group)
 
 ```json
 {
-  "tool": "get_account_summary",
+  "tool": "get_usage_summary",
   "arguments": {
     "account": "example-customer",
     "startDate": "now-1y",
-    "endDate": "now"
+    "endDate": "now",
+    "groupBy": "none"
   }
 }
 ```
@@ -159,8 +159,8 @@ After publishing a new version to npm:
     "groupBy": "account",
     "direction": "increase",
     "topN": 10,
-    "currentPeriodDays": 30,
-    "previousPeriodDays": 30
+    "startDate": "now-30d",
+    "endDate": "now"
   }
 }
 ```
@@ -175,7 +175,9 @@ After publishing a new version to npm:
     "breakdownType": "version",
     "topN": 10,
     "startDate": "now-30d",
-    "endDate": "now"
+    "endDate": "now",
+    "account": "optional-account-name",
+    "group": "optional-group-name"
   }
 }
 ```
@@ -355,6 +357,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## 🏷️ Version History
 
+- **v0.6.0** - Removed `get_account_summary` and `get_group_summary` (functionality consolidated into `get_usage_summary`), standardized subscription enum values, added date capping to high-risk tools, optimized queries with `track_total_hits: false`, fixed `average_per_period` calculation in grouped visit trends
 - **v0.5.0** - Added `find_entities_by_metric` tool with multi-metric filtering support, updated default limits
 - **v0.4.0** - Tool consolidation: merged 14 tools into 11 specialized analytics tools
 - **v0.3.0** - Specialized analytics tools for stats-* indices

package/build/errors/handlers.d.ts

@@ -22,6 +22,7 @@ export declare class RateLimitError extends ElasticMCPError {
 }
 export declare class ElasticsearchError extends ElasticMCPError {
     constructor(message: string, originalError?: Error, context?: Record<string, unknown>);
+    static fromResponseError(error: any, toolName: string, args?: unknown): ElasticsearchError;
 }
 export interface ErrorResponse {
     error: {

package/build/errors/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/errors/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAG3D,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAY,EACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAUpC;AAED,qBAAa,eAAgB,SAAQ,eAAe;gBACtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,qBAAa,eAAgB,SAAQ,eAAe;gBACtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,qBAAa,mBAAoB,SAAQ,eAAe;gBAC1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,qBAAa,aAAc,SAAQ,eAAe;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,qBAAa,cAAe,SAAQ,eAAe;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,qBAAa,kBAAmB,SAAQ,eAAe;gBACzC,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAUtF;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC7C,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;KAC/B,CAAC;CACH;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,MAAM;IAI1B,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa;IA+D9D,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAwBzC,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa;CA2BnD"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/errors/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAG3D,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAY,EACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAUpC;AAED,qBAAa,eAAgB,SAAQ,eAAe;gBACtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,qBAAa,eAAgB,SAAQ,eAAe;gBACtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,qBAAa,mBAAoB,SAAQ,eAAe;gBAC1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,qBAAa,aAAc,SAAQ,eAAe;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,qBAAa,cAAe,SAAQ,eAAe;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED,qBAAa,kBAAmB,SAAQ,eAAe;gBACzC,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAWrF,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,kBAAkB;CAkF3F;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC7C,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;KAC/B,CAAC;CACH;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,MAAM;IAI1B,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa;IA+D9D,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAwBzC,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa;CA2BnD"}

package/build/errors/handlers.js

@@ -61,6 +61,67 @@ class ElasticsearchError extends ElasticMCPError {
         });
         this.name = 'ElasticsearchError';
     }
+    static fromResponseError(error, toolName, args) {
+        // Check for circuit breaking exception (data too large)
+        const errorBody = error.body || error.meta?.body || {};
+        const errorType = errorBody.error?.type || errorBody.type;
+        const errorReason = errorBody.error?.reason || errorBody.reason || error.message || '';
+        // Check for circuit breaking or data-related errors
+        if (errorType === 'circuit_breaking_exception' ||
+            errorReason.toLowerCase().includes('circuit_breaking_exception') ||
+            errorReason.toLowerCase().includes('data too large') ||
+            errorReason.toLowerCase().includes('would be') ||
+            errorReason.toLowerCase().includes('larger than the limit')) {
+            const rootCauses = errorBody.error?.root_cause || [];
+            const dataSizeInfo = rootCauses.find((cause) => cause.reason?.includes('would be') || cause.reason?.includes('larger than'));
+            let dataUsageMessage = 'Query exceeded Elasticsearch data usage limits. ';
+            if (dataSizeInfo?.reason) {
+                dataUsageMessage += dataSizeInfo.reason;
+            }
+            else if (errorReason) {
+                dataUsageMessage += errorReason;
+            }
+            else {
+                dataUsageMessage += 'The query requires too much memory to execute.';
+            }
+            dataUsageMessage += ' Try reducing the date range, adding filters (account/group/subscription), or using a smaller time interval.';
+            return new ElasticsearchError(dataUsageMessage, error, {
+                tool: toolName,
+                args,
+                errorType: 'DATA_USAGE_LIMIT_EXCEEDED',
+                elasticsearchError: {
+                    type: errorType,
+                    reason: errorReason,
+                    rootCauses: rootCauses.map((cause) => ({
+                        type: cause.type,
+                        reason: cause.reason,
+                    })),
+                },
+            });
+        }
+        // Check for other common Elasticsearch errors
+        if (errorType === 'query_shard_exception' || errorReason.toLowerCase().includes('query_shard_exception')) {
+            return new ElasticsearchError(`Elasticsearch query error: ${errorReason || 'Query execution failed'}. Try adjusting your query parameters.`, error, {
+                tool: toolName,
+                args,
+                errorType: 'QUERY_ERROR',
+                elasticsearchError: {
+                    type: errorType,
+                    reason: errorReason,
+                },
+            });
+        }
+        // Generic Elasticsearch error with more context
+        return new ElasticsearchError(`Elasticsearch error: ${errorReason || error.message || 'Unknown error occurred'}`, error, {
+            tool: toolName,
+            args,
+            errorType: errorType || 'UNKNOWN',
+            elasticsearchError: {
+                type: errorType,
+                reason: errorReason,
+            },
+        });
+    }
 }
 exports.ElasticsearchError = ElasticsearchError;
 class ErrorHandler {

package/build/errors/handlers.js.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/errors/handlers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/errors/handlers.ts"],"names":[],"mappings":"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"}

package/build/server.d.ts

@@ -8,8 +8,6 @@ export declare class ElasticMCPServer {
     private getIndexFieldsTool;
     private topChangeTool;
     private periodSummaryTool;
-    private getAccountSummaryTool;
-    private getGroupSummaryTool;
     private getPlatformBreakdownTool;
     private getRatingDistributionTool;
     private getVisitTrendsTool;

package/build/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAqBA,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,cAAc,CAAS;IAG/B,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,qBAAqB,CAAwB;IACrD,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,wBAAwB,CAA2B;IAC3D,OAAO,CAAC,yBAAyB,CAA4B;IAC7D,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,wBAAwB,CAA2B;;IAoC3D,OAAO,CAAC,aAAa;IAodrB,OAAO,CAAC,qBAAqB;IAoCvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB7B;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAmBA,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,cAAc,CAAS;IAE/B,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,wBAAwB,CAA2B;IAC3D,OAAO,CAAC,yBAAyB,CAA4B;IAC7D,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,wBAAwB,CAA2B;;IAiC3D,OAAO,CAAC,aAAa;IAobrB,OAAO,CAAC,qBAAqB;IAoCvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB7B;AAED,eAAe,gBAAgB,CAAC"}

package/build/server.js

@@ -16,12 +16,9 @@ class ElasticMCPServer {
     elasticsearch;
     errorHandler;
     isShuttingDown = false;
-    // Tools
     getIndexFieldsTool;
     topChangeTool;
     periodSummaryTool;
-    getAccountSummaryTool;
-    getGroupSummaryTool;
     getPlatformBreakdownTool;
     getRatingDistributionTool;
     getVisitTrendsTool;
@@ -40,12 +37,9 @@ class ElasticMCPServer {
                 tools: {},
             },
         });
-        // Initialize tools
         this.getIndexFieldsTool = new index_js_2.GetIndexFieldsTool(this.elasticsearch, this.logger);
         this.topChangeTool = new index_js_2.TopChangeTool(this.elasticsearch, this.logger);
         this.periodSummaryTool = new index_js_2.PeriodSummaryTool(this.elasticsearch, this.logger);
-        this.getAccountSummaryTool = new index_js_2.GetAccountSummaryTool(this.elasticsearch, this.logger);
-        this.getGroupSummaryTool = new index_js_2.GetGroupSummaryTool(this.elasticsearch, this.logger);
         this.getPlatformBreakdownTool = new index_js_2.GetPlatformBreakdownTool(this.elasticsearch, this.logger);
         this.getRatingDistributionTool = new index_js_2.GetRatingDistributionTool(this.elasticsearch, this.logger);
         this.getVisitTrendsTool = new index_js_2.GetVisitTrendsTool(this.elasticsearch, this.logger);
@@ -61,13 +55,14 @@ class ElasticMCPServer {
                 tools: [
                     {
                         name: 'get_index_fields',
-                        description: 'Get all fields from an Elasticsearch index with optional filtering by field name and type. Use this tool when you need to discover available fields, their types, and correct field names before constructing queries. This is especially useful when unsure about field names or when looking for fields with specific types (e.g., keyword fields for exact matches or text fields for full-text search).',
+                        description: 'Get all fields from an Elasticsearch index with optional filtering by field name and type. Use this tool when you need to discover available fields, their types, and correct field names before constructing queries. This is especially useful when unsure about field names or when looking for fields with specific types (e.g., keyword fields for exact matches or text fields for full-text search). ⚠️ IMPORTANT: Do NOT specify the index parameter unless the user explicitly requests fields from a different index. The tool defaults to "stats-*" which covers all standard indices. Only include the index parameter if the user specifically mentions a different index name.',
                         inputSchema: {
                             type: 'object',
                             properties: {
                                 index: {
                                     type: 'string',
-                                    description: 'Index name or pattern (supports wildcards like stats-*)',
+                                    description: 'Index name or pattern (supports wildcards like stats-*). Defaults to "stats-*" if not specified. Only specify if you need fields from a different index.',
+                                    default: 'stats-*',
                                 },
                                 fieldFilter: {
                                     type: 'string',
@@ -83,13 +78,13 @@ class ElasticMCPServer {
                                     default: true,
                                 },
                             },
-                            required: ['index'],
+                            required: [],
                             additionalProperties: false,
                         },
                     },
                     {
                         name: 'top_change',
-                        description: 'Find top 5 accounts or groups with highest visit increase or decrease between two consecutive time periods. Returns items ranked by change with current period count, previous period count, absolute change, and percentage change. Supports filtering by subscription tier, and by group (when grouping by account). ⚠️ Data limits: Max 30 days per period (may auto-reduce to 14 days if both periods are 30). This tool aggregates ALL accounts before sorting, making it memory-intensive. Always returns top 5 results.',
+                        description: 'Find top N accounts or groups with highest visit/usage increase or decrease between two consecutive time periods. Returns items ranked by change with current period count, previous period count, absolute change, and percentage change. The previous period is automatically calculated to match the duration of the current period, ending where the current period starts. Supports filtering by subscription tier.',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -103,105 +98,53 @@ class ElasticMCPServer {
                                     enum: ['increase', 'decrease'],
                                     description: 'Direction: "increase" for highest growth, "decrease" for highest decline',
                                 },
-                                currentPeriodDays: {
-                                    type: 'number',
-                                    minimum: 1,
-                                    maximum: 365,
-                                    default: 30,
-                                    description: 'Number of days for current period (default: 30). ⚠️ Recommended: 14-30 days maximum to prevent data limit errors. Tool automatically caps at 30 days (may reduce to 14 if both periods are 30). Note: This tool aggregates ALL accounts before sorting, so large periods can cause memory issues.',
-                                },
-                                previousPeriodDays: {
+                                topN: {
                                     type: 'number',
                                     minimum: 1,
-                                    maximum: 365,
-                                    description: 'Number of days for previous period (defaults to same as currentPeriodDays). ⚠️ Recommended: 14-30 days maximum. Tool automatically caps at 30 days (may reduce to 14 if both periods are 30). Note: Large periods can cause memory issues as all accounts must be aggregated first.',
-                                },
-                                subscription: {
-                                    type: 'string',
-                                    description: 'Optional subscription tier to filter by',
-                                },
-                                group: {
-                                    type: 'string',
-                                    description: 'Optional group name to filter by (only valid when groupBy is "account")',
-                                },
-                            },
-                            required: ['groupBy', 'direction'],
-                            additionalProperties: false,
-                        },
-                    },
-                    {
-                        name: 'get_subscription_breakdown',
-                        description: 'Compare subscription tiers (Plus, Basic, etc.) across a time period. Always returns metrics grouped by subscription tier with per-tier breakdown (visits, accounts, providers, patients, ratings, call duration) plus totals. Use predefined period types (weekly/monthly/yearly) or custom date ranges. Automatically filters out test visits. ⚠️ Data limits: Max 365 days for yearly, 90 days for other periods. Tool automatically caps time periods to prevent errors. Best for subscription-tier analysis and comparisons.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                period: {
-                                    type: 'string',
-                                    enum: ['weekly', 'monthly', 'yearly'],
-                                    description: 'Time period type: "weekly" (defaults to last 7 days), "monthly" (defaults to last 30 days), or "yearly" (defaults to last 365 days)',
+                                    maximum: 50,
+                                    default: 5,
+                                    description: 'Number of top items to return (default: 5, max: 50)',
                                 },
                                 startDate: {
                                     type: 'string',
-                                    description: 'Start date in ISO format (YYYY-MM-DD) or date math (e.g., "now-30d", "2024-01-01"). Defaults to period-appropriate range relative to now',
+                                    description: 'Start date for current period in ISO format (YYYY-MM-DD) or date math (e.g., "now-30d", "now-1y"). Defaults to "now-30d"',
                                 },
                                 endDate: {
                                     type: 'string',
-                                    description: 'End date in ISO format (YYYY-MM-DD) or date math (e.g., "now"). Defaults to "now"',
-                                },
-                            },
-                            required: ['period'],
-                            additionalProperties: false,
-                        },
-                    },
-                    {
-                        name: 'get_account_summary',
-                        description: 'Get comprehensive statistics for a specific account over a time period. Returns subscription distribution, record counts, unique providers/patients, average call duration, and average ratings. Automatically filters out test visits and includes only valid meeting data. Default time period is last year. ⚠️ Data limits: Max 365 days. Tool automatically caps time periods to prevent errors.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                account: {
-                                    type: 'string',
-                                    description: 'Account name to summarize',
+                                    description: 'End date for current period in ISO format (YYYY-MM-DD) or date math (e.g., "now"). Defaults to "now"',
                                 },
-                                startDate: {
-                                    type: 'string',
-                                    description: 'Start date in ISO format (YYYY-MM-DD) or date math (e.g., "now-30d", "now-1y"). Defaults to "now-1y"',
-                                },
-                                endDate: {
+                                subscription: {
                                     type: 'string',
-                                    description: 'End date in ISO format (YYYY-MM-DD) or date math (e.g., "now"). Defaults to "now"',
+                                    enum: ['Enterprise', 'Premium', 'FVC', 'BVC', 'Plus'],
+                                    description: 'Optional subscription tier to filter by',
                                 },
                             },
-                            required: ['account'],
+                            required: ['groupBy', 'direction'],
                             additionalProperties: false,
                         },
                     },
                     {
-                        name: 'get_group_summary',
-                        description: 'Get summary statistics for a specific group over a time period, broken down by top 5 accounts plus "Other" category if needed. Returns group-level metrics and per-account breakdown for top accounts. Automatically filters out test visits and includes only valid meeting data. Default time period is last year. ⚠️ Data limits: Max 365 days. Tool automatically caps time periods to prevent errors.',
+                        name: 'get_subscription_breakdown',
+                        description: 'Compare subscription tiers (Enterprise, Premium, FVC, BVC, Plus) across a time period. Always returns metrics grouped by subscription tier with per-tier breakdown (visits, accounts, providers, patients, ratings, call duration) plus totals.',
                         inputSchema: {
                             type: 'object',
                             properties: {
-                                group: {
-                                    type: 'string',
-                                    description: 'Group name to summarize',
-                                },
                                 startDate: {
                                     type: 'string',
-                                    description: 'Start date in ISO format (YYYY-MM-DD) or date math (e.g., "now-30d", "now-1y"). Defaults to "now-1y"',
+                                    description: 'Start date in ISO format (YYYY-MM-DD) or date math (e.g., "now-30d", "now-1y"). Defaults to "now-30d"',
                                 },
                                 endDate: {
                                     type: 'string',
                                     description: 'End date in ISO format (YYYY-MM-DD) or date math (e.g., "now"). Defaults to "now"',
                                 },
                             },
-                            required: ['group'],
+                            required: [],
                             additionalProperties: false,
                         },
                     },
                     {
                         name: 'get_platform_breakdown',
-                        description: 'Get breakdown of top N platforms or platform versions by usage over a time period. Supports both provider and patient roles, and both platform-level (Web/iOS/Android) and platform-version-level breakdowns. Returns top N items (default 10) plus "Other" category if needed, with metrics per item including visit counts, unique accounts/providers/patients, ratings, and call duration. Automatically filters out test visits and includes only valid meeting data. Default time period is last 14 days. Recommended: max 30 days to prevent data limit errors, especially for patient platform breakdowns which have many unique platforms.',
+                        description: 'Get breakdown of top N platforms or platform versions by usage over a time period, can optionally be filtered by account or group. Supports both provider and patient roles. Returns top N items (default 10) plus "Other" category if needed, with metrics per item including visit counts, unique accounts/providers/patients, ratings, and call duration.',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -224,12 +167,20 @@ class ElasticMCPServer {
                                 },
                                 startDate: {
                                     type: 'string',
-                                    description: 'Start date. Format: ISO date (YYYY-MM-DD) or date math (now-30d, now-1y). Default: now-30d. ⚠️ Tool may cap to prevent data limits (max 90 days, 60 days when grouping).',
+                                    description: 'Start date. Format: ISO date (YYYY-MM-DD) or date math (now-30d, now-1y). Default: now-30d.',
                                 },
                                 endDate: {
                                     type: 'string',
                                     description: 'End date. Format: ISO date (YYYY-MM-DD) or date math (now). Default: now.',
                                 },
+                                account: {
+                                    type: 'string',
+                                    description: 'Optional account name to filter data to',
+                                },
+                                group: {
+                                    type: 'string',
+                                    description: 'Optional group name to filter data to',
+                                },
                             },
                             required: ['role', 'breakdownType'],
                             additionalProperties: false,
@@ -237,7 +188,7 @@ class ElasticMCPServer {
                     },
                     {
                         name: 'get_rating_distribution',
-                        description: 'Get rating distribution (histogram) for provider and/or patient ratings over a time period. Returns rating buckets with counts and percentages, plus statistics (average, min, max, total count). Supports grouping by subscription, account, or group for comparative analysis. Automatically filters out test visits and includes only valid meeting data. Default time period is last 30 days. ⚠️ Data limits: Max 90 days (60 days when grouping). Tool automatically caps time periods to prevent errors.',
+                        description: 'Get rating distribution (histogram) for provider and/or patient ratings over a time period. Returns rating buckets with counts and percentages, plus statistics (average, min, max, total count). Supports grouping by subscription, account, or group for comparative analysis.',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -255,7 +206,7 @@ class ElasticMCPServer {
                                 },
                                 startDate: {
                                     type: 'string',
-                                    description: 'Start date. Format: ISO date (YYYY-MM-DD) or date math (now-30d, now-1y). Default: now-30d. ⚠️ Tool may cap to prevent data limits (max 90 days, 60 days when grouping).',
+                                    description: 'Start date. Format: ISO date (YYYY-MM-DD) or date math (now-30d, now-1y). Default: now-30d.',
                                 },
                                 endDate: {
                                     type: 'string',
@@ -271,6 +222,7 @@ class ElasticMCPServer {
                                 },
                                 subscription: {
                                     type: 'string',
+                                    enum: ['Enterprise', 'Premium', 'FVC', 'BVC', 'Plus'],
                                     description: 'Optional subscription tier to filter by',
                                 },
                                 groupBy: {
@@ -286,14 +238,14 @@ class ElasticMCPServer {
                     },
                     {
                         name: 'get_visit_trends',
-                        description: 'Get visit count trends over time (daily, weekly, or monthly intervals) with optional grouping by subscription, account, or group. Returns time series data points with visit counts and unique counts (accounts, providers, patients) per period. Automatically filters out test visits and includes only valid meeting data. Recommended combinations: daily interval with 7-14 days, weekly interval with 12 weeks (3 months), monthly interval with 12 months (1 year). The tool automatically adjusts time periods to prevent data limit errors. Default time period is last 6 months (180 days).',
+                        description: 'Get visit/usage count trends over time (daily, weekly, or monthly intervals) with optional grouping by subscription, account, or group. Returns time series data points with visit counts and unique counts (accounts, providers, patients) per period.',
                         inputSchema: {
                             type: 'object',
                             properties: {
                                 interval: {
                                     type: 'string',
                                     enum: ['daily', 'weekly', 'monthly'],
-                                    description: 'Time interval for trends: "daily" (recommended max 14 days), "weekly" (recommended max 12 weeks), or "monthly" (recommended max 12 months)',
+                                    description: 'Time interval for trends: "weekly"(recommended max 12 weeks), or "monthly" (recommended max 12 months)',
                                 },
                                 startDate: {
                                     type: 'string',
@@ -319,6 +271,7 @@ class ElasticMCPServer {
                                 },
                                 subscription: {
                                     type: 'string',
+                                    enum: ['Enterprise', 'Premium', 'FVC', 'BVC', 'Plus'],
                                     description: 'Optional subscription tier to filter by',
                                 },
                             },
@@ -328,13 +281,13 @@ class ElasticMCPServer {
                     },
                     {
                         name: 'get_usage_summary',
-                        description: 'Get comprehensive metrics summary for a time period. Returns overall summary (visits, unique counts, ratings, call duration) plus distribution breakdowns (subscription tiers, provider platforms, patient platforms). Supports flexible filtering (by account/group/subscription) and optional grouping (by subscription/account/group) for comparative analysis. Automatically filters out test visits. Default time period is last 30 days. ⚠️ Data limits: Max 90 days (60 days when grouping). Tool automatically caps time periods to prevent errors. Best for flexible analysis and multi-dimensional summaries.',
+                        description: 'Get usage summary for a time period, can optionally be filtered by account, group, or subscription. Returns visits, unique counts, ratings, call duration plus distribution breakdowns (subscription tiers, provider platforms, patient platforms).',
                         inputSchema: {
                             type: 'object',
                             properties: {
                                 startDate: {
                                     type: 'string',
-                                    description: 'Start date. Format: ISO date (YYYY-MM-DD) or date math (now-30d, now-1y). Default: now-30d. ⚠️ Tool may cap to prevent data limits (max 90 days, 60 days when grouping).',
+                                    description: 'Start date. Format: ISO date (YYYY-MM-DD) or date math (now-30d, now-1y). Default: now-30d.',
                                 },
                                 endDate: {
                                     type: 'string',
@@ -351,6 +304,7 @@ class ElasticMCPServer {
                                 subscription: {
                                     type: 'string',
                                     description: 'FILTER: Optional subscription tier to filter data to',
+                                    enum: ['Enterprise', 'Premium', 'FVC', 'BVC', 'Plus'],
                                 },
                                 groupBy: {
                                     type: 'string',
@@ -365,7 +319,7 @@ class ElasticMCPServer {
                     },
                     {
                         name: 'find_entities_by_metric',
-                        description: 'Find groups or accounts filtered by metrics. Supports single metric (legacy) or multiple metrics (recommended). Available metrics: account_count (groups only), visit_count, provider_rating, patient_rating, avg_call_duration, unique_providers, unique_patients, provider_rating_count, patient_rating_count. Can filter accounts by group. Returns entities matching ALL criteria with their metric values. Automatically filters out test visits. Default time period is last year.',
+                        description: 'Find groups or accounts filtered by metrics. Supports single metric (legacy) or multiple metrics (recommended). Available metrics: account_count (groups only), visit_count, provider_rating, patient_rating, avg_call_duration, unique_providers, unique_patients, provider_rating_count, patient_rating_count. Can filter accounts by group. Returns entities matching ALL criteria with their metric values.',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -421,6 +375,7 @@ class ElasticMCPServer {
                                 },
                                 subscription: {
                                     type: 'string',
+                                    enum: ['Enterprise', 'Premium', 'FVC', 'BVC', 'Plus'],
                                     description: 'Optional subscription tier to filter by',
                                 },
                                 group: {
@@ -451,7 +406,6 @@ class ElasticMCPServer {
             try {
                 // Don't check connection status - let the actual API calls handle connection errors
                 // Connection checks often fail with limited permissions unnecessarily
-                // Execute the appropriate tool
                 let result;
                 switch (name) {
                     case 'get_index_fields':
@@ -463,12 +417,6 @@ class ElasticMCPServer {
                     case 'get_subscription_breakdown':
                         result = await this.periodSummaryTool.execute(args);
                         break;
-                    case 'get_account_summary':
-                        result = await this.getAccountSummaryTool.execute(args);
-                        break;
-                    case 'get_group_summary':
-                        result = await this.getGroupSummaryTool.execute(args);
-                        break;
                     case 'get_platform_breakdown':
                         result = await this.getPlatformBreakdownTool.execute(args);
                         break;
@@ -502,11 +450,23 @@ class ElasticMCPServer {
                     toolName: name,
                     error: errorResponse.error,
                 });
+                // Format error message with more context for data usage errors
+                let errorText = `Error: ${errorResponse.error.message}`;
+                // Add additional context for data usage errors
+                if (errorResponse.error.code === 'ELASTICSEARCH_ERROR' &&
+                    errorResponse.error.context?.errorType === 'DATA_USAGE_LIMIT_EXCEEDED') {
+                    errorText = `❌ Data Usage Error: ${errorResponse.error.message}\n\n` +
+                        `This query exceeded Elasticsearch memory limits. Suggestions:\n` +
+                        `• Reduce the date range (e.g., use "now-30d" instead of "now-1y")\n` +
+                        `• Add filters (account, group, or subscription)\n` +
+                        `• Use a smaller time interval (e.g., daily instead of monthly when grouped)\n` +
+                        `• Check the tool's date capping limits in the documentation`;
+                }
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: `Error: ${errorResponse.error.message}`,
+                            text: errorText,
                         },
                     ],
                     isError: true,