@metronome/mcp 0.3.0 → 2.0.0

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';
@@ -43,6 +45,7 @@ import retrieve_customers_v1_invoices from './v1/customers/invoices/retrieve-cus
 import list_customers_v1_invoices from './v1/customers/invoices/list-customers-v1-invoices';
 import add_charge_customers_v1_invoices from './v1/customers/invoices/add-charge-customers-v1-invoices';
 import list_breakdowns_customers_v1_invoices from './v1/customers/invoices/list-breakdowns-customers-v1-invoices';
+import retrieve_pdf_customers_v1_invoices from './v1/customers/invoices/retrieve-pdf-customers-v1-invoices';
 import create_customers_v1_billing_config from './v1/customers/billing-config/create-customers-v1-billing-config';
 import retrieve_customers_v1_billing_config from './v1/customers/billing-config/retrieve-customers-v1-billing-config';
 import delete_customers_v1_billing_config from './v1/customers/billing-config/delete-customers-v1-billing-config';
@@ -105,6 +108,9 @@ import retrieve_rate_cards_contracts_v1_named_schedules from './v1/contracts/rat
 import update_rate_cards_contracts_v1_named_schedules from './v1/contracts/rate-cards/named-schedules/update-rate-cards-contracts-v1-named-schedules';
 import retrieve_contracts_v1_named_schedules from './v1/contracts/named-schedules/retrieve-contracts-v1-named-schedules';
 import update_contracts_v1_named_schedules from './v1/contracts/named-schedules/update-contracts-v1-named-schedules';
+import list_v1_payments from './v1/payments/list-v1-payments';
+import attempt_v1_payments from './v1/payments/attempt-v1-payments';
+import cancel_v1_payments from './v1/payments/cancel-v1-payments';
 
 export const endpoints: Endpoint[] = [];
 
@@ -137,6 +143,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);
@@ -151,6 +159,7 @@ addEndpoint(retrieve_customers_v1_invoices);
 addEndpoint(list_customers_v1_invoices);
 addEndpoint(add_charge_customers_v1_invoices);
 addEndpoint(list_breakdowns_customers_v1_invoices);
+addEndpoint(retrieve_pdf_customers_v1_invoices);
 addEndpoint(create_customers_v1_billing_config);
 addEndpoint(retrieve_customers_v1_billing_config);
 addEndpoint(delete_customers_v1_billing_config);
@@ -213,6 +222,9 @@ addEndpoint(retrieve_rate_cards_contracts_v1_named_schedules);
 addEndpoint(update_rate_cards_contracts_v1_named_schedules);
 addEndpoint(retrieve_contracts_v1_named_schedules);
 addEndpoint(update_contracts_v1_named_schedules);
+addEndpoint(list_v1_payments);
+addEndpoint(attempt_v1_payments);
+addEndpoint(cancel_v1_payments);
 
 export type Filter = {
   type: 'resource' | 'operation' | 'tag' | 'tool';

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

@@ -18,17 +18,17 @@ 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 a threshold notification and remove it from active monitoring across all customers. Archived threshold notifications stop evaluating immediately and can optionally release their uniqueness key for reuse in future threshold notification configurations.\n\n### Use this endpoint to:\n- Decommission threshold notifications that are no longer needed\n- Clean up test or deprecated threshold notification configurations\n- Free up uniqueness keys for reuse with new threshold notifications\n- Stop threshold notification 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 threshold notification's ID\n\n### Usage guidelines:\n- Irreversible for evaluation: Archived threshold notifications cannot be re-enabled; create a new threshold notification to resume monitoring\n- Uniqueness key handling: Set `release_uniqueness_key` : `true` to reuse the key in future threshold notifications\n- Immediate effect: Threshold notification evaluation stops instantly across all customers\n- Historical preservation: Archive operation maintains threshold notification history and configuration for compliance and auditing\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/alert_archive_response',\n  $defs: {\n    alert_archive_response: {\n      type: 'object',\n      properties: {\n        data: {\n          $ref: '#/$defs/id'\n        }\n      },\n      required: [        'data'\n      ]\n    },\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: {
       id: {
         type: 'string',
-        description: 'The Metronome ID of the alert',
+        description: 'The Metronome ID of the threshold notification',
       },
       release_uniqueness_key: {
         type: 'boolean',
-        description: 'If true, resets the uniqueness key on this alert so it can be re-used',
+        description: 'If true, resets the uniqueness key on this threshold notification so it can be re-used',
       },
       jq_filter: {
         type: 'string',

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

@@ -18,13 +18,13 @@ 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 threshold notification to monitor customer spending, balances, and billing metrics in real-time. Metronome's notification 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 threshold notifications that continuously monitor various billing thresholds including spend limits, credit balances, commitment utilization, and invoice totals. Threshold notifications can be configured globally for all customers or targeted to specific customer accounts.\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 threshold notification configuration with its unique ID and current status\n- The customer's evaluation status (ok, in_alarm, or evaluating)\n- Threshold notification 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 threshold notification must have a unique `uniqueness_key` within your organization. Use `release_uniqueness_key` : `true` when archiving to reuse keys\n- Notification type requirements: Different threshold notification types require specific fields (e.g., `billable_metric_id` for usage notifications, `credit_type_id` for credit-based threshold notifications)\n- Webhook delivery: Threshold notifications trigger webhook notifications for real-time integration with your systems. Configure webhook endpoints before creating threshold notifications\n- Performance at scale: Metronome's event-driven architecture processes threshold notification 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  $ref: '#/$defs/alert_create_response',\n  $defs: {\n    alert_create_response: {\n      type: 'object',\n      properties: {\n        data: {\n          $ref: '#/$defs/id'\n        }\n      },\n      required: [        'data'\n      ]\n    },\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: {
       alert_type: {
         type: 'string',
-        description: 'Type of the alert',
+        description: 'Type of the threshold notification',
         enum: [
           'low_credit_balance_reached',
           'spend_threshold_reached',
@@ -44,22 +44,22 @@ export const tool: Tool = {
       },
       name: {
         type: 'string',
-        description: 'Name of the alert',
+        description: 'Name of the threshold notification',
       },
       threshold: {
         type: 'number',
         description:
-          'Threshold value of the alert policy.  Depending upon the alert type, this number may represent a financial amount, the days remaining, or a percentage reached.',
+          'Threshold value of the notification policy.  Depending upon the notification type, this number may represent a financial amount, the days remaining, or a percentage reached.',
       },
       billable_metric_id: {
         type: 'string',
         description:
-          'For alerts of type `usage_threshold_reached`, specifies which billable metric to track the usage for.',
+          'For threshold notifications of type `usage_threshold_reached`, specifies which billable metric to track the usage for.',
       },
       credit_grant_type_filters: {
         type: 'array',
         description:
-          'An array of strings, representing a way to filter the credit grant this alert applies to, by looking at the credit_grant_type field on the credit grant. This field is only defined for CreditPercentage and CreditBalance alerts',
+          'An array of strings, representing a way to filter the credit grant this threshold notification applies to, by looking at the credit_grant_type field on the credit grant. This field is only defined for CreditPercentage and CreditBalance notifications',
         items: {
           type: 'string',
         },
@@ -67,12 +67,12 @@ export const tool: Tool = {
       credit_type_id: {
         type: 'string',
         description:
-          "ID of the credit's currency, defaults to USD. If the specific alert type requires a pricing unit/currency, find the ID in the [Metronome app](https://app.metronome.com/offering/pricing-units).",
+          "ID of the credit's currency, defaults to USD. If the specific notification type requires a pricing unit/currency, find the ID in the [Metronome app](https://app.metronome.com/offering/pricing-units).",
       },
       custom_field_filters: {
         type: 'array',
         description:
-          'A list of custom field filters for alert types that support advanced filtering. Only present for contract invoices.',
+          'A list of custom field filters for threshold notification types that support advanced filtering. Only present for contract invoices.',
         items: {
           type: 'object',
           properties: {
@@ -93,17 +93,17 @@ export const tool: Tool = {
       customer_id: {
         type: 'string',
         description:
-          'If provided, will create this alert for this specific customer. To create an alert for all customers, do not specify a `customer_id`.',
+          'If provided, will create this threshold notification for this specific customer. To create a notification for all customers, do not specify a `customer_id`.',
       },
       evaluate_on_create: {
         type: 'boolean',
         description:
-          'If true, the alert will evaluate immediately on customers that already meet the alert threshold. If false, it will only evaluate on future customers that trigger the alert threshold. Defaults to true.',
+          'If true, the threshold notification will evaluate immediately on customers that already meet the notification threshold. If false, it will only evaluate on future customers that trigger the threshold. Defaults to true.',
       },
       group_values: {
         type: 'array',
         description:
-          'Only present for `spend_threshold_reached` alerts. Scope alert to a specific group key on individual line items.',
+          'Only present for `spend_threshold_reached` notifications. Scope notification to a specific group key on individual line items.',
         items: {
           type: 'object',
           properties: {
@@ -114,12 +114,13 @@ export const tool: Tool = {
               type: 'string',
             },
           },
-          required: ['key', 'value'],
+          required: ['key'],
         },
       },
       invoice_types_filter: {
         type: 'array',
-        description: 'Only supported for invoice_total_reached alerts. A list of invoice types to evaluate.',
+        description:
+          'Only supported for invoice_total_reached threshold notifications. A list of invoice types to evaluate.',
         items: {
           type: 'string',
         },
@@ -127,7 +128,7 @@ export const tool: Tool = {
       plan_id: {
         type: 'string',
         description:
-          'If provided, will create this alert for this specific plan. To create an alert for all customers, do not specify a `plan_id`.',
+          'If provided, will create this threshold notification for this specific plan. To create a notification for all customers, do not specify a `plan_id`.',
       },
       uniqueness_key: {
         type: 'string',

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        $ref: '#/$defs/audit_log_list_response'\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  $defs: {\n    audit_log_list_response: {\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}\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  $ref: '#/$defs/billable_metric_archive_response',\n  $defs: {\n    billable_metric_archive_response: {\n      type: 'object',\n      properties: {\n        data: {\n          $ref: '#/$defs/id'\n        }\n      },\n      required: [        'data'\n      ]\n    },\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  $ref: '#/$defs/billable_metric_create_response',\n  $defs: {\n    billable_metric_create_response: {\n      type: 'object',\n      properties: {\n        data: {\n          $ref: '#/$defs/id'\n        }\n      },\n      required: [        'data'\n      ]\n    },\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        $ref: '#/$defs/billable_metric_list_response'\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    billable_metric_list_response: {\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    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  $ref: '#/$defs/billable_metric_retrieve_response',\n  $defs: {\n    billable_metric_retrieve_response: {\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    },\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: {