portkey-admin-mcp 0.2.0 → 0.3.1

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",
+    "Get cost time-series data with summary.total_cost, summary.average_cost_per_request, and per-bucket total/avg cost. Use this for spend analysis and spike detection; use get_token_analytics when you need token volume instead of monetary cost.",
     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,
+    "Get request-volume time-series data with summary.total_requests, summary.successful_requests, summary.failed_requests, and per-bucket total/success/failed counts. Use this for traffic and reliability trends; use get_error_analytics when you only need error counts.",
+    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",
+    "Get token-usage time-series data with summary.total_tokens, summary.prompt_tokens, summary.completion_tokens, and per-bucket total/prompt/completion counts. Use this for consumption trends; use get_cost_analytics when you need spend instead of token volume.",
     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",
+    "Get latency time-series data with summary.avg_latency_ms, summary.p50_latency_ms, summary.p90_latency_ms, summary.p99_latency_ms, and per-bucket latency percentiles in ms. Use this to spot slowdowns and regressions; use get_cache_hit_latency when you only want cache-hit latency.",
     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",
+    "Get error-count time-series data with summary.total_errors and per-bucket counts. Use this for high-level error trends; use get_error_rate_analytics for percentages, or get_error_status_codes_analytics and get_error_stacks_analytics for breakdowns.",
     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",
+    "Get error-rate time-series data with summary.error_rate_percent and per-bucket percentages of total requests. Use this for reliability and SLA trends; use get_error_analytics for absolute error counts instead.",
     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",
+    "Get cache-hit-only latency time-series data with summary.total_latency, summary.avg_latency, and per-bucket total/avg latency. Use this to evaluate cached-response speed; use get_latency_analytics for all requests.",
     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",
+    "Get cache-effectiveness time-series data with summary.hit_rate, summary.total_hits, summary.total_misses, and per-bucket hits/misses/rate. Use this to measure cache effectiveness; use get_cache_hit_latency for speed rather than hit/miss ratio.",
     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",
+    "Get user-growth time-series data with summary.total_active_users, summary.total_new_users, and per-bucket active/new user counts. Use this for growth and adoption trends; use get_user_requests_analytics for per-user traffic or get_analytics_group_users for per-user cost and token detail.",
     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",
+    "Get stacked error-series data grouped by HTTP status code over time, with summary and per-code series. Use this to see which error classes dominate; use get_error_status_codes_analytics for distinct-code distribution instead.",
     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",
+    "Get HTTP error-code distribution time-series data with summary and per-code series. Use this to see which codes occur most often; use get_error_stacks_analytics for stacked or cumulative breakdowns.",
     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",
+    "Get per-user request-count time-series data with counts grouped by user. Use this to find heavy users and traffic concentration; use get_users_analytics for aggregate active and new user trends instead.",
     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",
+    "Get rescued-request time-series data showing requests recovered by retry or fallback handling. Use this only when your configs include resilience features, and use it to measure how often recovery logic saved requests.",
     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",
+    "Get feedback-submission time-series data with summary totals and per-bucket counts. Use this as the top-level feedback trend view; use get_feedback_models_analytics, get_feedback_scores_analytics, or get_feedback_weighted_analytics for breakdowns.",
     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",
+    "Get feedback time-series data grouped by model, with per-model counts over time. Use this to compare feedback volume and satisfaction across models; use get_feedback_analytics for the overall total instead.",
     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",
+    "Get raw feedback-score distribution time-series data with per-score buckets. Use this to understand sentiment mix; use get_feedback_weighted_analytics for calibrated scores with weighting.",
     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",
+    "Get weighted feedback-score time-series data using the weight recorded at feedback creation. Use this for calibrated quality metrics; use get_feedback_scores_analytics for the raw unweighted distribution.",
     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",
+    "Get a paginated per-user breakdown with total_groups, group_count, and a users array containing request count, cost, and token usage. Use this for billing, audits, or top-consumer analysis; use get_users_analytics for aggregate active and new user trends.",
     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",
+    "Get a paginated per-model breakdown with total_groups, group_count, and a models array containing request count, cost, and token usage. Use this to compare model cost, popularity, and efficiency; use get_token_analytics or get_cost_analytics for time-series trends instead.",
     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",
+    "Get a paginated metadata breakdown with total_groups, group_count, and a metadata_groups array grouped by the required metadata_key. Use this for custom breakdowns like per-environment or per-feature analysis; pass metadata_key in addition to the time window.",
     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.",
+    "List audit log events for a Portkey workspace or organization. Returns paginated action-level records with actor, resource, metadata, and timestamps for compliance or incident review; use this instead of analytics when you need individual events, not aggregates.",
     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 prompt collections in the workspace, optionally filtering by name or workspace. Returns ids, names, slugs, and timestamps so you can choose a collection_id before create_prompt, get_collection, or list_prompts.",
     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 this when you need a new namespace before create_prompt; returns the collection id and slug, and does not move any prompts.",
     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",
+    "Fetch one collection by id or slug and return its name, slug, workspace, and timestamps. Use list_collections when browsing and get_collection when you already know the target.",
     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 name or description only. This does not move prompts or change membership, so use it for metadata changes rather than reorganization.",
     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 cannot be undone; prompts stay in the workspace but lose their collection grouping, so reassign them first if organization matters.",
     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",
+    "List configs in the org with id, slug, name, status, workspace, and timestamps. Use this summary view to find a slug; use get_config for the full routing, cache, retry, and target settings before updating or deleting.",
     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",
+    "Get one config by slug and return its routing, cache, retry, and target settings. Requires a known slug; use list_configs to discover one before editing.",
     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 config that defines routing, cache, retry, and targets for requests. At least one of those settings is required; returns the new id and version_id.",
     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 a config by slug and create a new version. Only provided fields change; name and status are editable, while the slug stays fixed. Use list_config_versions if you need history first.",
     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 config by slug. This is permanent, removes all versions, and breaks anything still pointing at that slug; check list_config_versions first.",
     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 every version of a config with version number, config payload, creator, and timestamp. Use this to audit history or compare revisions before update_config or delete_config.",
     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 guardrails in the org with id, slug, status, ownership, and optional workspace/org filters. Use this to find IDs and slugs before get_guardrail, update_guardrail, or delete_guardrail.",
     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",
+    "Fetch one guardrail with its full checks and actions. Use this before updating rules or when you need the exact enforcement policy.",
     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 guardrail with checks and actions for request filtering. Create it first, then reference it from configs; the new version becomes the policy anchor for downstream use.",
     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 a guardrail's name, checks, or actions. This creates a new version, so configs keep pointing at the latest policy after the change.",
     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 id or slug. This is irreversible and removes the check from any configs that reference it, so review dependent configs first.",
     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 AI provider connections with optional workspace or type filters. Use this to find integration slugs before model or workspace updates. Returns total plus id, name, slug, provider, status, description, workspace counts, and config summary.",
     INTEGRATIONS_TOOL_SCHEMAS.listIntegrations,
     async (params) => {
       const integrations = await service.integrations.listIntegrations({
@@ -3154,7 +3338,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "create_integration",
-    "Create a new integration with an AI provider (e.g., OpenAI, Anthropic, Azure OpenAI, AWS Bedrock). Provider-specific params: Azure needs api_version + resource_name + deployment_name. AWS needs aws_region. Vertex AI needs vertex_project_id + vertex_region.",
+    "Create an org-level provider integration. Some backends need provider-specific fields, and the new integration becomes the source for downstream providers and workspace access. Returns the new integration id and slug.",
     INTEGRATIONS_TOOL_SCHEMAS.createIntegration,
     async (params) => {
       const configurations = {};
@@ -3202,7 +3386,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "get_integration",
-    "Retrieve detailed information about a specific integration by its slug",
+    "Fetch one integration by slug, including masked key, workspace access, allowed models, and configuration metadata. Use this before editing provider-specific settings or auditing access.",
     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 integration's name, key, or provider-specific config. Key and config changes take effect immediately and can disrupt dependent providers or live requests.",
     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 is irreversible and stops the org-level connection, which will break dependent virtual keys, providers, and workspace access.",
     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 models enabled on an integration. Use this to verify model availability before creating prompts or configs. Returns total plus model ids, display names, enabled state, and custom-model markers.",
     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, or register custom models for an integration. This changes model availability for every workspace using it, so confirm the downstream impact first. Returns success and the number of models updated.",
     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 custom model from an integration. Built-in models should be disabled instead, because deletion only applies to custom entries. Returns success after the custom model is removed.",
     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 workspaces that can use an integration, with their limits. Use this to audit access or confirm per-workspace cost and rate settings. Returns total plus workspace ids, names, enabled state, usage limits, and rate limits.",
     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 limits. Access changes and new limits apply to downstream usage immediately. Returns success and the number of workspaces updated.",
     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 provider API keys stored as virtual keys in your Portkey org. Use this to find slugs before wiring prompts/configs or auditing limits. Returns total plus name, slug, status, usage limits, rate limits, reset state, and model config.",
     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.",
+    "Store a provider API key as a virtual key. The raw key is encrypted and only returned at creation time, so save the returned slug and use it in prompts/configs. Optional usage and rate limits apply immediately, and the tool returns the new slug.",
     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",
+    "Fetch one virtual key by slug, including metadata, a masked secret, limits, status, and model config. Use this before updating or to inspect the current configuration.",
     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 a virtual key's name, secret, note, or limits. Rotating the key takes effect immediately, and limit changes apply to downstream prompts and configs using this slug. Returns the updated name, slug, and status.",
     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 is irreversible and will break prompts and configs that reference the slug, so confirm no active dependencies first. Returns success after removal.",
     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 Portkey API key for auth. Org keys grant broader access; workspace keys are scoped. The secret is only returned once, and using the key grants access immediately according to its scopes, defaults, and limits. Workspace keys require workspace_id and user keys require user_id.",
     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 for auditing access, scopes, defaults, limits, and expiration. Use this for API keys only; use list_virtual_keys for provider keys. Returns total plus id, type, status, workspace/user scope, limits, defaults, alert emails, and creation mode.",
     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",
+    "Fetch one API key by UUID without revealing the secret. Use this to inspect scopes, defaults, limits, expiration, and reset state before changing access.",
     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 API key's name, description, scopes, defaults, or limits. Changes affect what downstream callers can access; type and sub-type stay fixed after creation. Returns success after the update is applied.",
     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 cannot be undone, revokes access immediately, and can break active sessions using the key. Returns success after revocation.",
     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 prompt label for tagging prompt versions such as production, staging, or experiment. Requires either organisation_id or workspace_id to set scope, returns the new label id, and does not assign it to any versions yet.",
     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 labels across the workspace or organisation, with optional search and scope filters. Returns ids, names, colors, status, and timestamps so you can choose a label_id before get_prompt_label or 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",
+    "Fetch one label's full definition, including scope, color, and status. Use this when you already know the label_id; list_prompt_labels is better for browsing candidates.",
     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 only. This changes the label definition, not existing prompt-version assignments or history.",
     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 cannot be undone; versions carrying the label lose it, and any workflow resolving by that label will need a replacement.",
     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).",
+    "List rate limits in the org with id, type, unit, value, status, scope, conditions, and grouping. Use this to find an existing policy before get_rate_limit, update_rate_limit, or delete_rate_limit.",
     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",
+    "Get one rate limit by id and return its full conditions and grouping definition. Use list_rate_limits to discover ids or compare policies first.",
     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 request or token throttle with conditions, group_by, type, unit, and value. conditions and group_by are required; use usage limits when you need a cumulative budget instead.",
     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 a rate limit's name, unit, or value by id. Conditions and group_by are immutable after creation; use get_rate_limit first if you need the full policy.",
     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 by id. This is permanent and removes throttling immediately; review dependent configs and virtual keys before deleting.",
     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.",
+    "List usage limits in the org with id, type, credit_limit, status, reset schedule, scope, conditions, and grouping. Use this before get_usage_limit, update_usage_limit, or delete_usage_limit.",
     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",
+    "Get one usage limit by id and return its full budget, threshold, grouping, and reset details. Use list_usage_limits to discover ids or compare policies first.",
     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 cumulative budget for cost or tokens with optional alerts and weekly or monthly resets. conditions and group_by are required; use rate limits when you need request throttling.",
     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 a usage limit's name, credit_limit, alert_threshold, reset schedule, or reset target by id. 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 by id. This is permanent, removes the budget immediately, and clears tracked usage state; check list_usage_limit_entities first if you need impact.",
     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 the entities currently tracked against a usage limit, including current usage. Use this to see who is near or over budget before reset_usage_limit_entity or delete_usage_limit.",
     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 tracked usage for one entity under a usage limit. This changes accumulated usage for that entity only; use list_usage_limit_entities to confirm the target first.",
     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 log records for requests that bypassed the gateway. This writes request, response, and trace metadata into Portkey immediately, and the call will fail if request_provider does not match a configured integration. Use the span fields to stitch trace hierarchies together.",
     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 log export definition with filters and requested fields. This only sets up the export and does not start processing; call start_log_export next, then use get_log_export or download_log_export to inspect or retrieve the finished result.",
     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 log export jobs in a workspace with status, filters, and timestamps. Use this to find an export_id before calling get_log_export, start_log_export, cancel_log_export, or download_log_export.",
     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",
+    "Fetch one log export job by export_id and return its status, filters, requested fields, and file metadata. Use this when you already know the target; use list_log_exports for a workspace-wide overview.",
     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",
+    "Start processing a previously created log export job. This is asynchronous, only queues the export, and does not return rows or a download file; use get_log_export to poll progress and download_log_export after the job completes.",
     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 pending or running log export job. This permanently stops that export, so create a new log export if you need the same data again.",
     LOGGING_TOOL_SCHEMAS.cancelLogExport,
     async (params) => {
       const result = await service.logging.cancelLogExport(params.export_id);
@@ -4882,7 +5066,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "download_log_export",
-    "Get the download URL for a completed log export. Export must be in 'completed' status. Workflow: create_log_export -> start_log_export -> poll get_log_export until completed -> download_log_export.",
+    "Get a signed URL for downloading a completed log export. The export must already be finished; use get_log_export to confirm readiness and start_log_export if it has not run yet.",
     LOGGING_TOOL_SCHEMAS.downloadLogExport,
     async (params) => {
       const result = await service.logging.downloadLogExport(params.export_id);
@@ -4906,7 +5090,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "update_log_export",
-    "Update an existing log export configuration. Only time_of_generation_max, requested_fields, and workspace_id can be modified after creation.",
+    "Update an existing log export configuration before or between export runs. Only workspace_id, time_of_generation_max, and requested_fields can change after creation, so use get_log_export to review the current job and start_log_export after the definition is ready.",
     LOGGING_TOOL_SCHEMAS.updateLogExport,
     async (params) => {
       const updateData = {};
@@ -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 MCP integrations in the organization. Returns paginated integration records plus total and has_more for discovering integration IDs; use get_mcp_integration for one integration's full Portkey-side config and list_mcp_servers for the servers under an integration.",
     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 an MCP integration from an external server URL. Registers the Portkey-side connection and returns the new id and slug; if auth_type is headers, custom_headers are required, and you usually follow with create_mcp_server and capability updates.",
     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 one MCP integration by id or slug. Returns the full Portkey-side config, including auth type, transport, and masked configuration keys; use get_mcp_integration_metadata for the server's self-reported metadata.",
     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 MCP integration's name, description, URL, auth, or transport. Changes apply immediately and altering url or auth_type can break connected clients; use update_mcp_server when you only need to rename or re-describe a server.",
     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 and all servers beneath it. This is irreversible, removes connected access immediately, and should only be used after confirming nothing depends on the integration.",
     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 the external MCP server's self-reported metadata for an integration. Returns name, version, protocol, capability flags, and sync status; use get_mcp_integration for the Portkey-side connection 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 capabilities exposed by the external MCP server for an integration. Returns total plus enabled-state entries so you can decide what to toggle; use before update_mcp_integration_capabilities when you need to compare the current surface.",
     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. Changes take effect immediately for connected users and hide or expose the selected tools, resources, and prompts; use list_mcp_integration_capabilities first if you need the current state.",
     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 can access an MCP integration. Returns the global access mode plus per-workspace enablement for audit or permission review; use before 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 take effect immediately for all users in the selected workspaces; use list_mcp_integration_workspaces first to review the 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 MCP servers in the organization. Returns paginated server records plus total for discovering server IDs; use get_mcp_server for one server's details and list_mcp_integrations for the parent integration.",
     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",
+    "Create an MCP server under an existing integration. Registers the server and returns the new id and slug; use list_mcp_integrations first to find the parent integration, then capabilities or access tools to configure it.",
     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 one MCP server by id or slug. Returns server details including the parent integration, status, and created time; use get_mcp_server when you need the server record rather than the integration config.",
     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 MCP server's name or description. Changes apply immediately, but URL and auth live on the parent integration, so use update_mcp_integration for those fields.",
     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. This is irreversible, removes connected users' access immediately, and should be used only after confirming no workflows depend on the server.",
     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",
+    "Test connectivity to an MCP server. Sends a live check and returns success, response time, HTTP status, and any error; use this before changing configuration or when diagnosing reachability.",
     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 capabilities exposed by an MCP server instance. Returns total plus the current tool, resource, and prompt surface; use this instead of the integration-level capability list when you need server-specific exposure.",
     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 capabilities on an MCP server. Changes take effect immediately and override the integration-level settings for this server; use list_mcp_server_capabilities first to inspect the current surface.",
     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 for an MCP server. Returns the default access mode, override flags, and connection status so you can audit who can use it; use before update_mcp_server_user_access.",
     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. Changes take effect immediately and override the default access setting for the selected users; use list_mcp_server_user_access first if you need the current state.",
     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 reusable prompt partial for inclusion with {{> partial_name}}. Use this for shared snippets or macros; returns the partial id, slug, and version id, and the new version stays inactive until published.",
     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 partials across collections, with optional collection filtering. Returns ids, slugs, names, collections, and status so you can choose a prompt_partial_id before get/update/delete.",
     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",
+    "Fetch a partial's content and current version details. Use this before embedding, updating, or checking what {{> partial_name}} resolves to; returns the stored string plus version metadata.",
     PARTIALS_TOOL_SCHEMAS.getPromptPartial,
     async (params) => {
       const partial = await service.partials.getPromptPartial(
@@ -5776,7 +5960,7 @@ function registerPartialsTools(server, service) {
   );
   server.tool(
     "update_prompt_partial",
-    "Update an existing prompt partial. A new version is created in archived status \u2014 use publish_partial to make it active.",
+    "Create a new version of a partial by updating its content or metadata. Only provided fields change, and the new version stays inactive until publish_partial makes it current.",
     PARTIALS_TOOL_SCHEMAS.updatePromptPartial,
     async (params) => {
       const { prompt_partial_id, ...updateData } = params;
@@ -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 cannot be undone, and prompts that reference it with {{> name}} will fail to render until you replace the reference.",
     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 for one partial, including version numbers, descriptions, status, and timestamps. Use this when you need history or want to choose a version_id before publish_partial.",
     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 partial version as the default version. This changes which content {{> partial_name}} resolves to and replaces the previously active version.",
     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,7 @@ 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.
-
-IMPORTANT: The "string" parameter accepts TWO 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.`,
+    "Create a new prompt template and initial version. Use this for first-time setup; use migrate_prompt for idempotent CI/CD flows. Accepts plain text or structured chat messages, creates a new version immediately, and returns the prompt id, slug, and version id. For multi-message chat prompts pass messages (preferred) or a JSON-encoded array as string.",
     PROMPTS_TOOL_SCHEMAS.createPrompt,
     async (params) => {
       if (!params.model && !params.ai_model_id && !params.finetune_id) {
@@ -6179,6 +6384,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 +6410,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 +6424,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 +6457,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 prompts across the workspace, with optional collection, workspace, or search filters. Returns a paginated summary with id, name, slug, model, and status so you can choose a prompt_id before get_prompt, update_prompt, or render_prompt.",
     PROMPTS_TOOL_SCHEMAS.listPrompts,
     async (params) => {
       const prompts = await service.prompts.listPrompts(params);
@@ -6260,12 +6477,7 @@ Most production prompts use format #2 (multi-message). Use get_prompt to see exa
   );
   server.tool(
     "get_prompt",
-    `Retrieve detailed information about a specific prompt including its template, parameters, and version history.
-
-The template field shows the raw "string" value stored in Portkey:
-- If it starts with "[", it is a JSON-encoded messages array (multi-message prompt with roles).
-- Otherwise it is a plain string template.
-When updating a prompt, pass the same format back in the "string" field of update_prompt.`,
+    "Fetch a prompt's full definition, active version, and version history. Use this before updating, publishing, rendering, or copying a prompt when you need the stored template and metadata. For multi-message chat prompts pass messages (preferred) or a JSON-encoded array as string.",
     PROMPTS_TOOL_SCHEMAS.getPrompt,
     async (params) => {
       const prompt = await service.prompts.getPrompt(params.prompt_id);
@@ -6327,17 +6539,14 @@ When updating a prompt, pass the same format back in the "string" field of updat
   );
   server.tool(
     "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:
-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.`,
+    "Update an existing prompt and create a new archived version. Only provided fields change, and publish_prompt is what makes the new version active. For multi-message chat prompts pass messages (preferred) or a JSON-encoded array as string.",
     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 +6571,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 +6604,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 cannot be undone, immediately breaks callers using the slug, and should only be used after checking list_prompt_versions or confirming you do not need an audit trail.",
     PROMPTS_TOOL_SCHEMAS.deletePrompt,
     async (params) => {
       await service.prompts.deletePrompt(params.prompt_id);
@@ -6409,7 +6627,7 @@ Use get_prompt first to see the current format, then pass the same format back.
   );
   server.tool(
     "publish_prompt",
-    "Publish a specific version of a prompt, making it the default version that will be used when the prompt is called. This is useful for promoting a tested version to production.",
+    "Publish a specific version of a prompt as the active default. Use list_prompt_versions to choose the version and update_prompt when you need to create new content before promoting it.",
     PROMPTS_TOOL_SCHEMAS.publishPrompt,
     async (params) => {
       await service.prompts.publishPrompt(params.prompt_id, {
@@ -6436,7 +6654,7 @@ Use get_prompt first to see the current format, then pass the same format back.
   );
   server.tool(
     "list_prompt_versions",
-    "List all versions of a specific prompt with their details, including version number, description, template content, and creation date.",
+    "List all versions of one prompt, including version number, description, status, label, and a short template preview. Use this for history or to choose a version_id before publish_prompt or update_prompt_version.",
     PROMPTS_TOOL_SCHEMAS.listPromptVersions,
     async (params) => {
       const versions = await service.prompts.listPromptVersions(
@@ -6474,7 +6692,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 by substituting variables and returning the final messages without calling the model. Use this to verify template output before a completion; run_prompt_completion is the tool that actually invokes the model.",
     PROMPTS_TOOL_SCHEMAS.renderPrompt,
     async (params) => {
       const result = await service.prompts.renderPrompt(params.prompt_id, {
@@ -6506,7 +6724,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 against the configured model and return the completion. This makes a billable model call, so use render_prompt first when you want to check the template and validate_completion_metadata when billing fields are uncertain.",
     PROMPTS_TOOL_SCHEMAS.runPromptCompletion,
     async (params) => {
       const result = await service.prompts.runPromptCompletion(
@@ -6545,24 +6763,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 in one idempotent step for CI/CD and prompt-as-code flows. Finds existing prompts by name within the collection, stores app/env in template_metadata, and supports dry_run for safe preflight checks.",
     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: [
@@ -6587,7 +6817,7 @@ Use get_prompt first to see the current format, then pass the same format back.
   );
   server.tool(
     "promote_prompt",
-    "Promote a prompt from one environment to another (e.g., staging -> prod). Copies the current version to the target environment. If the target prompt already exists it is updated with a new version; otherwise a new prompt is created.",
+    "Copy a prompt from one environment to another and create or update the target automatically. Use this for staged releases when you want the target prompt synchronized without manual edits, and it returns both source and target version ids.",
     PROMPTS_TOOL_SCHEMAS.promotePrompt,
     async (params) => {
       const result = await service.prompts.promotePrompt({
@@ -6625,7 +6855,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.",
+    "Preflight billing metadata before run_prompt_completion. Validates required fields and values without making changes, so you can catch attribution errors before paying for the call.",
     PROMPTS_TOOL_SCHEMAS.validateCompletionMetadata,
     async (params) => {
       const result = service.prompts.validateBillingMetadata(params);
@@ -6650,7 +6880,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 prompt version by its version UUID. Use list_prompt_versions to find the id first; returns the template, parameters, and model config for that version.",
     PROMPTS_TOOL_SCHEMAS.getPromptVersion,
     async (params) => {
       const version = await service.prompts.getPromptVersion(
@@ -6669,7 +6899,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's label assignment. This only assigns or removes a label, and null clears the label after you look up ids with list_prompt_labels.",
     PROMPTS_TOOL_SCHEMAS.updatePromptVersion,
     async (params) => {
       if (params.label_id === void 0) {
@@ -6777,7 +7007,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 provider instances and their limits or status. Use this to find provider slugs for workspace-level updates; use list_integrations for the org-level source connection. Returns total plus provider name, slug, integration, status, limits, expiration, and reset flags.",
     PROVIDERS_TOOL_SCHEMAS.listProviders,
     async (params) => {
       const providers = await service.providers.listProviders({
@@ -6823,7 +7053,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 provider backed by an org integration. The provider inherits the integration key, but its limits and expiration are enforced independently for that workspace. Returns the new provider id and slug.",
     PROVIDERS_TOOL_SCHEMAS.createProvider,
     async (params) => {
       const result = await service.providers.createProvider({
@@ -6864,7 +7094,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "get_provider",
-    "Retrieve detailed information about a specific provider by its slug",
+    "Fetch one provider by slug, including limits, rate settings, expiration, and reset status. Use this to check consumption or audit configuration before updating.",
     PROVIDERS_TOOL_SCHEMAS.getProvider,
     async (params) => {
       const provider = await service.providers.getProvider(
@@ -6906,7 +7136,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "update_provider",
-    "Update an existing provider's name, note, limits, or expiration",
+    "Update a provider's metadata, limits, or expiration. reset_usage clears accumulated usage counters immediately, so use it only when you intend to reset quota tracking. Returns the updated provider id and slug.",
     PROVIDERS_TOOL_SCHEMAS.updateProvider,
     async (params) => {
       const result = await service.providers.updateProvider(
@@ -6949,7 +7179,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "delete_provider",
-    "Delete a provider by slug. This action cannot be undone.",
+    "Delete a workspace provider by slug. This is irreversible and will break prompts, configs, and virtual keys that reference it; use delete_integration for the org source instead. Returns success after the provider is removed.",
     PROVIDERS_TOOL_SCHEMAS.deleteProvider,
     async (params) => {
       await service.providers.deleteProvider(params.slug, params.workspace_id);
@@ -6996,15 +7226,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 trace or request. Writes a new feedback record linked by trace_id, returns the created feedback IDs and status, and takes effect immediately; use update_feedback when correcting an existing record.",
     TRACING_TOOL_SCHEMAS.createFeedback,
     async (params) => {
       const result = await service.tracing.createFeedback({
@@ -7033,7 +7260,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 an existing feedback record by ID. Returns the updated status and feedback IDs, changes only value, weight, and metadata, and leaves the trace linkage immutable; use create_feedback only for a new record.",
     TRACING_TOOL_SCHEMAS.updateFeedback,
     async (params) => {
       const result = await service.tracing.updateFeedback(params.id, {
@@ -7059,51 +7286,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 +7389,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 accepted org users with id, name, email, role, and timestamps. Use this to find a user_id before get_user, update_user, delete_user, or add_workspace_member; use list_user_invites for pending invitations.",
     USERS_TOOL_SCHEMAS.listAllUsers,
     async () => {
       const users = await service.users.listUsers();
@@ -7230,7 +7412,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "invite_user",
-    "Invite a new user to your Portkey organization with specific workspace access and API key permissions. After the invite is accepted, use add_workspace_member to assign workspace roles.",
+    "Invite a new org user and optionally provision workspace access and an API key in one call. Workspace assignments apply only after acceptance; use add_workspace_member or update_workspace_member later for follow-up changes.",
     USERS_TOOL_SCHEMAS.inviteUser,
     async (params) => {
       const result = await service.users.inviteUser(params);
@@ -7254,7 +7436,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",
+    "Return per-user request and cost analytics for a required time range. This is usage-by-user, not population metrics; use get_users_analytics for active-user or cohort trends.",
     USERS_TOOL_SCHEMAS.getUserStats,
     async (params) => {
       const stats = await service.users.getUserGroupedData(params);
@@ -7277,7 +7459,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "get_user",
-    "Retrieve detailed information about a specific user by their ID",
+    "Get one accepted user by id and return their profile, role, and timestamps. Use list_all_users to find the id if you only have a name or email, and get_user_invite for pending invitations.",
     USERS_TOOL_SCHEMAS.getUser,
     async (params) => {
       const user = await service.users.getUser(params.user_id);
@@ -7293,7 +7475,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 by id. Email and workspace roles are not editable here; use update_workspace_member for workspace membership changes.",
     USERS_TOOL_SCHEMAS.updateUser,
     async (params) => {
       const { user_id, ...updateData } = params;
@@ -7317,7 +7499,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.",
+    "Delete a user from the org by id. This is permanent, removes org and workspace memberships, revokes API keys, and ends active sessions; use delete_user_invite for pending invites instead.",
     USERS_TOOL_SCHEMAS.deleteUser,
     async (params) => {
       await service.users.deleteUser(params.user_id);
@@ -7340,7 +7522,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "list_user_invites",
-    "List all pending and sent user invitations in your Portkey organization",
+    "List pending and sent invitations with id, email, role, status, and expiry. Use this to check invite state; use list_all_users for users who already accepted.",
     USERS_TOOL_SCHEMAS.listUserInvites,
     async () => {
       const invites = await service.users.listUserInvites();
@@ -7363,7 +7545,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "get_user_invite",
-    "Retrieve details about a specific user invitation",
+    "Get one invitation by invite id and return its email, role, status, and expiry. Use this for pending invites only; use get_user for accepted users.",
     USERS_TOOL_SCHEMAS.getUserInvite,
     async (params) => {
       const invite = await service.users.getUserInvite(params.invite_id);
@@ -7379,7 +7561,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "delete_user_invite",
-    "Cancel and delete a pending user invitation",
+    "Delete a pending invite and revoke its invite link. This does not affect existing users; use delete_user for full user removal.",
     USERS_TOOL_SCHEMAS.deleteUserInvite,
     async (params) => {
       await service.users.deleteUserInvite(params.invite_id);
@@ -7402,7 +7584,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "resend_user_invite",
-    "Resend an invitation email to a pending user",
+    "Resend the email for a pending invite that has not been accepted. The invite must still exist; use get_user_invite first if you are unsure.",
     USERS_TOOL_SCHEMAS.resendUserInvite,
     async (params) => {
       await service.users.resendUserInvite(params.invite_id);
@@ -7532,7 +7714,7 @@ function formatWorkspaceDetail(workspace) {
 function registerWorkspacesTools(server, service) {
   server.tool(
     "list_workspaces",
-    "Retrieve all workspaces in your Portkey organization, including their configurations and metadata",
+    "List workspaces with id, name, slug, default settings, and timestamps. Use this to find a workspace_id before get_workspace, update_workspace, add_workspace_member, or remove_workspace_member.",
     WORKSPACES_TOOL_SCHEMAS.listWorkspaces,
     async (params) => {
       const workspaces = await service.workspaces.listWorkspaces(params);
@@ -7555,7 +7737,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "get_workspace",
-    "Retrieve detailed information about a specific workspace, including its configuration, metadata, and user access details",
+    "Get one workspace by id and return its full details, including defaults and the complete member list. Use this when you need membership detail; use list_workspaces for an overview.",
     WORKSPACES_TOOL_SCHEMAS.getWorkspace,
     async (params) => {
       const workspace = await service.workspaces.getWorkspace(
@@ -7573,7 +7755,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "create_workspace",
-    "Create a new workspace in your Portkey organization",
+    "Create a workspace to isolate resources, API keys, and team members. If slug is omitted it is auto-generated from the name; returns the new workspace id, name, and slug.",
     WORKSPACES_TOOL_SCHEMAS.createWorkspace,
     async (params) => {
       const workspace = await service.workspaces.createWorkspace({
@@ -7604,7 +7786,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 flag, or metadata by id. Only provided fields change; changing the slug can break URLs and other references.",
     WORKSPACES_TOOL_SCHEMAS.updateWorkspace,
     async (params) => {
       const { workspace_id, is_default, metadata, ...rest } = params;
@@ -7634,7 +7816,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "delete_workspace",
-    "Delete a workspace from your organization. Permanently deletes the workspace and all its members, configs, API keys, and resources. Cannot be undone.",
+    "Delete a workspace by id. This is permanent and removes the workspace, its members, configs, API keys, and resources.",
     WORKSPACES_TOOL_SCHEMAS.deleteWorkspace,
     async (params) => {
       await service.workspaces.deleteWorkspace(params.workspace_id);
@@ -7657,7 +7839,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "add_workspace_member",
-    "Add a user to a workspace with a specific role",
+    "Add an existing org user to a workspace with a role. Requires a UUID user_id; use list_all_users to find it, and invite_user first if the person is not yet in the org.",
     WORKSPACES_TOOL_SCHEMAS.addWorkspaceMember,
     async (params) => {
       const member = await service.workspaces.addWorkspaceMember(
@@ -7686,7 +7868,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "list_workspace_members",
-    "List all members of a workspace with their roles",
+    "List every member in a workspace with organization role, workspace role, status, and timestamps. Use this to find a user_id before get_workspace_member, update_workspace_member, or remove_workspace_member.",
     WORKSPACES_TOOL_SCHEMAS.listWorkspaceMembers,
     async (params) => {
       const members = await service.workspaces.listWorkspaceMembers(
@@ -7711,7 +7893,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "get_workspace_member",
-    "Get details about a specific member of a workspace",
+    "Get one workspace member by workspace_id and user_id. Use this when you already know both IDs; use list_workspace_members to browse the full roster.",
     WORKSPACES_TOOL_SCHEMAS.getWorkspaceMember,
     async (params) => {
       const member = await service.workspaces.getWorkspaceMember(
@@ -7730,7 +7912,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "update_workspace_member",
-    "Update a member's role in a workspace",
+    "Update a workspace member's role by workspace_id and user_id. Only the role changes here; use list_workspace_members or get_workspace_member to confirm the current assignment first.",
     WORKSPACES_TOOL_SCHEMAS.updateWorkspaceMember,
     async (params) => {
       const member = await service.workspaces.updateWorkspaceMember(
@@ -7759,7 +7941,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "remove_workspace_member",
-    "Remove a user from a workspace",
+    "Remove a user from a workspace and revoke workspace access. This does not delete the user from the organization; use delete_user for full removal.",
     WORKSPACES_TOOL_SCHEMAS.removeWorkspaceMember,
     async (params) => {
       await service.workspaces.removeWorkspaceMember(
@@ -7840,6 +8022,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 +8101,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 +8214,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 +8860,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 +8895,9 @@ function createMcpServer(options = {}) {
       instructions: SERVER_INSTRUCTIONS
     }
   );
-  registerAllTools(server, service, { domains: options.toolDomains });
+  registerAllTools(server, service, {
+    domains: options.toolDomains ?? parseConfiguredToolDomains()
+  });
   return {
     server,
     service