@metronome/mcp 1.0.0 → 2.0.0

package/src/tools/v1/invoices/regenerate-v1-invoices.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'regenerate_v1_invoices',
   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\nThis endpoint regenerates a voided invoice and recalculates the invoice based on up-to-date rates, available balances, and other fees regardless of the billing period.\n\n### Use this endpoint to:\nRecalculate an invoice with updated rate terms, available balance, and fees to correct billing disputes or discrepancies\n\n### Key response fields:\nThe regenerated invoice id, which is distinct from the previously voided invoice.\n\n### Usage guidelines:\nIf an invoice is attached to a contract with a billing provider on it, the regenerated invoice will be distributed based on the configuration.\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: 'The new invoice id'\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\nThis endpoint regenerates a voided invoice and recalculates the invoice based on up-to-date rates, available balances, and other fees regardless of the billing period.\n\n### Use this endpoint to:\nRecalculate an invoice with updated rate terms, available balance, and fees to correct billing disputes or discrepancies\n\n### Key response fields:\nThe regenerated invoice id, which is distinct from the previously voided invoice.\n\n### Usage guidelines:\nIf an invoice is attached to a contract with a billing provider on it, the regenerated invoice will be distributed based on the configuration.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/invoice_regenerate_response',\n  $defs: {\n    invoice_regenerate_response: {\n      type: 'object',\n      properties: {\n        data: {\n          type: 'object',\n          properties: {\n            id: {\n              type: 'string',\n              description: 'The new invoice id'\n            }\n          },\n          required: [            'id'\n          ]\n        }\n      }\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/invoices/void-v1-invoices.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'void_v1_invoices',
   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\nPermanently cancels an invoice by setting its status to voided, preventing collection and removing it from customer billing. Use this to correct billing errors, cancel incorrect charges, or handle disputed invoices that should not be collected. Returns the voided invoice ID with the status change applied immediately to stop any payment processing.\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        }\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 cancels an invoice by setting its status to voided, preventing collection and removing it from customer billing. Use this to correct billing errors, cancel incorrect charges, or handle disputed invoices that should not be collected. Returns the voided invoice ID with the status change applied immediately to stop any payment processing.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/invoice_void_response',\n  $defs: {\n    invoice_void_response: {\n      type: 'object',\n      properties: {\n        data: {\n          type: 'object',\n          properties: {\n            id: {\n              type: 'string'\n            }\n          },\n          required: [            'id'\n          ]\n        }\n      }\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/payments/attempt-v1-payments.ts

@@ -0,0 +1,48 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { maybeFilter } from '@metronome/mcp/filtering';
+import { Metadata, asTextContentResult } from '@metronome/mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Metronome from '@metronome/sdk';
+
+export const metadata: Metadata = {
+  resource: 'v1.payments',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'post',
+  httpPath: '/v1/payments/attempt',
+  operationId: 'attemptPayment-v1',
+};
+
+export const tool: Tool = {
+  name: 'attempt_v1_payments',
+  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\nTrigger a new attempt by canceling any existing attempts for this invoice and creating a new Payment. This will trigger another attempt to charge the Customer's configured Payment Gateway. \nPayment can only be attempted if all of the following are true:\n  - The Metronome Invoice is finalized\n  - PLG Invoicing is configured for the Customer\n  - You cannot attempt payments for invoices that have already been `paid` or `voided`.\n\nAttempting to payment on an ineligible Invoice or Customer will result in a `400` response.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/payment_attempt_response',\n  $defs: {\n    payment_attempt_response: {\n      type: 'object',\n      properties: {\n        data: {\n          $ref: '#/$defs/payment'\n        }\n      },\n      required: [        'data'\n      ]\n    },\n    payment: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        amount: {\n          type: 'number'\n        },\n        amount_paid: {\n          type: 'number'\n        },\n        contract_id: {\n          type: 'string'\n        },\n        created_at: {\n          type: 'string',\n          format: 'date-time'\n        },\n        customer_id: {\n          type: 'string'\n        },\n        error_message: {\n          type: 'string'\n        },\n        fiat_credit_type: {\n          $ref: '#/$defs/credit_type_data'\n        },\n        invoice_id: {\n          type: 'string'\n        },\n        payment_gateway: {\n          type: 'object',\n          properties: {\n            stripe: {\n              type: 'object',\n              properties: {\n                payment_intent_id: {\n                  type: 'string'\n                },\n                error: {\n                  type: 'object',\n                  properties: {\n                    code: {\n                      type: 'string'\n                    },\n                    decline_code: {\n                      type: 'string'\n                    },\n                    type: {\n                      type: 'string'\n                    }\n                  }\n                }\n              },\n              required: [                'payment_intent_id'\n              ]\n            },\n            type: {\n              type: 'string',\n              enum: [                'stripe'\n              ]\n            }\n          },\n          required: [            'stripe',\n            'type'\n          ]\n        },\n        status: {\n          $ref: '#/$defs/payment_status'\n        },\n        updated_at: {\n          type: 'string',\n          format: 'date-time'\n        }\n      },\n      required: [        'id'\n      ]\n    },\n    credit_type_data: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        name: {\n          type: 'string'\n        }\n      },\n      required: [        'id',\n        'name'\n      ]\n    },\n    payment_status: {\n      type: 'string',\n      enum: [        'pending',\n        'requires_intervention',\n        'paid',\n        'canceled'\n      ]\n    }\n  }\n}\n```",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      customer_id: {
+        type: 'string',
+      },
+      invoice_id: {
+        type: 'string',
+      },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
+    },
+    required: ['customer_id', 'invoice_id'],
+  },
+  annotations: {},
+};
+
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  return asTextContentResult(await maybeFilter(jq_filter, await client.v1.payments.attempt(body)));
+};
+
+export default { metadata, tool, handler };

package/src/tools/v1/payments/cancel-v1-payments.ts

@@ -0,0 +1,48 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { maybeFilter } from '@metronome/mcp/filtering';
+import { Metadata, asTextContentResult } from '@metronome/mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Metronome from '@metronome/sdk';
+
+export const metadata: Metadata = {
+  resource: 'v1.payments',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'post',
+  httpPath: '/v1/payments/cancel',
+  operationId: 'cancelPayment-v1',
+};
+
+export const tool: Tool = {
+  name: 'cancel_v1_payments',
+  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\nCancel an existing payment attempt for an invoice.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/payment_cancel_response',\n  $defs: {\n    payment_cancel_response: {\n      type: 'object',\n      properties: {\n        data: {\n          $ref: '#/$defs/payment'\n        }\n      },\n      required: [        'data'\n      ]\n    },\n    payment: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        amount: {\n          type: 'number'\n        },\n        amount_paid: {\n          type: 'number'\n        },\n        contract_id: {\n          type: 'string'\n        },\n        created_at: {\n          type: 'string',\n          format: 'date-time'\n        },\n        customer_id: {\n          type: 'string'\n        },\n        error_message: {\n          type: 'string'\n        },\n        fiat_credit_type: {\n          $ref: '#/$defs/credit_type_data'\n        },\n        invoice_id: {\n          type: 'string'\n        },\n        payment_gateway: {\n          type: 'object',\n          properties: {\n            stripe: {\n              type: 'object',\n              properties: {\n                payment_intent_id: {\n                  type: 'string'\n                },\n                error: {\n                  type: 'object',\n                  properties: {\n                    code: {\n                      type: 'string'\n                    },\n                    decline_code: {\n                      type: 'string'\n                    },\n                    type: {\n                      type: 'string'\n                    }\n                  }\n                }\n              },\n              required: [                'payment_intent_id'\n              ]\n            },\n            type: {\n              type: 'string',\n              enum: [                'stripe'\n              ]\n            }\n          },\n          required: [            'stripe',\n            'type'\n          ]\n        },\n        status: {\n          $ref: '#/$defs/payment_status'\n        },\n        updated_at: {\n          type: 'string',\n          format: 'date-time'\n        }\n      },\n      required: [        'id'\n      ]\n    },\n    credit_type_data: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        name: {\n          type: 'string'\n        }\n      },\n      required: [        'id',\n        'name'\n      ]\n    },\n    payment_status: {\n      type: 'string',\n      enum: [        'pending',\n        'requires_intervention',\n        'paid',\n        'canceled'\n      ]\n    }\n  }\n}\n```",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      customer_id: {
+        type: 'string',
+      },
+      invoice_id: {
+        type: 'string',
+      },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
+    },
+    required: ['customer_id', 'invoice_id'],
+  },
+  annotations: {},
+};
+
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  return asTextContentResult(await maybeFilter(jq_filter, await client.v1.payments.cancel(body)));
+};
+
+export default { metadata, tool, handler };

package/src/tools/v1/payments/list-v1-payments.ts

@@ -0,0 +1,69 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { maybeFilter } from '@metronome/mcp/filtering';
+import { Metadata, asTextContentResult } from '@metronome/mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Metronome from '@metronome/sdk';
+
+export const metadata: Metadata = {
+  resource: 'v1.payments',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'post',
+  httpPath: '/v1/payments/list',
+  operationId: 'listPayments-v1',
+};
+
+export const tool: Tool = {
+  name: 'list_v1_payments',
+  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\nFetch all payment attempts for the given invoice.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        $ref: '#/$defs/payment'\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    payment: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        amount: {\n          type: 'number'\n        },\n        amount_paid: {\n          type: 'number'\n        },\n        contract_id: {\n          type: 'string'\n        },\n        created_at: {\n          type: 'string',\n          format: 'date-time'\n        },\n        customer_id: {\n          type: 'string'\n        },\n        error_message: {\n          type: 'string'\n        },\n        fiat_credit_type: {\n          $ref: '#/$defs/credit_type_data'\n        },\n        invoice_id: {\n          type: 'string'\n        },\n        payment_gateway: {\n          type: 'object',\n          properties: {\n            stripe: {\n              type: 'object',\n              properties: {\n                payment_intent_id: {\n                  type: 'string'\n                },\n                error: {\n                  type: 'object',\n                  properties: {\n                    code: {\n                      type: 'string'\n                    },\n                    decline_code: {\n                      type: 'string'\n                    },\n                    type: {\n                      type: 'string'\n                    }\n                  }\n                }\n              },\n              required: [                'payment_intent_id'\n              ]\n            },\n            type: {\n              type: 'string',\n              enum: [                'stripe'\n              ]\n            }\n          },\n          required: [            'stripe',\n            'type'\n          ]\n        },\n        status: {\n          $ref: '#/$defs/payment_status'\n        },\n        updated_at: {\n          type: 'string',\n          format: 'date-time'\n        }\n      },\n      required: [        'id'\n      ]\n    },\n    credit_type_data: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        name: {\n          type: 'string'\n        }\n      },\n      required: [        'id',\n        'name'\n      ]\n    },\n    payment_status: {\n      type: 'string',\n      enum: [        'pending',\n        'requires_intervention',\n        'paid',\n        'canceled'\n      ]\n    }\n  }\n}\n```",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      customer_id: {
+        type: 'string',
+      },
+      invoice_id: {
+        type: 'string',
+      },
+      limit: {
+        type: 'integer',
+        description: 'The maximum number of payments to return. Defaults to 25.',
+      },
+      next_page: {
+        type: 'string',
+        description: 'The next page token from a previous response.',
+      },
+      statuses: {
+        type: 'array',
+        items: {
+          $ref: '#/$defs/payment_status',
+        },
+      },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
+    },
+    required: ['customer_id', 'invoice_id'],
+    $defs: {
+      payment_status: {
+        type: 'string',
+        enum: ['pending', 'requires_intervention', 'paid', 'canceled'],
+      },
+    },
+  },
+  annotations: {},
+};
+
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  const response = await client.v1.payments.list(body).asResponse();
+  return asTextContentResult(await maybeFilter(jq_filter, await response.json()));
+};
+
+export default { metadata, tool, handler };

package/src/tools/v1/plans/get-details-v1-plans.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'get_details_v1_plans',
   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\nFetch high level details of a specific plan.\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/plan_detail'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    plan_detail: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        custom_fields: {\n          type: 'object',\n          description: 'Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }',\n          additionalProperties: true\n        },\n        name: {\n          type: 'string'\n        },\n        credit_grants: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              amount_granted: {\n                type: 'number'\n              },\n              amount_granted_credit_type: {\n                $ref: '#/$defs/credit_type_data'\n              },\n              amount_paid: {\n                type: 'number'\n              },\n              amount_paid_credit_type: {\n                $ref: '#/$defs/credit_type_data'\n              },\n              effective_duration: {\n                type: 'number'\n              },\n              name: {\n                type: 'string'\n              },\n              priority: {\n                type: 'string'\n              },\n              send_invoice: {\n                type: 'boolean'\n              },\n              reason: {\n                type: 'string'\n              },\n              recurrence_duration: {\n                type: 'number'\n              },\n              recurrence_interval: {\n                type: 'number'\n              }\n            },\n            required: [              'amount_granted',\n              'amount_granted_credit_type',\n              'amount_paid',\n              'amount_paid_credit_type',\n              'effective_duration',\n              'name',\n              'priority',\n              'send_invoice'\n            ]\n          }\n        },\n        description: {\n          type: 'string'\n        },\n        minimums: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              credit_type: {\n                $ref: '#/$defs/credit_type_data'\n              },\n              name: {\n                type: 'string'\n              },\n              start_period: {\n                type: 'number',\n                description: 'Used in price ramps.  Indicates how many billing periods pass before the charge applies.'\n              },\n              value: {\n                type: 'number'\n              }\n            },\n            required: [              'credit_type',\n              'name',\n              'start_period',\n              'value'\n            ]\n          }\n        },\n        overage_rates: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              credit_type: {\n                $ref: '#/$defs/credit_type_data'\n              },\n              fiat_credit_type: {\n                $ref: '#/$defs/credit_type_data'\n              },\n              start_period: {\n                type: 'number',\n                description: 'Used in price ramps.  Indicates how many billing periods pass before the charge applies.'\n              },\n              to_fiat_conversion_factor: {\n                type: 'number'\n              }\n            },\n            required: [              'credit_type',\n              'fiat_credit_type',\n              'start_period',\n              'to_fiat_conversion_factor'\n            ]\n          }\n        }\n      },\n      required: [        'id',\n        'custom_fields',\n        'name'\n      ]\n    },\n    credit_type_data: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        name: {\n          type: 'string'\n        }\n      },\n      required: [        'id',\n        '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\nFetch high level details of a specific plan.\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/plan_get_details_response',\n  $defs: {\n    plan_get_details_response: {\n      type: 'object',\n      properties: {\n        data: {\n          $ref: '#/$defs/plan_detail'\n        }\n      },\n      required: [        'data'\n      ]\n    },\n    plan_detail: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        custom_fields: {\n          type: 'object',\n          description: 'Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }',\n          additionalProperties: true\n        },\n        name: {\n          type: 'string'\n        },\n        credit_grants: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              amount_granted: {\n                type: 'number'\n              },\n              amount_granted_credit_type: {\n                $ref: '#/$defs/credit_type_data'\n              },\n              amount_paid: {\n                type: 'number'\n              },\n              amount_paid_credit_type: {\n                $ref: '#/$defs/credit_type_data'\n              },\n              effective_duration: {\n                type: 'number'\n              },\n              name: {\n                type: 'string'\n              },\n              priority: {\n                type: 'string'\n              },\n              send_invoice: {\n                type: 'boolean'\n              },\n              reason: {\n                type: 'string'\n              },\n              recurrence_duration: {\n                type: 'number'\n              },\n              recurrence_interval: {\n                type: 'number'\n              }\n            },\n            required: [              'amount_granted',\n              'amount_granted_credit_type',\n              'amount_paid',\n              'amount_paid_credit_type',\n              'effective_duration',\n              'name',\n              'priority',\n              'send_invoice'\n            ]\n          }\n        },\n        description: {\n          type: 'string'\n        },\n        minimums: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              credit_type: {\n                $ref: '#/$defs/credit_type_data'\n              },\n              name: {\n                type: 'string'\n              },\n              start_period: {\n                type: 'number',\n                description: 'Used in price ramps.  Indicates how many billing periods pass before the charge applies.'\n              },\n              value: {\n                type: 'number'\n              }\n            },\n            required: [              'credit_type',\n              'name',\n              'start_period',\n              'value'\n            ]\n          }\n        },\n        overage_rates: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              credit_type: {\n                $ref: '#/$defs/credit_type_data'\n              },\n              fiat_credit_type: {\n                $ref: '#/$defs/credit_type_data'\n              },\n              start_period: {\n                type: 'number',\n                description: 'Used in price ramps.  Indicates how many billing periods pass before the charge applies.'\n              },\n              to_fiat_conversion_factor: {\n                type: 'number'\n              }\n            },\n            required: [              'credit_type',\n              'fiat_credit_type',\n              'start_period',\n              'to_fiat_conversion_factor'\n            ]\n          }\n        }\n      },\n      required: [        'id',\n        'custom_fields',\n        'name'\n      ]\n    },\n    credit_type_data: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        name: {\n          type: 'string'\n        }\n      },\n      required: [        'id',\n        'name'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/plans/list-charges-v1-plans.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_charges_v1_plans',
   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\nFetches a list of charges of a specific plan.\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          charge_type: {\n            type: 'string',\n            enum: [              'usage',\n              'fixed',\n              'composite',\n              'minimum',\n              'seat'\n            ]\n          },\n          credit_type: {\n            $ref: '#/$defs/credit_type_data'\n          },\n          custom_fields: {\n            type: 'object',\n            description: 'Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }',\n            additionalProperties: true\n          },\n          name: {\n            type: 'string'\n          },\n          prices: {\n            type: 'array',\n            items: {\n              type: 'object',\n              properties: {\n                tier: {\n                  type: 'number',\n                  description: 'Used in pricing tiers.  Indicates at what metric value the price applies.'\n                },\n                value: {\n                  type: 'number'\n                },\n                collection_interval: {\n                  type: 'number'\n                },\n                collection_schedule: {\n                  type: 'string'\n                },\n                quantity: {\n                  type: 'number'\n                }\n              },\n              required: [                'tier',\n                'value'\n              ]\n            }\n          },\n          product_id: {\n            type: 'string'\n          },\n          product_name: {\n            type: 'string'\n          },\n          quantity: {\n            type: 'number'\n          },\n          start_period: {\n            type: 'number',\n            description: 'Used in price ramps.  Indicates how many billing periods pass before the charge applies.'\n          },\n          tier_reset_frequency: {\n            type: 'number',\n            description: 'Used in pricing tiers.  Indicates how often the tier resets. Default is 1 - the tier count resets every billing period.'\n          },\n          unit_conversion: {\n            type: 'object',\n            description: 'Specifies how quantities for usage based charges will be converted.',\n            properties: {\n              division_factor: {\n                type: 'number',\n                description: 'The conversion factor'\n              },\n              rounding_behavior: {\n                type: 'string',\n                description: 'Whether usage should be rounded down or up to the nearest whole number. If null, quantity will be rounded to 20 decimal places.',\n                enum: [                  'floor',\n                  'ceiling'\n                ]\n              }\n            },\n            required: [              'division_factor'\n            ]\n          }\n        },\n        required: [          'id',\n          'charge_type',\n          'credit_type',\n          'custom_fields',\n          'name',\n          'prices',\n          'product_id',\n          'product_name'\n        ]\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    credit_type_data: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        name: {\n          type: 'string'\n        }\n      },\n      required: [        'id',\n        '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\nFetches a list of charges of a specific plan.\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        $ref: '#/$defs/plan_list_charges_response'\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    plan_list_charges_response: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        charge_type: {\n          type: 'string',\n          enum: [            'usage',\n            'fixed',\n            'composite',\n            'minimum',\n            'seat'\n          ]\n        },\n        credit_type: {\n          $ref: '#/$defs/credit_type_data'\n        },\n        custom_fields: {\n          type: 'object',\n          description: 'Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }',\n          additionalProperties: true\n        },\n        name: {\n          type: 'string'\n        },\n        prices: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              tier: {\n                type: 'number',\n                description: 'Used in pricing tiers.  Indicates at what metric value the price applies.'\n              },\n              value: {\n                type: 'number'\n              },\n              collection_interval: {\n                type: 'number'\n              },\n              collection_schedule: {\n                type: 'string'\n              },\n              quantity: {\n                type: 'number'\n              }\n            },\n            required: [              'tier',\n              'value'\n            ]\n          }\n        },\n        product_id: {\n          type: 'string'\n        },\n        product_name: {\n          type: 'string'\n        },\n        quantity: {\n          type: 'number'\n        },\n        start_period: {\n          type: 'number',\n          description: 'Used in price ramps.  Indicates how many billing periods pass before the charge applies.'\n        },\n        tier_reset_frequency: {\n          type: 'number',\n          description: 'Used in pricing tiers.  Indicates how often the tier resets. Default is 1 - the tier count resets every billing period.'\n        },\n        unit_conversion: {\n          type: 'object',\n          description: 'Specifies how quantities for usage based charges will be converted.',\n          properties: {\n            division_factor: {\n              type: 'number',\n              description: 'The conversion factor'\n            },\n            rounding_behavior: {\n              type: 'string',\n              description: 'Whether usage should be rounded down or up to the nearest whole number. If null, quantity will be rounded to 20 decimal places.',\n              enum: [                'floor',\n                'ceiling'\n              ]\n            }\n          },\n          required: [            'division_factor'\n          ]\n        }\n      },\n      required: [        'id',\n        'charge_type',\n        'credit_type',\n        'custom_fields',\n        'name',\n        'prices',\n        'product_id',\n        'product_name'\n      ]\n    },\n    credit_type_data: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        name: {\n          type: 'string'\n        }\n      },\n      required: [        'id',\n        'name'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/plans/list-customers-v1-plans.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_customers_v1_plans',
   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\nFetches a list of customers on a specific plan (by default, only currently active plans are included)\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          customer_details: {\n            $ref: '#/$defs/customer_detail'\n          },\n          plan_details: {\n            type: 'object',\n            properties: {\n              id: {\n                type: 'string'\n              },\n              custom_fields: {\n                type: 'object',\n                description: 'Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }',\n                additionalProperties: true\n              },\n              customer_plan_id: {\n                type: 'string'\n              },\n              name: {\n                type: 'string'\n              },\n              starting_on: {\n                type: 'string',\n                description: 'The start date of the plan',\n                format: 'date-time'\n              },\n              ending_before: {\n                type: 'string',\n                description: 'The end date of the plan',\n                format: 'date-time'\n              }\n            },\n            required: [              'id',\n              'custom_fields',\n              'customer_plan_id',\n              'name',\n              'starting_on'\n            ]\n          }\n        },\n        required: [          'customer_details',\n          'plan_details'\n        ]\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    customer_detail: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'the Metronome ID of the customer'\n        },\n        created_at: {\n          type: 'string',\n          description: 'RFC 3339 timestamp indicating when the customer was created.',\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        customer_config: {\n          type: 'object',\n          properties: {\n            salesforce_account_id: {\n              type: 'string',\n              description: 'The Salesforce account ID for the customer'\n            }\n          },\n          required: [            'salesforce_account_id'\n          ]\n        },\n        external_id: {\n          type: 'string',\n          description: '(deprecated, use ingest_aliases instead) the first ID (Metronome or ingest alias) that can be used in usage events'\n        },\n        ingest_aliases: {\n          type: 'array',\n          description: 'aliases for this customer that can be used instead of the Metronome customer ID in usage events',\n          items: {\n            type: 'string'\n          }\n        },\n        name: {\n          type: 'string'\n        },\n        archived_at: {\n          type: 'string',\n          description: 'RFC 3339 timestamp indicating when the customer was archived. Null if the customer is active.',\n          format: 'date-time'\n        },\n        current_billable_status: {\n          type: 'object',\n          description: 'This field\\'s availability is dependent on your client\\'s configuration.',\n          properties: {\n            value: {\n              type: 'string',\n              enum: [                'billable',\n                'unbillable'\n              ]\n            },\n            effective_at: {\n              type: 'string',\n              format: 'date-time'\n            }\n          },\n          required: [            'value'\n          ]\n        }\n      },\n      required: [        'id',\n        'created_at',\n        'custom_fields',\n        'customer_config',\n        'external_id',\n        'ingest_aliases',\n        '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\nFetches a list of customers on a specific plan (by default, only currently active plans are included)\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        $ref: '#/$defs/plan_list_customers_response'\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    plan_list_customers_response: {\n      type: 'object',\n      properties: {\n        customer_details: {\n          $ref: '#/$defs/customer_detail'\n        },\n        plan_details: {\n          type: 'object',\n          properties: {\n            id: {\n              type: 'string'\n            },\n            custom_fields: {\n              type: 'object',\n              description: 'Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }',\n              additionalProperties: true\n            },\n            customer_plan_id: {\n              type: 'string'\n            },\n            name: {\n              type: 'string'\n            },\n            starting_on: {\n              type: 'string',\n              description: 'The start date of the plan',\n              format: 'date-time'\n            },\n            ending_before: {\n              type: 'string',\n              description: 'The end date of the plan',\n              format: 'date-time'\n            }\n          },\n          required: [            'id',\n            'custom_fields',\n            'customer_plan_id',\n            'name',\n            'starting_on'\n          ]\n        }\n      },\n      required: [        'customer_details',\n        'plan_details'\n      ]\n    },\n    customer_detail: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'the Metronome ID of the customer'\n        },\n        created_at: {\n          type: 'string',\n          description: 'RFC 3339 timestamp indicating when the customer was created.',\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        customer_config: {\n          type: 'object',\n          properties: {\n            salesforce_account_id: {\n              type: 'string',\n              description: 'The Salesforce account ID for the customer'\n            }\n          },\n          required: [            'salesforce_account_id'\n          ]\n        },\n        external_id: {\n          type: 'string',\n          description: '(deprecated, use ingest_aliases instead) the first ID (Metronome or ingest alias) that can be used in usage events'\n        },\n        ingest_aliases: {\n          type: 'array',\n          description: 'aliases for this customer that can be used instead of the Metronome customer ID in usage events',\n          items: {\n            type: 'string'\n          }\n        },\n        name: {\n          type: 'string'\n        },\n        updated_at: {\n          type: 'string',\n          description: 'RFC 3339 timestamp indicating when the customer was last updated.',\n          format: 'date-time'\n        },\n        archived_at: {\n          type: 'string',\n          description: 'RFC 3339 timestamp indicating when the customer was archived. Null if the customer is active.',\n          format: 'date-time'\n        },\n        current_billable_status: {\n          type: 'object',\n          description: 'This field\\'s availability is dependent on your client\\'s configuration.',\n          properties: {\n            value: {\n              type: 'string',\n              enum: [                'billable',\n                'unbillable'\n              ]\n            },\n            effective_at: {\n              type: 'string',\n              format: 'date-time'\n            }\n          },\n          required: [            'value'\n          ]\n        }\n      },\n      required: [        'id',\n        'created_at',\n        'custom_fields',\n        'customer_config',\n        'external_id',\n        'ingest_aliases',\n        'name',\n        'updated_at'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/plans/list-v1-plans.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_v1_plans',
   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 available plans.\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          description: {\n            type: 'string'\n          },\n          name: {\n            type: 'string'\n          },\n          custom_fields: {\n            type: 'object',\n            description: 'Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }',\n            additionalProperties: true\n          }\n        },\n        required: [          'id',\n          'description',\n          'name'\n        ]\n      }\n    },\n    next_page: {\n      type: 'string'\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\nList all available plans.\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        $ref: '#/$defs/plan_list_response'\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    plan_list_response: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        description: {\n          type: 'string'\n        },\n        name: {\n          type: 'string'\n        },\n        custom_fields: {\n          type: 'object',\n          description: 'Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }',\n          additionalProperties: true\n        }\n      },\n      required: [        'id',\n        'description',\n        'name'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/pricing-units/list-v1-pricing-units.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_v1_pricing_units',
   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 pricing units. All fiat currency types (for example, USD or GBP) will be included, as well as any custom pricing units that were configured. Custom pricing units can be used to charge for usage in a non-fiat pricing unit, for example AI credits.\n\nNote: The USD (cents) pricing unit is 2714e483-4ff1-48e4-9e25-ac732e8f24f2.\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          is_currency: {\n            type: 'boolean'\n          },\n          name: {\n            type: 'string'\n          }\n        }\n      }\n    },\n    next_page: {\n      type: 'string'\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\nList all pricing units. All fiat currency types (for example, USD or GBP) will be included, as well as any custom pricing units that were configured. Custom pricing units can be used to charge for usage in a non-fiat pricing unit, for example AI credits.\n\nNote: The USD (cents) pricing unit is 2714e483-4ff1-48e4-9e25-ac732e8f24f2.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        $ref: '#/$defs/pricing_unit_list_response'\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    pricing_unit_list_response: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string'\n        },\n        is_currency: {\n          type: 'boolean'\n        },\n        name: {\n          type: 'string'\n        }\n      }\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/services/list-v1-services.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_v1_services',
   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\nGets Metronome's service registry with associated IP addresses for security allowlisting and firewall configuration. Use this endpoint to maintain an up-to-date list of IPs that your systems should trust for Metronome communications. Returns service names and their current IP ranges, with new IPs typically appearing 30+ days before first use to ensure smooth allowlist updates.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    services: {\n      type: 'array',\n      items: {\n        type: 'object',\n        properties: {\n          ips: {\n            type: 'array',\n            items: {\n              type: 'string'\n            }\n          },\n          name: {\n            type: 'string'\n          },\n          usage: {\n            type: 'string',\n            enum: [              'makes_connections_from',\n              'accepts_connections_at'\n            ]\n          }\n        },\n        required: [          'ips',\n          'name',\n          'usage'\n        ]\n      }\n    }\n  },\n  required: [    'services'\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\nGets Metronome's service registry with associated IP addresses for security allowlisting and firewall configuration. Use this endpoint to maintain an up-to-date list of IPs that your systems should trust for Metronome communications. Returns service names and their current IP ranges, with new IPs typically appearing 30+ days before first use to ensure smooth allowlist updates.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/service_list_response',\n  $defs: {\n    service_list_response: {\n      type: 'object',\n      properties: {\n        services: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              ips: {\n                type: 'array',\n                items: {\n                  type: 'string'\n                }\n              },\n              name: {\n                type: 'string'\n              },\n              usage: {\n                type: 'string',\n                enum: [                  'makes_connections_from',\n                  'accepts_connections_at'\n                ]\n              }\n            },\n            required: [              'ips',\n              'name',\n              'usage'\n            ]\n          }\n        }\n      },\n      required: [        'services'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/usage/ingest-v1-usage.ts

@@ -17,7 +17,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'ingest_v1_usage',
   description:
-    'The ingest endpoint is the primary method for sending usage events to Metronome, serving as the foundation for all billing calculations in your usage-based pricing model. This high-throughput endpoint is designed for real-time streaming ingestion, supports backdating 34 days, and is built to handle mission-critical usage data with enterprise-grade reliability. Metronome supports 100,000 events per second without requiring pre-aggregation or rollups and can scale up from there. See [Getting usage into Metronome](https://docs.metronome.com/connect-metronome/) to learn more about usage events.\n\n### Use this endpoint to:\nCreate a customer usage pipeline into Metronome that drives billable metrics, credit drawdown, and invoicing. Track customer behavior, resource consumption, and feature usage\n\n### What happens when you send events:\n- Events are validated and processed in real-time\n- Events are matched to customers using customer IDs or customer ingest aliases\n- Events are matched to billable metrics and are immediately available for usage and spend calculations\n\n### Usage guidelines:\n- Historical events can be backdated up to 34 days and will immediately impact live customer spend\n- Duplicate events are automatically detected and ignored (34-day deduplication window)\n\n#### Event structure:\nUsage events are simple JSON objects designed for flexibility and ease of integration:\n```json\n{\n  "transaction_id": "2021-01-01T00:00:00Z_cluster42",\n  "customer_id": "team@example.com",\n  "event_type": "api_request",\n  "timestamp": "2021-01-01T00:00:00Z",\n  "properties": {\n    "endpoint": "/v1/users",\n    "method": "POST",\n    "response_time_ms": 45,\n    "region": "us-west-2"\n  }\n}\n```\n\n#### Transaction ID\n  The transaction_id serves as your idempotency key, ensuring events are processed exactly once. Metronome maintains a 34-day deduplication window - significantly longer than typical 12-hour windows - enabling robust backfill scenarios without duplicate billing.\n  - Best Practices:\n    - Use UUIDs for one-time events: uuid4()\n    - For heartbeat events, use deterministic IDs\n    - Include enough context to avoid collisions across different event sources\n\n#### Customer ID\nIdentifies which customer should be billed for this usage. Supports two identification methods:\n  - Metronome Customer ID: The UUID returned when creating a customer\n  - Ingest Alias: Your system\'s identifier (email, account number, etc.) \n\nIngest aliases enable seamless integration without requiring ID mapping, and customers can have multiple aliases for flexibility.\n\n#### Event Type:\nCategorizes the event type for billable metric matching. Choose descriptive names that aligns with the product surface area.\n\n#### Properties:\nFlexible metadata also used to match billable metrics or to be used to serve as group keys to create multiple pricing dimensions or breakdown costs by novel properties for end customers or internal finance teams measuring underlying COGs.\n',
+    'The ingest endpoint is the primary method for sending usage events to Metronome, serving as the foundation for all billing calculations in your usage-based pricing model. This high-throughput endpoint is designed for real-time streaming ingestion, supports backdating 34 days, and is built to handle mission-critical usage data with enterprise-grade reliability. Metronome supports 100,000 events per second without requiring pre-aggregation or rollups and can scale up from there. See the [Send usage events](/guides/events/send-usage-events) guide to learn more about usage events.\n\n### Use this endpoint to:\nCreate a customer usage pipeline into Metronome that drives billable metrics, credit drawdown, and invoicing. Track customer behavior, resource consumption, and feature usage\n\n### What happens when you send events:\n- Events are validated and processed in real-time\n- Events are matched to customers using customer IDs or customer ingest aliases\n- Events are matched to billable metrics and are immediately available for usage and spend calculations\n\n### Usage guidelines:\n- Historical events can be backdated up to 34 days and will immediately impact live customer spend\n- Duplicate events are automatically detected and ignored (34-day deduplication window)\n\n#### Event structure:\nUsage events are simple JSON objects designed for flexibility and ease of integration:\n```json\n{\n  "transaction_id": "2021-01-01T00:00:00Z_cluster42",\n  "customer_id": "team@example.com",\n  "event_type": "api_request",\n  "timestamp": "2021-01-01T00:00:00Z",\n  "properties": {\n    "endpoint": "/v1/users",\n    "method": "POST",\n    "response_time_ms": 45,\n    "region": "us-west-2"\n  }\n}\n```\n\nLearn more about [usage event structure definitions](/guides/events/design-usage-events).\n\n#### Transaction ID\n  The transaction_id serves as your idempotency key, ensuring events are processed exactly once. Metronome maintains a 34-day deduplication window - significantly longer than typical 12-hour windows - enabling robust backfill scenarios without duplicate billing.\n  - Best Practices:\n    - Use UUIDs for one-time events: uuid4()\n    - For heartbeat events, use deterministic IDs\n    - Include enough context to avoid collisions across different event sources\n\n#### Customer ID\nIdentifies which customer should be billed for this usage. Supports two identification methods:\n  - Metronome Customer ID: The UUID returned when creating a customer\n  - Ingest Alias: Your system\'s identifier (email, account number, etc.) \n\nIngest aliases enable seamless integration without requiring ID mapping, and customers can have multiple aliases for flexibility.\n\n#### Event Type:\nCategorizes the event type for billable metric matching. Choose descriptive names that aligns with the product surface area.\n\n#### Properties:\nFlexible metadata also used to match billable metrics or to be used to serve as group keys to create multiple pricing dimensions or breakdown costs by novel properties for end customers or internal finance teams measuring underlying COGs.\n',
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/usage/list-v1-usage.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_v1_usage',
   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\nRetrieve aggregated usage data across multiple customers and billable metrics in a single query. This batch endpoint enables you to fetch usage patterns at scale, broken down by time windows, making it ideal for building analytics dashboards, generating reports, and monitoring platform-wide usage trends.\n\n### Use this endpoint to:\n- Generate platform-wide usage reports for internal teams\n- Monitor aggregate usage trends across your entire customer base\n- Create comparative usage analyses between customers or time periods\n- Support capacity planning with historical usage patterns\n\n### Key response fields:\nAn array of `UsageBatchAggregate` objects containing:\n\n- `customer_id`: The customer this usage belongs to\n- `billable_metric_id` and `billable_metric_name`: What was measured\n- `start_timestamp` and `end_timestamp`: Time window for this data point\n- `value`: Aggregated usage amount for the period\n- `groups` (optional): Usage broken down by group keys with values\n- `next_page`: Pagination cursor for large result sets\n\n### Usage guidelines:\n- Time windows: Set `window_size` to `hour`, `day`, or `none` (entire period)\n- Required parameters: Must specify `starting_on`, `ending_before`, and `window_size`\n- Filtering options:\n  - `customer_ids`: Limit to specific customers (omit for all customers)\n  - `billable_metrics`: Limit to specific metrics (omit for all metrics)\n- Pagination: Use `next_page` cursor to retrieve large datasets\n- Null values: Group values may be null when no usage matches that group\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          billable_metric_id: {\n            type: 'string'\n          },\n          billable_metric_name: {\n            type: 'string'\n          },\n          customer_id: {\n            type: 'string'\n          },\n          end_timestamp: {\n            type: 'string',\n            format: 'date-time'\n          },\n          start_timestamp: {\n            type: 'string',\n            format: 'date-time'\n          },\n          value: {\n            type: 'number'\n          },\n          groups: {\n            type: 'object',\n            description: 'Values will be either a number or null. Null indicates that there were no matches for the group_by value.',\n            additionalProperties: true\n          }\n        },\n        required: [          'billable_metric_id',\n          'billable_metric_name',\n          'customer_id',\n          'end_timestamp',\n          'start_timestamp',\n          'value'\n        ]\n      }\n    },\n    next_page: {\n      type: 'string'\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\nRetrieve aggregated usage data across multiple customers and billable metrics in a single query. This batch endpoint enables you to fetch usage patterns at scale, broken down by time windows, making it ideal for building analytics dashboards, generating reports, and monitoring platform-wide usage trends.\n\n### Use this endpoint to:\n- Generate platform-wide usage reports for internal teams\n- Monitor aggregate usage trends across your entire customer base\n- Create comparative usage analyses between customers or time periods\n- Support capacity planning with historical usage patterns\n\n### Key response fields:\nAn array of `UsageBatchAggregate` objects containing:\n\n- `customer_id`: The customer this usage belongs to\n- `billable_metric_id` and `billable_metric_name`: What was measured\n- `start_timestamp` and `end_timestamp`: Time window for this data point\n- `value`: Aggregated usage amount for the period\n- `groups` (optional): Usage broken down by group keys with values\n- `next_page`: Pagination cursor for large result sets\n\n### Usage guidelines:\n- Time windows: Set `window_size` to `hour`, `day`, or `none` (entire period)\n- Required parameters: Must specify `starting_on`, `ending_before`, and `window_size`\n- Filtering options:\n  - `customer_ids`: Limit to specific customers (omit for all customers)\n  - `billable_metrics`: Limit to specific metrics (omit for all metrics)\n- Pagination: Use `next_page` cursor to retrieve large datasets\n- Null values: Group values may be null when no usage matches that group\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        $ref: '#/$defs/usage_list_response'\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    usage_list_response: {\n      type: 'object',\n      properties: {\n        billable_metric_id: {\n          type: 'string'\n        },\n        billable_metric_name: {\n          type: 'string'\n        },\n        customer_id: {\n          type: 'string'\n        },\n        end_timestamp: {\n          type: 'string',\n          format: 'date-time'\n        },\n        start_timestamp: {\n          type: 'string',\n          format: 'date-time'\n        },\n        value: {\n          type: 'number'\n        },\n        groups: {\n          type: 'object',\n          description: 'Values will be either a number or null. Null indicates that there were no matches for the group_by value.',\n          additionalProperties: true\n        }\n      },\n      required: [        'billable_metric_id',\n        'billable_metric_name',\n        'customer_id',\n        'end_timestamp',\n        'start_timestamp',\n        'value'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/usage/list-with-groups-v1-usage.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_with_groups_v1_usage',
   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\nRetrieve granular usage data for a specific customer and billable metric, with the ability to break down usage by custom grouping dimensions. This endpoint enables deep usage analytics by segmenting data across attributes like region, user, model type, or any custom dimension defined in your billable metrics.\n\n### Use this endpoint to:\n- Analyze usage patterns broken down by specific attributes (region, user, department, etc.)\n- Build detailed usage dashboards with dimensional filtering\n- Identify high-usage segments for optimization opportunities\n\n### Key response fields:\nAn array of `PagedUsageAggregate` objects containing:\n- `starting_on` and `ending_before`: Time window boundaries\n- `group_key`: The dimension being grouped by (e.g., \"region\")\n- `group_value`: The specific value for this group (e.g., \"US-East\")\n- `value`: Aggregated usage for this group and time window\n- `next_page`: Pagination cursor for large datasets\n\n### Usage guidelines:\n- Required parameters: Must specify `customer_id`, `billable_metric_id`, and `window_size`\n- Time windows: Set `window_size` to hour, day, or none for different granularities\n- Group filtering: Use `group_by` to specify:\n    - key: The dimension to group by (must be set on the billable metric as a group key)\n    - values: Optional array to filter to specific values only\n- Pagination: Use limit and `next_page` for large result sets\n- Null handling: `group_value` may be null for unmatched data\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          ending_before: {\n            type: 'string',\n            format: 'date-time'\n          },\n          group_key: {\n            type: 'string'\n          },\n          group_value: {\n            type: 'string'\n          },\n          starting_on: {\n            type: 'string',\n            format: 'date-time'\n          },\n          value: {\n            type: 'number'\n          }\n        },\n        required: [          'ending_before',\n          'group_key',\n          'group_value',\n          'starting_on',\n          'value'\n        ]\n      }\n    },\n    next_page: {\n      type: 'string'\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\nRetrieve granular usage data for a specific customer and billable metric, with the ability to break down usage by custom grouping dimensions. This endpoint enables deep usage analytics by segmenting data across attributes like region, user, model type, or any custom dimension defined in your billable metrics.\n\n### Use this endpoint to:\n- Analyze usage patterns broken down by specific attributes (region, user, department, etc.)\n- Build detailed usage dashboards with dimensional filtering\n- Identify high-usage segments for optimization opportunities\n\n### Key response fields:\nAn array of `PagedUsageAggregate` objects containing:\n- `starting_on` and `ending_before`: Time window boundaries\n- `group_key`: The dimension being grouped by (e.g., \"region\")\n- `group_value`: The specific value for this group (e.g., \"US-East\")\n- `value`: Aggregated usage for this group and time window\n- `next_page`: Pagination cursor for large datasets\n\n### Usage guidelines:\n- Required parameters: Must specify `customer_id`, `billable_metric_id`, and `window_size`\n- Time windows: Set `window_size` to hour, day, or none for different granularities\n- Group filtering: Use `group_by` to specify:\n    - key: The dimension to group by (must be set on the billable metric as a group key)\n    - values: Optional array to filter to specific values only\n- Pagination: Use limit and `next_page` for large result sets\n- Null handling: `group_value` may be null for unmatched data\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'array',\n      items: {\n        $ref: '#/$defs/usage_list_with_groups_response'\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ],\n  $defs: {\n    usage_list_with_groups_response: {\n      type: 'object',\n      properties: {\n        ending_before: {\n          type: 'string',\n          format: 'date-time'\n        },\n        group_key: {\n          type: 'string'\n        },\n        group_value: {\n          type: 'string'\n        },\n        starting_on: {\n          type: 'string',\n          format: 'date-time'\n        },\n        value: {\n          type: 'number'\n        }\n      },\n      required: [        'ending_before',\n        'group_key',\n        'group_value',\n        'starting_on',\n        'value'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/v1/usage/search-v1-usage.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'search_v1_usage',
   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\nThis endpoint retrieves events by transaction ID for events that occurred within the last 34 days. It is specifically designed for sampling-based testing workflows to detect revenue leakage. The Event Search API provides a critical observability tool that validates the integrity of your usage pipeline by allowing you to sample raw events and verify their matching against active billable metrics. \n\nWhy event observability matters for revenue leakage:\nSilent revenue loss occurs when events are dropped, delayed, or fail to match billable metrics due to:\n- Upstream system failures\n- Event format changes\n- Misconfigured billable metrics\n\n### Use this endpoint to:\n- Sample raw events and validate they match the expected billable metrics\n- Build custom leakage detection alerts to prevent silent revenue loss\n- Verify event processing accuracy during system changes or metric updates\n- Debug event matching issues in real-time\n\n### Key response fields:\n- Complete event details including transaction ID, customer ID, and properties\n- Matched Metronome customer (if any)\n- Matched billable metric information (if any)\n- Processing status and duplicate detection flags\n\n### Usage guidelines:\n⚠️ Important: This endpoint is heavily rate limited and designed for sampling workflows only. Do not use this endpoint to check every event in your system. Instead, implement a sampling strategy to randomly validate a subset of events for observability purposes.\n\n\n# Response Schema\n```json\n{\n  type: 'array',\n  items: {\n    type: 'object',\n    properties: {\n      id: {\n        type: 'string'\n      },\n      customer_id: {\n        type: 'string',\n        description: 'The ID of the customer in the ingest event body'\n      },\n      event_type: {\n        type: 'string'\n      },\n      timestamp: {\n        type: 'string',\n        format: 'date-time'\n      },\n      transaction_id: {\n        type: 'string'\n      },\n      is_duplicate: {\n        type: 'boolean'\n      },\n      matched_billable_metrics: {\n        type: 'array',\n        items: {\n          type: 'object',\n          properties: {\n            id: {\n              type: 'string'\n            },\n            name: {\n              type: 'string'\n            },\n            aggregate: {\n              type: 'string',\n              description: '(DEPRECATED) use aggregation_type instead'\n            },\n            aggregate_keys: {\n              type: 'array',\n              description: '(DEPRECATED) use aggregation_key instead',\n              items: {\n                type: 'string'\n              }\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            filter: {\n              type: 'object',\n              description: '(DEPRECATED) use property_filters & event_type_filter instead',\n              additionalProperties: true\n            },\n            group_by: {\n              type: 'array',\n              description: '(DEPRECATED) use group_keys instead',\n              items: {\n                type: 'string',\n                description: 'A list of keys that can be used to additionally segment the values of the billable metric when making usage queries'\n              }\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      matched_customer: {\n        type: 'object',\n        description: 'The customer the event was matched to if a match was found',\n        properties: {\n          id: {\n            type: 'string'\n          },\n          name: {\n            type: 'string'\n          }\n        }\n      },\n      processed_at: {\n        type: 'string',\n        format: 'date-time'\n      },\n      properties: {\n        type: 'object',\n        additionalProperties: true\n      }\n    },\n    required: [      'id',\n      'customer_id',\n      'event_type',\n      'timestamp',\n      'transaction_id'\n    ]\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\nThis endpoint retrieves events by transaction ID for events that occurred within the last 34 days. It is specifically designed for sampling-based testing workflows to detect revenue leakage. The Event Search API provides a critical observability tool that validates the integrity of your usage pipeline by allowing you to sample raw events and verify their matching against active billable metrics. \n\nWhy event observability matters for revenue leakage:\nSilent revenue loss occurs when events are dropped, delayed, or fail to match billable metrics due to:\n- Upstream system failures\n- Event format changes\n- Misconfigured billable metrics\n\n### Use this endpoint to:\n- Sample raw events and validate they match the expected billable metrics\n- Build custom leakage detection alerts to prevent silent revenue loss\n- Verify event processing accuracy during system changes or metric updates\n- Debug event matching issues in real-time\n\n### Key response fields:\n- Complete event details including transaction ID, customer ID, and properties\n- Matched Metronome customer (if any)\n- Matched billable metric information (if any)\n- Processing status and duplicate detection flags\n\n### Usage guidelines:\n⚠️ Important: This endpoint is heavily rate limited and designed for sampling workflows only. Do not use this endpoint to check every event in your system. Instead, implement a sampling strategy to randomly validate a subset of events for observability purposes.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/usage_search_response',\n  $defs: {\n    usage_search_response: {\n      type: 'array',\n      items: {\n        type: 'object',\n        properties: {\n          id: {\n            type: 'string'\n          },\n          customer_id: {\n            type: 'string',\n            description: 'The ID of the customer in the ingest event body'\n          },\n          event_type: {\n            type: 'string'\n          },\n          timestamp: {\n            type: 'string',\n            format: 'date-time'\n          },\n          transaction_id: {\n            type: 'string'\n          },\n          is_duplicate: {\n            type: 'boolean'\n          },\n          matched_billable_metrics: {\n            type: 'array',\n            items: {\n              type: 'object',\n              properties: {\n                id: {\n                  type: 'string'\n                },\n                name: {\n                  type: 'string'\n                },\n                aggregate: {\n                  type: 'string',\n                  description: '(DEPRECATED) use aggregation_type instead'\n                },\n                aggregate_keys: {\n                  type: 'array',\n                  description: '(DEPRECATED) use aggregation_key instead',\n                  items: {\n                    type: 'string'\n                  }\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                filter: {\n                  type: 'object',\n                  description: '(DEPRECATED) use property_filters & event_type_filter instead',\n                  additionalProperties: true\n                },\n                group_by: {\n                  type: 'array',\n                  description: '(DEPRECATED) use group_keys instead',\n                  items: {\n                    type: 'string',\n                    description: 'A list of keys that can be used to additionally segment the values of the billable metric when making usage queries'\n                  }\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          matched_customer: {\n            type: 'object',\n            description: 'The customer the event was matched to if a match was found',\n            properties: {\n              id: {\n                type: 'string'\n              },\n              name: {\n                type: 'string'\n              }\n            }\n          },\n          processed_at: {\n            type: 'string',\n            format: 'date-time'\n          },\n          properties: {\n            type: 'object',\n            additionalProperties: true\n          }\n        },\n        required: [          'id',\n          'customer_id',\n          'event_type',\n          'timestamp',\n          'transaction_id'\n        ]\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/v2/contracts/edit-commit-v2-contracts.ts

@@ -18,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'edit_commit_v2_contracts',
   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\nEdit specific details for a contract-level or customer-level commit. Use this endpoint to modify individual commit access schedules, invoice schedules, applicable products, invoicing contracts, or other fields. \n\n### Usage guidelines:\n- As with all edits in Metronome, draft invoices will reflect the edit immediately, while finalized invoices are untouched unless voided and regenerated.\n- If a commit's invoice schedule item is associated with a finalized invoice, you cannot remove or update the invoice schedule item.\n- If a commit's invoice schedule item is associated with a voided invoice, you cannot remove the invoice schedule item.\n- You cannot remove an commit access schedule segment that was applied to a finalized invoice. You can void the invoice beforehand and then remove the access schedule segment.\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```",
+    "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\nEdit specific details for a contract-level or customer-level commit. Use this endpoint to modify individual commit access schedules, invoice schedules, applicable products, invoicing contracts, or other fields. \n\n### Usage guidelines:\n- As with all edits in Metronome, draft invoices will reflect the edit immediately, while finalized invoices are untouched unless voided and regenerated.\n- If a commit's invoice schedule item is associated with a finalized invoice, you cannot remove or update the invoice schedule item.\n- If a commit's invoice schedule item is associated with a voided invoice, you cannot remove the invoice schedule item.\n- You cannot remove an commit access schedule segment that was applied to a finalized invoice. You can void the invoice beforehand and then remove the access schedule segment.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/contract_edit_commit_response',\n  $defs: {\n    contract_edit_commit_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: {
@@ -106,6 +106,9 @@ export const tool: Tool = {
           type: 'string',
         },
       },
+      hierarchy_configuration: {
+        $ref: '#/$defs/commit_hierarchy_configuration',
+      },
       invoice_contract_id: {
         type: 'string',
         description: 'ID of contract to use for invoicing',
@@ -204,6 +207,52 @@ export const tool: Tool = {
     },
     required: ['commit_id', 'customer_id'],
     $defs: {
+      commit_hierarchy_configuration: {
+        type: 'object',
+        properties: {
+          child_access: {
+            anyOf: [
+              {
+                type: 'object',
+                properties: {
+                  type: {
+                    type: 'string',
+                    enum: ['ALL'],
+                  },
+                },
+                required: ['type'],
+              },
+              {
+                type: 'object',
+                properties: {
+                  type: {
+                    type: 'string',
+                    enum: ['NONE'],
+                  },
+                },
+                required: ['type'],
+              },
+              {
+                type: 'object',
+                properties: {
+                  contract_ids: {
+                    type: 'array',
+                    items: {
+                      type: 'string',
+                    },
+                  },
+                  type: {
+                    type: 'string',
+                    enum: ['CONTRACT_IDS'],
+                  },
+                },
+                required: ['contract_ids', 'type'],
+              },
+            ],
+          },
+        },
+        required: ['child_access'],
+      },
       commit_specifier_input: {
         type: 'object',
         properties: {