portkey-admin-mcp 0.2.0 → 0.3.0

package/build/server.js

@@ -1453,9 +1453,6 @@ var TracingService = class extends BaseService {
       data
     );
   }
-  async getTrace(id) {
-    return this.get(`/logs/${this.encodePathSegment(id)}`);
-  }
 };
 
 // src/services/users.service.ts
@@ -1689,23 +1686,99 @@ var baseAnalyticsSchema = {
   prompt_token_max: z.coerce.number().positive().optional().describe("Maximum number of prompt tokens"),
   completion_token_min: z.coerce.number().positive().optional().describe("Minimum number of completion tokens"),
   completion_token_max: z.coerce.number().positive().optional().describe("Maximum number of completion tokens"),
-  status_code: z.string().optional().describe("Filter by specific HTTP status codes (comma-separated)"),
+  status_code: z.string().optional().describe(
+    "Legacy Portkey query param for HTTP status codes. Comma-separated string; prefer status_codes for structured inputs."
+  ),
   weighted_feedback_min: z.coerce.number().min(-10).max(10).optional().describe("Minimum weighted feedback score (-10 to 10)"),
   weighted_feedback_max: z.coerce.number().min(-10).max(10).optional().describe("Maximum weighted feedback score (-10 to 10)"),
-  virtual_keys: z.string().optional().describe("Filter by specific virtual key slugs (comma-separated)"),
-  configs: z.string().optional().describe("Filter by specific config slugs (comma-separated)"),
+  virtual_keys: z.string().optional().describe(
+    "Legacy Portkey query param for virtual key slugs. Comma-separated string; prefer virtual_key_slugs for structured inputs."
+  ),
+  configs: z.string().optional().describe(
+    "Legacy Portkey query param for config slugs. Comma-separated string; prefer config_slugs for structured inputs."
+  ),
+  status_codes: z.array(z.string()).optional().describe(
+    "Structured alias for status_code. Use an array of HTTP status codes; normalized to the legacy comma-separated Portkey query param."
+  ),
+  virtual_key_slugs: z.array(z.string()).optional().describe(
+    "Structured alias for virtual_keys. Use an array of virtual key slugs; normalized to the legacy comma-separated Portkey query param."
+  ),
+  config_slugs: z.array(z.string()).optional().describe(
+    "Structured alias for configs. Use an array of config slugs; normalized to the legacy comma-separated Portkey query param."
+  ),
   workspace_slug: z.string().optional().describe("Filter by specific workspace"),
-  api_key_ids: z.string().optional().describe("Filter by specific API key UUIDs (comma-separated)"),
+  api_key_ids: z.preprocess((value) => {
+    if (value == null) {
+      return value;
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => String(item)).join(",");
+    }
+    return value;
+  }, z.string().optional()).describe(
+    "Legacy Portkey query param for API key UUIDs. Comma-separated string; request_analytics also accepts an array and normalizes it to this form."
+  ),
   metadata: z.string().optional().describe(
-    `Stringified JSON object for metadata filtering, e.g. '{"env":"prod","app":"myapp"}'.`
+    `Legacy Portkey query param for metadata filtering. Stringified JSON object, e.g. '{"env":"prod","app":"myapp"}'; prefer metadata_filter for structured inputs.`
   ),
   ai_org_model: z.string().optional().describe(
-    "Filter by provider and model, format: 'provider__model' with double underscore, e.g. 'openai__gpt-4' or 'anthropic__claude-3-opus'. Comma-separated for multiple."
+    "Legacy Portkey query param for provider/model pairs. Format: 'provider__model' with double underscore, e.g. 'openai__gpt-4' or 'anthropic__claude-3-opus'. Comma-separated string; prefer provider_models for structured inputs."
+  ),
+  provider_models: z.array(z.string()).optional().describe(
+    "Structured alias for ai_org_model. Use provider__model strings in an array; normalized to the legacy comma-separated Portkey query param."
+  ),
+  trace_id: z.string().optional().describe(
+    "Legacy Portkey query param for trace IDs. Comma-separated string; prefer trace_ids for structured inputs."
+  ),
+  trace_ids: z.array(z.string()).optional().describe(
+    "Structured alias for trace_id. Use an array of trace IDs; normalized to the legacy comma-separated Portkey query param."
+  ),
+  span_id: z.string().optional().describe(
+    "Legacy Portkey query param for span IDs. Comma-separated string; prefer span_ids for structured inputs."
+  ),
+  span_ids: z.array(z.string()).optional().describe(
+    "Structured alias for span_id. Use an array of span IDs; normalized to the legacy comma-separated Portkey query param."
+  ),
+  metadata_filter: z.record(z.string(), z.unknown()).optional().describe(
+    "Structured alias for metadata. Use an object such as { env: 'prod' }; normalized to a JSON string before the request is sent."
   ),
-  trace_id: z.string().optional().describe("Filter by trace IDs (comma-separated)"),
-  span_id: z.string().optional().describe("Filter by span IDs (comma-separated)"),
   prompt_slug: z.string().optional().describe("Filter by prompt slug")
 };
+var requestAnalyticsSchema = {
+  ...baseAnalyticsSchema,
+  status_codes: z.array(z.string()).optional().describe(
+    "Structured alias for status_code. Use an array of HTTP status codes; normalized to the legacy comma-separated Portkey query param."
+  ),
+  virtual_key_slugs: z.array(z.string()).optional().describe(
+    "Structured alias for virtual_keys. Use an array of virtual key slugs; normalized to the legacy comma-separated Portkey query param."
+  ),
+  config_slugs: z.array(z.string()).optional().describe(
+    "Structured alias for configs. Use an array of config slugs; normalized to the legacy comma-separated Portkey query param."
+  ),
+  api_key_ids: z.preprocess((value) => {
+    if (value == null) {
+      return value;
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => String(item)).join(",");
+    }
+    return value;
+  }, z.string().optional()).describe(
+    "API key UUIDs. Accepts the legacy comma-separated string or a structured array; normalized to the legacy Portkey query param before the request is sent."
+  ),
+  trace_ids: z.array(z.string()).optional().describe(
+    "Structured alias for trace_id. Use an array of trace IDs; normalized to the legacy comma-separated Portkey query param."
+  ),
+  span_ids: z.array(z.string()).optional().describe(
+    "Structured alias for span_id. Use an array of span IDs; normalized to the legacy comma-separated Portkey query param."
+  ),
+  provider_models: z.array(z.string()).optional().describe(
+    "Structured alias for ai_org_model. Use provider__model strings in an array; normalized to the legacy comma-separated Portkey query param."
+  ),
+  metadata_filter: z.record(z.string(), z.unknown()).optional().describe(
+    "Structured alias for metadata. Use an object such as { env: 'prod' }; normalized to a JSON string before the request is sent."
+  )
+};
 var paginatedAnalyticsSchema = {
   ...baseAnalyticsSchema,
   current_page: z.coerce.number().positive().optional().describe("Page number for pagination"),
@@ -1732,13 +1805,88 @@ function formatGroupedAnalytics(analytics, groupLabel) {
     [groupLabel]: analytics.data
   };
 }
+function normalizeCommaSeparatedParam(value) {
+  if (value == null) {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item)).join(",");
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return void 0;
+}
+function normalizeMetadataFilter(value) {
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return void 0;
+}
+function normalizeAnalyticsParams(params) {
+  const {
+    status_codes,
+    virtual_key_slugs,
+    config_slugs,
+    api_key_ids,
+    trace_ids,
+    span_ids,
+    provider_models,
+    metadata_filter,
+    ...legacyParams
+  } = params;
+  const normalizedParams = {
+    ...legacyParams
+  };
+  const statusCode = normalizeCommaSeparatedParam(status_codes) ?? normalizeCommaSeparatedParam(legacyParams.status_code);
+  if (statusCode !== void 0) {
+    normalizedParams.status_code = statusCode;
+  }
+  const virtualKeys = normalizeCommaSeparatedParam(virtual_key_slugs) ?? normalizeCommaSeparatedParam(legacyParams.virtual_keys);
+  if (virtualKeys !== void 0) {
+    normalizedParams.virtual_keys = virtualKeys;
+  }
+  const configs = normalizeCommaSeparatedParam(config_slugs) ?? normalizeCommaSeparatedParam(legacyParams.configs);
+  if (configs !== void 0) {
+    normalizedParams.configs = configs;
+  }
+  const apiKeyIds = normalizeCommaSeparatedParam(api_key_ids) ?? normalizeCommaSeparatedParam(legacyParams.api_key_ids);
+  if (apiKeyIds !== void 0) {
+    normalizedParams.api_key_ids = apiKeyIds;
+  }
+  const metadata = normalizeMetadataFilter(metadata_filter) ?? normalizeMetadataFilter(legacyParams.metadata);
+  if (metadata !== void 0) {
+    normalizedParams.metadata = metadata;
+  }
+  const providerModels = normalizeCommaSeparatedParam(provider_models) ?? normalizeCommaSeparatedParam(legacyParams.ai_org_model);
+  if (providerModels !== void 0) {
+    normalizedParams.ai_org_model = providerModels;
+  }
+  const traceId = normalizeCommaSeparatedParam(trace_ids) ?? normalizeCommaSeparatedParam(legacyParams.trace_id);
+  if (traceId !== void 0) {
+    normalizedParams.trace_id = traceId;
+  }
+  const spanId = normalizeCommaSeparatedParam(span_ids) ?? normalizeCommaSeparatedParam(legacyParams.span_id);
+  if (spanId !== void 0) {
+    normalizedParams.span_id = spanId;
+  }
+  return normalizedParams;
+}
 function registerAnalyticsTools(server, service) {
   server.tool(
     "get_cost_analytics",
-    "Retrieve detailed cost analytics data over time, including total costs and averages per request",
+    "Returns time-series of total and average cost per request over the specified period. Use to track spending trends and identify cost spikes. Differs from get_token_analytics which measures token consumption, not monetary cost. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getCostAnalytics(params);
+      const analytics = await service.analytics.getCostAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       const dataPoints = analytics.data_points.map((point) => ({
         timestamp: point.timestamp,
         total_cost: point.total,
@@ -1766,10 +1914,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_request_analytics",
-    "Retrieve request analytics as time-series data, showing total, successful, and failed requests over time",
-    baseAnalyticsSchema,
+    "Returns time-series of total, successful, and failed request counts over the specified period. Use to monitor traffic volume and success/failure trends. Differs from get_error_analytics which only shows error counts. Requires time_of_generation_min and time_of_generation_max.",
+    requestAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getRequestAnalytics(params);
+      const analytics = await service.analytics.getRequestAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       const dataPoints = analytics.data_points.map((point) => ({
         timestamp: point.timestamp,
         total: point.total,
@@ -1799,10 +1949,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_token_analytics",
-    "Retrieve token usage analytics as time-series data, showing total, prompt, and completion tokens over time",
+    "Returns time-series of total, prompt, and completion token counts over the specified period. Use to track token consumption and identify usage patterns. Differs from get_cost_analytics which shows monetary cost, not token volume. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getTokenAnalytics(params);
+      const analytics = await service.analytics.getTokenAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       const dataPoints = analytics.data_points.map((point) => ({
         timestamp: point.timestamp,
         total: point.total,
@@ -1832,10 +1984,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_latency_analytics",
-    "Retrieve latency analytics as time-series data, showing average, p50, p90, and p99 latency percentiles over time",
+    "Returns time-series of avg, p50, p90, and p99 latency percentiles in ms over the specified period. Use to monitor response times and detect latency regressions. Differs from get_cache_hit_latency which only measures latency for cached responses. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getLatencyAnalytics(params);
+      const analytics = await service.analytics.getLatencyAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       const dataPoints = analytics.data_points.map((point) => ({
         timestamp: point.timestamp,
         avg: point.avg,
@@ -1867,10 +2021,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_error_analytics",
-    "Retrieve error count analytics as time-series data, showing total error counts over time",
+    "Returns time-series of total error counts over the specified period. Use for high-level error trend monitoring. For error breakdown by status code, use get_error_status_codes_analytics or get_error_stacks_analytics; for error rate as a percentage, use get_error_rate_analytics. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getErrorAnalytics(params);
+      const analytics = await service.analytics.getErrorAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       const dataPoints = analytics.data_points.map((point) => ({
         timestamp: point.timestamp,
         total_errors: point.total
@@ -1896,10 +2052,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_error_rate_analytics",
-    "Retrieve error rate analytics as time-series data, showing the percentage of failed requests over time",
+    "Returns time-series of error rate as a percentage of total requests over the specified period. Use to track reliability trends and SLA compliance. Differs from get_error_analytics which shows absolute error counts, not percentages. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getErrorRateAnalytics(params);
+      const analytics = await service.analytics.getErrorRateAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       const dataPoints = analytics.data_points.map((point) => ({
         timestamp: point.timestamp,
         error_rate_percent: point.rate
@@ -1925,10 +2083,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_cache_hit_latency",
-    "Retrieve cache hit latency analytics as time-series data, showing total and average latency for cache hits over time",
+    "Returns time-series of latency specifically for cache hits over the specified period. Use to evaluate cache performance and response speed for cached requests. Differs from get_latency_analytics which measures latency across all requests. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getCacheHitLatency(params);
+      const analytics = await service.analytics.getCacheHitLatency(
+        normalizeAnalyticsParams(params)
+      );
       const dataPoints = analytics.data_points.map((point) => ({
         timestamp: point.timestamp,
         total: point.total,
@@ -1956,10 +2116,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_cache_hit_rate",
-    "Retrieve cache hit rate analytics as time-series data, showing hit rate percentage, total hits, and misses over time",
+    "Returns time-series of cache hit rate percentage, total hits, and misses over the specified period. Use to evaluate cache effectiveness and tune caching strategy. Unrelated to get_cache_hit_latency which measures speed of cached responses, not hit/miss ratio. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getCacheHitRate(params);
+      const analytics = await service.analytics.getCacheHitRate(
+        normalizeAnalyticsParams(params)
+      );
       const dataPoints = analytics.data_points.map((point) => ({
         timestamp: point.timestamp,
         rate: point.rate,
@@ -1989,10 +2151,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_users_analytics",
-    "Retrieve user activity analytics over time, showing active and new user counts",
+    "Returns time-series of active and new user counts over the specified period. Use for user growth tracking and adoption metrics. Differs from get_user_requests_analytics which shows per-user request breakdown, and get_analytics_group_users which shows per-user cost/token data. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getUsersAnalytics(params);
+      const analytics = await service.analytics.getUsersAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       const dataPoints = analytics.data_points.map((point) => ({
         timestamp: point.timestamp,
         active_users: point.active_users,
@@ -2020,10 +2184,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_error_stacks_analytics",
-    "Retrieve error analytics broken down by status code stacks over time",
+    "Returns errors broken down by status code stacks (e.g., 429, 500, 502) over the specified period. Use to identify which error types are most common and how they trend. Differs from get_error_status_codes_analytics which shows unique code distribution rather than stacked/cumulative breakdown. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getErrorStacksAnalytics(params);
+      const analytics = await service.analytics.getErrorStacksAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       return {
         content: [
           {
@@ -2040,10 +2206,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_error_status_codes_analytics",
-    "Retrieve unique error status code distribution analytics over time",
+    "Returns distribution of unique HTTP error status codes over the specified period. Use to see which status codes are occurring and their frequency. Differs from get_error_stacks_analytics which shows stacked/cumulative error breakdown rather than individual code distribution. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getErrorStatusCodesAnalytics(params);
+      const analytics = await service.analytics.getErrorStatusCodesAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       return {
         content: [
           {
@@ -2060,10 +2228,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_user_requests_analytics",
-    "Retrieve per-user request count analytics over time",
+    "Returns per-user request count breakdown over the specified period. Use to identify heavy users and per-user traffic patterns. Differs from get_users_analytics which shows aggregate active/new user counts, not individual user breakdowns. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getUserRequestsAnalytics(params);
+      const analytics = await service.analytics.getUserRequestsAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       return {
         content: [
           {
@@ -2080,10 +2250,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_rescued_requests_analytics",
-    "Retrieve analytics for requests rescued by retry or fallback strategies over time",
+    "Returns time-series of requests saved by retry or fallback strategies over the specified period. Use to evaluate the effectiveness of your Portkey configs' resilience features. Only relevant if configs include retry or fallback targets. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getRescuedRequestsAnalytics(params);
+      const analytics = await service.analytics.getRescuedRequestsAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       return {
         content: [
           {
@@ -2100,10 +2272,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_feedback_analytics",
-    "Retrieve feedback submission analytics over time",
+    "Returns time-series of feedback submission counts over the specified period. Use to track feedback volume trends. For breakdown by model, use get_feedback_models_analytics; for score distribution, use get_feedback_scores_analytics; for weighted scores, use get_feedback_weighted_analytics. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getFeedbackAnalytics(params);
+      const analytics = await service.analytics.getFeedbackAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       return {
         content: [
           {
@@ -2120,10 +2294,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_feedback_models_analytics",
-    "Retrieve feedback analytics grouped by AI model over time",
+    "Returns feedback counts grouped by AI model over the specified period. Use to compare user satisfaction and feedback volume across different models. Differs from get_feedback_analytics which shows total volume without model breakdown. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getFeedbackModelsAnalytics(params);
+      const analytics = await service.analytics.getFeedbackModelsAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       return {
         content: [
           {
@@ -2140,10 +2316,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_feedback_scores_analytics",
-    "Retrieve feedback score distribution analytics over time",
+    "Returns distribution of raw feedback score values over the specified period. Use to understand score patterns (e.g., mostly positive vs mixed). Differs from get_feedback_weighted_analytics which applies weight factors for calibrated metrics. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getFeedbackScoresAnalytics(params);
+      const analytics = await service.analytics.getFeedbackScoresAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       return {
         content: [
           {
@@ -2160,10 +2338,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_feedback_weighted_analytics",
-    "Retrieve weighted feedback analytics over time",
+    "Returns weighted feedback scores over the specified period, applying the weight factor set during feedback creation. Use for calibrated quality metrics where different feedback types have different importance. Differs from get_feedback_scores_analytics which shows raw unweighted scores. Requires time_of_generation_min and time_of_generation_max.",
     baseAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getFeedbackWeightedAnalytics(params);
+      const analytics = await service.analytics.getFeedbackWeightedAnalytics(
+        normalizeAnalyticsParams(params)
+      );
       return {
         content: [
           {
@@ -2180,10 +2360,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_analytics_group_users",
-    "Retrieve analytics data grouped by user with pagination",
+    "Returns analytics data aggregated per user with pagination, showing each user's request count, cost, and token usage. Use for per-user billing, audit, or identifying top consumers. Differs from get_users_analytics which shows aggregate active/new user counts over time. Requires time_of_generation_min and time_of_generation_max.",
     paginatedAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getAnalyticsGroupUsers(params);
+      const analytics = await service.analytics.getAnalyticsGroupUsers(
+        normalizeAnalyticsParams(params)
+      );
       return {
         content: [
           {
@@ -2200,10 +2382,12 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_analytics_group_models",
-    "Retrieve analytics data grouped by AI model with pagination",
+    "Returns analytics data aggregated per AI model with pagination, showing each model's request count, cost, and token usage. Use to compare model costs, popularity, and efficiency. Requires time_of_generation_min and time_of_generation_max.",
     paginatedAnalyticsSchema,
     async (params) => {
-      const analytics = await service.analytics.getAnalyticsGroupModels(params);
+      const analytics = await service.analytics.getAnalyticsGroupModels(
+        normalizeAnalyticsParams(params)
+      );
       return {
         content: [
           {
@@ -2220,13 +2404,13 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_analytics_group_metadata",
-    "Retrieve analytics data grouped by a specific metadata key with pagination",
+    "Returns analytics data grouped by a custom metadata key (e.g., 'env', 'app', 'client_id') with pagination. Use for custom breakdowns like per-environment or per-feature cost analysis. Requires the metadata_key parameter in addition to time_of_generation_min and time_of_generation_max.",
     analyticsGroupMetadataSchema,
     async (params) => {
       const { metadata_key, ...analyticsParams } = params;
       const analytics = await service.analytics.getAnalyticsGroupMetadata(
         metadata_key,
-        analyticsParams
+        normalizeAnalyticsParams(analyticsParams)
       );
       return {
         content: [
@@ -2270,7 +2454,7 @@ var AUDIT_TOOL_SCHEMAS = {
 function registerAuditTools(server, service) {
   server.tool(
     "list_audit_logs",
-    "Retrieve audit logs for your Portkey organization. Audit logs track all administrative actions including user management, configuration changes, and access events. Supports filtering by time range, actor, action type, and resource.",
+    "Retrieve audit logs for your Portkey organization. Use this for compliance and security reviews. Audit logs track all administrative actions including user management, configuration changes, and access events. Unlike analytics tools which show aggregated metrics, audit logs show individual action events with actor details. Supports filtering by time range, actor, action type, and resource.",
     AUDIT_TOOL_SCHEMAS.listAuditLogs,
     async (params) => {
       const result = await service.audit.listAuditLogs({
@@ -2350,7 +2534,7 @@ var COLLECTIONS_TOOL_SCHEMAS = {
 function registerCollectionsTools(server, service) {
   server.tool(
     "list_collections",
-    "List all prompt collections in your Portkey organization. Collections group prompts by app (e.g., hourlink, apizone, research-pilot).",
+    "List all prompt collections in your Portkey organization. Collections organize prompts by application (e.g., hourlink, apizone, research-pilot). Use to discover collection_id values before creating or listing prompts. Returns id, name, and slug per collection.",
     COLLECTIONS_TOOL_SCHEMAS.listCollections,
     async (params) => {
       const collections = await service.collections.listCollections(params);
@@ -2380,7 +2564,7 @@ function registerCollectionsTools(server, service) {
   );
   server.tool(
     "create_collection",
-    "Create a new prompt collection for organizing prompts by app. Use one collection per app (hourlink, apizone, research-pilot).",
+    "Create a new prompt collection for organizing prompts by app. Use one collection per app (hourlink, apizone, research-pilot). Returns the new collection_id and slug needed for create_prompt.",
     COLLECTIONS_TOOL_SCHEMAS.createCollection,
     async (params) => {
       const result = await service.collections.createCollection(params);
@@ -2404,7 +2588,7 @@ function registerCollectionsTools(server, service) {
   );
   server.tool(
     "get_collection",
-    "Retrieve detailed information about a specific collection",
+    "Retrieve full details of a specific collection by ID or slug, including name, slug, and workspace_id. Use get_collection when you have a specific ID; use list_collections to browse all collections.",
     COLLECTIONS_TOOL_SCHEMAS.getCollection,
     async (params) => {
       const collection = await service.collections.getCollection(
@@ -2433,7 +2617,7 @@ function registerCollectionsTools(server, service) {
   );
   server.tool(
     "update_collection",
-    "Update a collection's name or description",
+    "Update a collection's display name or description. Does not affect prompts within the collection.",
     COLLECTIONS_TOOL_SCHEMAS.updateCollection,
     async (params) => {
       await service.collections.updateCollection(params.collection_id, {
@@ -2459,7 +2643,7 @@ function registerCollectionsTools(server, service) {
   );
   server.tool(
     "delete_collection",
-    "Delete a collection by ID. This action cannot be undone. Prompts in this collection will become orphaned.",
+    "Delete a prompt collection by ID. This action cannot be undone. Prompts inside the collection are not deleted but lose their grouping and move to the top level. Reassign prompts to another collection first if organization must be preserved.",
     COLLECTIONS_TOOL_SCHEMAS.deleteCollection,
     async (params) => {
       const result = await service.collections.deleteCollection(
@@ -2557,7 +2741,7 @@ function hasConfigSettings(config) {
 function registerConfigsTools(server, service) {
   server.tool(
     "list_configs",
-    "Retrieve all configurations in your Portkey organization, including their status and workspace associations",
+    "Retrieve all configurations in your Portkey organization, including their status and workspace associations. Configs define request routing behavior (cache, retry, fallback, load balancing). Use to discover config slugs before inspecting or modifying them.",
     CONFIGS_TOOL_SCHEMAS.listConfigs,
     async () => {
       const configs = await service.configs.listConfigs();
@@ -2591,7 +2775,7 @@ function registerConfigsTools(server, service) {
   );
   server.tool(
     "get_config",
-    "Retrieve detailed information about a specific configuration, including cache settings, retry policies, and routing strategy",
+    "Retrieve detailed information about a specific configuration, including cache settings, retry policies, routing strategy, and targets. Use when you need to inspect a config's full settings or clone an existing config's structure.",
     CONFIGS_TOOL_SCHEMAS.getConfig,
     async (params) => {
       const response = await service.configs.getConfig(params.slug);
@@ -2635,7 +2819,7 @@ function registerConfigsTools(server, service) {
   );
   server.tool(
     "create_config",
-    "Create a new configuration with cache, retry, and routing settings. At least one setting is required: cache (cache_mode/cache_max_age), retry (retry_attempts/retry_on_status_codes), strategy_mode, or targets.",
+    "Create a new configuration that defines how AI requests are routed, cached, retried, and load-balanced across providers. At least one setting is required: cache (cache_mode/cache_max_age), retry (retry_attempts/retry_on_status_codes), strategy_mode, or targets.",
     CONFIGS_TOOL_SCHEMAS.createConfig,
     async (params) => {
       const config = buildConfigPayload(params);
@@ -2675,7 +2859,7 @@ function registerConfigsTools(server, service) {
   );
   server.tool(
     "update_config",
-    "Update an existing configuration's cache, retry, or routing settings",
+    "Update an existing configuration's cache, retry, or routing settings. Creates a new version; only provided fields are updated, unspecified fields remain unchanged.",
     CONFIGS_TOOL_SCHEMAS.updateConfig,
     async (params) => {
       const config = buildConfigPayload(params);
@@ -2710,7 +2894,7 @@ function registerConfigsTools(server, service) {
   );
   server.tool(
     "delete_config",
-    "Delete a configuration by slug. This action cannot be undone.",
+    "Delete a configuration by slug. This action cannot be undone and removes all versions. Requests and API keys referencing this config slug will fail immediately. Use list_config_versions first to review history; audit dependent API keys before deleting.",
     CONFIGS_TOOL_SCHEMAS.deleteConfig,
     async (params) => {
       const result = await service.configs.deleteConfig(params.slug);
@@ -2733,7 +2917,7 @@ function registerConfigsTools(server, service) {
   );
   server.tool(
     "list_config_versions",
-    "List all versions of a configuration to view its change history",
+    "List all versions of a configuration to view its change history. Use to audit past changes, compare versions, or find a specific version ID for rollback.",
     CONFIGS_TOOL_SCHEMAS.listConfigVersions,
     async (params) => {
       const result = await service.configs.listConfigVersions(params.slug);
@@ -2815,7 +2999,7 @@ var GUARDRAILS_TOOL_SCHEMAS = {
 function registerGuardrailsTools(server, service) {
   server.tool(
     "list_guardrails",
-    "List all guardrails in your Portkey organization with optional filtering by workspace or organization",
+    "List all guardrails in your Portkey organization with optional filtering by workspace or organization. Guardrails are content moderation and security policies applied to AI requests. Use to discover guardrail IDs and slugs before inspecting or modifying them.",
     GUARDRAILS_TOOL_SCHEMAS.listGuardrails,
     async (params) => {
       const result = await service.guardrails.listGuardrails(params);
@@ -2849,7 +3033,7 @@ function registerGuardrailsTools(server, service) {
   );
   server.tool(
     "get_guardrail",
-    "Retrieve detailed information about a specific guardrail, including its checks and actions configuration",
+    "Retrieve detailed information about a specific guardrail, including its full checks and actions configuration. Use when you need to inspect or modify a guardrail's rules, or to understand what checks are applied before updating.",
     GUARDRAILS_TOOL_SCHEMAS.getGuardrail,
     async (params) => {
       const guardrail = await service.guardrails.getGuardrail(
@@ -2884,7 +3068,7 @@ function registerGuardrailsTools(server, service) {
   );
   server.tool(
     "create_guardrail",
-    "Create a new guardrail with specified checks and actions for content moderation and security. checks is an array of check objects with id (e.g. 'default.jwt', 'default.pii'), optional name, is_enabled boolean, and parameters object.",
+    "Create a new guardrail with specified checks and actions for content moderation and security. Guardrails are applied to requests via configs -- create the guardrail first, then reference it in a config. checks is an array of check objects with id (e.g. 'default.jwt', 'default.pii'), optional name, is_enabled boolean, and parameters object.",
     GUARDRAILS_TOOL_SCHEMAS.createGuardrail,
     async (params) => {
       const result = await service.guardrails.createGuardrail({
@@ -2915,7 +3099,7 @@ function registerGuardrailsTools(server, service) {
   );
   server.tool(
     "update_guardrail",
-    "Update an existing guardrail's name, checks, or actions configuration",
+    "Update an existing guardrail's name, checks, or actions configuration. Creates a new version of the guardrail; existing references in configs continue working with the latest version.",
     GUARDRAILS_TOOL_SCHEMAS.updateGuardrail,
     async (params) => {
       const updateData = {};
@@ -2953,7 +3137,7 @@ function registerGuardrailsTools(server, service) {
   );
   server.tool(
     "delete_guardrail",
-    "Delete a guardrail by its ID or slug. This action cannot be undone.",
+    "Delete a guardrail by its ID or slug. This action cannot be undone. Configs referencing this guardrail as a before/after request hook will stop enforcing it, silently dropping the safety check. Review dependent configs before deleting.",
     GUARDRAILS_TOOL_SCHEMAS.deleteGuardrail,
     async (params) => {
       const result = await service.guardrails.deleteGuardrail(
@@ -3116,7 +3300,7 @@ var INTEGRATIONS_TOOL_SCHEMAS = {
 function registerIntegrationsTools(server, service) {
   server.tool(
     "list_integrations",
-    "List all integrations in your Portkey organization with optional filtering by workspace or type",
+    "List org-level connections to AI providers (OpenAI, Anthropic, Azure, etc.) with optional filtering by workspace or type. Use to discover integration slugs for other integration tools. Returns paginated results with id, slug, provider, and status. Differs from list_providers, which shows workspace-scoped provider instances.",
     INTEGRATIONS_TOOL_SCHEMAS.listIntegrations,
     async (params) => {
       const integrations = await service.integrations.listIntegrations({
@@ -3202,7 +3386,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "get_integration",
-    "Retrieve detailed information about a specific integration by its slug",
+    "Retrieve detailed information about a specific integration by its slug. Returns full config including masked API key, workspace access settings, and allowed models. Use when you need provider-specific details or to audit an integration's configuration.",
     INTEGRATIONS_TOOL_SCHEMAS.getIntegration,
     async (params) => {
       const integration = await service.integrations.getIntegration(
@@ -3239,7 +3423,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "update_integration",
-    "Update an existing integration's name, API key, description, or provider-specific configurations",
+    "Update an existing integration's name, API key, description, or provider-specific configurations. API key changes take effect immediately. Changing provider-specific configs (Azure resource_name, Vertex region, etc.) may break active requests using this integration.",
     INTEGRATIONS_TOOL_SCHEMAS.updateIntegration,
     async (params) => {
       const configurations = {};
@@ -3286,7 +3470,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "delete_integration",
-    "Delete an integration by slug. This action cannot be undone.",
+    "Delete an integration by slug. This action cannot be undone. Removes the org-level provider connection; all dependent virtual keys and providers will stop working.",
     INTEGRATIONS_TOOL_SCHEMAS.deleteIntegration,
     async (params) => {
       const result = await service.integrations.deleteIntegration(params.slug);
@@ -3309,7 +3493,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "list_integration_models",
-    "List all models available for a specific integration with their enabled status",
+    "List which AI models are enabled for a specific integration, with their enabled/disabled status and custom flag. Use to check model availability before creating prompts or configs. Returns paginated results with model id, name, and enabled state.",
     INTEGRATIONS_TOOL_SCHEMAS.listIntegrationModels,
     async (params) => {
       const models = await service.integrations.listIntegrationModels(
@@ -3347,7 +3531,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "update_integration_models",
-    "Update model access settings for an integration - enable/disable models or add custom models",
+    "Enable/disable specific models or register custom model names for an integration. Changes affect all workspaces using this integration. Pass an array of model configurations with slug, enabled state, and optional is_custom flag.",
     INTEGRATIONS_TOOL_SCHEMAS.updateIntegrationModels,
     async (params) => {
       const result = await service.integrations.updateIntegrationModels(
@@ -3376,7 +3560,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "delete_integration_model",
-    "Delete a specific custom model from an integration",
+    "Delete a specific custom model from an integration. Only custom models can be deleted; built-in models should be disabled via update_integration_models instead. Returns success status.",
     INTEGRATIONS_TOOL_SCHEMAS.deleteIntegrationModel,
     async (params) => {
       const result = await service.integrations.deleteIntegrationModel(
@@ -3402,7 +3586,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "list_integration_workspaces",
-    "List all workspaces that have access to a specific integration",
+    "List which workspaces can access a specific integration, including their usage limits and rate limits. Use to audit workspace access and review per-workspace spending/rate configurations. Returns paginated results.",
     INTEGRATIONS_TOOL_SCHEMAS.listIntegrationWorkspaces,
     async (params) => {
       const workspaces = await service.integrations.listIntegrationWorkspaces(
@@ -3441,7 +3625,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "update_integration_workspaces",
-    "Update workspace access settings for an integration - enable/disable workspace access and configure limits",
+    "Control which workspaces can use an integration and set per-workspace usage/rate limits. Pass an array of workspace configurations with id, enabled state, and optional credit_limit, alert_threshold, and rate_limit_rpm.",
     INTEGRATIONS_TOOL_SCHEMAS.updateIntegrationWorkspaces,
     async (params) => {
       const result = await service.integrations.updateIntegrationWorkspaces(
@@ -3569,7 +3753,7 @@ var KEYS_TOOL_SCHEMAS = {
 function registerKeysTools(server, service) {
   server.tool(
     "list_virtual_keys",
-    "Retrieve all virtual keys in your Portkey organization, including their usage limits, rate limits, and status",
+    "List virtual keys that securely store provider API keys (OpenAI, Anthropic, etc.) in your Portkey organization. Use to discover virtual key slugs referenced in prompts and configs. Returns all keys with their usage limits, rate limits, and status.",
     KEYS_TOOL_SCHEMAS.listVirtualKeys,
     async () => {
       const virtualKeys = await service.keys.listVirtualKeys();
@@ -3610,7 +3794,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "create_virtual_key",
-    "Create a new virtual key for a provider (e.g., openai, anthropic). Virtual keys securely store provider API keys.",
+    "Securely store a provider API key as a virtual key. The original key is encrypted and never returned after creation. Use the returned slug to reference this key in prompts and configs. Supports optional usage/rate limits.",
     KEYS_TOOL_SCHEMAS.createVirtualKey,
     async (params) => {
       const result = await service.keys.createVirtualKey({
@@ -3649,7 +3833,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "get_virtual_key",
-    "Retrieve detailed information about a specific virtual key by its slug",
+    "Retrieve detailed information about a specific virtual key by its slug. Returns key metadata with a masked version of the stored API key. Use to check usage limits, rate limits, and status.",
     KEYS_TOOL_SCHEMAS.getVirtualKey,
     async (params) => {
       const virtualKey = await service.keys.getVirtualKey(params.slug);
@@ -3687,7 +3871,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "update_virtual_key",
-    "Update an existing virtual key's name, API key, note, or limits",
+    "Update an existing virtual key's name, API key, note, or limits. Can rotate the underlying provider API key by passing a new key value. Changes to limits take effect immediately.",
     KEYS_TOOL_SCHEMAS.updateVirtualKey,
     async (params) => {
       const result = await service.keys.updateVirtualKey(params.slug, {
@@ -3721,7 +3905,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "delete_virtual_key",
-    "Delete a virtual key by slug. This action cannot be undone.",
+    "Delete a virtual key by slug. This action cannot be undone. Prompts and configs referencing this key will fail; ensure no active resources depend on it before deleting.",
     KEYS_TOOL_SCHEMAS.deleteVirtualKey,
     async (params) => {
       const result = await service.keys.deleteVirtualKey(params.slug);
@@ -3744,7 +3928,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "create_api_key",
-    "Create a new Portkey API key for authentication. Organisation-level keys provide full access, workspace keys are scoped. Scopes control read/write permissions to specific resources (logs, analytics, prompts, etc.).",
+    "Create a new Portkey API key for authentication. Organisation-level keys provide full access, workspace keys are scoped. Scopes control read/write permissions to specific resources (logs, analytics, prompts, etc.). Returns the key value only once at creation time \u2014 save it immediately.",
     KEYS_TOOL_SCHEMAS.createApiKey,
     async (params) => {
       if (params.type === "workspace" && !params.workspace_id) {
@@ -3815,7 +3999,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "list_api_keys",
-    "List all API keys in your Portkey organization with optional pagination and workspace filtering",
+    "List Portkey API keys (not provider keys \u2014 use list_virtual_keys for those) with optional pagination and workspace filtering. Use to audit access and review key scopes, limits, and expiration across your organization.",
     KEYS_TOOL_SCHEMAS.listApiKeys,
     async (params) => {
       const apiKeys = await service.keys.listApiKeys({
@@ -3868,7 +4052,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "get_api_key",
-    "Retrieve detailed information about a specific API key by its UUID",
+    "Retrieve detailed information about a specific API key by its UUID. Returns key metadata without the secret key value. Use to check scopes, usage/rate limits, defaults, and expiration.",
     KEYS_TOOL_SCHEMAS.getApiKey,
     async (params) => {
       const apiKey = await service.keys.getApiKey(params.id);
@@ -3915,7 +4099,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "update_api_key",
-    "Update an existing API key's name, description, scopes, or limits",
+    "Update an existing API key's name, description, scopes, or limits. Can modify scopes, usage/rate limits, defaults, and expiration. Cannot change key type or sub_type after creation.",
     KEYS_TOOL_SCHEMAS.updateApiKey,
     async (params) => {
       const result = await service.keys.updateApiKey(params.id, {
@@ -3953,7 +4137,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "delete_api_key",
-    "Delete an API key by UUID. This action cannot be undone.",
+    "Delete an API key by UUID. This action cannot be undone. Immediately revokes authentication; active sessions using this key will fail.",
     KEYS_TOOL_SCHEMAS.deleteApiKey,
     async (params) => {
       const result = await service.keys.deleteApiKey(params.id);
@@ -4013,7 +4197,7 @@ var LABELS_TOOL_SCHEMAS = {
 function registerLabelsTools(server, service) {
   server.tool(
     "create_prompt_label",
-    "Create a new prompt label to categorize and organize prompts. Labels can be color-coded and scoped to workspaces or organizations.",
+    "Create a new prompt label to categorize prompt versions (e.g., 'production', 'staging', 'experiment'). Requires either organisation_id or workspace_id to set the label's scope. Returns the new label's id. Use update_prompt_version to assign labels to specific prompt versions.",
     LABELS_TOOL_SCHEMAS.createPromptLabel,
     async (params) => {
       if (!params.organisation_id && !params.workspace_id) {
@@ -4053,7 +4237,7 @@ function registerLabelsTools(server, service) {
   );
   server.tool(
     "list_prompt_labels",
-    "List all prompt labels in your Portkey organization with optional filtering by workspace, organisation, or search query",
+    "List all prompt labels with optional filtering by workspace, organisation, or search query. Returns id, name, color_code, and status for each label. Use to discover label IDs before assigning them to prompt versions via update_prompt_version.",
     LABELS_TOOL_SCHEMAS.listPromptLabels,
     async (params) => {
       const result = await service.labels.listLabels(params);
@@ -4085,7 +4269,7 @@ function registerLabelsTools(server, service) {
   );
   server.tool(
     "get_prompt_label",
-    "Retrieve detailed information about a specific prompt label",
+    "Retrieve full details of a specific prompt label including its scope (organisation_id vs workspace_id), color, and status. Use when you need to inspect a label's properties before updating it.",
     LABELS_TOOL_SCHEMAS.getPromptLabel,
     async (params) => {
       const label = await service.labels.getLabel(params.label_id, {
@@ -4119,7 +4303,7 @@ function registerLabelsTools(server, service) {
   );
   server.tool(
     "update_prompt_label",
-    "Update an existing prompt label's name, description, or color",
+    "Update a prompt label's name, description, or color_code. Changes apply to the label definition only; existing prompt version assignments using this label are not affected.",
     LABELS_TOOL_SCHEMAS.updatePromptLabel,
     async (params) => {
       const { label_id, ...updateData } = params;
@@ -4143,7 +4327,7 @@ function registerLabelsTools(server, service) {
   );
   server.tool(
     "delete_prompt_label",
-    "Delete a prompt label by ID. This action cannot be undone.",
+    "Delete a prompt label by ID. This action cannot be undone. Prompt versions carrying this label lose it, and any workflow resolving prompts by this label (e.g., 'production', 'staging') will fail until reassigned. Audit label usage via list_prompts before deleting.",
     LABELS_TOOL_SCHEMAS.deletePromptLabel,
     async (params) => {
       await service.labels.deleteLabel(params.label_id);
@@ -4295,7 +4479,7 @@ function formatUsageLimitEntity(entity) {
 function registerLimitsTools(server, service) {
   server.tool(
     "list_rate_limits",
-    "Retrieve all rate limits in your Portkey organization. Rate limits control how many requests or tokens can be consumed per time unit (rpm/rph/rpd).",
+    "Retrieve all rate limits in your Portkey organization. Use to discover existing rate limit policies before creating new ones. Returns an array of rate limits each containing id, type, unit, value, and status. Rate limits control how many requests or tokens can be consumed per time unit (rpm/rph/rpd).",
     LIMITS_TOOL_SCHEMAS.listRateLimits,
     async (params) => {
       const result = await service.limits.listRateLimits(params.workspace_id);
@@ -4318,7 +4502,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "get_rate_limit",
-    "Retrieve detailed information about a specific rate limit by its ID",
+    "Retrieve detailed information about a specific rate limit by its ID. Returns full detail including conditions and group_by fields. Use when you have a specific rate limit ID from list_rate_limits and need to inspect its complete configuration.",
     LIMITS_TOOL_SCHEMAS.getRateLimit,
     async (params) => {
       const result = await service.limits.getRateLimit(params.id);
@@ -4334,7 +4518,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "create_rate_limit",
-    "Create a new rate limit policy to control request/token consumption per time unit. Requires conditions to match against and group_by to specify how limits are applied.",
+    "Create a new rate limit policy to throttle requests in real-time by controlling request/token consumption per time unit. Differs from usage limits, which cap cumulative consumption over time. Requires conditions to match against and group_by to specify how limits are applied.",
     LIMITS_TOOL_SCHEMAS.createRateLimit,
     async (params) => {
       const result = await service.limits.createRateLimit({
@@ -4366,7 +4550,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "update_rate_limit",
-    "Update an existing rate limit's name, unit, or value",
+    "Update an existing rate limit's name, unit, or value. Only name, unit, and value can be changed after creation; conditions and group_by are immutable. Returns the updated rate limit object.",
     LIMITS_TOOL_SCHEMAS.updateRateLimit,
     async (params) => {
       const result = await service.limits.updateRateLimit(params.id, {
@@ -4393,7 +4577,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "delete_rate_limit",
-    "Delete a rate limit by ID. This action cannot be undone.",
+    "Delete a rate limit policy by ID. This action cannot be undone. Requests previously throttled by this policy will no longer be limited; review dependent configs and virtual keys first to avoid unexpected traffic spikes.",
     LIMITS_TOOL_SCHEMAS.deleteRateLimit,
     async (params) => {
       await service.limits.deleteRateLimit(params.id);
@@ -4416,7 +4600,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "list_usage_limits",
-    "Retrieve all usage limits in your Portkey organization. Usage limits control how much cost or tokens can be consumed, with optional periodic resets.",
+    "Retrieve all usage limits in your Portkey organization. Differs from rate limits: usage limits cap total cumulative cost or tokens over time, optionally resetting on a weekly or monthly schedule. Returns an array of usage limits with id, type, credit_limit, status, and reset schedule.",
     LIMITS_TOOL_SCHEMAS.listUsageLimits,
     async (params) => {
       const result = await service.limits.listUsageLimits(params.workspace_id);
@@ -4439,7 +4623,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "get_usage_limit",
-    "Retrieve detailed information about a specific usage limit by its ID",
+    "Retrieve detailed information about a specific usage limit by its ID. Returns full detail including conditions, group_by, credit_limit, alert_threshold, and periodic reset schedule.",
     LIMITS_TOOL_SCHEMAS.getUsageLimit,
     async (params) => {
       const result = await service.limits.getUsageLimit(params.id);
@@ -4455,7 +4639,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "create_usage_limit",
-    "Create a new usage limit policy to control cost or token consumption. Requires conditions to match against and group_by to specify how limits are applied.",
+    "Create a new usage limit policy to enforce spending or token budgets over time. Differs from rate limits, which control real-time request velocity. Requires conditions to match against and group_by to specify how limits are applied. Supports optional periodic resets and alert thresholds.",
     LIMITS_TOOL_SCHEMAS.createUsageLimit,
     async (params) => {
       const result = await service.limits.createUsageLimit({
@@ -4488,7 +4672,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "update_usage_limit",
-    "Update an existing usage limit's configuration",
+    "Update an existing usage limit's configuration. Modifiable fields: name, credit_limit, alert_threshold, periodic_reset, and reset_usage_for_value. Conditions and group_by are immutable after creation.",
     LIMITS_TOOL_SCHEMAS.updateUsageLimit,
     async (params) => {
       const result = await service.limits.updateUsageLimit(params.id, {
@@ -4517,7 +4701,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "delete_usage_limit",
-    "Delete a usage limit by ID. This action cannot be undone.",
+    "Delete a usage limit policy by ID. This action cannot be undone. Budgets and quotas enforced by this policy are removed immediately and tracked entities lose accumulated usage state. Use list_usage_limit_entities first to review impact before deleting.",
     LIMITS_TOOL_SCHEMAS.deleteUsageLimit,
     async (params) => {
       await service.limits.deleteUsageLimit(params.id);
@@ -4540,7 +4724,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "list_usage_limit_entities",
-    "List all entities tracked against a usage limit policy, showing current usage per entity",
+    "List all entities (individual keys, users, or groups) tracked against a usage limit policy. Shows current consumption per entity, useful for monitoring who is approaching or has exceeded their budget.",
     LIMITS_TOOL_SCHEMAS.listUsageLimitEntities,
     async (params) => {
       const result = await service.limits.listUsageLimitEntities(
@@ -4565,7 +4749,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "reset_usage_limit_entity",
-    "Reset accumulated usage for a specific entity on a usage limit policy",
+    "Reset the accumulated usage counter to zero for a specific entity on a usage limit policy. Does not delete the entity or the policy itself. Use when an entity needs its budget restored before the next scheduled periodic reset.",
     LIMITS_TOOL_SCHEMAS.resetUsageLimitEntity,
     async (params) => {
       await service.limits.resetUsageLimitEntity(
@@ -4682,7 +4866,7 @@ var LOGGING_TOOL_SCHEMAS = {
 function registerLoggingTools(server, service) {
   server.tool(
     "insert_log",
-    "Insert a log entry (or multiple entries) into Portkey for tracking AI requests and responses. request_provider must match a configured integration (e.g. 'openai', 'anthropic'). Use metadata_span_id and metadata_parent_span_id to create trace hierarchies.",
+    "Insert a log entry (or multiple entries) into Portkey for tracking AI requests and responses. Use this for external or custom logs not routed through the Portkey gateway. request_provider must match a configured integration (e.g. 'openai', 'anthropic'). Use metadata_span_id and metadata_parent_span_id to create trace hierarchies.",
     LOGGING_TOOL_SCHEMAS.insertLog,
     async (params) => {
       const entry = {
@@ -4730,7 +4914,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "create_log_export",
-    "Create a new log export job to export logs matching specified filters. time_min/time_max accept ISO 8601 format ('2024-01-01T00:00:00Z'). requested_fields selects which columns to include.",
+    "Create a new log export job definition with filters and field selection. This only creates the job \u2014 you must call start_log_export to begin processing, then poll get_log_export to check status. time_min/time_max accept ISO 8601 format ('2024-01-01T00:00:00Z'). Returns the export ID and matching log count.",
     LOGGING_TOOL_SCHEMAS.createLogExport,
     async (params) => {
       const result = await service.logging.createLogExport({
@@ -4768,7 +4952,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "list_log_exports",
-    "List all log export jobs for a workspace",
+    "List all log export jobs for a workspace. Returns each export with its current status (pending/running/completed/failed), filters, and timestamps. Use this to find export_ids for subsequent get, start, cancel, or download operations.",
     LOGGING_TOOL_SCHEMAS.listLogExports,
     async (params) => {
       const result = await service.logging.listLogExports({
@@ -4803,7 +4987,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "get_log_export",
-    "Get details of a specific log export by its ID",
+    "Get details of a specific log export by its ID. Use this to check the current status of an export (pending/running/completed/failed) and view its full configuration. Unlike list_log_exports which returns summaries of all exports, this returns complete detail for a single export including filters and requested fields.",
     LOGGING_TOOL_SCHEMAS.getLogExport,
     async (params) => {
       const result = await service.logging.getLogExport(params.export_id);
@@ -4834,7 +5018,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "start_log_export",
-    "Start a log export job that was previously created",
+    "Trigger processing of a previously created log export job. You must call create_log_export first to define the export before starting it. After starting, poll get_log_export to monitor progress until status is 'completed', then use download_log_export to retrieve results.",
     LOGGING_TOOL_SCHEMAS.startLogExport,
     async (params) => {
       const result = await service.logging.startLogExport(params.export_id);
@@ -4858,7 +5042,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "cancel_log_export",
-    "Cancel a running log export job",
+    "Cancel a running or pending log export job. This permanently stops the export \u2014 it cannot be resumed after cancellation. To export the same data, create a new export job with create_log_export.",
     LOGGING_TOOL_SCHEMAS.cancelLogExport,
     async (params) => {
       const result = await service.logging.cancelLogExport(params.export_id);
@@ -5073,7 +5257,7 @@ function formatMcpIntegrationWorkspace(workspace) {
 function registerMcpIntegrationsTools(server, service) {
   server.tool(
     "list_mcp_integrations",
-    "List all MCP integrations in your Portkey organization with optional pagination and workspace filtering",
+    "List all MCP integrations in your Portkey organization with optional pagination and workspace filtering. MCP integrations connect external MCP servers to your Portkey org. Use to discover integration IDs needed by other tools. Differs from list_mcp_servers which shows server instances under an integration. Returns paginated array of integrations with total count and has_more flag.",
     MCP_INTEGRATIONS_TOOL_SCHEMAS.listMcpIntegrations,
     async (params) => {
       const result = await service.mcpIntegrations.listMcpIntegrations(params);
@@ -5097,7 +5281,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "create_mcp_integration",
-    "Create a new MCP integration in Portkey for connecting external MCP servers to your organization",
+    "Create a new MCP integration by registering an external MCP server URL with auth configuration. After creation, use create_mcp_server to add server instances and update_mcp_integration_capabilities to control which tools are exposed. Returns the new integration's id and slug.",
     MCP_INTEGRATIONS_TOOL_SCHEMAS.createMcpIntegration,
     async (params) => {
       if (params.auth_type === "headers" && (!params.custom_headers || Object.keys(params.custom_headers).length === 0)) {
@@ -5136,7 +5320,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "get_mcp_integration",
-    "Retrieve detailed information about a specific MCP integration by ID or slug",
+    "Retrieve detailed information about a specific MCP integration by ID or slug. Returns full integration config including auth type, transport, and configuration keys (header values are masked). Use to inspect Portkey-side connection details. Differs from get_mcp_integration_metadata which returns the external server's self-reported info.",
     MCP_INTEGRATIONS_TOOL_SCHEMAS.getMcpIntegration,
     async (params) => {
       const integration = await service.mcpIntegrations.getMcpIntegration(
@@ -5154,7 +5338,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "update_mcp_integration",
-    "Update an existing MCP integration's name, description, URL, auth, or transport",
+    "Update an existing MCP integration's name, description, URL, auth, or transport. Changing url or auth_type may break active connections. Changes take effect immediately for all connected users.",
     MCP_INTEGRATIONS_TOOL_SCHEMAS.updateMcpIntegration,
     async (params) => {
       const { id, custom_headers, ...rest } = params;
@@ -5181,7 +5365,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "delete_mcp_integration",
-    "Delete an MCP integration. This action cannot be undone.",
+    "Delete an MCP integration permanently. Also removes all MCP servers under this integration. Connected users will lose access immediately. This action cannot be undone.",
     MCP_INTEGRATIONS_TOOL_SCHEMAS.deleteMcpIntegration,
     async (params) => {
       await service.mcpIntegrations.deleteMcpIntegration(params.id);
@@ -5204,7 +5388,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "get_mcp_integration_metadata",
-    "Retrieve metadata for a specific MCP integration",
+    "Retrieve server-reported metadata for an MCP integration including name, version, protocol, and sync status. Use to verify the external server is responding and check its capabilities. Differs from get_mcp_integration which shows Portkey-side config.",
     MCP_INTEGRATIONS_TOOL_SCHEMAS.getMcpIntegrationMetadata,
     async (params) => {
       const metadata = await service.mcpIntegrations.getMcpIntegrationMetadata(
@@ -5226,7 +5410,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "list_mcp_integration_capabilities",
-    "List all capabilities (tools, resources, prompts) available on an MCP integration",
+    "List all capabilities (tools, resources, prompts) the external MCP server exposes on an integration. Use before update_mcp_integration_capabilities to see what can be enabled or disabled. Returns total count and array of capabilities with their enabled status.",
     MCP_INTEGRATIONS_TOOL_SCHEMAS.listMcpIntegrationCapabilities,
     async (params) => {
       const result = await service.mcpIntegrations.listMcpIntegrationCapabilities(params.id);
@@ -5246,7 +5430,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "update_mcp_integration_capabilities",
-    "Bulk enable or disable capabilities on an MCP integration",
+    "Bulk enable or disable capabilities on an MCP integration to control which MCP tools, resources, and prompts are available to users. Disabled capabilities are hidden from connected clients. Changes take effect immediately.",
     MCP_INTEGRATIONS_TOOL_SCHEMAS.updateMcpIntegrationCapabilities,
     async (params) => {
       await service.mcpIntegrations.updateMcpIntegrationCapabilities(
@@ -5274,7 +5458,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "list_mcp_integration_workspaces",
-    "List workspace access settings for an MCP integration",
+    "List which workspaces have access to an MCP integration. Returns global access setting and per-workspace enabled status. Use to audit access before modifying permissions with update_mcp_integration_workspaces.",
     MCP_INTEGRATIONS_TOOL_SCHEMAS.listMcpIntegrationWorkspaces,
     async (params) => {
       const result = await service.mcpIntegrations.listMcpIntegrationWorkspaces(
@@ -5302,7 +5486,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "update_mcp_integration_workspaces",
-    "Bulk update workspace access for an MCP integration",
+    "Grant or revoke workspace access to an MCP integration in bulk. Changes affect all users in the workspace immediately. Use list_mcp_integration_workspaces first to see current access state.",
     MCP_INTEGRATIONS_TOOL_SCHEMAS.updateMcpIntegrationWorkspaces,
     async (params) => {
       await service.mcpIntegrations.updateMcpIntegrationWorkspaces(params.id, {
@@ -5417,7 +5601,7 @@ function formatMcpServerUserAccess(user) {
 function registerMcpServersTools(server, service) {
   server.tool(
     "list_mcp_servers",
-    "List all MCP servers in your Portkey organization with optional pagination and workspace filtering",
+    "List all MCP servers in your Portkey organization with optional pagination and workspace filtering. MCP servers are instances under MCP integrations. Use to discover server IDs needed by other tools. Differs from list_mcp_integrations which shows the parent integration connections. Returns paginated array of servers with total count.",
     MCP_SERVERS_TOOL_SCHEMAS.listMcpServers,
     async (params) => {
       const result = await service.mcpServers.listMcpServers(params);
@@ -5440,7 +5624,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "create_mcp_server",
-    "Register a new MCP server under an existing MCP integration",
+    "Register a new MCP server instance under an existing MCP integration. Use list_mcp_integrations to find the mcp_integration_id first. Returns the new server's id and slug.",
     MCP_SERVERS_TOOL_SCHEMAS.createMcpServer,
     async (params) => {
       const result = await service.mcpServers.createMcpServer(params);
@@ -5464,7 +5648,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "get_mcp_server",
-    "Retrieve detailed information about a specific MCP server by ID or slug",
+    "Retrieve detailed information about a specific MCP server by ID or slug. Returns server details including linked integration ID and status. Use to check server configuration and health.",
     MCP_SERVERS_TOOL_SCHEMAS.getMcpServer,
     async (params) => {
       const mcpServer = await service.mcpServers.getMcpServer(params.id);
@@ -5480,7 +5664,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "update_mcp_server",
-    "Update an existing MCP server's name or description",
+    "Update an existing MCP server's name or description. Only name and description can be changed on a server. To change the URL or auth configuration, update the parent MCP integration instead.",
     MCP_SERVERS_TOOL_SCHEMAS.updateMcpServer,
     async (params) => {
       const { id, ...data } = params;
@@ -5504,7 +5688,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "delete_mcp_server",
-    "Delete an MCP server. This action cannot be undone.",
+    "Delete an MCP server instance by ID. This action cannot be undone. Connected users and workspaces lose access immediately, and workspace access grants to this server are removed. Verify no active integrations depend on it before deleting.",
     MCP_SERVERS_TOOL_SCHEMAS.deleteMcpServer,
     async (params) => {
       await service.mcpServers.deleteMcpServer(params.id);
@@ -5527,7 +5711,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "test_mcp_server",
-    "Test connectivity to an MCP server to verify it is reachable and responding",
+    "Send a connectivity check to an MCP server to verify it is reachable and responding. Returns success/failure, response time in ms, and any error message. Use to diagnose connection issues before investigating configuration.",
     MCP_SERVERS_TOOL_SCHEMAS.testMcpServer,
     async (params) => {
       const result = await service.mcpServers.testMcpServer(params.id);
@@ -5543,7 +5727,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "list_mcp_server_capabilities",
-    "List all capabilities (tools, resources, prompts) exposed by an MCP server",
+    "List all capabilities (tools, resources, prompts) exposed by an MCP server instance. Differs from list_mcp_integration_capabilities which shows integration-level capability settings. Returns total count and array of capabilities.",
     MCP_SERVERS_TOOL_SCHEMAS.listMcpServerCapabilities,
     async (params) => {
       const result = await service.mcpServers.listMcpServerCapabilities(
@@ -5565,7 +5749,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "update_mcp_server_capabilities",
-    "Bulk enable or disable capabilities on an MCP server",
+    "Enable or disable specific capabilities on an MCP server instance. Overrides integration-level capability settings for this server. Changes take effect immediately for connected users.",
     MCP_SERVERS_TOOL_SCHEMAS.updateMcpServerCapabilities,
     async (params) => {
       await service.mcpServers.updateMcpServerCapabilities(params.id, {
@@ -5590,7 +5774,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "list_mcp_server_user_access",
-    "List user access settings for an MCP server",
+    "List per-user access settings for an MCP server including override flags and connection status. Returns default_user_access setting and array of users. Use to audit who can access this server before modifying permissions.",
     MCP_SERVERS_TOOL_SCHEMAS.listMcpServerUserAccess,
     async (params) => {
       const result = await service.mcpServers.listMcpServerUserAccess(
@@ -5616,7 +5800,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "update_mcp_server_user_access",
-    "Bulk update user access for an MCP server",
+    "Grant or revoke individual user access to an MCP server. Overrides the default_user_access setting for specified users. Changes take effect immediately.",
     MCP_SERVERS_TOOL_SCHEMAS.updateMcpServerUserAccess,
     async (params) => {
       await service.mcpServers.updateMcpServerUserAccess(params.id, {
@@ -5681,7 +5865,7 @@ var PARTIALS_TOOL_SCHEMAS = {
 function registerPartialsTools(server, service) {
   server.tool(
     "create_prompt_partial",
-    "Create a new prompt partial (reusable text snippet) that can be included in prompts using mustache syntax like {{> partial_name}}",
+    "Create a new prompt partial (reusable text snippet) that can be included in prompts using mustache syntax like {{> partial_name}}. After creation, use publish_partial to make it the default version. Returns id, slug, and version_id.",
     PARTIALS_TOOL_SCHEMAS.createPromptPartial,
     async (params) => {
       const result = await service.partials.createPromptPartial({
@@ -5711,7 +5895,7 @@ function registerPartialsTools(server, service) {
   );
   server.tool(
     "list_prompt_partials",
-    "List all prompt partials in your Portkey organization with optional filtering by collection",
+    "List all prompt partials in your Portkey organization with optional filtering by collection. Returns all partials with id, slug, name, and status. Use to discover partial IDs or check if a partial already exists before creating.",
     PARTIALS_TOOL_SCHEMAS.listPromptPartials,
     async (params) => {
       const partials = await service.partials.listPromptPartials(params);
@@ -5742,7 +5926,7 @@ function registerPartialsTools(server, service) {
   );
   server.tool(
     "get_prompt_partial",
-    "Retrieve detailed information about a specific prompt partial including its content and version info",
+    "Retrieve detailed information about a specific prompt partial. Returns the partial's content string and current version info. Use to inspect content before including it in a prompt via {{> partial_name}}.",
     PARTIALS_TOOL_SCHEMAS.getPromptPartial,
     async (params) => {
       const partial = await service.partials.getPromptPartial(
@@ -5803,7 +5987,7 @@ function registerPartialsTools(server, service) {
   );
   server.tool(
     "delete_prompt_partial",
-    "Delete a prompt partial by ID. This action cannot be undone.",
+    "Delete a prompt partial by ID. This action cannot be undone. Prompts referencing this partial via {{> name}} will fail to render. Ensure no active prompts depend on it.",
     PARTIALS_TOOL_SCHEMAS.deletePromptPartial,
     async (params) => {
       await service.partials.deletePromptPartial(params.prompt_partial_id);
@@ -5826,7 +6010,7 @@ function registerPartialsTools(server, service) {
   );
   server.tool(
     "list_partial_versions",
-    "List all versions of a prompt partial to view its change history",
+    "List all versions of a prompt partial to view its change history. Returns all versions with content preview. Use to find a version number before calling publish_partial to roll back or promote a version.",
     PARTIALS_TOOL_SCHEMAS.listPartialVersions,
     async (params) => {
       const versions = await service.partials.listPartialVersions(
@@ -5861,7 +6045,7 @@ function registerPartialsTools(server, service) {
   );
   server.tool(
     "publish_partial",
-    "Publish a specific version of a prompt partial, making it the default version",
+    "Publish a specific version of a prompt partial, making it the default version. After publishing, all prompts using {{> partial_name}} will resolve to this version's content.",
     PARTIALS_TOOL_SCHEMAS.publishPartial,
     async (params) => {
       await service.partials.publishPartial(params.prompt_partial_id, {
@@ -5962,14 +6146,25 @@ function toPromptToolChoice(toolChoice) {
 
 // src/tools/prompts.tools.ts
 var PROMPT_VARIABLES_SCHEMA = z15.record(z15.string(), z15.union([z15.string(), z15.coerce.number(), z15.boolean()])).describe("Variable values to substitute into the template");
+var PROMPT_TEMPLATE_CONTENT_BLOCK_SCHEMA = z15.object({
+  type: z15.string().describe("Content block type"),
+  text: z15.string().optional().describe("Text content for text-based blocks")
+}).passthrough().describe("Content block within a structured chat message");
+var PROMPT_TEMPLATE_MESSAGE_SCHEMA = z15.object({
+  role: z15.enum(["system", "user", "assistant"]).describe("Message role in the chat template"),
+  content: z15.array(PROMPT_TEMPLATE_CONTENT_BLOCK_SCHEMA).describe("Message content blocks")
+}).passthrough().describe("Structured chat message in a prompt template");
 var PROMPTS_TOOL_SCHEMAS = {
   createPrompt: {
     name: z15.string().describe("Display name for the prompt"),
     collection_id: z15.string().describe(
       "Collection ID to organize the prompt in (use list_collections to find)"
     ),
-    string: z15.string().describe(
-      `The prompt template. Plain text OR a JSON-encoded messages array string for multi-message chat prompts: '[{"role":"system","content":[{"type":"text","text":"..."}]},{"role":"user","content":[{"type":"text","text":"{{input}}"}]}]'. Use get_prompt on an existing prompt to see the exact format.`
+    string: z15.string().optional().describe(
+      "Legacy prompt template string. Use plain text for single-message prompts, or a JSON-encoded messages array string for multi-message chat prompts."
+    ),
+    messages: z15.array(PROMPT_TEMPLATE_MESSAGE_SCHEMA).optional().describe(
+      "Structured chat template alias. Serialized to the legacy string format before creation."
     ),
     parameters: z15.record(z15.string(), z15.unknown()).describe("Default values for template variables"),
     virtual_key: z15.string().describe("Virtual key slug for model access"),
@@ -6006,7 +6201,10 @@ var PROMPTS_TOOL_SCHEMAS = {
     name: z15.string().optional().describe("New display name for the prompt"),
     collection_id: z15.string().optional().describe("Move to a different collection"),
     string: z15.string().optional().describe(
-      "Updated prompt template. Plain text OR a JSON-encoded messages array string for multi-message chat prompts. Use get_prompt to see the current format before updating."
+      "Legacy prompt template string. Use plain text for single-message prompts, or a JSON-encoded messages array string for multi-message chat prompts."
+    ),
+    messages: z15.array(PROMPT_TEMPLATE_MESSAGE_SCHEMA).optional().describe(
+      "Structured chat template alias for updates. Serialized to the legacy string format before the prompt is updated."
     ),
     parameters: z15.record(z15.string(), z15.unknown()).optional().describe("New default values for template variables"),
     model: z15.string().optional().describe("New model identifier"),
@@ -6052,7 +6250,12 @@ var PROMPTS_TOOL_SCHEMAS = {
     app: PromptAppIdentifierSchema,
     env: PromptEnvironmentIdentifierSchema,
     collection_id: z15.string().describe("Collection ID to search in and create under"),
-    string: z15.string().describe("Prompt template string with {{variable}} mustache syntax"),
+    string: z15.string().optional().describe(
+      "Legacy prompt template string with {{variable}} mustache syntax."
+    ),
+    messages: z15.array(PROMPT_TEMPLATE_MESSAGE_SCHEMA).optional().describe(
+      "Structured chat template alias for migrations. Serialized to the legacy string format before the prompt is created or updated."
+    ),
     parameters: z15.record(z15.string(), z15.unknown()).describe("Default values for template variables"),
     virtual_key: z15.string().describe("Virtual key slug for model access"),
     model: z15.string().optional().describe("Model identifier"),
@@ -6095,6 +6298,15 @@ var PROMPTS_TOOL_SCHEMAS = {
     )
   }
 };
+function normalizePromptTemplateString(params) {
+  if (params.string !== void 0) {
+    return params.string;
+  }
+  if (params.messages !== void 0) {
+    return JSON.stringify(params.messages);
+  }
+  return void 0;
+}
 function extractPromptTemplateString(template) {
   const inner = typeof template === "object" && template !== null && "string" in template ? template.string : template;
   if (inner === void 0) {
@@ -6158,14 +6370,14 @@ function formatPromptListResponse(prompts, params) {
 function registerPromptsTools(server, service) {
   server.tool(
     "create_prompt",
-    `Create a new prompt template in Portkey. Supports both single-message and multi-message (chat) templates.
+    `Create a new prompt template in Portkey. Supports both the legacy string template and a structured messages alias for chat prompts.
 
-IMPORTANT: The "string" parameter accepts TWO formats:
+IMPORTANT: The "string" parameter accepts TWO legacy formats:
 1. Plain text: "Hello {{name}}, how can I help?"
 2. Multi-message JSON array (MUST be a JSON-encoded string):
    '[{"role":"system","content":[{"type":"text","text":"You are a helpful assistant."}]},{"role":"user","content":[{"type":"text","text":"{{user_input}}"}]}]'
 
-Most production prompts use format #2 (multi-message). Use get_prompt to see examples of the format.`,
+For structured prompts, prefer the "messages" alias and let the server serialize it to the legacy string format.`,
     PROMPTS_TOOL_SCHEMAS.createPrompt,
     async (params) => {
       if (!params.model && !params.ai_model_id && !params.finetune_id) {
@@ -6179,6 +6391,18 @@ Most production prompts use format #2 (multi-message). Use get_prompt to see exa
           isError: true
         };
       }
+      const templateString = normalizePromptTemplateString(params);
+      if (templateString === void 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Error creating prompt: Provide either string or messages"
+            }
+          ],
+          isError: true
+        };
+      }
       if (params.dry_run) {
         return {
           content: [
@@ -6193,7 +6417,7 @@ Most production prompts use format #2 (multi-message). Use get_prompt to see exa
                     name: params.name,
                     collection_id: params.collection_id,
                     model: params.model,
-                    template_length: params.string.length,
+                    template_length: templateString.length,
                     parameter_count: Object.keys(params.parameters ?? {}).length
                   }
                 },
@@ -6207,17 +6431,17 @@ Most production prompts use format #2 (multi-message). Use get_prompt to see exa
       const result = await service.prompts.createPrompt({
         name: params.name,
         collection_id: params.collection_id,
-        string: params.string,
+        string: templateString,
         parameters: params.parameters,
         virtual_key: params.virtual_key,
-        model: params.model,
-        ai_model_id: params.ai_model_id,
-        finetune_id: params.finetune_id,
-        version_description: params.version_description,
-        template_metadata: params.template_metadata,
-        functions: params.functions,
-        tools: params.tools,
-        tool_choice: toPromptToolChoice(params.tool_choice)
+        ...params.model !== void 0 ? { model: params.model } : {},
+        ...params.ai_model_id !== void 0 ? { ai_model_id: params.ai_model_id } : {},
+        ...params.finetune_id !== void 0 ? { finetune_id: params.finetune_id } : {},
+        ...params.version_description !== void 0 ? { version_description: params.version_description } : {},
+        ...params.template_metadata !== void 0 ? { template_metadata: params.template_metadata } : {},
+        ...params.functions !== void 0 ? { functions: params.functions } : {},
+        ...params.tools !== void 0 ? { tools: params.tools } : {},
+        ...params.tool_choice !== void 0 ? { tool_choice: toPromptToolChoice(params.tool_choice) } : {}
       });
       return {
         content: [
@@ -6240,7 +6464,7 @@ Most production prompts use format #2 (multi-message). Use get_prompt to see exa
   );
   server.tool(
     "list_prompts",
-    "List all prompts in your Portkey organization with optional filtering by collection, workspace, or search query",
+    "List all prompts in your Portkey organization with optional filtering by collection, workspace, or search query. Returns paginated results with id, name, slug, model, and status. Use collection_id to filter by app. Use to discover prompt_id values before calling get_prompt.",
     PROMPTS_TOOL_SCHEMAS.listPrompts,
     async (params) => {
       const prompts = await service.prompts.listPrompts(params);
@@ -6329,15 +6553,19 @@ When updating a prompt, pass the same format back in the "string" field of updat
     "update_prompt",
     `Update an existing prompt template. Creates a new version. Uses patch mode \u2014 only provided fields are updated, others are kept from the current version.
 
-IMPORTANT: The "string" parameter accepts the same two formats as create_prompt:
+IMPORTANT: The legacy "string" parameter accepts the same two formats as create_prompt:
 1. Plain text: "Hello {{name}}"
 2. Multi-message JSON array (MUST be a JSON-encoded string):
    '[{"role":"system","content":[{"type":"text","text":"..."}]},{"role":"user","content":[{"type":"text","text":"{{input}}"}]}]'
 
-Use get_prompt first to see the current format, then pass the same format back. New versions are created in "archived" status \u2014 use publish_prompt to make active.`,
+For structured chat prompts, prefer the "messages" alias and let the server serialize it for you. New versions are created in "archived" status \u2014 use publish_prompt to make active.`,
     PROMPTS_TOOL_SCHEMAS.updatePrompt,
     async (params) => {
-      const { prompt_id, dry_run, ...updateData } = params;
+      const { prompt_id, dry_run, messages, ...updateData } = params;
+      const templateString = normalizePromptTemplateString({
+        string: updateData.string,
+        messages
+      });
       if (dry_run) {
         const current = await service.prompts.getPrompt(prompt_id);
         return {
@@ -6362,8 +6590,17 @@ Use get_prompt first to see the current format, then pass the same format back.
         };
       }
       const result = await service.prompts.updatePrompt(prompt_id, {
-        ...updateData,
-        tool_choice: toPromptToolChoice(updateData.tool_choice)
+        ...updateData.name !== void 0 ? { name: updateData.name } : {},
+        ...updateData.collection_id !== void 0 ? { collection_id: updateData.collection_id } : {},
+        ...templateString !== void 0 ? { string: templateString } : {},
+        ...updateData.parameters !== void 0 ? { parameters: updateData.parameters } : {},
+        ...updateData.model !== void 0 ? { model: updateData.model } : {},
+        ...updateData.virtual_key !== void 0 ? { virtual_key: updateData.virtual_key } : {},
+        ...updateData.version_description !== void 0 ? { version_description: updateData.version_description } : {},
+        ...updateData.template_metadata !== void 0 ? { template_metadata: updateData.template_metadata } : {},
+        ...updateData.functions !== void 0 ? { functions: updateData.functions } : {},
+        ...updateData.tools !== void 0 ? { tools: updateData.tools } : {},
+        ...updateData.tool_choice !== void 0 ? { tool_choice: toPromptToolChoice(updateData.tool_choice) } : {}
       });
       return {
         content: [
@@ -6386,7 +6623,7 @@ Use get_prompt first to see the current format, then pass the same format back.
   );
   server.tool(
     "delete_prompt",
-    "Delete a prompt by its ID. This action cannot be undone and will remove the prompt and all its versions.",
+    "Delete a prompt and all its versions by ID. This action cannot be undone. Applications calling this prompt slug will fail immediately. Use list_prompt_versions first to review history; consider archiving via update_prompt status instead if an audit trail is needed.",
     PROMPTS_TOOL_SCHEMAS.deletePrompt,
     async (params) => {
       await service.prompts.deletePrompt(params.prompt_id);
@@ -6474,7 +6711,7 @@ Use get_prompt first to see the current format, then pass the same format back.
   );
   server.tool(
     "render_prompt",
-    "Render a prompt template by substituting variables, returning the final messages without executing",
+    "Render a prompt template by substituting variables, returning the final messages without executing. Previews the final messages after variable substitution without sending to the AI model. Use to verify template output before running a completion. Differs from run_prompt_completion which actually calls the model.",
     PROMPTS_TOOL_SCHEMAS.renderPrompt,
     async (params) => {
       const result = await service.prompts.renderPrompt(params.prompt_id, {
@@ -6506,7 +6743,7 @@ Use get_prompt first to see the current format, then pass the same format back.
   );
   server.tool(
     "run_prompt_completion",
-    "Execute a prompt template with variables and get the model completion response. REQUIRES billing metadata (client_id, app, env). Use validate_completion_metadata first if uncertain.",
+    "Execute a prompt template against the configured AI model and return the model's response. Costs money \u2014 use render_prompt to preview first. REQUIRES billing metadata (client_id, app, env). Use validate_completion_metadata first if uncertain.",
     PROMPTS_TOOL_SCHEMAS.runPromptCompletion,
     async (params) => {
       const result = await service.prompts.runPromptCompletion(
@@ -6545,24 +6782,36 @@ Use get_prompt first to see the current format, then pass the same format back.
   );
   server.tool(
     "migrate_prompt",
-    "Create or update a prompt based on whether it exists. Useful for CI/CD and prompt-as-code workflows. Finds existing prompts by name within the collection. The app and env values are added to template_metadata automatically.",
+    "Create or update a prompt based on whether it exists. Useful for CI/CD and prompt-as-code workflows. Finds existing prompts by name within the collection. The app and env values are added to template_metadata automatically. For structured chat prompts, prefer the messages alias instead of hand-encoding JSON into string.",
     PROMPTS_TOOL_SCHEMAS.migratePrompt,
     async (params) => {
+      const templateString = normalizePromptTemplateString(params);
+      if (templateString === void 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Error migrating prompt: Provide either string or messages"
+            }
+          ],
+          isError: true
+        };
+      }
       const result = await service.prompts.migratePrompt({
         name: params.name,
         app: params.app,
         env: params.env,
         collection_id: params.collection_id,
-        string: params.string,
+        string: templateString,
         parameters: params.parameters,
         virtual_key: params.virtual_key,
-        model: params.model,
-        version_description: params.version_description,
-        template_metadata: params.template_metadata,
-        functions: params.functions,
-        tools: params.tools,
-        tool_choice: toPromptToolChoice(params.tool_choice),
-        dry_run: params.dry_run
+        ...params.model !== void 0 ? { model: params.model } : {},
+        ...params.version_description !== void 0 ? { version_description: params.version_description } : {},
+        ...params.template_metadata !== void 0 ? { template_metadata: params.template_metadata } : {},
+        ...params.functions !== void 0 ? { functions: params.functions } : {},
+        ...params.tools !== void 0 ? { tools: params.tools } : {},
+        ...params.tool_choice !== void 0 ? { tool_choice: toPromptToolChoice(params.tool_choice) } : {},
+        ...params.dry_run !== void 0 ? { dry_run: params.dry_run } : {}
       });
       return {
         content: [
@@ -6625,7 +6874,7 @@ Use get_prompt first to see the current format, then pass the same format back.
   );
   server.tool(
     "validate_completion_metadata",
-    "Validate billing metadata before running a completion. Checks for required fields (client_id, app, env) and valid values.",
+    "Validate billing metadata before running a completion. Checks for required fields (client_id, app, env) and valid values. Call this before run_prompt_completion to catch missing or invalid billing fields. Does not make any changes.",
     PROMPTS_TOOL_SCHEMAS.validateCompletionMetadata,
     async (params) => {
       const result = service.prompts.validateBillingMetadata(params);
@@ -6650,7 +6899,7 @@ Use get_prompt first to see the current format, then pass the same format back.
   );
   server.tool(
     "get_prompt_version",
-    "Retrieve a specific version of a prompt by its version ID",
+    "Retrieve a specific version of a prompt by its version UUID. Use list_prompt_versions to find version IDs. Returns full template, parameters, and model config for that version.",
     PROMPTS_TOOL_SCHEMAS.getPromptVersion,
     async (params) => {
       const version = await service.prompts.getPromptVersion(
@@ -6669,7 +6918,7 @@ Use get_prompt first to see the current format, then pass the same format back.
   );
   server.tool(
     "update_prompt_version",
-    "Update a specific prompt version, e.g. to assign or remove a label",
+    "Update a specific prompt version. Currently only supports assigning or removing a label. Use list_prompt_labels to find label IDs. Pass null to remove the current label.",
     PROMPTS_TOOL_SCHEMAS.updatePromptVersion,
     async (params) => {
       if (params.label_id === void 0) {
@@ -6777,7 +7026,7 @@ var PROVIDERS_TOOL_SCHEMAS = {
 function registerProvidersTools(server, service) {
   server.tool(
     "list_providers",
-    "List all providers in your Portkey organization with optional pagination and workspace filtering",
+    "List workspace-scoped providers, which are instances of org-level integrations with their own usage and rate limits. Differs from list_integrations which shows org-level provider connections. Use to discover provider slugs for a workspace. Returns name, slug, limits, and status per provider.",
     PROVIDERS_TOOL_SCHEMAS.listProviders,
     async (params) => {
       const providers = await service.providers.listProviders({
@@ -6823,7 +7072,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "create_provider",
-    "Create a new provider configuration in Portkey. Providers define integrations with AI model providers like OpenAI, Anthropic, etc.",
+    "Create a workspace-scoped provider linked to an org-level integration. Use list_integrations to find the integration_id first. Providers inherit the integration's API key but can have independent usage limits, rate limits, and expiration. Returns the new provider's id and slug.",
     PROVIDERS_TOOL_SCHEMAS.createProvider,
     async (params) => {
       const result = await service.providers.createProvider({
@@ -6864,7 +7113,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "get_provider",
-    "Retrieve detailed information about a specific provider by its slug",
+    "Retrieve full provider details by slug, including usage limits, rate limits, and expiration. Use to check current consumption against limits or inspect provider configuration before updating.",
     PROVIDERS_TOOL_SCHEMAS.getProvider,
     async (params) => {
       const provider = await service.providers.getProvider(
@@ -6906,7 +7155,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "update_provider",
-    "Update an existing provider's name, note, limits, or expiration",
+    "Update a provider's name, note, usage limits, rate limits, or expiration. Set reset_usage to true to clear accumulated usage counters without changing the limit. Returns the updated provider's id and slug.",
     PROVIDERS_TOOL_SCHEMAS.updateProvider,
     async (params) => {
       const result = await service.providers.updateProvider(
@@ -6949,7 +7198,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "delete_provider",
-    "Delete a provider by slug. This action cannot be undone.",
+    "Delete a workspace-level provider by slug. This action cannot be undone. Virtual keys, configs, and prompts referencing this provider will stop working. Audit dependent resources first; use delete_integration for org-level provider connections instead.",
     PROVIDERS_TOOL_SCHEMAS.deleteProvider,
     async (params) => {
       await service.providers.deleteProvider(params.slug, params.workspace_id);
@@ -6996,15 +7245,12 @@ var TRACING_TOOL_SCHEMAS = {
     ),
     weight: z17.coerce.number().positive().optional().describe("New weighting factor for the feedback"),
     metadata: z17.record(z17.string(), z17.unknown()).optional().describe("New or updated custom metadata for the feedback")
-  },
-  getTrace: {
-    id: z17.string().describe("The unique identifier of the trace to retrieve")
   }
 };
 function registerTracingTools(server, service) {
   server.tool(
     "create_feedback",
-    "Create feedback for a specific trace/request. Use this to capture user feedback (thumbs up/down, ratings) on AI generations. Feedback is linked via trace_id and can include custom metadata for analysis.",
+    "Create feedback for a specific trace/request. Use this to capture user feedback (thumbs up/down, ratings) on AI generations. Feedback is linked via trace_id and can include custom metadata for analysis. Trace IDs are surfaced in request logs and via log exports (create_log_export).",
     TRACING_TOOL_SCHEMAS.createFeedback,
     async (params) => {
       const result = await service.tracing.createFeedback({
@@ -7033,7 +7279,7 @@ function registerTracingTools(server, service) {
   );
   server.tool(
     "update_feedback",
-    "Update existing feedback by ID. Allows modifying the feedback value, weight, or metadata after initial creation.",
+    "Update existing feedback by ID. Use this instead of create_feedback when feedback already exists and needs correction or refinement. Only value, weight, and metadata can be changed; the trace_id association is immutable. Returns the updated feedback status and IDs.",
     TRACING_TOOL_SCHEMAS.updateFeedback,
     async (params) => {
       const result = await service.tracing.updateFeedback(params.id, {
@@ -7059,51 +7305,6 @@ function registerTracingTools(server, service) {
       };
     }
   );
-  server.tool(
-    "get_trace",
-    "Retrieve detailed information about a specific trace by ID. Returns full request/response data, all spans, metadata, cost, token usage, and any associated feedback.",
-    TRACING_TOOL_SCHEMAS.getTrace,
-    async (params) => {
-      const result = await service.tracing.getTrace(params.id);
-      const trace = result.data;
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(
-              {
-                success: result.success,
-                trace: {
-                  id: trace.id,
-                  trace_id: trace.trace_id,
-                  request: trace.request,
-                  response: trace.response,
-                  metadata: trace.metadata,
-                  workspace_id: trace.workspace_id,
-                  organisation_id: trace.organisation_id,
-                  cost: trace.cost,
-                  tokens: trace.tokens,
-                  spans: trace.spans?.map((span) => ({
-                    span_id: span.span_id,
-                    span_name: span.span_name,
-                    parent_span_id: span.parent_span_id,
-                    start_time: span.start_time,
-                    end_time: span.end_time,
-                    status: span.status,
-                    attributes: span.attributes
-                  })),
-                  feedback: trace.feedback,
-                  created_at: trace.created_at
-                }
-              },
-              null,
-              2
-            )
-          }
-        ]
-      };
-    }
-  );
 }
 
 // src/tools/users.tools.ts
@@ -7207,7 +7408,7 @@ function formatUserAnalyticsGroup(group) {
 function registerUsersTools(server, service) {
   server.tool(
     "list_all_users",
-    "List all users in your Portkey organization, including their roles and account details",
+    "List all users in your Portkey organization. Returns each user's ID, name, email, role, and timestamps. Use this for browsing or auditing the full member list; use get_user to fetch a single user by ID.",
     USERS_TOOL_SCHEMAS.listAllUsers,
     async () => {
       const users = await service.users.listUsers();
@@ -7254,7 +7455,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "get_user_stats",
-    "Retrieve detailed analytics data about user activity within a specified time range, including request counts and costs",
+    "Retrieve per-user request count and cost analytics for a required time range (time_of_generation_min/max). Unlike get_users_analytics which tracks active/new user counts over time, this returns usage-based stats grouped by user. Supports filtering by cost, tokens, status codes, and virtual keys.",
     USERS_TOOL_SCHEMAS.getUserStats,
     async (params) => {
       const stats = await service.users.getUserGroupedData(params);
@@ -7277,7 +7478,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "get_user",
-    "Retrieve detailed information about a specific user by their ID",
+    "Retrieve a single user's profile by their ID. Returns ID, name, email, role, and timestamps. Use this when you already have a user ID; use list_all_users to browse or search all organization members.",
     USERS_TOOL_SCHEMAS.getUser,
     async (params) => {
       const user = await service.users.getUser(params.user_id);
@@ -7293,7 +7494,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "update_user",
-    "Update a user's profile information including name and organization role",
+    "Update a user's first name, last name, or organization role (admin/member). Cannot change the user's email address or workspace-level roles; use update_workspace_member for workspace roles.",
     USERS_TOOL_SCHEMAS.updateUser,
     async (params) => {
       const { user_id, ...updateData } = params;
@@ -7317,7 +7518,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "delete_user",
-    "Remove a user from your Portkey organization. Permanently removes the user and all their org/workspace memberships. Cannot be undone.",
+    "Remove a user from your Portkey organization by ID. This action cannot be undone. Permanently removes org and workspace memberships and revokes the user's API keys; active sessions will fail immediately. Use delete_user_invite for pending invitations instead.",
     USERS_TOOL_SCHEMAS.deleteUser,
     async (params) => {
       await service.users.deleteUser(params.user_id);
@@ -7340,7 +7541,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "list_user_invites",
-    "List all pending and sent user invitations in your Portkey organization",
+    "List all pending and sent user invitations in your Portkey organization. Returns each invite's ID, email, role, status, and expiry. Use this to check invitation status; use list_all_users for users who have already accepted.",
     USERS_TOOL_SCHEMAS.listUserInvites,
     async () => {
       const invites = await service.users.listUserInvites();
@@ -7363,7 +7564,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "get_user_invite",
-    "Retrieve details about a specific user invitation",
+    "Retrieve a specific invitation by its invite ID. Returns the invite's email, role, status, creation date, and expiry. This looks up a pending invitation, not an existing user; use get_user for accepted members.",
     USERS_TOOL_SCHEMAS.getUserInvite,
     async (params) => {
       const invite = await service.users.getUserInvite(params.invite_id);
@@ -7379,7 +7580,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "delete_user_invite",
-    "Cancel and delete a pending user invitation",
+    "Cancel and permanently delete a pending user invitation. This revokes the invite link so it can no longer be accepted. Does not remove existing users; use delete_user for that.",
     USERS_TOOL_SCHEMAS.deleteUserInvite,
     async (params) => {
       await service.users.deleteUserInvite(params.invite_id);
@@ -7402,7 +7603,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "resend_user_invite",
-    "Resend an invitation email to a pending user",
+    "Resend the invitation email for a pending invite that has not yet been accepted. Use when the original email was lost or expired. The invite must still exist; check with get_user_invite first if unsure.",
     USERS_TOOL_SCHEMAS.resendUserInvite,
     async (params) => {
       await service.users.resendUserInvite(params.invite_id);
@@ -7532,7 +7733,7 @@ function formatWorkspaceDetail(workspace) {
 function registerWorkspacesTools(server, service) {
   server.tool(
     "list_workspaces",
-    "Retrieve all workspaces in your Portkey organization, including their configurations and metadata",
+    "Retrieve a paginated list of all workspaces in your Portkey organization. Returns id, name, slug, and configuration for each workspace. Use this tool first to discover workspace_id values needed by other workspace-scoped operations.",
     WORKSPACES_TOOL_SCHEMAS.listWorkspaces,
     async (params) => {
       const workspaces = await service.workspaces.listWorkspaces(params);
@@ -7555,7 +7756,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "get_workspace",
-    "Retrieve detailed information about a specific workspace, including its configuration, metadata, and user access details",
+    "Retrieve full details for a single workspace by ID, including its configuration, metadata, and complete member list with roles. Unlike list_workspaces, this includes the full user roster \u2014 use it when you need member details or workspace membership counts.",
     WORKSPACES_TOOL_SCHEMAS.getWorkspace,
     async (params) => {
       const workspace = await service.workspaces.getWorkspace(
@@ -7573,7 +7774,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "create_workspace",
-    "Create a new workspace in your Portkey organization",
+    "Create a new workspace to isolate resources, API keys, and team members within your Portkey organization. A URL-friendly slug is auto-generated from the name if not provided. Returns the created workspace's id, name, and slug.",
     WORKSPACES_TOOL_SCHEMAS.createWorkspace,
     async (params) => {
       const workspace = await service.workspaces.createWorkspace({
@@ -7604,7 +7805,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "update_workspace",
-    "Update an existing workspace's settings and metadata",
+    "Update a workspace's name, slug, description, default status, or metadata. Only provided fields are changed; omitted fields remain unchanged. Warning: changing a workspace's slug may break existing references and URLs that depend on it.",
     WORKSPACES_TOOL_SCHEMAS.updateWorkspace,
     async (params) => {
       const { workspace_id, is_default, metadata, ...rest } = params;
@@ -7657,7 +7858,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "add_workspace_member",
-    "Add a user to a workspace with a specific role",
+    "Add an existing organization user to a workspace with a specified role (admin, manager, or member). Requires user_id as a UUID \u2014 use list_all_users to find it. For users not yet in the organization, use invite_user first.",
     WORKSPACES_TOOL_SCHEMAS.addWorkspaceMember,
     async (params) => {
       const member = await service.workspaces.addWorkspaceMember(
@@ -7686,7 +7887,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "list_workspace_members",
-    "List all members of a workspace with their roles",
+    "List all members of a workspace, returning each member's user_id, name, organization role, workspace role, and status. Use this to discover user_id values needed for get_workspace_member, update_workspace_member, or remove_workspace_member.",
     WORKSPACES_TOOL_SCHEMAS.listWorkspaceMembers,
     async (params) => {
       const members = await service.workspaces.listWorkspaceMembers(
@@ -7711,7 +7912,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "get_workspace_member",
-    "Get details about a specific member of a workspace",
+    "Get details about a single workspace member by workspace_id and user_id. Returns the member's name, organization role, workspace role, and status. Unlike list_workspace_members, this fetches a single member directly when you already know both IDs.",
     WORKSPACES_TOOL_SCHEMAS.getWorkspaceMember,
     async (params) => {
       const member = await service.workspaces.getWorkspaceMember(
@@ -7730,7 +7931,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "update_workspace_member",
-    "Update a member's role in a workspace",
+    "Update a workspace member's role. Only the role can be changed \u2014 valid values are admin, manager, or member. Use list_workspace_members or get_workspace_member to check the current role first.",
     WORKSPACES_TOOL_SCHEMAS.updateWorkspaceMember,
     async (params) => {
       const member = await service.workspaces.updateWorkspaceMember(
@@ -7759,7 +7960,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "remove_workspace_member",
-    "Remove a user from a workspace",
+    "Remove a user from a workspace, revoking their workspace-level access. This does not delete the user from the organization \u2014 use delete_user for full org removal. The user can be re-added later with add_workspace_member.",
     WORKSPACES_TOOL_SCHEMAS.removeWorkspaceMember,
     async (params) => {
       await service.workspaces.removeWorkspaceMember(
@@ -7840,6 +8041,37 @@ var DESTRUCTIVE_TOOL_PREFIXES = [
   "cancel_",
   "reset_"
 ];
+var ENTERPRISE_GATED_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "get_cost_analytics",
+  "get_request_analytics",
+  "get_token_analytics",
+  "get_latency_analytics",
+  "get_error_analytics",
+  "get_error_rate_analytics",
+  "get_cache_hit_latency",
+  "get_cache_hit_rate",
+  "get_users_analytics",
+  "get_error_stacks_analytics",
+  "get_error_status_codes_analytics",
+  "get_user_requests_analytics",
+  "get_rescued_requests_analytics",
+  "get_feedback_analytics",
+  "get_feedback_models_analytics",
+  "get_feedback_scores_analytics",
+  "get_feedback_weighted_analytics",
+  "get_analytics_group_users",
+  "get_analytics_group_models",
+  "get_analytics_group_metadata",
+  "list_audit_logs",
+  "get_integration",
+  "list_integration_models",
+  "list_integration_workspaces",
+  "list_all_users",
+  "get_user",
+  "list_user_invites",
+  "get_user_stats"
+]);
+var ENTERPRISE_GATED_DESCRIPTION_NOTE = "Enterprise-gated. Returns 403 on non-Enterprise Portkey plans.";
 function isToolAnnotationsLike(value) {
   if (!isRecord2(value)) {
     return false;
@@ -7888,6 +8120,15 @@ function inferToolAnnotations(toolName) {
     openWorldHint: true
   };
 }
+function augmentToolDescription(toolName, description) {
+  if (!description || !ENTERPRISE_GATED_TOOL_NAMES.has(toolName)) {
+    return description;
+  }
+  if (description.includes(ENTERPRISE_GATED_DESCRIPTION_NOTE)) {
+    return description;
+  }
+  return `${description} ${ENTERPRISE_GATED_DESCRIPTION_NOTE}`;
+}
 function getToolErrorMessage(error) {
   if (error instanceof Error && error.message) {
     return error.message;
@@ -7992,6 +8233,7 @@ function buildToolRegistration(name, rest) {
   if (typeof args[0] === "string") {
     description = args.shift();
   }
+  description = augmentToolDescription(name, description);
   let inputSchema;
   let annotations = inferredAnnotations;
   if (args.length === 1) {
@@ -8637,7 +8879,27 @@ function readPackageVersion() {
   return "0.0.0";
 }
 var PACKAGE_VERSION = readPackageVersion();
-var SERVER_INSTRUCTIONS = "Portkey Admin API server. Use list_* tools for discovery and get_* tools for details. Analytics tools require time_of_generation_min/max. Prompt workflows: create_prompt -> publish_prompt. Always validate_completion_metadata before run_prompt_completion.";
+var SERVER_INSTRUCTIONS = "Portkey Admin API server. Use list_* tools for discovery and get_* tools for details. Analytics tools require time_of_generation_min/max. Prompt workflows: create_prompt -> publish_prompt. Always validate_completion_metadata before run_prompt_completion. If the server is configured with only some domains, stay within that subset instead of assuming every Portkey admin tool is available.";
+function parseConfiguredToolDomains(rawValue = process.env.PORTKEY_TOOL_DOMAINS?.trim() || process.env.MCP_TOOL_DOMAINS?.trim()) {
+  if (!rawValue) {
+    return void 0;
+  }
+  const requestedDomains = rawValue.split(",").map((value) => value.trim().toLowerCase()).filter((value) => value.length > 0);
+  if (requestedDomains.length === 0) {
+    throw new Error(
+      `Invalid PORTKEY_TOOL_DOMAINS value. Expected one or more domains from: ${TOOL_DOMAIN_NAMES.join(", ")}`
+    );
+  }
+  const invalidDomains = requestedDomains.filter(
+    (value) => !isToolDomain(value)
+  );
+  if (invalidDomains.length > 0) {
+    throw new Error(
+      `Unknown tool domains in PORTKEY_TOOL_DOMAINS: ${invalidDomains.join(", ")}. Valid domains: ${TOOL_DOMAIN_NAMES.join(", ")}`
+    );
+  }
+  return normalizeToolDomains(requestedDomains);
+}
 function createMcpServer(options = {}) {
   const service = getSharedPortkeyService();
   const server = new McpServer(
@@ -8652,7 +8914,9 @@ function createMcpServer(options = {}) {
       instructions: SERVER_INSTRUCTIONS
     }
   );
-  registerAllTools(server, service, { domains: options.toolDomains });
+  registerAllTools(server, service, {
+    domains: options.toolDomains ?? parseConfiguredToolDomains()
+  });
   return {
     server,
     service