@metronome/mcp 0.1.0-beta.11 → 0.1.0

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

@@ -1,7 +1,9 @@
 // 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 type { Metadata } from '../../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -16,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_price_adjustments_customers_v1_plans',
   description:
-    'Lists a customer plans adjustments. See the [price adjustments documentation](https://plans-docs.metronome.com/pricing/managing-plans/#price-adjustments) for details.',
+    "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\nLists a customer plans adjustments. See the [price adjustments documentation](https://plans-docs.metronome.com/pricing/managing-plans/#price-adjustments) for details.\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          charge_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          prices: {\n            type: 'array',\n            items: {\n              type: 'object',\n              properties: {\n                adjustment_type: {\n                  type: 'string',\n                  description: 'Determines how the value will be applied.',\n                  enum: [                    'fixed',\n                    'quantity',\n                    'percentage',\n                    'override'\n                  ]\n                },\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              },\n              required: [                'adjustment_type'\n              ]\n            }\n          },\n          start_period: {\n            type: 'number'\n          },\n          quantity: {\n            type: 'number'\n          }\n        },\n        required: [          'charge_id',\n          'charge_type',\n          'prices',\n          'start_period'\n        ]\n      }\n    },\n    next_page: {\n      type: 'string'\n    }\n  },\n  required: [    'data',\n    'next_page'\n  ]\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -34,13 +36,24 @@ export const tool: Tool = {
         type: 'string',
         description: 'Cursor that indicates where the next page of results should start.',
       },
+      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', 'customer_plan_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.customers.plans.listPriceAdjustments(body);
+  const response = await client.v1.customers.plans.listPriceAdjustments(body).asResponse();
+  return asTextContentResult(await maybeFilter(args, await response.json()));
 };
 
 export default { metadata, tool, handler };

package/src/tools/v1/customers/preview-events-v1-customers.ts

@@ -0,0 +1,77 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+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.customers',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'post',
+  httpPath: '/v1/customers/{customer_id}/previewEvents',
+  operationId: 'previewCustomerEvents-v1',
+};
+
+export const tool: Tool = {
+  name: 'preview_events_v1_customers',
+  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\nPreview how a set of events will affect a customer's invoice. Generates a draft invoice for a customer using their current contract configuration and the provided events. This is useful for testing how new events will affect the customer's invoice before they are actually processed.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      customer_id: {
+        type: 'string',
+      },
+      events: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            event_type: {
+              type: 'string',
+            },
+            customer_id: {
+              type: 'string',
+              description:
+                "This has no effect for preview events, but may be set for consistency with Event objects. They will be processed even if they do not match the customer's ID or ingest aliases.",
+            },
+            properties: {
+              type: 'object',
+            },
+            timestamp: {
+              type: 'string',
+              description: 'RFC 3339 formatted. If not provided, the current time will be used.',
+            },
+            transaction_id: {
+              type: 'string',
+              description:
+                'This has no effect for preview events, but may be set for consistency with Event objects. Duplicate transaction_ids are NOT filtered out, even within the same request.',
+            },
+          },
+          required: ['event_type'],
+        },
+      },
+      mode: {
+        type: 'string',
+        description:
+          'If set to "replace", the preview will be generated as if those were the only events for the specified customer. If set to "merge", the events will be merged with any existing events for the specified customer. Defaults to "replace".',
+        enum: ['replace', 'merge'],
+      },
+      skip_zero_qty_line_items: {
+        type: 'boolean',
+        description: 'If set, all zero quantity line items will be filtered out of the response.',
+      },
+    },
+    required: ['customer_id', 'events'],
+  },
+  annotations: {},
+};
+
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
+  const body = args as any;
+  return asTextContentResult(await client.v1.customers.previewEvents(body));
+};
+
+export default { metadata, tool, handler };

package/src/tools/v1/customers/retrieve-v1-customers.ts

@@ -1,7 +1,9 @@
 // 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 type { Metadata } from '../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -15,20 +17,31 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'retrieve_v1_customers',
-  description: 'Get a customer by Metronome ID.',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nGet a customer by Metronome ID.\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/customer_detail'\n    }\n  },\n  required: [    'data'\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        },\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```",
   inputSchema: {
     type: 'object',
     properties: {
       customer_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'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.customers.retrieve(body);
+  return asTextContentResult(await maybeFilter(args, await client.v1.customers.retrieve(body)));
 };
 
 export default { metadata, tool, handler };

package/src/tools/v1/customers/set-ingest-aliases-v1-customers.ts

@@ -1,7 +1,8 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { Metadata, asTextContentResult } from '@metronome/mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -16,7 +17,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'set_ingest_aliases_v1_customers',
   description:
-    'Sets the ingest aliases for a customer. Ingest aliases can be used in the `customer_id` field when sending usage events to Metronome. This call is idempotent. It fully replaces the set of ingest aliases for the given customer.\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\nSets the ingest aliases for a customer. Ingest aliases can be used in the `customer_id` field when sending usage events to Metronome. This call is idempotent. It fully replaces the set of ingest aliases for the given customer.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {}\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -29,13 +30,22 @@ export const tool: Tool = {
           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', 'ingest_aliases'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.customers.setIngestAliases(body);
+  const response = await client.v1.customers.setIngestAliases(body).asResponse();
+  return asTextContentResult(await response.text());
 };
 
 export default { metadata, tool, handler };

package/src/tools/v1/customers/set-name-v1-customers.ts

@@ -1,7 +1,9 @@
 // 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 type { Metadata } from '../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -15,7 +17,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'set_name_v1_customers',
-  description: "Updates the specified customer's name.\n",
+  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\nUpdates the specified customer's name.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      $ref: '#/$defs/customer'\n    }\n  },\n  required: [    'data'\n  ],\n  $defs: {\n    customer: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'the Metronome ID of the customer'\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        custom_fields: {\n          type: 'object'\n        }\n      },\n      required: [        'id',\n        'external_id',\n        'ingest_aliases',\n        'name'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -27,13 +30,21 @@ export const tool: Tool = {
         description:
           'The new name for the customer. This will be truncated to 160 characters if the provided name is longer.',
       },
+      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', 'name'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.customers.setName(body);
+  return asTextContentResult(await maybeFilter(args, await client.v1.customers.setName(body)));
 };
 
 export default { metadata, tool, handler };

package/src/tools/v1/customers/update-config-v1-customers.ts

@@ -1,7 +1,8 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { Metadata, asTextContentResult } from '@metronome/mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -15,7 +16,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'update_config_v1_customers',
-  description: "Updates the specified customer's config.\n",
+  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\nUpdates the specified customer's config.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {}\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -31,13 +33,22 @@ export const tool: Tool = {
         type: 'string',
         description: 'The Salesforce account ID for the customer',
       },
+      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'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.customers.updateConfig(body);
+  const response = await client.v1.customers.updateConfig(body).asResponse();
+  return asTextContentResult(await response.text());
 };
 
 export default { metadata, tool, handler };

package/src/tools/v1/dashboards/get-embeddable-url-v1-dashboards.ts

@@ -1,7 +1,9 @@
 // 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 type { Metadata } from '../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -16,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'get_embeddable_url_v1_dashboards',
   description:
-    'Retrieve an embeddable dashboard url for a customer.  The dashboard can be embedded using an iframe in a website.  This will show information such as usage data and customer invoices.',
+    "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 an embeddable dashboard url for a customer.  The dashboard can be embedded using an iframe in a website.  This will show information such as usage data and customer invoices.\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    data: {\n      type: 'object',\n      properties: {\n        url: {\n          type: 'string'\n        }\n      }\n    }\n  },\n  required: [    'data'\n  ]\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -26,7 +28,7 @@ export const tool: Tool = {
       dashboard: {
         type: 'string',
         description: 'The type of dashboard to retrieve.',
-        enum: ['invoices', 'usage', 'credits'],
+        enum: ['invoices', 'usage', 'credits', 'commits_and_credits'],
       },
       bm_group_key_overrides: {
         type: 'array',
@@ -87,7 +89,6 @@ export const tool: Tool = {
               description: 'Hex value representation of the color',
             },
           },
-          required: [],
         },
       },
       dashboard_options: {
@@ -108,13 +109,21 @@ export const tool: Tool = {
           required: ['key', 'value'],
         },
       },
+      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', 'dashboard'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.dashboards.getEmbeddableURL(body);
+  return asTextContentResult(await maybeFilter(args, await client.v1.dashboards.getEmbeddableURL(body)));
 };
 
 export default { metadata, tool, handler };

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

@@ -1,7 +1,9 @@
 // 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 type { Metadata } from '../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -15,7 +17,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'regenerate_v1_invoices',
-  description: 'Regenerate a voided contract invoice',
+  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\nRegenerate a voided contract invoice\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```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -23,13 +26,21 @@ export const tool: Tool = {
         type: 'string',
         description: 'The invoice id to regenerate',
       },
+      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: ['id'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.invoices.regenerate(body);
+  return asTextContentResult(await maybeFilter(args, await client.v1.invoices.regenerate(body)));
 };
 
 export default { metadata, tool, handler };

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

@@ -1,7 +1,9 @@
 // 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 type { Metadata } from '../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -15,7 +17,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'void_v1_invoices',
-  description: 'Void an invoice',
+  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\nVoid an invoice\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```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -23,13 +26,21 @@ export const tool: Tool = {
         type: 'string',
         description: 'The invoice id to void',
       },
+      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: ['id'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.invoices.void(body);
+  return asTextContentResult(await maybeFilter(args, await client.v1.invoices.void(body)));
 };
 
 export default { metadata, tool, handler };

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

@@ -1,7 +1,9 @@
 // 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 type { Metadata } from '../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -15,20 +17,31 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'get_details_v1_plans',
-  description: 'Fetch high level details of a specific plan.',
+  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        },\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: {
       plan_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: ['plan_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.plans.getDetails(body);
+  return asTextContentResult(await maybeFilter(args, await client.v1.plans.getDetails(body)));
 };
 
 export default { metadata, tool, handler };

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

@@ -1,7 +1,9 @@
 // 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 type { Metadata } from '../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -15,7 +17,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'list_charges_v1_plans',
-  description: 'Fetches a list of charges of a specific plan.',
+  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          },\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```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -30,13 +33,24 @@ export const tool: Tool = {
         type: 'string',
         description: 'Cursor that indicates where the next page of results should start.',
       },
+      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: ['plan_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.plans.listCharges(body);
+  const response = await client.v1.plans.listCharges(body).asResponse();
+  return asTextContentResult(await maybeFilter(args, await response.json()));
 };
 
 export default { metadata, tool, handler };

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

@@ -1,7 +1,9 @@
 // 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 type { Metadata } from '../../';
 import Metronome from '@metronome/sdk';
 
 export const metadata: Metadata = {
@@ -16,7 +18,7 @@ export const metadata: Metadata = {
 export const tool: Tool = {
   name: 'list_customers_v1_plans',
   description:
-    'Fetches a list of customers on a specific plan (by default, only currently active plans are included)',
+    "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              },\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        },\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```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -37,13 +39,24 @@ export const tool: Tool = {
           "Status of customers on a given plan. Defaults to `active`.\n\n* `all` - Return current, past, and upcoming customers of the plan.\n* `active` - Return current customers of the plan.\n* `ended` - Return past customers of the plan.\n* `upcoming` - Return upcoming customers of the plan.\n\nMultiple statuses can be OR'd together using commas, e.g. `active,ended`.\n**Note:** `ended,upcoming` combination is not yet supported.",
         enum: ['all', 'active', 'ended', 'upcoming'],
       },
+      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: ['plan_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Metronome, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Metronome, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.v1.plans.listCustomers(body);
+  const response = await client.v1.plans.listCustomers(body).asResponse();
+  return asTextContentResult(await maybeFilter(args, await response.json()));
 };
 
 export default { metadata, tool, handler };