@metronome/mcp 0.3.0 → 1.0.0

package/src/server.ts

@@ -3,7 +3,13 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Endpoint, endpoints, HandlerFunction, query } from './tools';
-import { CallToolRequestSchema, ListToolsRequestSchema, Tool } from '@modelcontextprotocol/sdk/types.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  SetLevelRequestSchema,
+  Implementation,
+  Tool,
+} from '@modelcontextprotocol/sdk/types.js';
 import { ClientOptions } from '@metronome/sdk';
 import Metronome from '@metronome/sdk';
 import {
@@ -14,6 +20,7 @@ import {
   parseEmbeddedJSON,
 } from './compat';
 import { dynamicTools } from './dynamic-tools';
+import { codeTool } from './code-tool';
 import { McpOptions } from './options';
 
 export { McpOptions } from './options';
@@ -26,7 +33,7 @@ export const newMcpServer = () =>
   new McpServer(
     {
       name: 'metronome_sdk_api',
-      version: '0.3.0',
+      version: '1.0.0',
     },
     { capabilities: { tools: {}, logging: {} } },
   );
@@ -40,72 +47,125 @@ export const server = newMcpServer();
  */
 export function initMcpServer(params: {
   server: Server | McpServer;
-  clientOptions: ClientOptions;
-  mcpOptions: McpOptions;
-  endpoints?: { tool: Tool; handler: HandlerFunction }[];
-}) {
-  const transformedEndpoints = selectTools(endpoints, params.mcpOptions);
-  const client = new Metronome(params.clientOptions);
-  const capabilities = {
-    ...defaultClientCapabilities,
-    ...(params.mcpOptions.client ? knownClients[params.mcpOptions.client] : params.mcpOptions.capabilities),
-  };
-  init({ server: params.server, client, endpoints: transformedEndpoints, capabilities });
-}
-
-export function init(params: {
-  server: Server | McpServer;
-  client?: Metronome;
-  endpoints?: { tool: Tool; handler: HandlerFunction }[];
-  capabilities?: Partial<ClientCapabilities>;
+  clientOptions?: ClientOptions;
+  mcpOptions?: McpOptions;
 }) {
   const server = params.server instanceof McpServer ? params.server.server : params.server;
-  const providedEndpoints = params.endpoints || endpoints;
+  const mcpOptions = params.mcpOptions ?? {};
+
+  let providedEndpoints: Endpoint[] | null = null;
+  let endpointMap: Record<string, Endpoint> | null = null;
+
+  const initTools = async (implementation?: Implementation) => {
+    if (implementation && (!mcpOptions.client || mcpOptions.client === 'infer')) {
+      mcpOptions.client =
+        implementation.name.toLowerCase().includes('claude') ? 'claude'
+        : implementation.name.toLowerCase().includes('cursor') ? 'cursor'
+        : undefined;
+      mcpOptions.capabilities = {
+        ...(mcpOptions.client && knownClients[mcpOptions.client]),
+        ...mcpOptions.capabilities,
+      };
+    }
+    providedEndpoints ??= await selectTools(endpoints, mcpOptions);
+    endpointMap ??= Object.fromEntries(providedEndpoints.map((endpoint) => [endpoint.tool.name, endpoint]));
+  };
 
-  const endpointMap = Object.fromEntries(providedEndpoints.map((endpoint) => [endpoint.tool.name, endpoint]));
+  const logAtLevel =
+    (level: 'debug' | 'info' | 'warning' | 'error') =>
+    (message: string, ...rest: unknown[]) => {
+      void server.sendLoggingMessage({
+        level,
+        data: { message, rest },
+      });
+    };
+  const logger = {
+    debug: logAtLevel('debug'),
+    info: logAtLevel('info'),
+    warn: logAtLevel('warning'),
+    error: logAtLevel('error'),
+  };
 
-  const client = params.client || new Metronome({ defaultHeaders: { 'X-Stainless-MCP': 'true' } });
+  let client = new Metronome({
+    logger,
+    ...params.clientOptions,
+    defaultHeaders: {
+      ...params.clientOptions?.defaultHeaders,
+      'X-Stainless-MCP': 'true',
+    },
+  });
 
   server.setRequestHandler(ListToolsRequestSchema, async () => {
+    if (providedEndpoints === null) {
+      await initTools(server.getClientVersion());
+    }
     return {
-      tools: providedEndpoints.map((endpoint) => endpoint.tool),
+      tools: providedEndpoints!.map((endpoint) => endpoint.tool),
     };
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (endpointMap === null) {
+      await initTools(server.getClientVersion());
+    }
     const { name, arguments: args } = request.params;
-    const endpoint = endpointMap[name];
+    const endpoint = endpointMap![name];
     if (!endpoint) {
       throw new Error(`Unknown tool: ${name}`);
     }
 
-    return executeHandler(endpoint.tool, endpoint.handler, client, args, params.capabilities);
+    return executeHandler(endpoint.tool, endpoint.handler, client, args, mcpOptions.capabilities);
+  });
+
+  server.setRequestHandler(SetLevelRequestSchema, async (request) => {
+    const { level } = request.params;
+    switch (level) {
+      case 'debug':
+        client = client.withOptions({ logLevel: 'debug' });
+        break;
+      case 'info':
+        client = client.withOptions({ logLevel: 'info' });
+        break;
+      case 'notice':
+      case 'warning':
+        client = client.withOptions({ logLevel: 'warn' });
+        break;
+      case 'error':
+        client = client.withOptions({ logLevel: 'error' });
+        break;
+      default:
+        client = client.withOptions({ logLevel: 'off' });
+        break;
+    }
+    return {};
   });
 }
 
 /**
  * Selects the tools to include in the MCP Server based on the provided options.
  */
-export function selectTools(endpoints: Endpoint[], options: McpOptions): Endpoint[] {
-  const filteredEndpoints = query(options.filters, endpoints);
+export async function selectTools(endpoints: Endpoint[], options?: McpOptions): Promise<Endpoint[]> {
+  const filteredEndpoints = query(options?.filters ?? [], endpoints);
 
   let includedTools = filteredEndpoints;
 
   if (includedTools.length > 0) {
-    if (options.includeDynamicTools) {
+    if (options?.includeDynamicTools) {
       includedTools = dynamicTools(includedTools);
     }
   } else {
-    if (options.includeAllTools) {
+    if (options?.includeAllTools) {
       includedTools = endpoints;
-    } else if (options.includeDynamicTools) {
+    } else if (options?.includeDynamicTools) {
       includedTools = dynamicTools(endpoints);
+    } else if (options?.includeCodeTools) {
+      includedTools = [await codeTool()];
     } else {
       includedTools = endpoints;
     }
   }
 
-  const capabilities = { ...defaultClientCapabilities, ...options.capabilities };
+  const capabilities = { ...defaultClientCapabilities, ...options?.capabilities };
   return applyCompatibilityTransformations(includedTools, capabilities);
 }
 

package/src/stdio.ts

@@ -1,12 +1,11 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { init, newMcpServer } from './server';
-import { Endpoint } from './tools';
+import { initMcpServer, newMcpServer } from './server';
 import { McpOptions } from './options';
 
-export const launchStdioServer = async (options: McpOptions, endpoints: Endpoint[]) => {
+export const launchStdioServer = async (options: McpOptions) => {
   const server = newMcpServer();
 
-  init({ server, endpoints });
+  initMcpServer({ server, mcpOptions: options });
 
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/src/tools/index.ts

@@ -29,6 +29,8 @@ import archive_v1_customers from './v1/customers/archive-v1-customers';
 import list_billable_metrics_v1_customers from './v1/customers/list-billable-metrics-v1-customers';
 import list_costs_v1_customers from './v1/customers/list-costs-v1-customers';
 import preview_events_v1_customers from './v1/customers/preview-events-v1-customers';
+import retrieve_billing_configurations_v1_customers from './v1/customers/retrieve-billing-configurations-v1-customers';
+import set_billing_configurations_v1_customers from './v1/customers/set-billing-configurations-v1-customers';
 import set_ingest_aliases_v1_customers from './v1/customers/set-ingest-aliases-v1-customers';
 import set_name_v1_customers from './v1/customers/set-name-v1-customers';
 import update_config_v1_customers from './v1/customers/update-config-v1-customers';
@@ -137,6 +139,8 @@ addEndpoint(archive_v1_customers);
 addEndpoint(list_billable_metrics_v1_customers);
 addEndpoint(list_costs_v1_customers);
 addEndpoint(preview_events_v1_customers);
+addEndpoint(retrieve_billing_configurations_v1_customers);
+addEndpoint(set_billing_configurations_v1_customers);
 addEndpoint(set_ingest_aliases_v1_customers);
 addEndpoint(set_name_v1_customers);
 addEndpoint(update_config_v1_customers);

package/src/tools/v1/alerts/archive-v1-alerts.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'archive_v1_alerts',
   description:
-    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nArchive an existing alert\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/id'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    id: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        }\n      },\n      required: [        'id'\n      ]\n    }\n  }\n}\n```",
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nPermanently disable an alert and remove it from active monitoring across all customers. Archived alerts stop evaluating immediately and can optionally release their uniqueness key for reuse in future alert configurations.\n\n### Use this endpoint to:\n- Decommission alerts that are no longer needed\n- Clean up test or deprecated alert configurations\n- Free up uniqueness keys for reuse with new alerts\n- Stop alert evaluations without losing historical configuration data\n- Disable outdated monitoring rules during pricing model transitions\n\n### Key response fields:\n- data: Object containing the archived alert's ID\n- Alert evaluation stops immediately for all affected customers\n- Historical alert data and configurations remain accessible for audit purposes\n\n### Usage guidelines:\n- Irreversible for evaluation: Archived alerts cannot be re-enabled; create a new alert to resume monitoring\n- Uniqueness key handling: Set `release_uniqueness_key` : `true` to reuse the key in future alerts\n- Immediate effect: Alert evaluation stops instantly across all customers\n- Historical preservation: Archive operation maintains alert history and configuration for compliance and auditing\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/id'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    id: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        }\n      },\n      required: [        'id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/alerts/create-v1-alerts.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'create_v1_alerts',
   description:
-    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nCreate a new alert\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/id'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    id: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        }\n      },\n      required: [        'id'\n      ]\n    }\n  }\n}\n```",
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nCreate a new alert to monitor customer spending, balances, and billing metrics in real-time. Metronome's alert system provides industry-leading speed with immediate evaluation capabilities, enabling you to proactively manage customer accounts and prevent revenue leakage.\n\nThis endpoint creates configurable alerts that continuously monitor various billing thresholds including spend limits, credit balances, commitment utilization, and invoice totals. Alerts can be configured globally for all customers or targeted to specific customer accounts. Custom fields can be used on certain alert types to further target alerts to groups of customers.\n\n### Use this endpoint to:\n- Proactively monitor customer spending patterns to prevent unexpected overages or credit exhaustion\n- Automate notifications when customers approach commitment limits or credit thresholds\n- Enable real-time intervention for accounts at risk of churn or payment issues\n- Scale billing operations by automating threshold-based workflows and notifications\n\n### Key response fields: \nA successful response returns a CustomerAlert object containing:\n\n- The alert configuration with its unique ID and current status\n- The customer's evaluation status (ok, in_alarm, or evaluating)\n- Alert metadata including type, threshold values, and update timestamps\n\n### Usage guidelines:\n- Immediate evaluation: Set `evaluate_on_create` : `true` (default) for instant evaluation against existing customers\n- Uniqueness constraints: Each alert must have a unique `uniqueness_key` within your organization. Use `release_uniqueness_key` : `true` when archiving to reuse keys\n- Alert type requirements: Different alert types require specific fields (e.g., `billable_metric_id` for usage alerts, `credit_type_id` for credit-based alerts)\n- Webhook delivery: Alerts trigger webhook notifications for real-time integration with your systems. Configure webhook endpoints before creating alerts\n- Performance at scale: Metronome's event-driven architecture processes alert evaluations in real-time as usage events stream in, unlike competitors who rely on periodic polling or batch evaluation cycles\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/id'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    id: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        }\n      },\n      required: [        'id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -114,7 +114,7 @@ export const tool: Tool = {
               type: 'string',
             },
           },
-          required: ['key', 'value'],
+          required: ['key'],
         },
       },
       invoice_types_filter: {

package/src/tools/v1/audit-logs/list-v1-audit-logs.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_v1_audit_logs',
   description:
-    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nRetrieves a range of audit logs. If no further audit logs are currently available, the data array will be empty. As new audit logs are created, subsequent requests using the same next_page value will be in the returned data array, ensuring a continuous and uninterrupted reading of audit logs.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        type: 'object',\n        properties: {\n          id: {\n            type: 'string'\n          },\n          request: {\n            type: 'object',\n            properties: {\n              id: {\n                type: 'string'\n              },\n              ip: {\n                type: 'string'\n              },\n              user_agent: {\n                type: 'string'\n              }\n            },\n            required: [              'id'\n            ]\n          },\n          timestamp: {\n            type: 'string',\n            format: 'date-time'\n          },\n          action: {\n            type: 'string'\n          },\n          actor: {\n            type: 'object',\n            properties: {\n              id: {\n                type: 'string'\n              },\n              name: {\n                type: 'string'\n              },\n              email: {\n                type: 'string'\n              }\n            },\n            required: [              'id',\n              'name'\n            ]\n          },\n          description: {\n            type: 'string'\n          },\n          resource_id: {\n            type: 'string'\n          },\n          resource_type: {\n            type: 'string'\n          },\n          status: {\n            type: 'string',\n            enum: [              'success',\n              'failure',\n              'pending'\n            ]\n          }\n        },\n        required: [          'id',\n          'request',\n          'timestamp'\n        ]\n      }\n    },\n    next_page: {\n      type: 'string',\n      description: 'The next_page parameter is always returned to support ongoing log retrieval. It enables continuous querying, even when some requests return no new data. Save the next_page token from each response and use it for future requests to ensure no logs are missed. This setup is ideal for regular updates via automated processes, like cron jobs, to fetch logs continuously as they become available. When you receive an empty data array, it indicates a temporary absence of new logs, but subsequent requests might return new data.'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ]\n}\n```",
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nGet a comprehensive audit trail of all operations performed in your Metronome account, whether initiated through the API, web interface, or automated processes. This endpoint provides detailed logs of who did what and when, enabling compliance reporting, security monitoring, and operational troubleshooting across all interaction channels.\n\n### Use this endpoint to:\n- Monitor all account activity for security and compliance purposes\n- Track configuration changes regardless of source (API, UI, or system)\n- Investigate issues by reviewing historical operations\n\n### Key response fields: \nAn array of AuditLog objects containing:\n- id: Unique identifier for the audit log entry\n- timestamp: When the action occurred (RFC 3339 format)\n- actor: Information about who performed the action\n- request: Details including request ID, IP address, and user agent\n- `resource_type`: The type of resource affected (e.g., customer, contract, invoice)\n- `resource_id`: The specific resource identifier\n- `action`: The operation performed\n- `next_page`: Cursor for continuous log retrieval\n\n### Usage guidelines:\n- Continuous retrieval: The next_page token enables uninterrupted log streaming—save it between requests to ensure no logs are missed\n- Empty responses: An empty data array means no new logs yet; continue polling with the same next_page token\n- Date filtering:\n    - `starting_on`: Earliest logs to return (inclusive)\n    - `ending_before`: Latest logs to return (exclusive)\n    - Cannot be used with `next_page`\n- Resource filtering: Must specify both `resource_type` and `resource_id` together\n- Sort order: Default is `date_asc`; use `date_desc` for newest first\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        type: 'object',\n        properties: {\n          id: {\n            type: 'string'\n          },\n          request: {\n            type: 'object',\n            properties: {\n              id: {\n                type: 'string'\n              },\n              ip: {\n                type: 'string'\n              },\n              user_agent: {\n                type: 'string'\n              }\n            },\n            required: [              'id'\n            ]\n          },\n          timestamp: {\n            type: 'string',\n            format: 'date-time'\n          },\n          action: {\n            type: 'string'\n          },\n          actor: {\n            type: 'object',\n            properties: {\n              id: {\n                type: 'string'\n              },\n              name: {\n                type: 'string'\n              },\n              email: {\n                type: 'string'\n              }\n            },\n            required: [              'id',\n              'name'\n            ]\n          },\n          description: {\n            type: 'string'\n          },\n          resource_id: {\n            type: 'string'\n          },\n          resource_type: {\n            type: 'string'\n          },\n          status: {\n            type: 'string',\n            enum: [              'success',\n              'failure',\n              'pending'\n            ]\n          }\n        },\n        required: [          'id',\n          'request',\n          'timestamp'\n        ]\n      }\n    },\n    next_page: {\n      type: 'string',\n      description: 'The next_page parameter is always returned to support ongoing log retrieval. It enables continuous querying, even when some requests return no new data. Save the next_page token from each response and use it for future requests to ensure no logs are missed. This setup is ideal for regular updates via automated processes, like cron jobs, to fetch logs continuously as they become available. When you receive an empty data array, it indicates a temporary absence of new logs, but subsequent requests might return new data.'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ]\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/billable-metrics/archive-v1-billable-metrics.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'archive_v1_billable_metrics',
   description:
-    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nArchive an existing billable metric.\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/id'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    id: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        }\n      },\n      required: [        'id'\n      ]\n    }\n  }\n}\n```",
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nUse this endpoint to retire billable metrics that are no longer used. After a billable metric is archived, that billable metric can no longer be used in any new Products to define how that product should be metered. If you archive a billable metric that is already associated with a Product, the Product will continue to function as usual, metering based on the definition of the archived billable metric. \n\nArchived billable metrics will be returned on the `getBillableMetric` and `listBillableMetrics` endpoints with a populated `archived_at` field.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/id'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    id: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        }\n      },\n      required: [        'id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/billable-metrics/create-v1-billable-metrics.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'create_v1_billable_metrics',
   description:
-    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nCreates a new Billable Metric.\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/id'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    id: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        }\n      },\n      required: [        'id'\n      ]\n    }\n  }\n}\n```",
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nCreate billable metrics programmatically with this endpoint—an essential step in configuring your pricing and packaging in Metronome.\n\nA billable metric is a customizable query that filters and aggregates events from your event stream. These metrics are continuously tracked as usage data enters Metronome through the ingestion pipeline. The ingestion process transforms raw usage data into actionable pricing metrics, enabling accurate metering and billing for your products.\n\n### Use this endpoint to: \n- Create individual or multiple billable metrics as part of a setup workflow.\n- Automate the entire pricing configuration process, from metric creation to customer contract setup.\n- Define metrics using either standard filtering/aggregation or a custom SQL query.\n\n### Key response fields: \n- The ID of the billable metric that was created\n- The created billable metric will be available to be used in Products, usage endpoints, and alerts. \n\n### Usage guidelines: \n- Metrics defined using standard filtering and aggregation are Streaming billable metrics, which have been optimized for ultra low latency and high throughput workflows. \n- Use SQL billable metrics if you require more flexible aggregation options.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/id'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    id: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        }\n      },\n      required: [        'id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/billable-metrics/list-v1-billable-metrics.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_v1_billable_metrics',
   description:
-    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nList all billable metrics.\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        type: 'object',\n        properties: {\n          id: {\n            type: 'string',\n            description: 'ID of the billable metric'\n          },\n          name: {\n            type: 'string',\n            description: 'The display name of the billable metric.'\n          },\n          aggregation_key: {\n            type: 'string',\n            description: 'A key that specifies which property of the event is used to aggregate data. This key must be one of the property filter names and is not applicable when the aggregation type is \\'count\\'.'\n          },\n          aggregation_type: {\n            type: 'string',\n            description: 'Specifies the type of aggregation performed on matching events.',\n            enum: [              'COUNT',\n              'LATEST',\n              'MAX',\n              'SUM',\n              'UNIQUE'\n            ]\n          },\n          archived_at: {\n            type: 'string',\n            description: 'RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived.',\n            format: 'date-time'\n          },\n          custom_fields: {\n            type: 'object',\n            additionalProperties: true\n          },\n          event_type_filter: {\n            $ref: '#/$defs/event_type_filter'\n          },\n          group_keys: {\n            type: 'array',\n            description: 'Property names that are used to group usage costs on an invoice. Each entry represents a set of properties used to slice events into distinct buckets.',\n            items: {\n              type: 'array',\n              items: {\n                type: 'string'\n              }\n            }\n          },\n          property_filters: {\n            type: 'array',\n            description: 'A list of filters to match events to this billable metric. Each filter defines a rule on an event property. All rules must pass for the event to match the billable metric.',\n            items: {\n              $ref: '#/$defs/property_filter'\n            }\n          },\n          sql: {\n            type: 'string',\n            description: 'The SQL query associated with the billable metric'\n          }\n        },\n        required: [          'id',\n          'name'\n        ]\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    event_type_filter: {\n      type: 'object',\n      description: 'An optional filtering rule to match the \\'event_type\\' property of an event.',\n      properties: {\n        in_values: {\n          type: 'array',\n          description: 'A list of event types that are explicitly included in the billable metric. If specified, only events of these types will match the billable metric. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        },\n        not_in_values: {\n          type: 'array',\n          description: 'A list of event types that are explicitly excluded from the billable metric. If specified, events of these types will not match the billable metric. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        }\n      }\n    },\n    property_filter: {\n      type: 'object',\n      properties: {\n        name: {\n          type: 'string',\n          description: 'The name of the event property.'\n        },\n        exists: {\n          type: 'boolean',\n          description: 'Determines whether the property must exist in the event. If true, only events with this property will pass the filter. If false, only events without this property will pass the filter. If null or omitted, the existence of the property is optional.'\n        },\n        in_values: {\n          type: 'array',\n          description: 'Specifies the allowed values for the property to match an event. An event will pass the filter only if its property value is included in this list. If undefined, all property values will pass the filter. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        },\n        not_in_values: {\n          type: 'array',\n          description: 'Specifies the values that prevent an event from matching the filter. An event will not pass the filter if its property value is included in this list. If null or empty, all property values will pass the filter. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        }\n      },\n      required: [        'name'\n      ]\n    }\n  }\n}\n```",
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nRetrieves all billable metrics with their complete configurations. Use this for programmatic discovery and management of billable metrics, such as associating metrics to products and auditing for orphaned or archived metrics. \nImportant: Archived metrics are excluded by default; use `include_archived`=`true` parameter to include them.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        type: 'object',\n        properties: {\n          id: {\n            type: 'string',\n            description: 'ID of the billable metric'\n          },\n          name: {\n            type: 'string',\n            description: 'The display name of the billable metric.'\n          },\n          aggregation_key: {\n            type: 'string',\n            description: 'A key that specifies which property of the event is used to aggregate data. This key must be one of the property filter names and is not applicable when the aggregation type is \\'count\\'.'\n          },\n          aggregation_type: {\n            type: 'string',\n            description: 'Specifies the type of aggregation performed on matching events.',\n            enum: [              'COUNT',\n              'LATEST',\n              'MAX',\n              'SUM',\n              'UNIQUE'\n            ]\n          },\n          archived_at: {\n            type: 'string',\n            description: 'RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived.',\n            format: 'date-time'\n          },\n          custom_fields: {\n            type: 'object',\n            description: 'Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }',\n            additionalProperties: true\n          },\n          event_type_filter: {\n            $ref: '#/$defs/event_type_filter'\n          },\n          group_keys: {\n            type: 'array',\n            description: 'Property names that are used to group usage costs on an invoice. Each entry represents a set of properties used to slice events into distinct buckets.',\n            items: {\n              type: 'array',\n              items: {\n                type: 'string'\n              }\n            }\n          },\n          property_filters: {\n            type: 'array',\n            description: 'A list of filters to match events to this billable metric. Each filter defines a rule on an event property. All rules must pass for the event to match the billable metric.',\n            items: {\n              $ref: '#/$defs/property_filter'\n            }\n          },\n          sql: {\n            type: 'string',\n            description: 'The SQL query associated with the billable metric'\n          }\n        },\n        required: [          'id',\n          'name'\n        ]\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    event_type_filter: {\n      type: 'object',\n      description: 'An optional filtering rule to match the \\'event_type\\' property of an event.',\n      properties: {\n        in_values: {\n          type: 'array',\n          description: 'A list of event types that are explicitly included in the billable metric. If specified, only events of these types will match the billable metric. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        },\n        not_in_values: {\n          type: 'array',\n          description: 'A list of event types that are explicitly excluded from the billable metric. If specified, events of these types will not match the billable metric. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        }\n      }\n    },\n    property_filter: {\n      type: 'object',\n      properties: {\n        name: {\n          type: 'string',\n          description: 'The name of the event property.'\n        },\n        exists: {\n          type: 'boolean',\n          description: 'Determines whether the property must exist in the event. If true, only events with this property will pass the filter. If false, only events without this property will pass the filter. If null or omitted, the existence of the property is optional.'\n        },\n        in_values: {\n          type: 'array',\n          description: 'Specifies the allowed values for the property to match an event. An event will pass the filter only if its property value is included in this list. If undefined, all property values will pass the filter. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        },\n        not_in_values: {\n          type: 'array',\n          description: 'Specifies the values that prevent an event from matching the filter. An event will not pass the filter if its property value is included in this list. If null or empty, all property values will pass the filter. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        }\n      },\n      required: [        'name'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/billable-metrics/retrieve-v1-billable-metrics.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'retrieve_v1_billable_metrics',
   description:
-    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nGet a billable metric.\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'ID of the billable metric'\n        },\n        name: {\n          type: 'string',\n          description: 'The display name of the billable metric.'\n        },\n        aggregation_key: {\n          type: 'string',\n          description: 'A key that specifies which property of the event is used to aggregate data. This key must be one of the property filter names and is not applicable when the aggregation type is \\'count\\'.'\n        },\n        aggregation_type: {\n          type: 'string',\n          description: 'Specifies the type of aggregation performed on matching events.',\n          enum: [            'COUNT',\n            'LATEST',\n            'MAX',\n            'SUM',\n            'UNIQUE'\n          ]\n        },\n        archived_at: {\n          type: 'string',\n          description: 'RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived.',\n          format: 'date-time'\n        },\n        custom_fields: {\n          type: 'object',\n          additionalProperties: true\n        },\n        event_type_filter: {\n          $ref: '#/$defs/event_type_filter'\n        },\n        group_keys: {\n          type: 'array',\n          description: 'Property names that are used to group usage costs on an invoice. Each entry represents a set of properties used to slice events into distinct buckets.',\n          items: {\n            type: 'array',\n            items: {\n              type: 'string'\n            }\n          }\n        },\n        property_filters: {\n          type: 'array',\n          description: 'A list of filters to match events to this billable metric. Each filter defines a rule on an event property. All rules must pass for the event to match the billable metric.',\n          items: {\n            $ref: '#/$defs/property_filter'\n          }\n        },\n        sql: {\n          type: 'string',\n          description: 'The SQL query associated with the billable metric'\n        }\n      },\n      required: [        'id',\n        'name'\n      ]\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    event_type_filter: {\n      type: 'object',\n      description: 'An optional filtering rule to match the \\'event_type\\' property of an event.',\n      properties: {\n        in_values: {\n          type: 'array',\n          description: 'A list of event types that are explicitly included in the billable metric. If specified, only events of these types will match the billable metric. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        },\n        not_in_values: {\n          type: 'array',\n          description: 'A list of event types that are explicitly excluded from the billable metric. If specified, events of these types will not match the billable metric. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        }\n      }\n    },\n    property_filter: {\n      type: 'object',\n      properties: {\n        name: {\n          type: 'string',\n          description: 'The name of the event property.'\n        },\n        exists: {\n          type: 'boolean',\n          description: 'Determines whether the property must exist in the event. If true, only events with this property will pass the filter. If false, only events without this property will pass the filter. If null or omitted, the existence of the property is optional.'\n        },\n        in_values: {\n          type: 'array',\n          description: 'Specifies the allowed values for the property to match an event. An event will pass the filter only if its property value is included in this list. If undefined, all property values will pass the filter. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        },\n        not_in_values: {\n          type: 'array',\n          description: 'Specifies the values that prevent an event from matching the filter. An event will not pass the filter if its property value is included in this list. If null or empty, all property values will pass the filter. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        }\n      },\n      required: [        'name'\n      ]\n    }\n  }\n}\n```",
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nRetrieves the complete configuration for a specific billable metric by its ID. Use this to review billable metric setup before associating it with products. Returns the metric's `name`, `event_type_filter`, `property_filters`, `aggregation_type`, `aggregation_key`, `group_keys`, `custom fields`, and `SQL query` (if it's a SQL billable metric). \n\nImportant: \n- Archived billable metrics will include an `archived_at` timestamp; they no longer process new usage events but remain accessible for historical reference.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'ID of the billable metric'\n        },\n        name: {\n          type: 'string',\n          description: 'The display name of the billable metric.'\n        },\n        aggregation_key: {\n          type: 'string',\n          description: 'A key that specifies which property of the event is used to aggregate data. This key must be one of the property filter names and is not applicable when the aggregation type is \\'count\\'.'\n        },\n        aggregation_type: {\n          type: 'string',\n          description: 'Specifies the type of aggregation performed on matching events.',\n          enum: [            'COUNT',\n            'LATEST',\n            'MAX',\n            'SUM',\n            'UNIQUE'\n          ]\n        },\n        archived_at: {\n          type: 'string',\n          description: 'RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived.',\n          format: 'date-time'\n        },\n        custom_fields: {\n          type: 'object',\n          description: 'Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }',\n          additionalProperties: true\n        },\n        event_type_filter: {\n          $ref: '#/$defs/event_type_filter'\n        },\n        group_keys: {\n          type: 'array',\n          description: 'Property names that are used to group usage costs on an invoice. Each entry represents a set of properties used to slice events into distinct buckets.',\n          items: {\n            type: 'array',\n            items: {\n              type: 'string'\n            }\n          }\n        },\n        property_filters: {\n          type: 'array',\n          description: 'A list of filters to match events to this billable metric. Each filter defines a rule on an event property. All rules must pass for the event to match the billable metric.',\n          items: {\n            $ref: '#/$defs/property_filter'\n          }\n        },\n        sql: {\n          type: 'string',\n          description: 'The SQL query associated with the billable metric'\n        }\n      },\n      required: [        'id',\n        'name'\n      ]\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    event_type_filter: {\n      type: 'object',\n      description: 'An optional filtering rule to match the \\'event_type\\' property of an event.',\n      properties: {\n        in_values: {\n          type: 'array',\n          description: 'A list of event types that are explicitly included in the billable metric. If specified, only events of these types will match the billable metric. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        },\n        not_in_values: {\n          type: 'array',\n          description: 'A list of event types that are explicitly excluded from the billable metric. If specified, events of these types will not match the billable metric. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        }\n      }\n    },\n    property_filter: {\n      type: 'object',\n      properties: {\n        name: {\n          type: 'string',\n          description: 'The name of the event property.'\n        },\n        exists: {\n          type: 'boolean',\n          description: 'Determines whether the property must exist in the event. If true, only events with this property will pass the filter. If false, only events without this property will pass the filter. If null or omitted, the existence of the property is optional.'\n        },\n        in_values: {\n          type: 'array',\n          description: 'Specifies the allowed values for the property to match an event. An event will pass the filter only if its property value is included in this list. If undefined, all property values will pass the filter. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        },\n        not_in_values: {\n          type: 'array',\n          description: 'Specifies the values that prevent an event from matching the filter. An event will not pass the filter if its property value is included in this list. If null or empty, all property values will pass the filter. Must be non-empty if present.',\n          items: {\n            type: 'string'\n          }\n        }\n      },\n      required: [        'name'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/contracts/add-manual-balance-entry-v1-contracts.ts

@@ -16,7 +16,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'add_manual_balance_entry_v1_contracts',
-  description: 'Add a manual balance entry\n',
+  description:
+    'Manually adjust the available balance on a commit or credit. This entry is appended to the commit ledger as a new event. Optionally include a description that provides the reasoning for the entry.\n\n### Use this endpoint to:\n- Address incorrect usage burn-down caused by malformed usage or invalid config\n- Decrease available balance to account for outages where usage may have not been tracked or sent to Metronome\n- Issue credits to customers in the form of increased balance on existing commit or credit\n\n### Usage guidelines:\nManual ledger entries can be extremely useful for resolving discrepancies in Metronome. However, most corrections to inaccurate billings can be modified upstream of the commit, whether that is via contract editing, rate editing, or other actions that cause an invoice to be recalculated.\n',
   inputSchema: {
     type: 'object',
     properties: {