portkey-admin-mcp 0.3.0 → 0.3.2

package/build/server.js

@@ -1881,7 +1881,7 @@ function normalizeAnalyticsParams(params) {
 function registerAnalyticsTools(server, service) {
   server.tool(
     "get_cost_analytics",
-    "Returns time-series of total and average cost per request over the specified period. Use to track spending trends and identify cost spikes. Differs from get_token_analytics which measures token consumption, not monetary cost. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -1914,7 +1914,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_request_analytics",
-    "Returns time-series of total, successful, and failed request counts over the specified period. Use to monitor traffic volume and success/failure trends. Differs from get_error_analytics which only shows error counts. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -1949,7 +1949,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_token_analytics",
-    "Returns time-series of total, prompt, and completion token counts over the specified period. Use to track token consumption and identify usage patterns. Differs from get_cost_analytics which shows monetary cost, not token volume. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -1984,7 +1984,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_latency_analytics",
-    "Returns time-series of avg, p50, p90, and p99 latency percentiles in ms over the specified period. Use to monitor response times and detect latency regressions. Differs from get_cache_hit_latency which only measures latency for cached responses. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2021,7 +2021,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_error_analytics",
-    "Returns time-series of total error counts over the specified period. Use for high-level error trend monitoring. For error breakdown by status code, use get_error_status_codes_analytics or get_error_stacks_analytics; for error rate as a percentage, use get_error_rate_analytics. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2052,7 +2052,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_error_rate_analytics",
-    "Returns time-series of error rate as a percentage of total requests over the specified period. Use to track reliability trends and SLA compliance. Differs from get_error_analytics which shows absolute error counts, not percentages. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2083,7 +2083,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_cache_hit_latency",
-    "Returns time-series of latency specifically for cache hits over the specified period. Use to evaluate cache performance and response speed for cached requests. Differs from get_latency_analytics which measures latency across all requests. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2116,7 +2116,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_cache_hit_rate",
-    "Returns time-series of cache hit rate percentage, total hits, and misses over the specified period. Use to evaluate cache effectiveness and tune caching strategy. Unrelated to get_cache_hit_latency which measures speed of cached responses, not hit/miss ratio. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2151,7 +2151,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_users_analytics",
-    "Returns time-series of active and new user counts over the specified period. Use for user growth tracking and adoption metrics. Differs from get_user_requests_analytics which shows per-user request breakdown, and get_analytics_group_users which shows per-user cost/token data. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2184,7 +2184,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_error_stacks_analytics",
-    "Returns errors broken down by status code stacks (e.g., 429, 500, 502) over the specified period. Use to identify which error types are most common and how they trend. Differs from get_error_status_codes_analytics which shows unique code distribution rather than stacked/cumulative breakdown. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2206,7 +2206,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_error_status_codes_analytics",
-    "Returns distribution of unique HTTP error status codes over the specified period. Use to see which status codes are occurring and their frequency. Differs from get_error_stacks_analytics which shows stacked/cumulative error breakdown rather than individual code distribution. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2228,7 +2228,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_user_requests_analytics",
-    "Returns per-user request count breakdown over the specified period. Use to identify heavy users and per-user traffic patterns. Differs from get_users_analytics which shows aggregate active/new user counts, not individual user breakdowns. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2250,7 +2250,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_rescued_requests_analytics",
-    "Returns time-series of requests saved by retry or fallback strategies over the specified period. Use to evaluate the effectiveness of your Portkey configs' resilience features. Only relevant if configs include retry or fallback targets. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2272,7 +2272,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_feedback_analytics",
-    "Returns time-series of feedback submission counts over the specified period. Use to track feedback volume trends. For breakdown by model, use get_feedback_models_analytics; for score distribution, use get_feedback_scores_analytics; for weighted scores, use get_feedback_weighted_analytics. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2294,7 +2294,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_feedback_models_analytics",
-    "Returns feedback counts grouped by AI model over the specified period. Use to compare user satisfaction and feedback volume across different models. Differs from get_feedback_analytics which shows total volume without model breakdown. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2316,7 +2316,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_feedback_scores_analytics",
-    "Returns distribution of raw feedback score values over the specified period. Use to understand score patterns (e.g., mostly positive vs mixed). Differs from get_feedback_weighted_analytics which applies weight factors for calibrated metrics. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2338,7 +2338,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_feedback_weighted_analytics",
-    "Returns weighted feedback scores over the specified period, applying the weight factor set during feedback creation. Use for calibrated quality metrics where different feedback types have different importance. Differs from get_feedback_scores_analytics which shows raw unweighted scores. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2360,7 +2360,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_analytics_group_users",
-    "Returns analytics data aggregated per user with pagination, showing each user's request count, cost, and token usage. Use for per-user billing, audit, or identifying top consumers. Differs from get_users_analytics which shows aggregate active/new user counts over time. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2382,7 +2382,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_analytics_group_models",
-    "Returns analytics data aggregated per AI model with pagination, showing each model's request count, cost, and token usage. Use to compare model costs, popularity, and efficiency. Requires time_of_generation_min and time_of_generation_max.",
+    "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(
@@ -2404,7 +2404,7 @@ function registerAnalyticsTools(server, service) {
   );
   server.tool(
     "get_analytics_group_metadata",
-    "Returns analytics data grouped by a custom metadata key (e.g., 'env', 'app', 'client_id') with pagination. Use for custom breakdowns like per-environment or per-feature cost analysis. Requires the metadata_key parameter in addition to time_of_generation_min and time_of_generation_max.",
+    "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;
@@ -2454,7 +2454,7 @@ var AUDIT_TOOL_SCHEMAS = {
 function registerAuditTools(server, service) {
   server.tool(
     "list_audit_logs",
-    "Retrieve audit logs for your Portkey organization. Use this for compliance and security reviews. Audit logs track all administrative actions including user management, configuration changes, and access events. Unlike analytics tools which show aggregated metrics, audit logs show individual action events with actor details. Supports filtering by time range, actor, action type, and resource.",
+    "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({
@@ -2534,7 +2534,7 @@ var COLLECTIONS_TOOL_SCHEMAS = {
 function registerCollectionsTools(server, service) {
   server.tool(
     "list_collections",
-    "List all prompt collections in your Portkey organization. Collections organize prompts by application (e.g., hourlink, apizone, research-pilot). Use to discover collection_id values before creating or listing prompts. Returns id, name, and slug per collection.",
+    "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);
@@ -2564,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). Returns the new collection_id and slug needed for create_prompt.",
+    "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);
@@ -2588,7 +2588,7 @@ function registerCollectionsTools(server, service) {
   );
   server.tool(
     "get_collection",
-    "Retrieve full details of a specific collection by ID or slug, including name, slug, and workspace_id. Use get_collection when you have a specific ID; use list_collections to browse all collections.",
+    "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(
@@ -2617,7 +2617,7 @@ function registerCollectionsTools(server, service) {
   );
   server.tool(
     "update_collection",
-    "Update a collection's display name or description. Does not affect prompts within the collection.",
+    "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, {
@@ -2643,7 +2643,7 @@ function registerCollectionsTools(server, service) {
   );
   server.tool(
     "delete_collection",
-    "Delete a prompt collection by ID. This action cannot be undone. Prompts inside the collection are not deleted but lose their grouping and move to the top level. Reassign prompts to another collection first if organization must be preserved.",
+    "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(
@@ -2741,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. Configs define request routing behavior (cache, retry, fallback, load balancing). Use to discover config slugs before inspecting or modifying them.",
+    "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();
@@ -2775,7 +2775,7 @@ function registerConfigsTools(server, service) {
   );
   server.tool(
     "get_config",
-    "Retrieve detailed information about a specific configuration, including cache settings, retry policies, routing strategy, and targets. Use when you need to inspect a config's full settings or clone an existing config's structure.",
+    "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);
@@ -2819,7 +2819,7 @@ function registerConfigsTools(server, service) {
   );
   server.tool(
     "create_config",
-    "Create a new configuration that defines how AI requests are routed, cached, retried, and load-balanced across providers. At least one setting is required: cache (cache_mode/cache_max_age), retry (retry_attempts/retry_on_status_codes), strategy_mode, or targets.",
+    "Create a config that defines routing, cache, retry, and targets for requests; use update_config to modify an existing one and list_config_versions for history. At least one setting is required, new configs become active immediately once referenced by a key or prompt, and the call returns the new id and version_id.",
     CONFIGS_TOOL_SCHEMAS.createConfig,
     async (params) => {
       const config = buildConfigPayload(params);
@@ -2859,7 +2859,7 @@ function registerConfigsTools(server, service) {
   );
   server.tool(
     "update_config",
-    "Update an existing configuration's cache, retry, or routing settings. Creates a new version; only provided fields are updated, unspecified fields remain unchanged.",
+    "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);
@@ -2894,7 +2894,7 @@ function registerConfigsTools(server, service) {
   );
   server.tool(
     "delete_config",
-    "Delete a configuration by slug. This action cannot be undone and removes all versions. Requests and API keys referencing this config slug will fail immediately. Use list_config_versions first to review history; audit dependent API keys before deleting.",
+    "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);
@@ -2917,7 +2917,7 @@ function registerConfigsTools(server, service) {
   );
   server.tool(
     "list_config_versions",
-    "List all versions of a configuration to view its change history. Use to audit past changes, compare versions, or find a specific version ID for rollback.",
+    "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);
@@ -2999,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. Guardrails are content moderation and security policies applied to AI requests. Use to discover guardrail IDs and slugs before inspecting or modifying them.",
+    "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);
@@ -3033,7 +3033,7 @@ function registerGuardrailsTools(server, service) {
   );
   server.tool(
     "get_guardrail",
-    "Retrieve detailed information about a specific guardrail, including its full checks and actions configuration. Use when you need to inspect or modify a guardrail's rules, or to understand what checks are applied before updating.",
+    "Fetch one guardrail by id or slug with its full checks and actions; use list_guardrails to discover ids first. Use before update_guardrail or delete_guardrail when you need the exact enforcement policy, and returns the full check and action configuration alongside status and ownership.",
     GUARDRAILS_TOOL_SCHEMAS.getGuardrail,
     async (params) => {
       const guardrail = await service.guardrails.getGuardrail(
@@ -3068,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. Guardrails are applied to requests via configs -- create the guardrail first, then reference it in a config. checks is an array of check objects with id (e.g. 'default.jwt', 'default.pii'), optional name, is_enabled boolean, and parameters object.",
+    "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({
@@ -3099,7 +3099,7 @@ function registerGuardrailsTools(server, service) {
   );
   server.tool(
     "update_guardrail",
-    "Update an existing guardrail's name, checks, or actions configuration. Creates a new version of the guardrail; existing references in configs continue working with the latest version.",
+    "Update a guardrail's name, checks, or actions, unlike create_guardrail which registers a new one or delete_guardrail which removes it. This creates a new version that takes effect immediately for dependent configs, so review list_guardrails first; returns the updated id, slug, and version_id.",
     GUARDRAILS_TOOL_SCHEMAS.updateGuardrail,
     async (params) => {
       const updateData = {};
@@ -3137,7 +3137,7 @@ function registerGuardrailsTools(server, service) {
   );
   server.tool(
     "delete_guardrail",
-    "Delete a guardrail by its ID or slug. This action cannot be undone. Configs referencing this guardrail as a before/after request hook will stop enforcing it, silently dropping the safety check. Review dependent configs before deleting.",
+    "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(
@@ -3300,7 +3300,7 @@ var INTEGRATIONS_TOOL_SCHEMAS = {
 function registerIntegrationsTools(server, service) {
   server.tool(
     "list_integrations",
-    "List org-level connections to AI providers (OpenAI, Anthropic, Azure, etc.) with optional filtering by workspace or type. Use to discover integration slugs for other integration tools. Returns paginated results with id, slug, provider, and status. Differs from list_providers, which shows workspace-scoped provider instances.",
+    "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({
@@ -3338,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 = {};
@@ -3386,7 +3386,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "get_integration",
-    "Retrieve detailed information about a specific integration by its slug. Returns full config including masked API key, workspace access settings, and allowed models. Use when you need provider-specific details or to audit an integration's configuration.",
+    "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(
@@ -3423,7 +3423,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "update_integration",
-    "Update an existing integration's name, API key, description, or provider-specific configurations. API key changes take effect immediately. Changing provider-specific configs (Azure resource_name, Vertex region, etc.) may break active requests using this integration.",
+    "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 = {};
@@ -3470,7 +3470,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "delete_integration",
-    "Delete an integration by slug. This action cannot be undone. Removes the org-level provider connection; all dependent virtual keys and providers will stop working.",
+    "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);
@@ -3493,7 +3493,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "list_integration_models",
-    "List which AI models are enabled for a specific integration, with their enabled/disabled status and custom flag. Use to check model availability before creating prompts or configs. Returns paginated results with model id, name, and enabled state.",
+    "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(
@@ -3531,7 +3531,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "update_integration_models",
-    "Enable/disable specific models or register custom model names for an integration. Changes affect all workspaces using this integration. Pass an array of model configurations with slug, enabled state, and optional is_custom flag.",
+    "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(
@@ -3560,7 +3560,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "delete_integration_model",
-    "Delete a specific custom model from an integration. Only custom models can be deleted; built-in models should be disabled via update_integration_models instead. Returns success status.",
+    "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(
@@ -3586,7 +3586,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "list_integration_workspaces",
-    "List which workspaces can access a specific integration, including their usage limits and rate limits. Use to audit workspace access and review per-workspace spending/rate configurations. Returns paginated results.",
+    "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(
@@ -3625,7 +3625,7 @@ function registerIntegrationsTools(server, service) {
   );
   server.tool(
     "update_integration_workspaces",
-    "Control which workspaces can use an integration and set per-workspace usage/rate limits. Pass an array of workspace configurations with id, enabled state, and optional credit_limit, alert_threshold, and rate_limit_rpm.",
+    "Control which workspaces can use an integration and set per-workspace limits, unlike update_integration which edits the org-level connection. Call list_integration_workspaces first to review current state; access changes and new limits apply to downstream usage immediately, and the call returns success plus the number of workspaces updated.",
     INTEGRATIONS_TOOL_SCHEMAS.updateIntegrationWorkspaces,
     async (params) => {
       const result = await service.integrations.updateIntegrationWorkspaces(
@@ -3753,7 +3753,7 @@ var KEYS_TOOL_SCHEMAS = {
 function registerKeysTools(server, service) {
   server.tool(
     "list_virtual_keys",
-    "List virtual keys that securely store provider API keys (OpenAI, Anthropic, etc.) in your Portkey organization. Use to discover virtual key slugs referenced in prompts and configs. Returns all keys with their usage limits, rate limits, and status.",
+    "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();
@@ -3794,7 +3794,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "create_virtual_key",
-    "Securely store a provider API key as a virtual key. The original key is encrypted and never returned after creation. Use the returned slug to reference this key in prompts and configs. Supports optional usage/rate limits.",
+    "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({
@@ -3833,7 +3833,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "get_virtual_key",
-    "Retrieve detailed information about a specific virtual key by its slug. Returns key metadata with a masked version of the stored API key. Use to check usage limits, rate limits, and status.",
+    "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);
@@ -3871,7 +3871,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "update_virtual_key",
-    "Update an existing virtual key's name, API key, note, or limits. Can rotate the underlying provider API key by passing a new key value. Changes to limits take effect immediately.",
+    "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, {
@@ -3905,7 +3905,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "delete_virtual_key",
-    "Delete a virtual key by slug. This action cannot be undone. Prompts and configs referencing this key will fail; ensure no active resources depend on it before deleting.",
+    "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);
@@ -3928,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.). Returns the key value only once at creation time \u2014 save it immediately.",
+    "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) {
@@ -3999,7 +3999,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "list_api_keys",
-    "List Portkey API keys (not provider keys \u2014 use list_virtual_keys for those) with optional pagination and workspace filtering. Use to audit access and review key scopes, limits, and expiration across your organization.",
+    "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({
@@ -4052,7 +4052,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "get_api_key",
-    "Retrieve detailed information about a specific API key by its UUID. Returns key metadata without the secret key value. Use to check scopes, usage/rate limits, defaults, and expiration.",
+    "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);
@@ -4099,7 +4099,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "update_api_key",
-    "Update an existing API key's name, description, scopes, or limits. Can modify scopes, usage/rate limits, defaults, and expiration. Cannot change key type or sub_type after creation.",
+    "Update an API key's name, description, scopes, defaults, or limits, unlike delete_api_key which revokes it or create_api_key which issues a new one. Changes take effect immediately for downstream callers, type and sub-type stay fixed after creation, and the call returns success without rotating the secret.",
     KEYS_TOOL_SCHEMAS.updateApiKey,
     async (params) => {
       const result = await service.keys.updateApiKey(params.id, {
@@ -4137,7 +4137,7 @@ function registerKeysTools(server, service) {
   );
   server.tool(
     "delete_api_key",
-    "Delete an API key by UUID. This action cannot be undone. Immediately revokes authentication; active sessions using this key will fail.",
+    "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);
@@ -4197,7 +4197,7 @@ var LABELS_TOOL_SCHEMAS = {
 function registerLabelsTools(server, service) {
   server.tool(
     "create_prompt_label",
-    "Create a new prompt label to categorize prompt versions (e.g., 'production', 'staging', 'experiment'). Requires either organisation_id or workspace_id to set the label's scope. Returns the new label's id. Use update_prompt_version to assign labels to specific prompt versions.",
+    "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) {
@@ -4237,7 +4237,7 @@ function registerLabelsTools(server, service) {
   );
   server.tool(
     "list_prompt_labels",
-    "List all prompt labels with optional filtering by workspace, organisation, or search query. Returns id, name, color_code, and status for each label. Use to discover label IDs before assigning them to prompt versions via update_prompt_version.",
+    "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);
@@ -4269,7 +4269,7 @@ function registerLabelsTools(server, service) {
   );
   server.tool(
     "get_prompt_label",
-    "Retrieve full details of a specific prompt label including its scope (organisation_id vs workspace_id), color, and status. Use when you need to inspect a label's properties before updating it.",
+    "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, {
@@ -4303,7 +4303,7 @@ function registerLabelsTools(server, service) {
   );
   server.tool(
     "update_prompt_label",
-    "Update a prompt label's name, description, or color_code. Changes apply to the label definition only; existing prompt version assignments using this label are not affected.",
+    "Update a prompt label's name, description, or color only, unlike update_prompt_version which changes which label a version carries. This takes effect immediately for all versions already tagged with the label, but does not reassign labels or touch history; use list_prompt_labels to find the label_id first.",
     LABELS_TOOL_SCHEMAS.updatePromptLabel,
     async (params) => {
       const { label_id, ...updateData } = params;
@@ -4327,7 +4327,7 @@ function registerLabelsTools(server, service) {
   );
   server.tool(
     "delete_prompt_label",
-    "Delete a prompt label by ID. This action cannot be undone. Prompt versions carrying this label lose it, and any workflow resolving prompts by this label (e.g., 'production', 'staging') will fail until reassigned. Audit label usage via list_prompts before deleting.",
+    "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);
@@ -4479,7 +4479,7 @@ function formatUsageLimitEntity(entity) {
 function registerLimitsTools(server, service) {
   server.tool(
     "list_rate_limits",
-    "Retrieve all rate limits in your Portkey organization. Use to discover existing rate limit policies before creating new ones. Returns an array of rate limits each containing id, type, unit, value, and status. Rate limits control how many requests or tokens can be consumed per time unit (rpm/rph/rpd).",
+    "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);
@@ -4502,7 +4502,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "get_rate_limit",
-    "Retrieve detailed information about a specific rate limit by its ID. Returns full detail including conditions and group_by fields. Use when you have a specific rate limit ID from list_rate_limits and need to inspect its complete configuration.",
+    "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);
@@ -4518,7 +4518,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "create_rate_limit",
-    "Create a new rate limit policy to throttle requests in real-time by controlling request/token consumption per time unit. Differs from usage limits, which cap cumulative consumption over time. Requires conditions to match against and group_by to specify how limits are applied.",
+    "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({
@@ -4550,7 +4550,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "update_rate_limit",
-    "Update an existing rate limit's name, unit, or value. Only name, unit, and value can be changed after creation; conditions and group_by are immutable. Returns the updated rate limit object.",
+    "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, {
@@ -4577,7 +4577,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "delete_rate_limit",
-    "Delete a rate limit policy by ID. This action cannot be undone. Requests previously throttled by this policy will no longer be limited; review dependent configs and virtual keys first to avoid unexpected traffic spikes.",
+    "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);
@@ -4600,7 +4600,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "list_usage_limits",
-    "Retrieve all usage limits in your Portkey organization. Differs from rate limits: usage limits cap total cumulative cost or tokens over time, optionally resetting on a weekly or monthly schedule. Returns an array of usage limits with id, type, credit_limit, status, and reset schedule.",
+    "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);
@@ -4623,7 +4623,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "get_usage_limit",
-    "Retrieve detailed information about a specific usage limit by its ID. Returns full detail including conditions, group_by, credit_limit, alert_threshold, and periodic reset schedule.",
+    "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);
@@ -4639,7 +4639,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "create_usage_limit",
-    "Create a new usage limit policy to enforce spending or token budgets over time. Differs from rate limits, which control real-time request velocity. Requires conditions to match against and group_by to specify how limits are applied. Supports optional periodic resets and alert thresholds.",
+    "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({
@@ -4672,7 +4672,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "update_usage_limit",
-    "Update an existing usage limit's configuration. Modifiable fields: name, credit_limit, alert_threshold, periodic_reset, and reset_usage_for_value. Conditions and group_by are immutable after creation.",
+    "Update a usage limit's name, credit_limit, alert_threshold, reset schedule, or reset target by id, unlike update_rate_limit which tunes request throttling. New values apply immediately to tracked usage, conditions and group_by are immutable after creation, and the call returns the updated id without clearing accumulated usage (use reset_usage_limit_entity for that).",
     LIMITS_TOOL_SCHEMAS.updateUsageLimit,
     async (params) => {
       const result = await service.limits.updateUsageLimit(params.id, {
@@ -4701,7 +4701,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "delete_usage_limit",
-    "Delete a usage limit policy by ID. This action cannot be undone. Budgets and quotas enforced by this policy are removed immediately and tracked entities lose accumulated usage state. Use list_usage_limit_entities first to review impact before deleting.",
+    "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);
@@ -4724,7 +4724,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "list_usage_limit_entities",
-    "List all entities (individual keys, users, or groups) tracked against a usage limit policy. Shows current consumption per entity, useful for monitoring who is approaching or has exceeded their budget.",
+    "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(
@@ -4749,7 +4749,7 @@ function registerLimitsTools(server, service) {
   );
   server.tool(
     "reset_usage_limit_entity",
-    "Reset the accumulated usage counter to zero for a specific entity on a usage limit policy. Does not delete the entity or the policy itself. Use when an entity needs its budget restored before the next scheduled periodic reset.",
+    "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(
@@ -4866,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. Use this for external or custom logs not routed through the Portkey gateway. request_provider must match a configured integration (e.g. 'openai', 'anthropic'). Use metadata_span_id and metadata_parent_span_id to create trace hierarchies.",
+    "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 = {
@@ -4914,7 +4914,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "create_log_export",
-    "Create a new log export job definition with filters and field selection. This only creates the job \u2014 you must call start_log_export to begin processing, then poll get_log_export to check status. time_min/time_max accept ISO 8601 format ('2024-01-01T00:00:00Z'). Returns the export ID and matching log count.",
+    "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({
@@ -4952,7 +4952,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "list_log_exports",
-    "List all log export jobs for a workspace. Returns each export with its current status (pending/running/completed/failed), filters, and timestamps. Use this to find export_ids for subsequent get, start, cancel, or download operations.",
+    "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({
@@ -4987,7 +4987,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "get_log_export",
-    "Get details of a specific log export by its ID. Use this to check the current status of an export (pending/running/completed/failed) and view its full configuration. Unlike list_log_exports which returns summaries of all exports, this returns complete detail for a single export including filters and requested fields.",
+    "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);
@@ -5018,7 +5018,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "start_log_export",
-    "Trigger processing of a previously created log export job. You must call create_log_export first to define the export before starting it. After starting, poll get_log_export to monitor progress until status is 'completed', then use download_log_export to retrieve results.",
+    "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);
@@ -5042,7 +5042,7 @@ function registerLoggingTools(server, service) {
   );
   server.tool(
     "cancel_log_export",
-    "Cancel a running or pending log export job. This permanently stops the export \u2014 it cannot be resumed after cancellation. To export the same data, create a new export job with create_log_export.",
+    "Cancel a pending or running log export job, unlike start_log_export which queues one or delete_integration which removes the source. This permanently stops that export, takes effect immediately, and does not roll back already-processed rows; call create_log_export and start_log_export again to retry.",
     LOGGING_TOOL_SCHEMAS.cancelLogExport,
     async (params) => {
       const result = await service.logging.cancelLogExport(params.export_id);
@@ -5066,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);
@@ -5090,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 = {};
@@ -5257,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. MCP integrations connect external MCP servers to your Portkey org. Use to discover integration IDs needed by other tools. Differs from list_mcp_servers which shows server instances under an integration. Returns paginated array of integrations with total count and has_more flag.",
+    "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);
@@ -5281,7 +5281,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "create_mcp_integration",
-    "Create a new MCP integration by registering an external MCP server URL with auth configuration. After creation, use create_mcp_server to add server instances and update_mcp_integration_capabilities to control which tools are exposed. Returns the new integration's id and slug.",
+    "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)) {
@@ -5320,7 +5320,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "get_mcp_integration",
-    "Retrieve detailed information about a specific MCP integration by ID or slug. Returns full integration config including auth type, transport, and configuration keys (header values are masked). Use to inspect Portkey-side connection details. Differs from get_mcp_integration_metadata which returns the external server's self-reported info.",
+    "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(
@@ -5338,7 +5338,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "update_mcp_integration",
-    "Update an existing MCP integration's name, description, URL, auth, or transport. Changing url or auth_type may break active connections. Changes take effect immediately for all connected users.",
+    "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;
@@ -5365,7 +5365,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "delete_mcp_integration",
-    "Delete an MCP integration permanently. Also removes all MCP servers under this integration. Connected users will lose access immediately. 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);
@@ -5388,7 +5388,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "get_mcp_integration_metadata",
-    "Retrieve server-reported metadata for an MCP integration including name, version, protocol, and sync status. Use to verify the external server is responding and check its capabilities. Differs from get_mcp_integration which shows Portkey-side config.",
+    "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(
@@ -5410,7 +5410,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "list_mcp_integration_capabilities",
-    "List all capabilities (tools, resources, prompts) the external MCP server exposes on an integration. Use before update_mcp_integration_capabilities to see what can be enabled or disabled. Returns total count and array of capabilities with their enabled status.",
+    "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);
@@ -5430,7 +5430,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "update_mcp_integration_capabilities",
-    "Bulk enable or disable capabilities on an MCP integration to control which MCP tools, resources, and prompts are available to users. Disabled capabilities are hidden from connected clients. Changes take effect immediately.",
+    "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(
@@ -5458,7 +5458,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "list_mcp_integration_workspaces",
-    "List which workspaces have access to an MCP integration. Returns global access setting and per-workspace enabled status. Use to audit access before modifying permissions with update_mcp_integration_workspaces.",
+    "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(
@@ -5486,7 +5486,7 @@ function registerMcpIntegrationsTools(server, service) {
   );
   server.tool(
     "update_mcp_integration_workspaces",
-    "Grant or revoke workspace access to an MCP integration in bulk. Changes affect all users in the workspace immediately. Use list_mcp_integration_workspaces first to see current access state.",
+    "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, {
@@ -5601,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. MCP servers are instances under MCP integrations. Use to discover server IDs needed by other tools. Differs from list_mcp_integrations which shows the parent integration connections. Returns paginated array of servers with total count.",
+    "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);
@@ -5624,7 +5624,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "create_mcp_server",
-    "Register a new MCP server instance under an existing MCP integration. Use list_mcp_integrations to find the mcp_integration_id first. Returns the new server's id and slug.",
+    "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);
@@ -5648,7 +5648,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "get_mcp_server",
-    "Retrieve detailed information about a specific MCP server by ID or slug. Returns server details including linked integration ID and status. Use to check server configuration and health.",
+    "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);
@@ -5664,7 +5664,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "update_mcp_server",
-    "Update an existing MCP server's name or description. Only name and description can be changed on a server. To change the URL or auth configuration, update the parent MCP integration instead.",
+    "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;
@@ -5688,7 +5688,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "delete_mcp_server",
-    "Delete an MCP server instance by ID. This action cannot be undone. Connected users and workspaces lose access immediately, and workspace access grants to this server are removed. Verify no active integrations depend on it before deleting.",
+    "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);
@@ -5711,7 +5711,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "test_mcp_server",
-    "Send a connectivity check to an MCP server to verify it is reachable and responding. Returns success/failure, response time in ms, and any error message. Use to diagnose connection issues before investigating configuration.",
+    "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);
@@ -5727,7 +5727,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "list_mcp_server_capabilities",
-    "List all capabilities (tools, resources, prompts) exposed by an MCP server instance. Differs from list_mcp_integration_capabilities which shows integration-level capability settings. Returns total count and array of capabilities.",
+    "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(
@@ -5749,7 +5749,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "update_mcp_server_capabilities",
-    "Enable or disable specific capabilities on an MCP server instance. Overrides integration-level capability settings for this server. Changes take effect immediately for connected users.",
+    "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, {
@@ -5774,7 +5774,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "list_mcp_server_user_access",
-    "List per-user access settings for an MCP server including override flags and connection status. Returns default_user_access setting and array of users. Use to audit who can access this server before modifying permissions.",
+    "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(
@@ -5800,7 +5800,7 @@ function registerMcpServersTools(server, service) {
   );
   server.tool(
     "update_mcp_server_user_access",
-    "Grant or revoke individual user access to an MCP server. Overrides the default_user_access setting for specified users. Changes take effect immediately.",
+    "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, {
@@ -5865,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}}. After creation, use publish_partial to make it the default version. Returns id, slug, and version_id.",
+    "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({
@@ -5895,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. Returns all partials with id, slug, name, and status. Use to discover partial IDs or check if a partial already exists before creating.",
+    "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_prompt_partial, update_prompt_partial, delete_prompt_partial, or publish_partial.",
     PARTIALS_TOOL_SCHEMAS.listPromptPartials,
     async (params) => {
       const partials = await service.partials.listPromptPartials(params);
@@ -5926,7 +5926,7 @@ function registerPartialsTools(server, service) {
   );
   server.tool(
     "get_prompt_partial",
-    "Retrieve detailed information about a specific prompt partial. Returns the partial's content string and current version info. Use to inspect content before including it in a prompt via {{> partial_name}}.",
+    "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(
@@ -5960,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;
@@ -5987,7 +5987,7 @@ function registerPartialsTools(server, service) {
   );
   server.tool(
     "delete_prompt_partial",
-    "Delete a prompt partial by ID. This action cannot be undone. Prompts referencing this partial via {{> name}} will fail to render. Ensure no active prompts depend on it.",
+    "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);
@@ -6010,7 +6010,7 @@ function registerPartialsTools(server, service) {
   );
   server.tool(
     "list_partial_versions",
-    "List all versions of a prompt partial to view its change history. Returns all versions with content preview. Use to find a version number before calling publish_partial to roll back or promote a version.",
+    "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(
@@ -6045,7 +6045,7 @@ function registerPartialsTools(server, service) {
   );
   server.tool(
     "publish_partial",
-    "Publish a specific version of a prompt partial, making it the default version. After publishing, all prompts using {{> partial_name}} will resolve to this version's content.",
+    "Publish a specific partial version as the default, unlike update_prompt_partial which creates a new draft without activating it. Use after list_partial_versions to pick a version_id; this immediately changes what {{> partial_name}} resolves to for all prompts and replaces the previously active version without a rollback path.",
     PARTIALS_TOOL_SCHEMAS.publishPartial,
     async (params) => {
       await service.partials.publishPartial(params.prompt_partial_id, {
@@ -6370,14 +6370,7 @@ function formatPromptListResponse(prompts, params) {
 function registerPromptsTools(server, service) {
   server.tool(
     "create_prompt",
-    `Create a new prompt template in Portkey. Supports both the legacy string template and a structured messages alias for chat prompts.
-
-IMPORTANT: The "string" parameter accepts TWO legacy formats:
-1. Plain text: "Hello {{name}}, how can I help?"
-2. Multi-message JSON array (MUST be a JSON-encoded string):
-   '[{"role":"system","content":[{"type":"text","text":"You are a helpful assistant."}]},{"role":"user","content":[{"type":"text","text":"{{user_input}}"}]}]'
-
-For structured prompts, prefer the "messages" alias and let the server serialize it to the legacy string 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) {
@@ -6464,7 +6457,7 @@ For structured prompts, prefer the "messages" alias and let the server serialize
   );
   server.tool(
     "list_prompts",
-    "List all prompts in your Portkey organization with optional filtering by collection, workspace, or search query. Returns paginated results with id, name, slug, model, and status. Use collection_id to filter by app. Use to discover prompt_id values before calling get_prompt.",
+    "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);
@@ -6484,12 +6477,7 @@ For structured prompts, prefer the "messages" alias and let the server serialize
   );
   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);
@@ -6551,14 +6539,7 @@ 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 legacy "string" parameter accepts the same two formats as create_prompt:
-1. Plain text: "Hello {{name}}"
-2. Multi-message JSON array (MUST be a JSON-encoded string):
-   '[{"role":"system","content":[{"type":"text","text":"..."}]},{"role":"user","content":[{"type":"text","text":"{{input}}"}]}]'
-
-For structured chat prompts, prefer the "messages" alias and let the server serialize it for you. New versions are created in "archived" status \u2014 use publish_prompt to make active.`,
+    "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, messages, ...updateData } = params;
@@ -6623,7 +6604,7 @@ For structured chat prompts, prefer the "messages" alias and let the server seri
   );
   server.tool(
     "delete_prompt",
-    "Delete a prompt and all its versions by ID. This action cannot be undone. Applications calling this prompt slug will fail immediately. Use list_prompt_versions first to review history; consider archiving via update_prompt status instead if an audit trail is needed.",
+    "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);
@@ -6646,7 +6627,7 @@ For structured chat prompts, prefer the "messages" alias and let the server seri
   );
   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, unlike promote_prompt which copies across environments or update_prompt which creates a new draft. This immediately routes all callers using the slug to that version and there is no rollback, so use list_prompt_versions to pick the version and update_prompt first if you need to create new content before promoting it.",
     PROMPTS_TOOL_SCHEMAS.publishPrompt,
     async (params) => {
       await service.prompts.publishPrompt(params.prompt_id, {
@@ -6673,7 +6654,7 @@ For structured chat prompts, prefer the "messages" alias and let the server seri
   );
   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(
@@ -6711,7 +6692,7 @@ For structured chat prompts, prefer the "messages" alias and let the server seri
   );
   server.tool(
     "render_prompt",
-    "Render a prompt template by substituting variables, returning the final messages without executing. Previews the final messages after variable substitution without sending to the AI model. Use to verify template output before running a completion. Differs from run_prompt_completion which actually calls the model.",
+    "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, {
@@ -6743,7 +6724,7 @@ For structured chat prompts, prefer the "messages" alias and let the server seri
   );
   server.tool(
     "run_prompt_completion",
-    "Execute a prompt template against the configured AI model and return the model's response. Costs money \u2014 use render_prompt to preview first. REQUIRES billing metadata (client_id, app, env). Use validate_completion_metadata first if uncertain.",
+    "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(
@@ -6782,7 +6763,7 @@ For structured chat prompts, prefer the "messages" alias and let the server seri
   );
   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. For structured chat prompts, prefer the messages alias instead of hand-encoding JSON into string.",
+    "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);
@@ -6836,7 +6817,7 @@ For structured chat prompts, prefer the "messages" alias and let the server seri
   );
   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({
@@ -6874,7 +6855,7 @@ For structured chat prompts, prefer the "messages" alias and let the server seri
   );
   server.tool(
     "validate_completion_metadata",
-    "Validate billing metadata before running a completion. Checks for required fields (client_id, app, env) and valid values. Call this before run_prompt_completion to catch missing or invalid billing fields. Does not make any changes.",
+    "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);
@@ -6899,7 +6880,7 @@ For structured chat prompts, prefer the "messages" alias and let the server seri
   );
   server.tool(
     "get_prompt_version",
-    "Retrieve a specific version of a prompt by its version UUID. Use list_prompt_versions to find version IDs. Returns full template, parameters, and model config for that version.",
+    "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(
@@ -6918,7 +6899,7 @@ For structured chat prompts, prefer the "messages" alias and let the server seri
   );
   server.tool(
     "update_prompt_version",
-    "Update a specific prompt version. Currently only supports assigning or removing a label. Use list_prompt_labels to find label IDs. Pass null to remove the current label.",
+    "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) {
@@ -7026,7 +7007,7 @@ var PROVIDERS_TOOL_SCHEMAS = {
 function registerProvidersTools(server, service) {
   server.tool(
     "list_providers",
-    "List workspace-scoped providers, which are instances of org-level integrations with their own usage and rate limits. Differs from list_integrations which shows org-level provider connections. Use to discover provider slugs for a workspace. Returns name, slug, limits, and status per provider.",
+    "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({
@@ -7072,7 +7053,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "create_provider",
-    "Create a workspace-scoped provider linked to an org-level integration. Use list_integrations to find the integration_id first. Providers inherit the integration's API key but can have independent usage limits, rate limits, and expiration. Returns the new provider's id and slug.",
+    "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({
@@ -7113,7 +7094,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "get_provider",
-    "Retrieve full provider details by slug, including usage limits, rate limits, and expiration. Use to check current consumption against limits or inspect provider configuration before updating.",
+    "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(
@@ -7155,7 +7136,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "update_provider",
-    "Update a provider's name, note, usage limits, rate limits, or expiration. Set reset_usage to true to clear accumulated usage counters without changing the limit. Returns the updated provider's id and slug.",
+    "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(
@@ -7198,7 +7179,7 @@ function registerProvidersTools(server, service) {
   );
   server.tool(
     "delete_provider",
-    "Delete a workspace-level provider by slug. This action cannot be undone. Virtual keys, configs, and prompts referencing this provider will stop working. Audit dependent resources first; use delete_integration for org-level provider connections instead.",
+    "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);
@@ -7250,7 +7231,7 @@ var TRACING_TOOL_SCHEMAS = {
 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. Trace IDs are surfaced in request logs and via log exports (create_log_export).",
+    "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({
@@ -7279,7 +7260,7 @@ function registerTracingTools(server, service) {
   );
   server.tool(
     "update_feedback",
-    "Update existing feedback by ID. Use this instead of create_feedback when feedback already exists and needs correction or refinement. Only value, weight, and metadata can be changed; the trace_id association is immutable. Returns the updated feedback status and IDs.",
+    "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, {
@@ -7408,7 +7389,7 @@ function formatUserAnalyticsGroup(group) {
 function registerUsersTools(server, service) {
   server.tool(
     "list_all_users",
-    "List all users in your Portkey organization. Returns each user's ID, name, email, role, and timestamps. Use this for browsing or auditing the full member list; use get_user to fetch a single user by ID.",
+    "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();
@@ -7431,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);
@@ -7455,7 +7436,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "get_user_stats",
-    "Retrieve per-user request count and cost analytics for a required time range (time_of_generation_min/max). Unlike get_users_analytics which tracks active/new user counts over time, this returns usage-based stats grouped by user. Supports filtering by cost, tokens, status codes, and virtual keys.",
+    "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);
@@ -7478,7 +7459,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "get_user",
-    "Retrieve a single user's profile by their ID. Returns ID, name, email, role, and timestamps. Use this when you already have a user ID; use list_all_users to browse or search all organization members.",
+    "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);
@@ -7494,7 +7475,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "update_user",
-    "Update a user's first name, last name, or organization role (admin/member). Cannot change the user's email address or workspace-level roles; use update_workspace_member for workspace roles.",
+    "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;
@@ -7518,7 +7499,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "delete_user",
-    "Remove a user from your Portkey organization by ID. This action cannot be undone. Permanently removes org and workspace memberships and revokes the user's API keys; active sessions will fail immediately. Use delete_user_invite for pending invitations instead.",
+    "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);
@@ -7541,7 +7522,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "list_user_invites",
-    "List all pending and sent user invitations in your Portkey organization. Returns each invite's ID, email, role, status, and expiry. Use this to check invitation status; use list_all_users for users who have already accepted.",
+    "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();
@@ -7564,7 +7545,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "get_user_invite",
-    "Retrieve a specific invitation by its invite ID. Returns the invite's email, role, status, creation date, and expiry. This looks up a pending invitation, not an existing user; use get_user for accepted members.",
+    "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);
@@ -7580,7 +7561,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "delete_user_invite",
-    "Cancel and permanently delete a pending user invitation. This revokes the invite link so it can no longer be accepted. Does not remove existing users; use delete_user for that.",
+    "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);
@@ -7603,7 +7584,7 @@ function registerUsersTools(server, service) {
   );
   server.tool(
     "resend_user_invite",
-    "Resend the invitation email for a pending invite that has not yet been accepted. Use when the original email was lost or expired. The invite must still exist; check with get_user_invite first if unsure.",
+    "Resend the email for a pending invite that has not been accepted, unlike invite_user which creates a new invite. This sends a fresh email without modifying the invite record, expiry, or role; use get_user_invite first if you are unsure whether the invite still exists and list_user_invites to discover invite_ids.",
     USERS_TOOL_SCHEMAS.resendUserInvite,
     async (params) => {
       await service.users.resendUserInvite(params.invite_id);
@@ -7733,7 +7714,7 @@ function formatWorkspaceDetail(workspace) {
 function registerWorkspacesTools(server, service) {
   server.tool(
     "list_workspaces",
-    "Retrieve a paginated list of all workspaces in your Portkey organization. Returns id, name, slug, and configuration for each workspace. Use this tool first to discover workspace_id values needed by other workspace-scoped operations.",
+    "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);
@@ -7756,7 +7737,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "get_workspace",
-    "Retrieve full details for a single workspace by ID, including its configuration, metadata, and complete member list with roles. Unlike list_workspaces, this includes the full user roster \u2014 use it when you need member details or workspace membership counts.",
+    "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(
@@ -7774,7 +7755,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "create_workspace",
-    "Create a new workspace to isolate resources, API keys, and team members within your Portkey organization. A URL-friendly slug is auto-generated from the name if not provided. Returns the created workspace's id, name, and slug.",
+    "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({
@@ -7805,7 +7786,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "update_workspace",
-    "Update a workspace's name, slug, description, default status, or metadata. Only provided fields are changed; omitted fields remain unchanged. Warning: changing a workspace's slug may break existing references and URLs that depend on it.",
+    "Update a workspace's name, slug, description, default flag, or metadata by id, unlike update_workspace_member which changes role assignments within a workspace. Only provided fields change and updates take effect immediately; changing the slug can break URLs, API key references, and other external links, so confirm no dependencies first.",
     WORKSPACES_TOOL_SCHEMAS.updateWorkspace,
     async (params) => {
       const { workspace_id, is_default, metadata, ...rest } = params;
@@ -7835,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);
@@ -7858,7 +7839,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "add_workspace_member",
-    "Add an existing organization user to a workspace with a specified role (admin, manager, or member). Requires user_id as a UUID \u2014 use list_all_users to find it. For users not yet in the organization, use invite_user first.",
+    "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(
@@ -7887,7 +7868,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "list_workspace_members",
-    "List all members of a workspace, returning each member's user_id, name, organization role, workspace role, and status. Use this to discover user_id values needed for get_workspace_member, update_workspace_member, or remove_workspace_member.",
+    "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(
@@ -7912,7 +7893,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "get_workspace_member",
-    "Get details about a single workspace member by workspace_id and user_id. Returns the member's name, organization role, workspace role, and status. Unlike list_workspace_members, this fetches a single member directly when you already know both IDs.",
+    "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(
@@ -7931,7 +7912,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "update_workspace_member",
-    "Update a workspace member's role. Only the role can be changed \u2014 valid values are admin, manager, or member. Use list_workspace_members or get_workspace_member to check the current role first.",
+    "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(
@@ -7960,7 +7941,7 @@ function registerWorkspacesTools(server, service) {
   );
   server.tool(
     "remove_workspace_member",
-    "Remove a user from a workspace, revoking their workspace-level access. This does not delete the user from the organization \u2014 use delete_user for full org removal. The user can be re-added later with add_workspace_member.",
+    "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(