@flexprice/mcp-server 2.0.10 → 2.0.12

package/bin/mcp-server.js

@@ -50445,9 +50445,9 @@ var init_config = __esm(() => {
   SDK_METADATA = {
     language: "typescript",
     openapiDocVersion: "1.0",
-    sdkVersion: "2.0.10",
-    genVersion: "2.866.2",
-    userAgent: "speakeasy-sdk/mcp-typescript 2.0.10 2.866.2 1.0 @flexprice/mcp-server"
+    sdkVersion: "2.0.12",
+    genVersion: "2.869.23",
+    userAgent: "speakeasy-sdk/mcp-typescript 2.0.12 2.869.23 1.0 @flexprice/mcp-server"
   };
 });
 
@@ -51334,6 +51334,21 @@ function createRegisterResourceTemplate(logger, server, getSDK, allowedScopes) {
 var init_resources = () => {};
 
 // src/mcp-server/tools.ts
+function buildAnnotationFilter(annotations) {
+  const filter = {};
+  if (!annotations || annotations.length === 0) {
+    return filter;
+  }
+  for (const a of annotations) {
+    if (!VALID_ANNOTATIONS.includes(a)) {
+      throw new Error(`Invalid annotation filter: "${a}". Valid values are: ${VALID_ANNOTATIONS.join(", ")}`);
+    }
+  }
+  for (const name of VALID_ANNOTATIONS) {
+    filter[annotationToKey[name]] = annotations.includes(name);
+  }
+  return filter;
+}
 async function formatResult(response) {
   let content = [];
   const contentType = response?.headers.get("content-type") ?? "";
@@ -51349,7 +51364,7 @@ async function formatResult(response) {
   }
   return response.ok ? { content } : { content, isError: true };
 }
-function createRegisterTool(logger, server, getSDK, allowedScopes, allowedTools, dynamic) {
+function createRegisterTool(logger, server, getSDK, allowedScopes, allowedTools, dynamic, annotationFilter) {
   const tools = [];
   const toolMap = new Map;
   const registerTool = (tool) => {
@@ -51363,6 +51378,21 @@ function createRegisterTool(logger, server, getSDK, allowedScopes, allowedTools,
     if (allowedScopes.size > 0 && !scopes.every((s) => allowedScopes.has(s))) {
       return;
     }
+    if (annotationFilter) {
+      const a = tool.annotations;
+      if (annotationFilter.readOnlyHint !== undefined && a.readOnlyHint !== annotationFilter.readOnlyHint) {
+        return;
+      }
+      if (annotationFilter.destructiveHint !== undefined && a.destructiveHint !== annotationFilter.destructiveHint) {
+        return;
+      }
+      if (annotationFilter.idempotentHint !== undefined && a.idempotentHint !== annotationFilter.idempotentHint) {
+        return;
+      }
+      if (annotationFilter.openWorldHint !== undefined && a.openWorldHint !== annotationFilter.openWorldHint) {
+        return;
+      }
+    }
     toolMap.set(tool.name, tool);
     if (dynamic) {
       logger.debug("Collected tool for dynamic mode", { name: tool.name });
@@ -51591,11 +51621,24 @@ function buildSDK(headers, cliFlags, disableStaticAuth, logger) {
     } : undefined
   });
 }
+var VALID_ANNOTATIONS, annotationToKey;
 var init_tools = __esm(() => {
   init_zod();
   init_core3();
   init_scopes();
   init_shared();
+  VALID_ANNOTATIONS = [
+    "readOnly",
+    "destructive",
+    "idempotent",
+    "openWorld"
+  ];
+  annotationToKey = {
+    readOnly: "readOnlyHint",
+    destructive: "destructiveHint",
+    idempotent: "idempotentHint",
+    openWorld: "openWorldHint"
+  };
 });
 
 // src/lib/primitives.ts
@@ -51793,8 +51836,8 @@ var init_dtointegrationentitymapping = __esm(() => {
     "paypal"
   ]).describe('provider is the integration provider name (e.g., "stripe", "razorpay")');
   DtoIntegrationEntityMapping$zodSchema = object({
-    id: string2(),
-    provider: Provider$zodSchema
+    id: string2().describe("id is the external entity ID from the provider"),
+    provider: Provider$zodSchema.describe('provider is the integration provider name (e.g., "stripe", "razorpay")')
   }).describe("Integration entity mapping for external provider systems");
 });
 
@@ -51818,21 +51861,27 @@ var init_dtocreatecustomerrequest = __esm(() => {
   init_dtointegrationentitymapping();
   init_dtotaxrateoverride();
   DtoCreateCustomerRequest$zodSchema = object({
-    address_city: string2().optional(),
-    address_country: string2().optional(),
-    address_line1: string2().optional(),
-    address_line2: string2().optional(),
-    address_postal_code: string2().optional(),
-    address_state: string2().optional(),
-    email: string2().optional(),
-    external_id: string2(),
-    integration_entity_mapping: array(DtoIntegrationEntityMapping$zodSchema).optional(),
-    metadata: record(string2(), string2()).optional(),
-    name: string2().optional(),
-    parent_customer_external_id: string2().optional(),
-    parent_customer_id: string2().optional(),
-    skip_onboarding_workflow: boolean2().optional(),
-    tax_rate_overrides: array(DtoTaxRateOverride$zodSchema).optional()
+    address_city: string2().optional().describe("address_city is the city name with maximum 100 characters"),
+    address_country: string2().optional().describe("address_country is the two-letter ISO 3166-1 alpha-2 country code"),
+    address_line1: string2().optional().describe("address_line1 is the primary address line with maximum 255 characters"),
+    address_line2: string2().optional().describe("address_line2 is the secondary address line with maximum 255 characters"),
+    address_postal_code: string2().optional().describe("address_postal_code is the ZIP code or postal code with maximum 20 characters"),
+    address_state: string2().optional().describe("address_state is the state, province, or region name with maximum 100 characters"),
+    email: string2().optional().describe("email is the customer's email address and must be a valid email format if provided"),
+    external_id: string2().describe("external_id is the unique identifier from your system to reference this customer (required)"),
+    integration_entity_mapping: array(DtoIntegrationEntityMapping$zodSchema).optional().describe("integration_entity_mapping contains provider integration mappings for this customer"),
+    metadata: record(string2(), string2()).optional().describe("metadata contains additional key-value pairs for storing extra information"),
+    name: string2().optional().describe("name is the full name or company name of the customer"),
+    parent_customer_external_id: string2().optional().describe(`Deprecated: See ParentCustomerID.
+parent_customer_external_id is the external ID of the parent customer from your system.
+Exactly one of parent_customer_id or parent_customer_external_id may be provided.`),
+    parent_customer_id: string2().optional().describe(`Deprecated: Customer parent hierarchy is deprecated in favor of subscription-level hierarchy.
+This field is accepted for backward compatibility but no hierarchy validations are enforced.
+parent_customer_id is the internal FlexPrice ID of the parent customer.`),
+    skip_onboarding_workflow: boolean2().optional().describe(`skip_onboarding_workflow when true, prevents the customer onboarding workflow from being triggered
+This is used internally when a customer is created via a workflow to prevent infinite loops
+Default: false`),
+    tax_rate_overrides: array(DtoTaxRateOverride$zodSchema).optional().describe("tax_rate_overrides contains tax rate configurations to be linked to this customer")
   }).describe("Request object for creating a new customer in the system");
 });
 
@@ -51942,7 +51991,7 @@ var init_customersCreateCustomer2 = __esm(() => {
   init_dtocreatecustomerrequest();
   init_tools();
   args = {
-    request: DtoCreateCustomerRequest$zodSchema
+    request: DtoCreateCustomerRequest$zodSchema.describe(`Customer`)
   };
   tool$customersCreateCustomer = {
     name: "create-customer",
@@ -52111,22 +52160,24 @@ var init_dtocustomerresponse = __esm(() => {
   init_zod();
   init_status();
   DtoCustomerResponse$zodSchema = object({
-    address_city: string2().optional(),
-    address_country: string2().optional(),
-    address_line1: string2().optional(),
-    address_line2: string2().optional(),
-    address_postal_code: string2().optional(),
-    address_state: string2().optional(),
+    address_city: string2().optional().describe("AddressCity is the city of the customer's address"),
+    address_country: string2().optional().describe("AddressCountry is the country of the customer's address (ISO 3166-1 alpha-2)"),
+    address_line1: string2().optional().describe("AddressLine1 is the first line of the customer's address"),
+    address_line2: string2().optional().describe("AddressLine2 is the second line of the customer's address"),
+    address_postal_code: string2().optional().describe("AddressPostalCode is the postal code of the customer's address"),
+    address_state: string2().optional().describe("AddressState is the state of the customer's address"),
     created_at: string2().optional(),
     created_by: string2().optional(),
-    email: string2().optional(),
-    environment_id: string2().optional(),
-    external_id: string2().optional(),
-    id: string2().optional(),
-    metadata: record(string2(), string2()).optional(),
-    name: string2().optional(),
-    parent_customer: lazy(() => DtoCustomerResponse$zodSchema).optional(),
-    parent_customer_id: string2().optional(),
+    email: string2().optional().describe("Email is the email of the customer"),
+    environment_id: string2().optional().describe("EnvironmentID is the environment identifier for the customer"),
+    external_id: string2().optional().describe("ExternalID is the external identifier for the customer"),
+    id: string2().optional().describe("ID is the unique identifier for the customer"),
+    metadata: record(string2(), string2()).optional().describe("Metadata"),
+    name: string2().optional().describe("Name is the name of the customer"),
+    parent_customer: lazy(() => DtoCustomerResponse$zodSchema).optional().describe("Customer response object containing all customer information"),
+    parent_customer_id: string2().optional().describe(`Deprecated: Customer parent hierarchy is deprecated in favor of subscription-level hierarchy.
+Retained for backward compatibility; no hierarchy rules are enforced at the service layer.
+ParentCustomerID is the parent customer identifier for the customer.`),
     status: Status$zodSchema.optional(),
     tenant_id: string2().optional(),
     updated_at: string2().optional(),
@@ -52436,7 +52487,7 @@ var init_dtoaggregatedentitlement = __esm(() => {
   DtoAggregatedEntitlement$zodSchema = object({
     is_enabled: boolean2().optional(),
     is_soft_limit: boolean2().optional(),
-    static_values: array(string2()).optional(),
+    static_values: array(string2()).optional().describe("For static/SLA features"),
     usage_limit: int().optional(),
     usage_reset_period: EntitlementUsageResetPeriod$zodSchema.optional()
   });
@@ -52559,7 +52610,6 @@ var WindowSize$zodSchema;
 var init_windowsize = __esm(() => {
   init_zod();
   WindowSize$zodSchema = _enum([
-    "MONTH",
     "MINUTE",
     "15MIN",
     "30MIN",
@@ -52568,7 +52618,8 @@ var init_windowsize = __esm(() => {
     "6HOUR",
     "12HOUR",
     "DAY",
-    "WEEK"
+    "WEEK",
+    "MONTH"
   ]);
 });
 
@@ -52580,10 +52631,18 @@ var init_meteraggregation = __esm(() => {
   init_windowsize();
   MeterAggregation$zodSchema = object({
     bucket_size: WindowSize$zodSchema.optional(),
-    expression: string2().optional(),
-    field: string2().optional(),
-    group_by: string2().optional(),
-    multiplier: string2().optional(),
+    expression: string2().optional().describe(`Expression is an optional CEL expression to compute per-event quantity from event.properties.
+When set, it replaces Field-based extraction. Property names are used directly (e.g., token * duration * pixel).`),
+    field: string2().optional().describe(`Field is the key in $event.properties on which the aggregation is to be applied
+For ex if the aggregation type is sum for API usage, the field could be "duration_ms"
+Ignored when Expression is set.`),
+    group_by: string2().optional().describe(`GroupBy is the property name in event.properties to group by before aggregating.
+Currently only supported for MAX aggregation with bucket_size.
+When set, aggregation is applied per unique value of this property within each bucket,
+then the per-group results are summed to produce the bucket total.`),
+    multiplier: string2().optional().describe(`Multiplier is the multiplier for the aggregation
+For ex if the aggregation type is sum_with_multiplier for API usage, the multiplier could be 1000
+to scale up by a factor of 1000. If not provided, it will be null.`),
     type: AggregationType$zodSchema.optional()
   });
 });
@@ -52593,8 +52652,10 @@ var MeterFilter$zodSchema;
 var init_meterfilter = __esm(() => {
   init_zod();
   MeterFilter$zodSchema = object({
-    key: string2().optional(),
-    values: array(string2()).optional()
+    key: string2().optional().describe(`Key is the key for the filter from $event.properties
+Currently we support only first level keys in the properties and not nested keys`),
+    values: array(string2()).optional().describe(`Values are the possible values for the filter to be considered for the meter
+For ex "model_name" could have values "o1-mini", "gpt-4o" etc`)
   });
 });
 
@@ -52645,9 +52706,9 @@ var ReportingUnit$zodSchema;
 var init_reportingunit = __esm(() => {
   init_zod();
   ReportingUnit$zodSchema = object({
-    conversion_rate: number2().optional(),
-    unit_plural: string2().optional(),
-    unit_singular: string2().optional()
+    conversion_rate: number2().optional().describe("Multiplier: reporting_unit_value = unit_value * conversion_rate; must be > 0"),
+    unit_plural: string2().optional().describe('Display unit label, plural (e.g. "seconds")'),
+    unit_singular: string2().optional().describe('Display unit label, singular (e.g. "second")')
   });
 });
 
@@ -53070,7 +53131,7 @@ var init_dtobillingperiodinfo = __esm(() => {
   init_zod();
   DtoBillingPeriodInfo$zodSchema = object({
     end_time: string2().optional(),
-    period: string2().optional(),
+    period: string2().optional().describe('e.g., "monthly", "yearly"'),
     start_time: string2().optional()
   });
 });
@@ -53432,7 +53493,7 @@ var init_customersQueryCustomer2 = __esm(() => {
   init_customerfilter();
   init_tools();
   args8 = {
-    request: CustomerFilter$zodSchema
+    request: CustomerFilter$zodSchema.describe(`Filter`)
   };
   tool$customersQueryCustomer = {
     name: "query-customer",
@@ -53467,19 +53528,24 @@ var init_dtoupdatecustomerrequest = __esm(() => {
   init_zod();
   init_dtointegrationentitymapping();
   DtoUpdateCustomerRequest$zodSchema = object({
-    address_city: string2().optional(),
-    address_country: string2().optional(),
-    address_line1: string2().optional(),
-    address_line2: string2().optional(),
-    address_postal_code: string2().optional(),
-    address_state: string2().optional(),
-    email: string2().optional(),
-    external_id: string2().optional(),
-    integration_entity_mapping: array(DtoIntegrationEntityMapping$zodSchema).optional(),
-    metadata: record(string2(), string2()).optional(),
-    name: string2().optional(),
-    parent_customer_external_id: string2().optional(),
-    parent_customer_id: string2().optional()
+    address_city: string2().optional().describe("address_city is the updated city name with maximum 100 characters"),
+    address_country: string2().optional().describe("address_country is the updated two-letter ISO 3166-1 alpha-2 country code"),
+    address_line1: string2().optional().describe("address_line1 is the updated primary address line with maximum 255 characters"),
+    address_line2: string2().optional().describe("address_line2 is the updated secondary address line with maximum 255 characters"),
+    address_postal_code: string2().optional().describe("address_postal_code is the updated postal code with maximum 20 characters"),
+    address_state: string2().optional().describe("address_state is the updated state, province, or region name with maximum 100 characters"),
+    email: string2().optional().describe("email is the updated email address and must be a valid email format if provided"),
+    external_id: string2().optional().describe("external_id is the updated external identifier for the customer"),
+    integration_entity_mapping: array(DtoIntegrationEntityMapping$zodSchema).optional().describe("integration_entity_mapping contains provider integration mappings for this customer"),
+    metadata: record(string2(), string2()).optional().describe("metadata contains updated key-value pairs that will replace existing metadata"),
+    name: string2().optional().describe("name is the updated name or company name for the customer"),
+    parent_customer_external_id: string2().optional().describe(`Deprecated: See ParentCustomerID.
+parent_customer_external_id is the external ID of the parent customer from your system.
+Exactly one of parent_customer_id or parent_customer_external_id may be provided.
+If you provide the external ID, the parent customer value will be ignored.`),
+    parent_customer_id: string2().optional().describe(`Deprecated: Customer parent hierarchy is deprecated in favor of subscription-level hierarchy.
+This field is accepted for backward compatibility but no hierarchy validations are enforced.
+parent_customer_id is the internal FlexPrice ID of the parent customer.`)
   }).describe("Request object for updating an existing customer. All fields are optional - only provided fields will be updated");
 });
 
@@ -53491,7 +53557,7 @@ var init_updatecustomerop = __esm(() => {
   init_dtoupdatecustomerrequest();
   init_errorserrorresponse();
   UpdateCustomerRequest$zodSchema = object({
-    body: DtoUpdateCustomerRequest$zodSchema,
+    body: DtoUpdateCustomerRequest$zodSchema.describe("Customer"),
     external_customer_id: string2().describe("Customer External ID").optional(),
     id: string2().describe("Customer ID").optional()
   });
@@ -53633,21 +53699,23 @@ var init_githubcomflexpriceflexpriceinternaldomaincustomercustomer = __esm(() =>
   init_zod();
   init_status();
   GithubComFlexpriceFlexpriceInternalDomainCustomerCustomer$zodSchema = object({
-    address_city: string2().optional(),
-    address_country: string2().optional(),
-    address_line1: string2().optional(),
-    address_line2: string2().optional(),
-    address_postal_code: string2().optional(),
-    address_state: string2().optional(),
+    address_city: string2().optional().describe("AddressCity is the city of the customer's address"),
+    address_country: string2().optional().describe("AddressCountry is the country of the customer's address (ISO 3166-1 alpha-2)"),
+    address_line1: string2().optional().describe("AddressLine1 is the first line of the customer's address"),
+    address_line2: string2().optional().describe("AddressLine2 is the second line of the customer's address"),
+    address_postal_code: string2().optional().describe("AddressPostalCode is the postal code of the customer's address"),
+    address_state: string2().optional().describe("AddressState is the state of the customer's address"),
     created_at: string2().optional(),
     created_by: string2().optional(),
-    email: string2().optional(),
-    environment_id: string2().optional(),
-    external_id: string2().optional(),
-    id: string2().optional(),
-    metadata: record(string2(), string2()).optional(),
-    name: string2().optional(),
-    parent_customer_id: string2().optional(),
+    email: string2().optional().describe("Email is the email of the customer"),
+    environment_id: string2().optional().describe("EnvironmentID is the environment identifier for the customer"),
+    external_id: string2().optional().describe("ExternalID is the external identifier for the customer"),
+    id: string2().optional().describe("ID is the unique identifier for the customer"),
+    metadata: record(string2(), string2()).optional().describe("Metadata"),
+    name: string2().optional().describe("Name is the name of the customer"),
+    parent_customer_id: string2().optional().describe(`Deprecated: Customer parent hierarchy is deprecated in favor of subscription-level hierarchy.
+Retained for backward compatibility; no hierarchy rules are enforced at the service layer.
+ParentCustomerID is the parent customer identifier for the customer.`),
     status: Status$zodSchema.optional(),
     tenant_id: string2().optional(),
     updated_at: string2().optional(),
@@ -53681,11 +53749,14 @@ var init_metermeter = __esm(() => {
     aggregation: MeterAggregation$zodSchema.optional(),
     created_at: string2().optional(),
     created_by: string2().optional(),
-    environment_id: string2().optional(),
-    event_name: string2().optional(),
-    filters: array(MeterFilter$zodSchema).optional(),
-    id: string2().optional(),
-    name: string2().optional(),
+    environment_id: string2().optional().describe("EnvironmentID is the environment identifier for the meter"),
+    event_name: string2().optional().describe(`EventName is the unique identifier for the event that this meter is tracking
+It is a mandatory field in the events table and hence being used as the primary matching field
+We can have multiple meters tracking the same event but with different filters and aggregation`),
+    filters: array(MeterFilter$zodSchema).optional().describe(`Filters define the criteria for the meter to be applied on the events before aggregation
+It also defines the possible values on which later the charges will be applied`),
+    id: string2().optional().describe("ID is the unique identifier for the meter"),
+    name: string2().optional().describe("Name is the display name of the meter"),
     reset_usage: ResetUsage$zodSchema.optional(),
     status: Status$zodSchema.optional(),
     tenant_id: string2().optional(),
@@ -53790,7 +53861,7 @@ var init_pricejsonbtransformquantity = __esm(() => {
   init_zod();
   init_roundtype();
   PriceJSONBTransformQuantity$zodSchema = object({
-    divide_by: int().optional(),
+    divide_by: int().optional().describe("Divide quantity by this number"),
     round: RoundType$zodSchema.optional()
   });
 });
@@ -53800,9 +53871,13 @@ var PricePriceTier$zodSchema;
 var init_pricepricetier = __esm(() => {
   init_zod();
   PricePriceTier$zodSchema = object({
-    flat_amount: string2().optional(),
-    unit_amount: string2().optional(),
-    up_to: int().optional()
+    flat_amount: string2().optional().describe(`flat_amount is the flat amount for the given tier (optional)
+Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c"`),
+    unit_amount: string2().optional().describe("unit_amount is the amount per unit for the given tier"),
+    up_to: int().optional().describe(`up_to is the quantity up to which this tier applies. It is null for the last tier.
+IMPORTANT: Tier boundaries are INCLUSIVE.
+- If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier
+- This behavior is consistent across both VOLUME and SLAB tier modes`)
   });
 });
 
@@ -53842,43 +53917,46 @@ var init_priceprice = __esm(() => {
   init_priceunittype();
   init_status();
   PricePrice$zodSchema = object({
-    amount: string2().optional(),
+    amount: string2().optional().describe(`Amount stored in main currency units (e.g., dollars, not cents)
+For USD: 12.50 means $12.50`),
     billing_cadence: BillingCadence$zodSchema.optional(),
     billing_model: BillingModel$zodSchema.optional(),
     billing_period: BillingPeriod$zodSchema.optional(),
-    billing_period_count: int().optional(),
-    conversion_rate: string2().optional(),
+    billing_period_count: int().optional().describe("BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12"),
+    conversion_rate: string2().optional().describe("ConversionRate is the conversion rate of the price unit to the fiat currency"),
     created_at: string2().optional(),
     created_by: string2().optional(),
-    currency: string2().optional(),
-    description: string2().optional(),
-    display_amount: string2().optional(),
-    display_name: string2().optional(),
-    display_price_unit_amount: string2().optional(),
-    end_date: string2().optional(),
-    entity_id: string2().optional(),
+    currency: string2().optional().describe("Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp"),
+    description: string2().optional().describe("Description of the price"),
+    display_amount: string2().optional().describe(`DisplayAmount is the formatted amount with currency symbol
+For USD: $12.50`),
+    display_name: string2().optional().describe("DisplayName is the name of the price"),
+    display_price_unit_amount: string2().optional().describe("DisplayPriceUnitAmount is the formatted amount of the price unit"),
+    end_date: string2().optional().describe("EndDate is the end date of the price"),
+    entity_id: string2().optional().describe('EntityID holds the value of the "entity_id" field.'),
     entity_type: PriceEntityType$zodSchema.optional(),
-    environment_id: string2().optional(),
-    group_id: string2().optional(),
-    id: string2().optional(),
+    environment_id: string2().optional().describe("EnvironmentID is the environment identifier for the price"),
+    group_id: string2().optional().describe("GroupID references the group this price belongs to"),
+    id: string2().optional().describe("ID uuid identifier for the price"),
     invoice_cadence: InvoiceCadence$zodSchema.optional(),
-    lookup_key: string2().optional(),
+    lookup_key: string2().optional().describe("LookupKey used for looking up the price in the database"),
     metadata: record(string2(), string2()).optional(),
-    meter_id: string2().optional(),
-    min_quantity: string2().nullable().optional(),
-    parent_price_id: string2().optional(),
-    price_unit: string2().optional(),
-    price_unit_amount: string2().optional(),
-    price_unit_id: string2().optional(),
-    price_unit_tiers: array(PricePriceTier$zodSchema).optional(),
+    meter_id: string2().optional().describe("MeterID is the id of the meter for usage based pricing"),
+    min_quantity: string2().nullable().optional().describe("MinQuantity is the minimum quantity of the price"),
+    parent_price_id: string2().optional().describe("ParentPriceID references the root price (always set for price lineage tracking)"),
+    price_unit: string2().optional().describe("PriceUnit is the code of the price unit (e.g., 'btc', 'eth')"),
+    price_unit_amount: string2().optional().describe("PriceUnitAmount is the amount of the price unit"),
+    price_unit_id: string2().optional().describe("PriceUnitID is the id of the price unit (for CUSTOM type)"),
+    price_unit_tiers: array(PricePriceTier$zodSchema).optional().describe("PriceUnitTiers are the tiers for the price unit when BillingModel is TIERED"),
     price_unit_type: PriceUnitType$zodSchema.optional(),
-    start_date: string2().optional(),
+    start_date: string2().optional().describe("StartDate is the start date of the price"),
     status: Status$zodSchema.optional(),
     tenant_id: string2().optional(),
     tier_mode: BillingTier$zodSchema.optional(),
     tiers: array(PricePriceTier$zodSchema).optional(),
     transform_quantity: PriceJSONBTransformQuantity$zodSchema.optional(),
-    trial_period: int().optional(),
+    trial_period: int().optional().describe(`TrialPeriod is the number of days for the trial period
+Note: This is only applicable for recurring prices (BILLING_CADENCE_RECURRING)`),
     type: PriceType$zodSchema.optional(),
     updated_at: string2().optional(),
     updated_by: string2().optional()
@@ -53946,8 +54024,8 @@ var init_subscriptionsubscriptionlineitem = __esm(() => {
   init_subscriptionlineitementitytype();
   SubscriptionSubscriptionLineItem$zodSchema = object({
     billing_period: BillingPeriod$zodSchema.optional(),
-    billing_period_count: int().optional(),
-    commitment_amount: string2().optional(),
+    billing_period_count: int().optional().describe("from price at create; default 1"),
+    commitment_amount: string2().optional().describe("Commitment fields"),
     commitment_duration: BillingPeriod$zodSchema.optional(),
     commitment_overage_factor: string2().optional(),
     commitment_quantity: string2().optional(),
@@ -54347,11 +54425,11 @@ var init_dtogetusageanalyticsrequest = __esm(() => {
   init_windowsize();
   DtoGetUsageAnalyticsRequest$zodSchema = object({
     end_time: string2().optional(),
-    expand: array(string2()).optional(),
+    expand: array(string2()).optional().describe('allowed values: "price", "meter", "feature", "subscription_line_item","plan","addon"'),
     external_customer_id: string2(),
     feature_ids: array(string2()).optional(),
-    group_by: array(string2()).optional(),
-    property_filters: record(string2(), array(string2())).optional(),
+    group_by: array(string2()).optional().describe('allowed values: "source", "feature_id", "properties.<field_name>"'),
+    property_filters: record(string2(), array(string2())).optional().describe("Property filters to filter the events by the keys in `properties` field of the event"),
     sources: array(string2()).optional(),
     start_time: string2().optional(),
     window_size: WindowSize$zodSchema.optional()
@@ -54438,7 +54516,7 @@ var init_eventsGetUsageAnalytics2 = __esm(() => {
   init_dtogetusageanalyticsrequest();
   init_tools();
   args11 = {
-    request: DtoGetUsageAnalyticsRequest$zodSchema
+    request: DtoGetUsageAnalyticsRequest$zodSchema.describe(`Request body`)
   };
   tool$eventsGetUsageAnalytics = {
     name: "get-usage-analytics",
@@ -54473,7 +54551,22 @@ var init_dtogetusagebymeterrequest = __esm(() => {
   init_zod();
   init_windowsize();
   DtoGetUsageByMeterRequest$zodSchema = object({
-    billing_anchor: string2().optional(),
+    billing_anchor: string2().optional().describe(`BillingAnchor enables custom monthly billing periods for meter usage aggregation.
+
+Usage guidelines:
+- Only effective when WindowSize = "MONTH"
+- For other window sizes (DAY, HOUR, WEEK), this field is ignored
+- When nil, uses standard calendar months (1st to 1st)
+- When provided, creates custom monthly periods (e.g., 5th to 5th)
+
+Common use cases:
+- Subscription billing periods that don't align with calendar months
+- Customer-specific billing cycles (e.g., signed up on 15th)
+- Multi-tenant systems with different billing anchor dates
+
+Example: If BillingAnchor = "2024-03-05T14:30:45Z" and WindowSize = "MONTH":
+  - March period: 2024-03-05 14:30:45 to 2024-04-05 14:30:45
+  - April period: 2024-04-05 14:30:45 to 2024-05-05 14:30:45`),
     bucket_size: WindowSize$zodSchema.optional(),
     customer_id: string2().optional(),
     end_time: string2().optional(),
@@ -54565,7 +54658,7 @@ var init_eventsGetUsageByMeter2 = __esm(() => {
   init_dtogetusagebymeterrequest();
   init_tools();
   args12 = {
-    request: DtoGetUsageByMeterRequest$zodSchema
+    request: DtoGetUsageByMeterRequest$zodSchema.describe(`Request body`)
   };
   tool$eventsGetUsageByMeter = {
     name: "get-usage-by-meter",
@@ -54602,16 +54695,32 @@ var init_dtogetusagerequest = __esm(() => {
   init_windowsize();
   DtoGetUsageRequest$zodSchema = object({
     aggregation_type: AggregationType$zodSchema,
-    billing_anchor: string2().optional(),
+    billing_anchor: string2().optional().describe(`BillingAnchor enables custom monthly billing periods for usage aggregation.
+
+When to use:
+- WindowSize = "MONTH" AND you need custom monthly periods (not calendar months)
+- Subscription billing that doesn't align with calendar months
+- Example: Customer signed up on 15th, so billing periods are 15th to 15th
+
+When NOT to use:
+- WindowSize != "MONTH" (ignored for DAY, HOUR, WEEK, etc.)
+- Standard calendar-based billing (1st to 1st of each month)
+
+Example values:
+- "2024-03-05T14:30:45.123456789Z" (5th of each month at 2:30:45 PM)
+- "2024-01-15T00:00:00Z" (15th of each month at midnight)
+- "2024-02-29T12:00:00Z" (29th of each month at noon - handles leap years)`),
     bucket_size: WindowSize$zodSchema.optional(),
     customer_id: string2().optional(),
     end_time: string2().optional(),
     event_name: string2(),
     external_customer_id: string2().optional(),
     filters: record(string2(), array(string2())).optional(),
-    group_by_property: string2().optional(),
+    group_by_property: string2().optional().describe(`GroupByProperty is the property name in event.properties to group by before aggregating.
+When set, aggregation is applied per unique value of this property within each bucket,
+then the per-group results are summed to produce the bucket total.`),
     multiplier: string2().optional(),
-    property_name: string2().optional(),
+    property_name: string2().optional().describe("will be empty/ignored in case of COUNT"),
     start_time: string2().optional(),
     window_size: WindowSize$zodSchema.optional()
   });
@@ -54697,7 +54806,7 @@ var init_eventsGetUsageStatistics2 = __esm(() => {
   init_dtogetusagerequest();
   init_tools();
   args13 = {
-    request: DtoGetUsageRequest$zodSchema
+    request: DtoGetUsageRequest$zodSchema.describe(`Request body`)
   };
   tool$eventsGetUsageStatistics = {
     name: "get-usage-statistics",
@@ -54735,9 +54844,9 @@ var init_dtoingesteventrequest = __esm(() => {
     event_id: string2().optional(),
     event_name: string2(),
     external_customer_id: string2(),
-    properties: record(string2(), string2()).optional(),
+    properties: record(string2(), string2()).optional().describe("Handled separately for dynamic columns"),
     source: string2().optional(),
-    timestamp: string2().optional()
+    timestamp: string2().optional().describe("Handled separately due to parsing")
   });
 });
 
@@ -54821,7 +54930,7 @@ var init_eventsIngestEvent2 = __esm(() => {
   init_dtoingesteventrequest();
   init_tools();
   args14 = {
-    request: DtoIngestEventRequest$zodSchema
+    request: DtoIngestEventRequest$zodSchema.describe(`Event data`)
   };
   tool$eventsIngestEvent = {
     name: "ingest-event",
@@ -54940,7 +55049,7 @@ var init_eventsIngestEventsBulk2 = __esm(() => {
   init_dtobulkingesteventrequest();
   init_tools();
   args15 = {
-    request: DtoBulkIngestEventRequest$zodSchema
+    request: DtoBulkIngestEventRequest$zodSchema.describe(`Event data`)
   };
   tool$eventsIngestEventsBulk = {
     name: "ingest-events-bulk",
@@ -54974,19 +55083,21 @@ var DtoGetEventsRequest$zodSchema;
 var init_dtogeteventsrequest = __esm(() => {
   init_zod();
   DtoGetEventsRequest$zodSchema = object({
-    end_time: string2().optional(),
-    event_id: string2().optional(),
-    event_name: string2().optional(),
-    external_customer_id: string2().optional(),
-    iter_first_key: string2().optional(),
-    iter_last_key: string2().optional(),
-    offset: int().optional(),
-    order: string2().optional(),
-    page_size: int().optional(),
-    property_filters: record(string2(), array(string2())).optional(),
-    sort: string2().optional(),
-    source: string2().optional(),
-    start_time: string2().optional()
+    end_time: string2().optional().describe(`End time of the events to be fetched in ISO 8601 format
+Defaults to now if not provided`),
+    event_id: string2().optional().describe("Event ID is the idempotency key for the event"),
+    event_name: string2().optional().describe("Event name / Unique identifier for the event in your system"),
+    external_customer_id: string2().optional().describe("Customer ID in your system that was sent with the event"),
+    iter_first_key: string2().optional().describe("First key to iterate over the events"),
+    iter_last_key: string2().optional().describe("Last key to iterate over the events"),
+    offset: int().optional().describe("Offset to fetch the events and is set to 0 by default"),
+    order: string2().optional().describe("Order by condition. Allowed values (case sensitive): asc, desc (default: desc)"),
+    page_size: int().optional().describe("Page size to fetch the events and is set to 50 by default"),
+    property_filters: record(string2(), array(string2())).optional().describe("Property filters to filter the events by the keys in `properties` field of the event"),
+    sort: string2().optional().describe("Sort by the field. Allowed values (case sensitive): timestamp, event_name (default: timestamp)"),
+    source: string2().optional().describe("Source to filter the events by the source"),
+    start_time: string2().optional().describe(`Start time of the events to be fetched in ISO 8601 format
+Defaults to last 7 days from now if not provided`)
   });
 });
 
@@ -55070,7 +55181,7 @@ var init_eventsListRawEvents2 = __esm(() => {
   init_dtogeteventsrequest();
   init_tools();
   args16 = {
-    request: DtoGetEventsRequest$zodSchema
+    request: DtoGetEventsRequest$zodSchema.describe(`Request body`)
   };
   tool$eventsListRawEvents = {
     name: "list-raw-events",
@@ -55247,11 +55358,11 @@ var init_commitmentinfo = __esm(() => {
     amount: string2().optional(),
     computed_commitment_utilized_amount: string2().optional(),
     computed_overage_amount: string2().optional(),
-    computed_true_up_amount: string2().optional(),
+    computed_true_up_amount: string2().optional().describe("total_cost = computed_commitment_utilized_amount + computed_overage_amount + computed_true_up_amount"),
     duration: BillingPeriod$zodSchema.optional(),
     is_windowed: boolean2().optional(),
     overage_factor: string2().optional(),
-    quantity: string2().optional(),
+    quantity: string2().optional().describe("Only used for quantity-based commitments"),
     true_up_enabled: boolean2().optional(),
     type: CommitmentType$zodSchema.optional()
   });
@@ -55263,26 +55374,27 @@ var init_dtocreateinvoicelineitemrequest = __esm(() => {
   init_zod();
   init_commitmentinfo();
   DtoCreateInvoiceLineItemRequest$zodSchema = object({
-    amount: string2(),
+    amount: string2().describe("amount is the monetary amount for this line item"),
     commitment_info: CommitmentInfo$zodSchema.optional(),
-    display_name: string2().optional(),
-    entity_id: string2().optional(),
-    entity_type: string2().optional(),
-    invoice_level_discount: string2().optional(),
-    line_item_discount: string2().optional(),
+    display_name: string2().optional().describe("display_name is the optional human-readable name for this line item"),
+    entity_id: string2().optional().describe("entity_id is the optional unique identifier of the entity associated with this line item"),
+    entity_type: string2().optional().describe("entity_type is the optional type of the entity associated with this line item"),
+    invoice_level_discount: string2().optional().describe("invoice_level_discount is the discount amount in invoice currency applied to all line items on the invoice."),
+    line_item_discount: string2().optional().describe("line_item_discount is the discount amount in invoice currency applied directly to this line item."),
     metadata: record(string2(), string2()).optional(),
-    meter_display_name: string2().optional(),
-    meter_id: string2().optional(),
-    period_end: string2().optional(),
-    period_start: string2().optional(),
-    plan_display_name: string2().optional(),
-    plan_id: string2().optional(),
-    prepaid_credits_applied: string2().optional(),
-    price_id: string2().optional(),
-    price_type: string2().optional(),
-    price_unit: string2().optional(),
-    price_unit_amount: string2().optional(),
-    quantity: string2()
+    meter_display_name: string2().optional().describe("meter_display_name is the optional human-readable name of the meter"),
+    meter_id: string2().optional().describe("meter_id is the optional unique identifier of the meter used for usage tracking"),
+    period_end: string2().optional().describe("period_end is the optional end date of the period this line item covers"),
+    period_start: string2().optional().describe("period_start is the optional start date of the period this line item covers"),
+    plan_display_name: string2().optional().describe("plan_display_name is the optional human-readable name of the plan"),
+    plan_id: string2().optional().describe(`TODO: !REMOVE after migration
+plan_id is the optional unique identifier of the plan associated with this line item`),
+    prepaid_credits_applied: string2().optional().describe("prepaid_credits_applied is the amount in invoice currency reduced from this line item due to prepaid credits application."),
+    price_id: string2().optional().describe("price_id is the optional unique identifier of the price associated with this line item"),
+    price_type: string2().optional().describe("price_type indicates the type of pricing (fixed, usage, tiered, etc.)"),
+    price_unit: string2().optional().describe("price_unit is the optional 3-digit ISO code of the price unit associated with this line item"),
+    price_unit_amount: string2().optional().describe("price_unit_amount is the optional amount converted to the price unit currency"),
+    quantity: string2().describe("quantity is the quantity of units for this line item")
   });
 });
 
@@ -55303,7 +55415,7 @@ var init_dtoinvoicelineitemcoupon = __esm(() => {
   DtoInvoiceLineItemCoupon$zodSchema = object({
     coupon_association_id: string2().optional(),
     coupon_id: string2(),
-    line_item_id: string2()
+    line_item_id: string2().describe("price_id used to match the line item")
   });
 });
 
@@ -55432,34 +55544,34 @@ var init_dtocreateinvoicerequest = __esm(() => {
   init_invoicetype();
   init_paymentstatus();
   DtoCreateInvoiceRequest$zodSchema = object({
-    amount_due: string2(),
-    amount_paid: string2().optional(),
-    billing_period: string2().optional(),
+    amount_due: string2().describe("amount_due is the total amount that needs to be paid for this invoice"),
+    amount_paid: string2().optional().describe("amount_paid is the amount that has been paid towards this invoice"),
+    billing_period: string2().optional().describe('billing_period is the period this invoice covers (e.g., "monthly", "yearly")'),
     billing_reason: InvoiceBillingReason$zodSchema.optional(),
-    coupons: array(string2()).optional(),
-    currency: string2(),
-    customer_id: string2(),
-    description: string2().optional(),
-    due_date: string2().optional(),
-    idempotency_key: string2().optional(),
-    invoice_coupons: array(DtoInvoiceCoupon$zodSchema).optional(),
-    invoice_number: string2().optional(),
-    invoice_pdf_url: string2().optional(),
+    coupons: array(string2()).optional().describe("coupons"),
+    currency: string2().describe("currency is the three-letter ISO currency code (e.g., USD, EUR) for the invoice"),
+    customer_id: string2().describe("customer_id is the unique identifier of the customer this invoice belongs to"),
+    description: string2().optional().describe("description is an optional text description of the invoice"),
+    due_date: string2().optional().describe("due_date is the date by which payment is expected"),
+    idempotency_key: string2().optional().describe("idempotency_key is an optional key used to prevent duplicate invoice creation"),
+    invoice_coupons: array(DtoInvoiceCoupon$zodSchema).optional().describe("Invoice Coupons"),
+    invoice_number: string2().optional().describe("invoice_number is an optional human-readable identifier for the invoice"),
+    invoice_pdf_url: string2().optional().describe("invoice_pdf_url is the URL where customers can download the PDF version of this invoice"),
     invoice_status: InvoiceStatus$zodSchema.optional(),
     invoice_type: InvoiceType$zodSchema.optional(),
-    line_item_coupons: array(DtoInvoiceLineItemCoupon$zodSchema).optional(),
-    line_items: array(DtoCreateInvoiceLineItemRequest$zodSchema).optional(),
+    line_item_coupons: array(DtoInvoiceLineItemCoupon$zodSchema).optional().describe("Invoice Line Item Coupons"),
+    line_items: array(DtoCreateInvoiceLineItemRequest$zodSchema).optional().describe("line_items contains the individual items that make up this invoice"),
     metadata: record(string2(), string2()).optional(),
     payment_status: PaymentStatus$zodSchema.optional(),
-    period_end: string2().optional(),
-    period_start: string2().optional(),
-    prepared_tax_rates: array(DtoTaxRateResponse$zodSchema).optional(),
-    subscription_id: string2().optional(),
-    subtotal: string2(),
-    tax_rate_overrides: array(DtoTaxRateOverride$zodSchema).optional(),
-    tax_rates: array(string2()).optional(),
-    total: string2(),
-    total_prepaid_applied: string2().optional()
+    period_end: string2().optional().describe("period_end is the end date of the billing period"),
+    period_start: string2().optional().describe("period_start is the start date of the billing period"),
+    prepared_tax_rates: array(DtoTaxRateResponse$zodSchema).optional().describe("prepared_tax_rates contains the tax rates pre-resolved by the caller (e.g., billing service)"),
+    subscription_id: string2().optional().describe("subscription_id is the optional unique identifier of the subscription associated with this invoice"),
+    subtotal: string2().describe("subtotal is the amount before taxes and discounts are applied"),
+    tax_rate_overrides: array(DtoTaxRateOverride$zodSchema).optional().describe("tax_rate_overrides is the tax rate overrides to be applied to the invoice"),
+    tax_rates: array(string2()).optional().describe("tax_rates"),
+    total: string2().describe("total is the total amount of the invoice including taxes and discounts"),
+    total_prepaid_applied: string2().optional().describe("total_prepaid_applied is the total amount of prepaid applied to this invoice.")
   });
 });
 
@@ -55543,7 +55655,7 @@ var init_invoicesCreateInvoice2 = __esm(() => {
   init_dtocreateinvoicerequest();
   init_tools();
   args18 = {
-    request: DtoCreateInvoiceRequest$zodSchema
+    request: DtoCreateInvoiceRequest$zodSchema.describe(`Invoice details`)
   };
   tool$invoicesCreateInvoice = {
     name: "create-invoice",
@@ -55706,16 +55818,16 @@ var DtoCustomerInvoiceSummary$zodSchema;
 var init_dtocustomerinvoicesummary = __esm(() => {
   init_zod();
   DtoCustomerInvoiceSummary$zodSchema = object({
-    currency: string2().optional(),
-    customer_id: string2().optional(),
-    overdue_invoice_count: int().optional(),
-    total_invoice_count: int().optional(),
-    total_overdue_amount: string2().optional(),
-    total_revenue_amount: string2().optional(),
-    total_unpaid_amount: string2().optional(),
-    unpaid_fixed_charges: string2().optional(),
-    unpaid_invoice_count: int().optional(),
-    unpaid_usage_charges: string2().optional()
+    currency: string2().optional().describe("currency is the three-letter ISO currency code for this summary"),
+    customer_id: string2().optional().describe("customer_id is the unique identifier of the customer"),
+    overdue_invoice_count: int().optional().describe("overdue_invoice_count is the number of overdue invoices for this customer in this currency"),
+    total_invoice_count: int().optional().describe("total_invoice_count is the total number of invoices for this customer in this currency"),
+    total_overdue_amount: string2().optional().describe("total_overdue_amount is the total amount of overdue invoices in this currency"),
+    total_revenue_amount: string2().optional().describe("total_revenue_amount is the total revenue generated from this customer in this currency"),
+    total_unpaid_amount: string2().optional().describe("total_unpaid_amount is the total amount of unpaid invoices in this currency"),
+    unpaid_fixed_charges: string2().optional().describe("unpaid_fixed_charges is the total amount of unpaid fixed charges in this currency"),
+    unpaid_invoice_count: int().optional().describe("unpaid_invoice_count is the number of unpaid invoices for this customer in this currency"),
+    unpaid_usage_charges: string2().optional().describe("unpaid_usage_charges is the total amount of unpaid usage-based charges in this currency")
   });
 });
 
@@ -55725,9 +55837,9 @@ var init_dtocustomermulticurrencyinvoicesummary = __esm(() => {
   init_zod();
   init_dtocustomerinvoicesummary();
   DtoCustomerMultiCurrencyInvoiceSummary$zodSchema = object({
-    customer_id: string2().optional(),
-    default_currency: string2().optional(),
-    summaries: array(DtoCustomerInvoiceSummary$zodSchema).optional()
+    customer_id: string2().optional().describe("customer_id is the unique identifier of the customer"),
+    default_currency: string2().optional().describe("default_currency is the primary currency for this customer"),
+    summaries: array(DtoCustomerInvoiceSummary$zodSchema).optional().describe("summaries contains the invoice summaries for each currency")
   });
 });
 
@@ -55907,11 +56019,11 @@ var DtoSourceUsageItem$zodSchema;
 var init_dtosourceusageitem = __esm(() => {
   init_zod();
   DtoSourceUsageItem$zodSchema = object({
-    cost: string2().optional(),
-    event_count: int().optional(),
-    percentage: string2().optional(),
-    source: string2().optional(),
-    usage: string2().optional()
+    cost: string2().optional().describe("cost is the cost attributed to this source for the line item"),
+    event_count: int().optional().describe("event_count is the number of events from this source (optional)"),
+    percentage: string2().optional().describe("percentage is the percentage of total line item cost from this source (optional)"),
+    source: string2().optional().describe("source is the name of the event source"),
+    usage: string2().optional().describe("usage is the total usage amount from this source (optional, for additional context)")
   });
 });
 
@@ -55920,11 +56032,11 @@ var DtoUsageBreakdownItem$zodSchema;
 var init_dtousagebreakdownitem = __esm(() => {
   init_zod();
   DtoUsageBreakdownItem$zodSchema = object({
-    cost: string2().optional(),
-    event_count: int().optional(),
-    grouped_by: record(string2(), string2()).optional(),
-    percentage: string2().optional(),
-    usage: string2().optional()
+    cost: string2().optional().describe("cost is the cost attributed to this group for the line item"),
+    event_count: int().optional().describe("event_count is the number of events from this group (optional)"),
+    grouped_by: record(string2(), string2()).optional().describe('grouped_by contains the grouping field values (e.g., {"source": "api", "org_id": "org123"})'),
+    percentage: string2().optional().describe("percentage is the percentage of total line item cost from this group (optional)"),
+    usage: string2().optional().describe("usage is the total usage amount from this group (optional, for additional context)")
   });
 });
 
@@ -55949,15 +56061,15 @@ var init_dtoinvoicelineitemresponse = __esm(() => {
     environment_id: string2().optional(),
     id: string2().optional(),
     invoice_id: string2().optional(),
-    invoice_level_discount: string2().optional(),
-    line_item_discount: string2().optional(),
+    invoice_level_discount: string2().optional().describe("invoice_level_discount is the discount amount in invoice currency applied to all line items on the invoice."),
+    line_item_discount: string2().optional().describe("line_item_discount is the discount amount in invoice currency applied directly to this line item."),
     metadata: record(string2(), string2()).optional(),
     meter_display_name: string2().optional(),
     meter_id: string2().optional(),
     period_end: string2().optional(),
     period_start: string2().optional(),
     plan_display_name: string2().optional(),
-    prepaid_credits_applied: string2().optional(),
+    prepaid_credits_applied: string2().optional().describe("prepaid_credits_applied is the amount in invoice currency reduced from this line item due to prepaid credits application."),
     price_id: string2().optional(),
     price_type: string2().optional(),
     price_unit: string2().optional(),
@@ -55969,8 +56081,8 @@ var init_dtoinvoicelineitemresponse = __esm(() => {
     tenant_id: string2().optional(),
     updated_at: string2().optional(),
     updated_by: string2().optional(),
-    usage_analytics: array(DtoSourceUsageItem$zodSchema).optional(),
-    usage_breakdown: array(DtoUsageBreakdownItem$zodSchema).optional()
+    usage_analytics: array(DtoSourceUsageItem$zodSchema).optional().describe("usage_analytics contains usage analytics for this line item (legacy - grouped by source)"),
+    usage_breakdown: array(DtoUsageBreakdownItem$zodSchema).optional().describe("usage_breakdown contains flexible usage breakdown for this line item (supports any grouping)")
   });
 });
 
@@ -56038,15 +56150,15 @@ var init_dtocouponassociationresponse = __esm(() => {
     coupon_id: string2().optional(),
     created_at: string2().optional(),
     created_by: string2().optional(),
-    end_date: string2().optional(),
+    end_date: string2().optional().describe("Optional"),
     environment_id: string2().optional(),
     id: string2().optional(),
     metadata: record(string2(), string2()).optional(),
     start_date: string2().optional(),
     status: Status$zodSchema.optional(),
-    subscription_id: string2().optional(),
-    subscription_line_item_id: string2().optional(),
-    subscription_phase_id: string2().optional(),
+    subscription_id: string2().optional().describe("Mandatory"),
+    subscription_line_item_id: string2().optional().describe("Optional"),
+    subscription_phase_id: string2().optional().describe("Optional"),
     tenant_id: string2().optional(),
     updated_at: string2().optional(),
     updated_by: string2().optional()
@@ -56122,7 +56234,10 @@ var init_dtocreditgrantresponse = __esm(() => {
   init_status();
   DtoCreditGrantResponse$zodSchema = object({
     cadence: CreditGrantCadence$zodSchema.optional(),
-    conversion_rate: string2().optional(),
+    conversion_rate: string2().optional().describe(`amount in the currency =  number of credits * conversion_rate
+ex if conversion_rate is 1, then 1 USD = 1 credit
+ex if conversion_rate is 2, then 1 USD = 0.5 credits
+ex if conversion_rate is 0.5, then 1 USD = 2 credits`),
     created_at: string2().optional(),
     created_by: string2().optional(),
     credit_grant_anchor: string2().optional(),
@@ -56144,7 +56259,10 @@ var init_dtocreditgrantresponse = __esm(() => {
     status: Status$zodSchema.optional(),
     subscription_id: string2().optional(),
     tenant_id: string2().optional(),
-    topup_conversion_rate: string2().optional(),
+    topup_conversion_rate: string2().optional().describe(`topup_conversion_rate is the conversion rate for the topup to the currency
+ex if topup_conversion_rate is 1, then 1 USD = 1 credit
+ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits
+ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits`),
     updated_at: string2().optional(),
     updated_by: string2().optional()
   });
@@ -56205,47 +56323,50 @@ var init_dtopriceresponse = __esm(() => {
   init_status();
   DtoPriceResponse$zodSchema = object({
     addon: lazy(() => DtoAddonResponse$zodSchema).optional(),
-    amount: string2().optional(),
+    amount: string2().optional().describe(`Amount stored in main currency units (e.g., dollars, not cents)
+For USD: 12.50 means $12.50`),
     billing_cadence: BillingCadence$zodSchema.optional(),
     billing_model: BillingModel$zodSchema.optional(),
     billing_period: BillingPeriod$zodSchema.optional(),
-    billing_period_count: int().optional(),
-    conversion_rate: string2().optional(),
+    billing_period_count: int().optional().describe("BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12"),
+    conversion_rate: string2().optional().describe("ConversionRate is the conversion rate of the price unit to the fiat currency"),
     created_at: string2().optional(),
     created_by: string2().optional(),
-    currency: string2().optional(),
-    description: string2().optional(),
-    display_amount: string2().optional(),
-    display_name: string2().optional(),
-    display_price_unit_amount: string2().optional(),
-    end_date: string2().optional(),
-    entity_id: string2().optional(),
+    currency: string2().optional().describe("Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp"),
+    description: string2().optional().describe("Description of the price"),
+    display_amount: string2().optional().describe(`DisplayAmount is the formatted amount with currency symbol
+For USD: $12.50`),
+    display_name: string2().optional().describe("DisplayName is the name of the price"),
+    display_price_unit_amount: string2().optional().describe("DisplayPriceUnitAmount is the formatted amount of the price unit"),
+    end_date: string2().optional().describe("EndDate is the end date of the price"),
+    entity_id: string2().optional().describe('EntityID holds the value of the "entity_id" field.'),
     entity_type: PriceEntityType$zodSchema.optional(),
-    environment_id: string2().optional(),
+    environment_id: string2().optional().describe("EnvironmentID is the environment identifier for the price"),
     group: DtoGroupResponse$zodSchema.optional(),
-    group_id: string2().optional(),
-    id: string2().optional(),
+    group_id: string2().optional().describe("GroupID references the group this price belongs to"),
+    id: string2().optional().describe("ID uuid identifier for the price"),
     invoice_cadence: InvoiceCadence$zodSchema.optional(),
-    lookup_key: string2().optional(),
+    lookup_key: string2().optional().describe("LookupKey used for looking up the price in the database"),
     metadata: record(string2(), string2()).optional(),
     meter: DtoMeterResponse$zodSchema.optional(),
-    meter_id: string2().optional(),
-    min_quantity: string2().nullable().optional(),
-    parent_price_id: string2().optional(),
+    meter_id: string2().optional().describe("MeterID is the id of the meter for usage based pricing"),
+    min_quantity: string2().nullable().optional().describe("MinQuantity is the minimum quantity of the price"),
+    parent_price_id: string2().optional().describe("ParentPriceID references the root price (always set for price lineage tracking)"),
     plan: lazy(() => DtoPlanResponse$zodSchema).optional(),
-    price_unit: string2().optional(),
-    price_unit_amount: string2().optional(),
-    price_unit_id: string2().optional(),
-    price_unit_tiers: array(PricePriceTier$zodSchema).optional(),
+    price_unit: string2().optional().describe("PriceUnit is the code of the price unit (e.g., 'btc', 'eth')"),
+    price_unit_amount: string2().optional().describe("PriceUnitAmount is the amount of the price unit"),
+    price_unit_id: string2().optional().describe("PriceUnitID is the id of the price unit (for CUSTOM type)"),
+    price_unit_tiers: array(PricePriceTier$zodSchema).optional().describe("PriceUnitTiers are the tiers for the price unit when BillingModel is TIERED"),
     price_unit_type: PriceUnitType$zodSchema.optional(),
     pricing_unit: DtoPriceUnitResponse$zodSchema.optional(),
-    start_date: string2().optional(),
+    start_date: string2().optional().describe("StartDate is the start date of the price"),
     status: Status$zodSchema.optional(),
     tenant_id: string2().optional(),
     tier_mode: BillingTier$zodSchema.optional(),
     tiers: array(PricePriceTier$zodSchema).optional(),
     transform_quantity: PriceJSONBTransformQuantity$zodSchema.optional(),
-    trial_period: int().optional(),
+    trial_period: int().optional().describe(`TrialPeriod is the number of days for the trial period
+Note: This is only applicable for recurring prices (BILLING_CADENCE_RECURRING)`),
     type: PriceType$zodSchema.optional(),
     updated_at: string2().optional(),
     updated_by: string2().optional()
@@ -56270,7 +56391,7 @@ var init_dtoaddonresponse = __esm(() => {
     lookup_key: string2().optional(),
     metadata: record(string2(), any()).optional(),
     name: string2().optional(),
-    prices: array(lazy(() => DtoPriceResponse$zodSchema)).optional(),
+    prices: array(lazy(() => DtoPriceResponse$zodSchema)).optional().describe("Optional expanded fields"),
     status: Status$zodSchema.optional(),
     tenant_id: string2().optional(),
     type: AddonType$zodSchema.optional(),
@@ -56318,7 +56439,7 @@ var init_dtoentitlementresponse = __esm(() => {
     is_soft_limit: boolean2().optional(),
     parent_entitlement_id: string2().optional(),
     plan: lazy(() => DtoPlanResponse$zodSchema).optional(),
-    plan_id: string2().optional(),
+    plan_id: string2().optional().describe("TODO: Remove this once we have a proper entitlement entity type"),
     start_date: string2().optional(),
     static_value: string2().optional(),
     status: Status$zodSchema.optional(),
@@ -56350,7 +56471,7 @@ var init_dtoplanresponse = __esm(() => {
     lookup_key: string2().optional(),
     metadata: record(string2(), string2()).optional(),
     name: string2().optional(),
-    prices: array(lazy(() => DtoPriceResponse$zodSchema)).optional(),
+    prices: array(lazy(() => DtoPriceResponse$zodSchema)).optional().describe("TODO: Add inline addons"),
     status: Status$zodSchema.optional(),
     tenant_id: string2().optional(),
     updated_at: string2().optional(),
@@ -56366,13 +56487,13 @@ var init_dtosubscriptionphaseresponse = __esm(() => {
   DtoSubscriptionPhaseResponse$zodSchema = object({
     created_at: string2().optional(),
     created_by: string2().optional(),
-    end_date: string2().optional(),
-    environment_id: string2().optional(),
-    id: string2().optional(),
+    end_date: string2().optional().describe("EndDate is when the phase ends (nil if phase is still active or indefinite)"),
+    environment_id: string2().optional().describe("EnvironmentID is the environment identifier for the phase"),
+    id: string2().optional().describe("ID is the unique identifier for the subscription phase"),
     metadata: record(string2(), string2()).optional(),
-    start_date: string2().optional(),
+    start_date: string2().optional().describe("StartDate is when the phase starts"),
     status: Status$zodSchema.optional(),
-    subscription_id: string2().optional(),
+    subscription_id: string2().optional().describe("SubscriptionID is the identifier for the subscription"),
     tenant_id: string2().optional(),
     updated_at: string2().optional(),
     updated_by: string2().optional()
@@ -56449,20 +56570,20 @@ var init_subscriptionsubscriptionpause = __esm(() => {
   SubscriptionSubscriptionPause$zodSchema = object({
     created_at: string2().optional(),
     created_by: string2().optional(),
-    environment_id: string2().optional(),
-    id: string2().optional(),
+    environment_id: string2().optional().describe("EnvironmentID is the environment identifier for the pause"),
+    id: string2().optional().describe("ID is the unique identifier for the subscription pause"),
     metadata: record(string2(), string2()).optional(),
-    original_period_end: string2().optional(),
-    original_period_start: string2().optional(),
-    pause_end: string2().optional(),
+    original_period_end: string2().optional().describe("OriginalPeriodEnd is the end of the billing period when the pause was created"),
+    original_period_start: string2().optional().describe("OriginalPeriodStart is the start of the billing period when the pause was created"),
+    pause_end: string2().optional().describe("PauseEnd is when the pause will end (null for indefinite)"),
     pause_mode: PauseMode$zodSchema.optional(),
-    pause_start: string2().optional(),
+    pause_start: string2().optional().describe("PauseStart is when the pause actually started"),
     pause_status: PauseStatus$zodSchema.optional(),
-    reason: string2().optional(),
+    reason: string2().optional().describe("Reason is the reason for pausing"),
     resume_mode: ResumeMode$zodSchema.optional(),
-    resumed_at: string2().optional(),
+    resumed_at: string2().optional().describe("ResumedAt is when the pause was actually ended (if manually resumed)"),
     status: Status$zodSchema.optional(),
-    subscription_id: string2().optional(),
+    subscription_id: string2().optional().describe("SubscriptionID is the identifier for the subscription"),
     tenant_id: string2().optional(),
     updated_at: string2().optional(),
     updated_by: string2().optional()
@@ -56490,57 +56611,63 @@ var init_dtosubscriptionresponse = __esm(() => {
   init_subscriptionsubscriptionlineitem();
   init_subscriptionsubscriptionpause();
   DtoSubscriptionResponse$zodSchema = object({
-    active_pause_id: string2().optional(),
-    billing_anchor: string2().optional(),
+    active_pause_id: string2().optional().describe(`ActivePauseID references the current active pause configuration
+This will be null if no pause is active or scheduled`),
+    billing_anchor: string2().optional().describe(`BillingAnchor is the reference point that aligns future billing cycle dates.
+It sets the day of week for week intervals, the day of month for month and year intervals,
+and the month of year for year intervals. The timestamp is in UTC format.`),
     billing_cadence: BillingCadence$zodSchema.optional(),
     billing_cycle: BillingCycle$zodSchema.optional(),
     billing_period: BillingPeriod$zodSchema.optional(),
-    billing_period_count: int().optional(),
-    cancel_at: string2().optional(),
-    cancel_at_period_end: boolean2().optional(),
-    cancelled_at: string2().optional(),
-    collection_method: string2().optional(),
-    commitment_amount: string2().optional(),
+    billing_period_count: int().optional().describe("BillingPeriodCount is the total number units of the billing period."),
+    cancel_at: string2().optional().describe("CancelAt is the date the subscription will be canceled"),
+    cancel_at_period_end: boolean2().optional().describe("CancelAtPeriodEnd is whether the subscription was canceled at the end of the current period"),
+    cancelled_at: string2().optional().describe("CanceledAt is the date the subscription was canceled"),
+    collection_method: string2().optional().describe("CollectionMethod determines how invoices are collected"),
+    commitment_amount: string2().optional().describe("CommitmentAmount is the minimum amount a customer commits to paying for a billing period"),
     commitment_duration: BillingPeriod$zodSchema.optional(),
-    coupon_associations: array(DtoCouponAssociationResponse$zodSchema).optional(),
+    coupon_associations: array(DtoCouponAssociationResponse$zodSchema).optional().describe("CouponAssociations are the coupon associations for this subscription"),
     created_at: string2().optional(),
     created_by: string2().optional(),
-    credit_grants: array(DtoCreditGrantResponse$zodSchema).optional(),
-    currency: string2().optional(),
-    current_period_end: string2().optional(),
-    current_period_start: string2().optional(),
-    customer: DtoCustomerResponse$zodSchema.optional(),
-    customer_id: string2().optional(),
+    credit_grants: array(DtoCreditGrantResponse$zodSchema).optional().describe("Credit grants are the credit grants for this subscription"),
+    currency: string2().optional().describe("Currency is the currency of the subscription in lowercase 3 digit ISO codes"),
+    current_period_end: string2().optional().describe(`CurrentPeriodEnd is the end of the current period that the subscription has been invoiced for.
+At the end of this period, a new invoice will be created.`),
+    current_period_start: string2().optional().describe(`CurrentPeriodStart is the end of the current period that the subscription has been invoiced for.
+At the end of this period, a new invoice will be created.`),
+    customer: DtoCustomerResponse$zodSchema.optional().describe("Customer response object containing all customer information"),
+    customer_id: string2().optional().describe("CustomerID is the identifier for the customer in our system"),
     customer_timezone: string2().optional(),
     enable_true_up: boolean2().optional(),
-    end_date: string2().optional(),
-    environment_id: string2().optional(),
-    gateway_payment_method_id: string2().optional(),
-    id: string2().optional(),
-    invoicing_customer_id: string2().optional(),
+    end_date: string2().optional().describe("EndDate is the end date of the subscription"),
+    environment_id: string2().optional().describe("EnvironmentID is the environment identifier for the subscription"),
+    gateway_payment_method_id: string2().optional().describe("GatewayPaymentMethodID is the gateway payment method ID for this subscription"),
+    id: string2().optional().describe("ID is the unique identifier for the subscription"),
+    invoicing_customer_id: string2().optional().describe(`InvoicingCustomerID is the customer ID to use for invoicing
+This can differ from the subscription customer (e.g., parent company invoicing for child company)`),
     latest_invoice: lazy(() => DtoInvoiceResponse$zodSchema).optional(),
     line_items: array(SubscriptionSubscriptionLineItem$zodSchema).optional(),
-    lookup_key: string2().optional(),
+    lookup_key: string2().optional().describe("LookupKey is the key used to lookup the subscription in our system"),
     metadata: record(string2(), string2()).optional(),
-    overage_factor: string2().optional(),
-    parent_subscription_id: string2().optional(),
+    overage_factor: string2().optional().describe("OverageFactor is a multiplier applied to usage beyond the commitment amount"),
+    parent_subscription_id: string2().optional().describe("ParentSubscriptionID is the parent subscription ID for hierarchy (e.g. child subscription under a parent)"),
     pause_status: PauseStatus$zodSchema.optional(),
     pauses: array(SubscriptionSubscriptionPause$zodSchema).optional(),
-    payment_behavior: string2().optional(),
+    payment_behavior: string2().optional().describe("PaymentBehavior determines how subscription payments are handled"),
     payment_terms: PaymentTerms$zodSchema.optional(),
-    phases: array(DtoSubscriptionPhaseResponse$zodSchema).optional(),
+    phases: array(DtoSubscriptionPhaseResponse$zodSchema).optional().describe("Phases are the subscription phases for this subscription"),
     plan: DtoPlanResponse$zodSchema.optional(),
-    plan_id: string2().optional(),
+    plan_id: string2().optional().describe("PlanID is the identifier for the plan in our system"),
     proration_behavior: ProrationBehavior$zodSchema.optional(),
-    start_date: string2().optional(),
+    start_date: string2().optional().describe("StartDate is the start date of the subscription"),
     status: Status$zodSchema.optional(),
     subscription_status: SubscriptionStatus$zodSchema.optional(),
     tenant_id: string2().optional(),
-    trial_end: string2().optional(),
-    trial_start: string2().optional(),
+    trial_end: string2().optional().describe("TrialEnd is the end date of the trial period"),
+    trial_start: string2().optional().describe("TrialStart is the start date of the trial period"),
     updated_at: string2().optional(),
     updated_by: string2().optional(),
-    version: int().optional()
+    version: int().optional().describe("Version is used for optimistic locking")
   });
 });
 
@@ -56600,52 +56727,55 @@ var init_dtoinvoiceresponse = __esm(() => {
   init_paymentstatus();
   init_status();
   DtoInvoiceResponse$zodSchema = object({
-    adjustment_amount: string2().optional(),
-    amount_due: string2().optional(),
-    amount_paid: string2().optional(),
-    amount_remaining: string2().optional(),
-    billing_period: string2().optional(),
-    billing_reason: string2().optional(),
-    billing_sequence: int().optional(),
-    coupon_applications: array(DtoCouponApplicationResponse$zodSchema).optional(),
+    adjustment_amount: string2().optional().describe(`adjustment_amount is the total sum of credit notes of type "adjustment".
+These are non-cash reductions applied to the invoice (e.g. goodwill credit, billing correction).`),
+    amount_due: string2().optional().describe("amount_due is the total amount that needs to be paid for this invoice"),
+    amount_paid: string2().optional().describe("amount_paid is the amount that has already been paid towards this invoice"),
+    amount_remaining: string2().optional().describe("amount_remaining is the outstanding amount still owed on this invoice (calculated as amount_due minus amount_paid)"),
+    billing_period: string2().optional().describe('billing_period describes the billing period this invoice covers (e.g., "January 2024", "Q1 2024")'),
+    billing_reason: string2().optional().describe('billing_reason indicates why this invoice was generated (e.g., "subscription_billing", "manual_charge")'),
+    billing_sequence: int().optional().describe("billing_sequence is the sequential number indicating the billing cycle for subscription invoices"),
+    coupon_applications: array(DtoCouponApplicationResponse$zodSchema).optional().describe("coupon_applications contains the coupon applications associated with this invoice (overrides embedded field)"),
     created_at: string2().optional(),
     created_by: string2().optional(),
-    currency: string2().optional(),
-    customer: DtoCustomerResponse$zodSchema.optional(),
-    customer_id: string2().optional(),
-    description: string2().optional(),
-    due_date: string2().optional(),
-    environment_id: string2().optional(),
-    finalized_at: string2().optional(),
-    id: string2().optional(),
-    idempotency_key: string2().optional(),
-    invoice_number: string2().optional(),
-    invoice_pdf_url: string2().optional(),
+    currency: string2().optional().describe("currency is the three-letter ISO currency code (e.g., USD, EUR, GBP) that applies to all monetary amounts on this invoice"),
+    customer: DtoCustomerResponse$zodSchema.optional().describe("Customer response object containing all customer information"),
+    customer_id: string2().optional().describe("customer_id is the ID of the customer who will receive this invoice"),
+    description: string2().optional().describe("description is an optional description or notes about this invoice"),
+    due_date: string2().optional().describe("due_date is the date when payment for this invoice is due"),
+    environment_id: string2().optional().describe("environment_id is the ID of the environment this invoice belongs to (for multi-environment setups)"),
+    finalized_at: string2().optional().describe("finalized_at is the timestamp when this invoice was finalized and made ready for payment"),
+    id: string2().optional().describe("id is the unique identifier for this invoice"),
+    idempotency_key: string2().optional().describe("idempotency_key is a unique key used to prevent duplicate invoice creation when retrying API calls"),
+    invoice_number: string2().optional().describe("invoice_number is the human-readable invoice number displayed to customers (e.g., INV-2024-001)"),
+    invoice_pdf_url: string2().optional().describe("invoice_pdf_url is the URL where customers can download the PDF version of this invoice"),
     invoice_status: InvoiceStatus$zodSchema.optional(),
     invoice_type: InvoiceType$zodSchema.optional(),
-    line_items: array(DtoInvoiceLineItemResponse$zodSchema).optional(),
+    line_items: array(DtoInvoiceLineItemResponse$zodSchema).optional().describe("line_items contains the individual items that make up this invoice (overrides embedded field)"),
     metadata: record(string2(), string2()).optional(),
-    overpaid_amount: string2().optional(),
-    paid_at: string2().optional(),
+    overpaid_amount: string2().optional().describe("overpaid_amount is the amount overpaid if payment_status is OVERPAID (amount_paid - total)"),
+    paid_at: string2().optional().describe("paid_at is the timestamp when this invoice was fully paid"),
     payment_status: PaymentStatus$zodSchema.optional(),
-    period_end: string2().optional(),
-    period_start: string2().optional(),
-    recalculated_invoice_id: string2().optional(),
-    refunded_amount: string2().optional(),
+    period_end: string2().optional().describe("period_end is the end date of the billing period covered by this invoice"),
+    period_start: string2().optional().describe("period_start is the start date of the billing period covered by this invoice"),
+    recalculated_invoice_id: string2().optional().describe(`recalculated_invoice_id is the ID of the replacement invoice created when this invoice was voided and recalculated.
+When set, it forms a parent→child link from this (voided) invoice to the new replacement invoice.`),
+    refunded_amount: string2().optional().describe(`refunded_amount is the total sum of credit notes of type "refund".
+These are actual refunds issued to the customer.`),
     status: Status$zodSchema.optional(),
     subscription: lazy(() => DtoSubscriptionResponse$zodSchema).optional(),
-    subscription_id: string2().optional(),
-    subtotal: string2().optional(),
-    taxes: array(DtoTaxAppliedResponse$zodSchema).optional(),
+    subscription_id: string2().optional().describe("subscription_id is the ID of the subscription this invoice is associated with (only present for subscription-based invoices)"),
+    subtotal: string2().optional().describe("subtotal is the sum of all line items before any taxes, discounts, or additional fees"),
+    taxes: array(DtoTaxAppliedResponse$zodSchema).optional().describe("tax_applied_records contains the tax applied records associated with this invoice"),
     tenant_id: string2().optional(),
-    total: string2().optional(),
-    total_discount: string2().optional(),
-    total_prepaid_credits_applied: string2().optional(),
-    total_tax: string2().optional(),
+    total: string2().optional().describe("total is the final amount including taxes, fees, and discounts"),
+    total_discount: string2().optional().describe("total_discount is the sum of all coupon discounts applied to the invoice"),
+    total_prepaid_credits_applied: string2().optional().describe("total_prepaid_credits_applied is the total amount of prepaid credits applied to this invoice."),
+    total_tax: string2().optional().describe("total_tax is the sum of all taxes combined at the invoice level."),
     updated_at: string2().optional(),
     updated_by: string2().optional(),
-    version: int().optional(),
-    voided_at: string2().optional()
+    version: int().optional().describe("version is the version number for tracking changes to this invoice"),
+    voided_at: string2().optional().describe("voided_at is the timestamp when this invoice was voided or cancelled")
   });
 });
 
@@ -56924,10 +57054,10 @@ var DtoGetPreviewInvoiceRequest$zodSchema;
 var init_dtogetpreviewinvoicerequest = __esm(() => {
   init_zod();
   DtoGetPreviewInvoiceRequest$zodSchema = object({
-    hide_zero_charges_line_items: boolean2().default(false),
-    period_end: string2().optional(),
-    period_start: string2().optional(),
-    subscription_id: string2()
+    hide_zero_charges_line_items: boolean2().default(false).describe("hide_zero_charges_line_items indicates whether to hide line items with zero cost"),
+    period_end: string2().optional().describe("period_end is the optional end date of the period to preview"),
+    period_start: string2().optional().describe("period_start is the optional start date of the period to preview"),
+    subscription_id: string2().describe("subscription_id is the unique identifier of the subscription to preview invoice for")
   });
 });
 
@@ -57011,7 +57141,7 @@ var init_invoicesGetInvoicePreview2 = __esm(() => {
   init_dtogetpreviewinvoicerequest();
   init_tools();
   args23 = {
-    request: DtoGetPreviewInvoiceRequest$zodSchema
+    request: DtoGetPreviewInvoiceRequest$zodSchema.describe(`Preview Invoice Request`)
   };
   tool$invoicesGetInvoicePreview = {
     name: "get-invoice-preview",
@@ -57055,29 +57185,37 @@ var init_invoicefilter = __esm(() => {
     "desc"
   ]);
   InvoiceFilter$zodSchema = object({
-    amount_due_gt: number2().optional(),
-    amount_remaining_gt: number2().optional(),
-    customer_id: string2().optional(),
+    amount_due_gt: number2().optional().describe(`amount_due_gt filters invoices with a total amount due greater than the specified value
+Useful for finding invoices above a certain threshold or identifying high-value invoices`),
+    amount_remaining_gt: number2().optional().describe(`amount_remaining_gt filters invoices with an outstanding balance greater than the specified value
+Useful for finding invoices that still have significant unpaid amounts`),
+    customer_id: string2().optional().describe(`customer_id filters invoices for a specific customer using FlexPrice's internal customer ID
+This is the ID returned by FlexPrice when creating or retrieving customers`),
     end_time: string2().optional(),
     expand: string2().optional(),
-    external_customer_id: string2().optional(),
+    external_customer_id: string2().optional().describe(`external_customer_id filters invoices for a customer using your system's customer identifier
+This is the ID you provided when creating the customer in FlexPrice`),
     filters: array(FilterCondition$zodSchema).optional(),
-    invoice_ids: array(string2()).optional(),
-    invoice_status: array(InvoiceStatus$zodSchema).optional(),
+    invoice_ids: array(string2()).optional().describe(`invoice_ids restricts results to invoices with the specified IDs
+Use this to retrieve specific invoices when you know their exact identifiers`),
+    invoice_status: array(InvoiceStatus$zodSchema).optional().describe(`invoice_status filters by the current state of invoices in their lifecycle
+Multiple statuses can be specified to include invoices in any of the listed states`),
     invoice_type: InvoiceType$zodSchema.optional(),
     limit: int().optional(),
     offset: int().optional(),
     order: InvoiceFilterOrder$zodSchema.optional(),
-    payment_status: array(PaymentStatus$zodSchema).optional(),
-    period_end_gte: string2().optional(),
-    period_end_lte: string2().optional(),
-    period_start_gte: string2().optional(),
-    period_start_lte: string2().optional(),
-    skip_line_items: boolean2().optional(),
+    payment_status: array(PaymentStatus$zodSchema).optional().describe(`payment_status filters by the payment state of invoices
+Multiple statuses can be specified to include invoices with any of the listed payment states`),
+    period_end_gte: string2().optional().describe("period_end_gte filters invoices with period_end >= value"),
+    period_end_lte: string2().optional().describe("period_end_lte filters invoices with period_end <= value"),
+    period_start_gte: string2().optional().describe("period_start_gte filters invoices with period_start >= value"),
+    period_start_lte: string2().optional().describe("period_start_lte filters invoices with period_start <= value"),
+    skip_line_items: boolean2().optional().describe("SkipLineItems if true, will not include line items in the response"),
     sort: array(SortCondition$zodSchema).optional(),
     start_time: string2().optional(),
     status: Status$zodSchema.optional(),
-    subscription_id: string2().optional()
+    subscription_id: string2().optional().describe(`subscription_id filters invoices generated for a specific subscription
+Only returns invoices that were created as part of the specified subscription's billing`)
   });
 });
 
@@ -57161,7 +57299,7 @@ var init_invoicesQueryInvoice2 = __esm(() => {
   init_invoicefilter();
   init_tools();
   args24 = {
-    request: InvoiceFilter$zodSchema
+    request: InvoiceFilter$zodSchema.describe(`Filter`)
   };
   tool$invoicesQueryInvoice = {
     name: "query-invoice",
@@ -57599,7 +57737,7 @@ var init_dtoupdateinvoicerequest = __esm(() => {
   init_zod();
   DtoUpdateInvoiceRequest$zodSchema = object({
     due_date: string2().optional(),
-    invoice_pdf_url: string2().optional(),
+    invoice_pdf_url: string2().optional().describe("invoice_pdf_url is the URL where customers can download the PDF version of this invoice"),
     metadata: record(string2(), string2()).optional()
   });
 });
@@ -57612,7 +57750,7 @@ var init_updateinvoiceop = __esm(() => {
   init_dtoupdateinvoicerequest();
   init_errorserrorresponse();
   UpdateInvoiceRequest$zodSchema = object({
-    body: DtoUpdateInvoiceRequest$zodSchema,
+    body: DtoUpdateInvoiceRequest$zodSchema.describe("Invoice Update Request"),
     id: string2().describe("Invoice ID")
   });
   UpdateInvoiceResponse$zodSchema = union([
@@ -57742,7 +57880,7 @@ var init_dtoupdatepaymentstatusrequest = __esm(() => {
   init_zod();
   init_paymentstatus();
   DtoUpdatePaymentStatusRequest$zodSchema = object({
-    amount: string2().optional(),
+    amount: string2().optional().describe("amount is the optional payment amount to record"),
     payment_status: PaymentStatus$zodSchema
   });
 });
@@ -57755,7 +57893,7 @@ var init_updateinvoicepaymentstatusop = __esm(() => {
   init_dtoupdatepaymentstatusrequest();
   init_errorserrorresponse();
   UpdateInvoicePaymentStatusRequest$zodSchema = object({
-    body: DtoUpdatePaymentStatusRequest$zodSchema,
+    body: DtoUpdatePaymentStatusRequest$zodSchema.describe("Payment Status Update Request"),
     id: string2().describe("Invoice ID")
   });
   UpdateInvoicePaymentStatusResponse$zodSchema = union([
@@ -58101,7 +58239,7 @@ var init_plansCreatePlan2 = __esm(() => {
   init_dtocreateplanrequest();
   init_tools();
   args31 = {
-    request: DtoCreatePlanRequest$zodSchema
+    request: DtoCreatePlanRequest$zodSchema.describe(`Plan configuration`)
   };
   tool$plansCreatePlan = {
     name: "create-plan",
@@ -58393,11 +58531,11 @@ var DtoClonePlanRequest$zodSchema;
 var init_dtocloneplanrequest = __esm(() => {
   init_zod();
   DtoClonePlanRequest$zodSchema = object({
-    description: string2().optional(),
-    display_order: int().optional(),
-    lookup_key: string2().optional(),
+    description: string2().optional().describe("Description overrides the source plan's description when provided"),
+    display_order: int().optional().describe("DisplayOrder overrides the source plan's display order when provided"),
+    lookup_key: string2().optional().describe("LookupKey is required and must be unique across published plans"),
     metadata: record(string2(), string2()).optional(),
-    name: string2().optional()
+    name: string2().optional().describe("Name is required and must be different from the source plan's name")
   });
 });
 
@@ -58409,7 +58547,7 @@ var init_postplansidcloneop = __esm(() => {
   init_dtoplanresponse();
   init_errorserrorresponse();
   PostPlansIdCloneRequest$zodSchema = object({
-    body: DtoClonePlanRequest$zodSchema,
+    body: DtoClonePlanRequest$zodSchema.describe("Clone configuration"),
     id: string2().describe("Source Plan ID")
   });
   PostPlansIdCloneResponse$zodSchema = union([
@@ -58547,7 +58685,7 @@ var init_planfilter = __esm(() => {
   PlanFilter$zodSchema = object({
     end_time: string2().optional(),
     expand: string2().optional(),
-    filters: array(FilterCondition$zodSchema).optional(),
+    filters: array(FilterCondition$zodSchema).optional().describe("filters allows complex filtering based on multiple fields"),
     limit: int().optional(),
     lookup_key: string2().optional(),
     offset: int().optional(),
@@ -58639,7 +58777,7 @@ var init_plansQueryPlan2 = __esm(() => {
   init_planfilter();
   init_tools();
   args35 = {
-    request: PlanFilter$zodSchema
+    request: PlanFilter$zodSchema.describe(`Filter`)
   };
   tool$plansQueryPlan = {
     name: "query-plan",
@@ -58818,7 +58956,7 @@ var init_updateplanop = __esm(() => {
   init_dtoupdateplanrequest();
   init_errorserrorresponse();
   UpdatePlanRequest$zodSchema = object({
-    body: DtoUpdatePlanRequest$zodSchema,
+    body: DtoUpdatePlanRequest$zodSchema.describe("Plan update"),
     id: string2().describe("Plan ID")
   });
   UpdatePlanResponse$zodSchema = union([
@@ -58947,9 +59085,13 @@ var DtoCreatePriceTier$zodSchema;
 var init_dtocreatepricetier = __esm(() => {
   init_zod();
   DtoCreatePriceTier$zodSchema = object({
-    flat_amount: string2().optional(),
-    unit_amount: string2(),
-    up_to: int().optional()
+    flat_amount: string2().optional().describe(`flat_amount is the flat amount for the given tier (optional)
+Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c"`),
+    unit_amount: string2().describe("unit_amount is the amount per unit for the given tier"),
+    up_to: int().optional().describe(`up_to is the quantity up to which this tier applies. It is null for the last tier.
+IMPORTANT: Tier boundaries are INCLUSIVE.
+- If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier
+- This behavior is consistent across both VOLUME and SLAB tier modes`)
   });
 });
 
@@ -58971,7 +59113,7 @@ var init_pricetransformquantity = __esm(() => {
   init_zod();
   init_roundtype();
   PriceTransformQuantity$zodSchema = object({
-    divide_by: int().optional(),
+    divide_by: int().optional().describe("Divide quantity by this number"),
     round: RoundType$zodSchema.optional()
   });
 });
@@ -59004,12 +59146,12 @@ var init_dtocreatepricerequest = __esm(() => {
     entity_id: string2(),
     entity_type: PriceEntityType$zodSchema,
     filter_values: record(string2(), array(string2())).optional(),
-    group_id: string2().optional(),
+    group_id: string2().optional().describe("GroupID is the id of the group to add the price to"),
     invoice_cadence: InvoiceCadence$zodSchema,
     lookup_key: string2().optional(),
     metadata: record(string2(), string2()).optional(),
     meter_id: string2().optional(),
-    min_quantity: int().optional(),
+    min_quantity: int().optional().describe("MinQuantity is the minimum quantity of the price"),
     price_unit_config: DtoPriceUnitConfig$zodSchema.optional(),
     price_unit_type: PriceUnitType$zodSchema,
     start_date: string2().optional(),
@@ -59101,7 +59243,7 @@ var init_pricesCreatePrice2 = __esm(() => {
   init_dtocreatepricerequest();
   init_tools();
   args38 = {
-    request: DtoCreatePriceRequest$zodSchema
+    request: DtoCreatePriceRequest$zodSchema.describe(`Price configuration`)
   };
   tool$pricesCreatePrice = {
     name: "create-price",
@@ -59220,7 +59362,7 @@ var init_pricesCreatePricesBulk2 = __esm(() => {
   init_dtocreatebulkpricerequest();
   init_tools();
   args39 = {
-    request: DtoCreateBulkPriceRequest$zodSchema
+    request: DtoCreateBulkPriceRequest$zodSchema.describe(`Bulk price configuration`)
   };
   tool$pricesCreatePricesBulk = {
     name: "create-prices-bulk",
@@ -59266,7 +59408,7 @@ var init_deletepriceop = __esm(() => {
   init_dtosuccessresponse();
   init_errorserrorresponse();
   DeletePriceRequest$zodSchema = object({
-    body: DtoDeletePriceRequest$zodSchema,
+    body: DtoDeletePriceRequest$zodSchema.describe("Delete Price Request"),
     id: string2().describe("Price ID")
   });
   DeletePriceResponse$zodSchema = union([
@@ -59665,13 +59807,13 @@ var init_pricefilter = __esm(() => {
     entity_ids: array(string2()).optional(),
     entity_type: PriceEntityType$zodSchema.optional(),
     expand: string2().optional(),
-    filters: array(FilterCondition$zodSchema).optional(),
+    filters: array(FilterCondition$zodSchema).optional().describe("DSL filters"),
     limit: int().optional(),
     meter_ids: array(string2()).optional(),
     offset: int().optional(),
     order: PriceFilterOrder$zodSchema.optional(),
     parent_price_id: string2().optional(),
-    plan_ids: array(string2()).optional(),
+    plan_ids: array(string2()).optional().describe("Price override filtering fields"),
     price_ids: array(string2()).optional(),
     sort: string2().optional(),
     start_date_lt: string2().optional(),
@@ -59761,7 +59903,7 @@ var init_pricesQueryPrice2 = __esm(() => {
   init_pricefilter();
   init_tools();
   args43 = {
-    request: PriceFilter$zodSchema
+    request: PriceFilter$zodSchema.describe(`Filter`)
   };
   tool$pricesQueryPrice = {
     name: "query-price",
@@ -59799,18 +59941,22 @@ var init_dtoupdatepricerequest = __esm(() => {
   init_dtocreatepricetier();
   init_pricetransformquantity();
   DtoUpdatePriceRequest$zodSchema = object({
-    amount: string2().optional(),
+    amount: string2().optional().describe("Amount is the new price amount that overrides the original price (optional)"),
     billing_model: BillingModel$zodSchema.optional(),
     description: string2().optional(),
     display_name: string2().optional(),
     effective_from: string2().optional(),
-    group_id: string2().optional(),
-    lookup_key: string2().optional(),
+    group_id: string2().optional().describe(`GroupID is the id of the group to update the price in.
+If not provided (nil), the group will not be changed
+If provided as empty string (""), the group will be removed (price will be ungrouped)
+If provided as a group ID, the price will be assigned to that group (must exist and be published)`),
+    lookup_key: string2().optional().describe(`All price fields that can be updated
+Non-critical fields (can be updated directly)`),
     metadata: record(string2(), string2()).optional(),
-    price_unit_amount: string2().optional(),
-    price_unit_tiers: array(DtoCreatePriceTier$zodSchema).optional(),
+    price_unit_amount: string2().optional().describe("PriceUnitAmount is the price unit amount (for CUSTOM price unit type, FLAT_FEE/PACKAGE billing models)"),
+    price_unit_tiers: array(DtoCreatePriceTier$zodSchema).optional().describe("PriceUnitTiers are the price unit tiers (for CUSTOM price unit type, TIERED billing model)"),
     tier_mode: BillingTier$zodSchema.optional(),
-    tiers: array(DtoCreatePriceTier$zodSchema).optional(),
+    tiers: array(DtoCreatePriceTier$zodSchema).optional().describe("Tiers determines the pricing tiers for this line item"),
     transform_quantity: PriceTransformQuantity$zodSchema.optional()
   });
 });
@@ -59823,7 +59969,7 @@ var init_updatepriceop = __esm(() => {
   init_dtoupdatepricerequest();
   init_errorserrorresponse();
   UpdatePriceRequest$zodSchema = object({
-    body: DtoUpdatePriceRequest$zodSchema,
+    body: DtoUpdatePriceRequest$zodSchema.describe("Price configuration"),
     id: string2().describe("Price ID")
   });
   UpdatePriceResponse$zodSchema = union([
@@ -59952,7 +60098,7 @@ var DtoActivateDraftSubscriptionRequest$zodSchema;
 var init_dtoactivatedraftsubscriptionrequest = __esm(() => {
   init_zod();
   DtoActivateDraftSubscriptionRequest$zodSchema = object({
-    start_date: string2()
+    start_date: string2().describe("start_date is the new start date for the subscription when activating")
   });
 });
 
@@ -59964,7 +60110,7 @@ var init_activatesubscriptionop = __esm(() => {
   init_dtosubscriptionresponse();
   init_errorserrorresponse();
   ActivateSubscriptionRequest$zodSchema = object({
-    body: DtoActivateDraftSubscriptionRequest$zodSchema,
+    body: DtoActivateDraftSubscriptionRequest$zodSchema.describe("Activate Draft Subscription Request"),
     id: string2().describe("Subscription ID")
   });
   ActivateSubscriptionResponse$zodSchema = union([
@@ -60095,13 +60241,13 @@ var init_dtolineitemcommitmentconfig = __esm(() => {
   init_billingperiod();
   init_commitmenttype();
   DtoLineItemCommitmentConfig$zodSchema = object({
-    commitment_amount: number2().optional(),
+    commitment_amount: number2().optional().describe("CommitmentAmount is the minimum amount committed for this line item"),
     commitment_duration: BillingPeriod$zodSchema.optional(),
-    commitment_quantity: number2().optional(),
+    commitment_quantity: number2().optional().describe("CommitmentQuantity is the minimum quantity committed for this line item"),
     commitment_type: CommitmentType$zodSchema.optional(),
-    enable_true_up: boolean2().optional(),
-    is_window_commitment: boolean2().optional(),
-    overage_factor: number2().optional()
+    enable_true_up: boolean2().optional().describe("EnableTrueUp determines if true-up fee should be applied when usage is below commitment"),
+    is_window_commitment: boolean2().optional().describe("IsWindowCommitment determines if commitment is applied per window (e.g., per day) rather than per billing period"),
+    overage_factor: number2().optional().describe("OverageFactor is a multiplier applied to usage beyond the commitment")
   });
 });
 
@@ -60112,7 +60258,7 @@ var init_dtoaddaddonrequest = __esm(() => {
   init_dtolineitemcommitmentconfig();
   DtoAddAddonRequest$zodSchema = object({
     addon_id: string2(),
-    line_item_commitments: record(string2(), DtoLineItemCommitmentConfig$zodSchema).optional(),
+    line_item_commitments: record(string2(), DtoLineItemCommitmentConfig$zodSchema).optional().describe("LineItemCommitments allows setting commitment configuration per addon line item (keyed by price_id)"),
     metadata: record(string2(), any()).optional(),
     start_date: string2().optional(),
     subscription_id: string2()
@@ -60199,7 +60345,7 @@ var init_subscriptionsAddSubscriptionAddon2 = __esm(() => {
   init_dtoaddaddonrequest();
   init_tools();
   args46 = {
-    request: DtoAddAddonRequest$zodSchema
+    request: DtoAddAddonRequest$zodSchema.describe(`Add Addon Request`)
   };
   tool$subscriptionsAddSubscriptionAddon = {
     name: "add-subscription-addon",
@@ -60244,7 +60390,8 @@ var init_cancellationtype = __esm(() => {
   init_zod();
   CancellationType$zodSchema = _enum([
     "immediate",
-    "end_of_period"
+    "end_of_period",
+    "scheduled_date"
   ]);
 });
 
@@ -60256,10 +60403,12 @@ var init_dtocancelsubscriptionrequest = __esm(() => {
   init_cancellationtype();
   init_prorationbehavior();
   DtoCancelSubscriptionRequest$zodSchema = object({
+    cancel_at: string2().optional().describe(`CancelAt is the custom date to cancel the subscription.
+Required when CancellationType is "scheduled_date". Must be in the future.`),
     cancel_immediately_inovice_policy: CancelImmediatelyInvoicePolicy$zodSchema.optional(),
     cancellation_type: CancellationType$zodSchema,
     proration_behavior: ProrationBehavior$zodSchema.optional(),
-    reason: string2().optional()
+    reason: string2().optional().describe("Reason for cancellation (for audit and business intelligence)")
   });
 });
 
@@ -60290,13 +60439,13 @@ var init_dtocancelsubscriptionresponse = __esm(() => {
   DtoCancelSubscriptionResponse$zodSchema = object({
     cancellation_type: CancellationType$zodSchema.optional(),
     effective_date: string2().optional(),
-    message: string2().optional(),
+    message: string2().optional().describe("Response metadata"),
     processed_at: string2().optional(),
     proration_details: array(DtoProrationDetail$zodSchema).optional(),
     proration_invoice: DtoInvoiceResponse$zodSchema.optional(),
     reason: string2().optional(),
     status: SubscriptionStatus$zodSchema.optional(),
-    subscription_id: string2().optional(),
+    subscription_id: string2().optional().describe("Basic cancellation info"),
     total_credit_amount: string2().optional()
   });
 });
@@ -60309,7 +60458,7 @@ var init_cancelsubscriptionop = __esm(() => {
   init_dtocancelsubscriptionresponse();
   init_errorserrorresponse();
   CancelSubscriptionRequest$zodSchema = object({
-    body: DtoCancelSubscriptionRequest$zodSchema,
+    body: DtoCancelSubscriptionRequest$zodSchema.describe("Cancel Subscription Request"),
     id: string2().describe("Subscription ID")
   });
   CancelSubscriptionResponse$zodSchema = union([
@@ -60449,9 +60598,9 @@ var init_dtocancelschedulerequest = __esm(() => {
   init_zod();
   init_subscriptionschedulechangetype();
   DtoCancelScheduleRequest$zodSchema = object({
-    schedule_id: string2().optional(),
+    schedule_id: string2().optional().describe("schedule_id is the ID of the schedule to cancel (optional if subscription_id and schedule_type are provided)"),
     schedule_type: SubscriptionScheduleChangeType$zodSchema.optional(),
-    subscription_id: string2().optional()
+    subscription_id: string2().optional().describe("subscription_id is the ID of the subscription (required if schedule_id is not provided)")
   }).describe("Request to cancel a subscription schedule (supports two modes)");
 });
 
@@ -60461,7 +60610,7 @@ var init_cancelsubscriptionscheduleop = __esm(() => {
   init_zod();
   init_dtocancelschedulerequest();
   CancelSubscriptionScheduleRequest$zodSchema = object({
-    body: DtoCancelScheduleRequest$zodSchema.optional(),
+    body: DtoCancelScheduleRequest$zodSchema.optional().describe("Cancel request (optional if using path parameter)"),
     schedule_id: string2().describe("Schedule ID (optional if using request body)")
   });
 });
@@ -60598,7 +60747,7 @@ var init_dtoaddaddontosubscriptionrequest = __esm(() => {
   init_dtolineitemcommitmentconfig();
   DtoAddAddonToSubscriptionRequest$zodSchema = object({
     addon_id: string2(),
-    line_item_commitments: record(string2(), DtoLineItemCommitmentConfig$zodSchema).optional(),
+    line_item_commitments: record(string2(), DtoLineItemCommitmentConfig$zodSchema).optional().describe("LineItemCommitments allows setting commitment configuration per addon line item (keyed by price_id)"),
     metadata: record(string2(), any()).optional(),
     start_date: string2().optional()
   });
@@ -60615,7 +60764,10 @@ var init_dtocreatecreditgrantrequest = __esm(() => {
   init_creditgrantscope();
   DtoCreateCreditGrantRequest$zodSchema = object({
     cadence: CreditGrantCadence$zodSchema,
-    conversion_rate: string2().optional(),
+    conversion_rate: string2().optional().describe(`amount in the currency =  number of credits * conversion_rate
+ex if conversion_rate is 1, then 1 USD = 1 credit
+ex if conversion_rate is 2, then 1 USD = 0.5 credits
+ex if conversion_rate is 0.5, then 1 USD = 2 credits`),
     credits: string2(),
     end_date: string2().optional(),
     expiration_duration: int().optional(),
@@ -60630,7 +60782,10 @@ var init_dtocreatecreditgrantrequest = __esm(() => {
     scope: CreditGrantScope$zodSchema,
     start_date: string2().optional(),
     subscription_id: string2().optional(),
-    topup_conversion_rate: string2().optional()
+    topup_conversion_rate: string2().optional().describe(`topup_conversion_rate is the conversion rate for the topup to the currency
+ex if topup_conversion_rate is 1, then 1 USD = 1 credit
+ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits
+ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits`)
   });
 });
 
@@ -60682,7 +60837,7 @@ var init_dtocreatesubscriptionlineitemrequest = __esm(() => {
   init_commitmenttype();
   init_dtosubscriptionpricecreaterequest();
   DtoCreateSubscriptionLineItemRequest$zodSchema = object({
-    commitment_amount: number2().optional(),
+    commitment_amount: number2().optional().describe("Commitment fields"),
     commitment_duration: BillingPeriod$zodSchema.optional(),
     commitment_overage_factor: number2().optional(),
     commitment_quantity: number2().optional(),
@@ -60693,7 +60848,7 @@ var init_dtocreatesubscriptionlineitemrequest = __esm(() => {
     end_date: string2().optional(),
     metadata: record(string2(), string2()).optional(),
     price: DtoSubscriptionPriceCreateRequest$zodSchema.optional(),
-    price_id: string2().optional(),
+    price_id: string2().optional().describe("PriceID references an existing price (plan, addon, or subscription-scoped). Exactly one of price_id or price must be set."),
     quantity: number2().optional(),
     start_date: string2().optional(),
     subscription_phase_id: string2().optional()
@@ -60705,10 +60860,11 @@ var DtoOverrideEntitlementRequest$zodSchema;
 var init_dtooverrideentitlementrequest = __esm(() => {
   init_zod();
   DtoOverrideEntitlementRequest$zodSchema = object({
-    entitlement_id: string2(),
-    is_enabled: boolean2().optional(),
-    static_value: string2().optional(),
-    usage_limit: int().optional()
+    entitlement_id: string2().describe("EntitlementID references the plan/addon entitlement to override"),
+    is_enabled: boolean2().optional().describe("IsEnabled determines if the entitlement is enabled or disabled"),
+    static_value: string2().optional().describe("StaticValue is the static value for static features"),
+    usage_limit: int().optional().describe(`UsageLimit is the new usage limit (only these 3 fields can be overridden)
+For metered features, nil means unlimited usage`)
   });
 });
 
@@ -60721,14 +60877,14 @@ var init_dtooverridelineitemrequest = __esm(() => {
   init_dtocreatepricetier();
   init_pricetransformquantity();
   DtoOverrideLineItemRequest$zodSchema = object({
-    amount: string2().optional(),
+    amount: string2().optional().describe("Amount is the new price amount that overrides the original price (optional)"),
     billing_model: BillingModel$zodSchema.optional(),
-    price_id: string2(),
-    price_unit_amount: string2().optional(),
-    price_unit_tiers: array(DtoCreatePriceTier$zodSchema).optional(),
-    quantity: string2().optional(),
+    price_id: string2().describe("PriceID references the plan price to override"),
+    price_unit_amount: string2().optional().describe("PriceUnitAmount is the amount of the price unit (for CUSTOM type, FLAT_FEE/PACKAGE billing models)"),
+    price_unit_tiers: array(DtoCreatePriceTier$zodSchema).optional().describe("PriceUnitTiers are the tiers for the price unit (for CUSTOM type, TIERED billing model)"),
+    quantity: string2().optional().describe("Quantity for this line item (optional)"),
     tier_mode: BillingTier$zodSchema.optional(),
-    tiers: array(DtoCreatePriceTier$zodSchema).optional(),
+    tiers: array(DtoCreatePriceTier$zodSchema).optional().describe("Tiers determines the pricing tiers for this line item"),
     transform_quantity: PriceTransformQuantity$zodSchema.optional()
   });
 });
@@ -60739,11 +60895,12 @@ var init_dtosubscriptionphasecreaterequest = __esm(() => {
   init_zod();
   init_dtooverridelineitemrequest();
   DtoSubscriptionPhaseCreateRequest$zodSchema = object({
-    coupons: array(string2()).optional(),
+    coupons: array(string2()).optional().describe("Coupons represents subscription-level coupons to be applied to this phase"),
     end_date: string2().optional(),
-    line_item_coupons: record(string2(), array(string2())).optional(),
+    line_item_coupons: record(string2(), array(string2())).optional().describe("LineItemCoupons represents line item-level coupons (map of line_item_id to coupon IDs)"),
     metadata: record(string2(), string2()).optional(),
-    override_line_items: array(DtoOverrideLineItemRequest$zodSchema).optional(),
+    override_line_items: array(DtoOverrideLineItemRequest$zodSchema).optional().describe(`OverrideLineItems allows customizing specific prices for this phase
+If not provided, phase will use the same line items as the subscription (plan prices)`),
     start_date: string2()
   });
 });
@@ -60792,41 +60949,50 @@ var init_dtocreatesubscriptionrequest = __esm(() => {
   init_prorationbehavior();
   init_subscriptionstatus();
   DtoCreateSubscriptionRequest$zodSchema = object({
-    addons: array(DtoAddAddonToSubscriptionRequest$zodSchema).optional(),
+    addons: array(DtoAddAddonToSubscriptionRequest$zodSchema).optional().describe("Addons represents addons to be added to the subscription during creation"),
     billing_cadence: BillingCadence$zodSchema,
     billing_cycle: BillingCycle$zodSchema.optional(),
     billing_period: BillingPeriod$zodSchema,
     billing_period_count: int().optional(),
     collection_method: CollectionMethod$zodSchema.optional(),
-    commitment_amount: string2().optional(),
+    commitment_amount: string2().optional().describe("CommitmentAmount is the minimum amount a customer commits to paying for a billing period"),
     commitment_duration: BillingPeriod$zodSchema.optional(),
     coupons: array(string2()).optional(),
-    credit_grants: array(DtoCreateCreditGrantRequest$zodSchema).optional(),
+    credit_grants: array(DtoCreateCreditGrantRequest$zodSchema).optional().describe("Credit grants to be applied when subscription is created"),
     currency: string2(),
-    customer_id: string2().optional(),
-    customer_timezone: string2().optional(),
-    enable_true_up: boolean2().optional(),
+    customer_id: string2().optional().describe(`customer_id is the flexprice customer id
+and it is prioritized over external_customer_id in case both are provided.`),
+    customer_timezone: string2().optional().describe(`Timezone of the customer.
+If not set, the default value is UTC.`),
+    enable_true_up: boolean2().optional().describe("Enable Commitment True Up Fee"),
     end_date: string2().optional(),
-    external_customer_id: string2().optional(),
+    external_customer_id: string2().optional().describe(`external_customer_id is the customer id in your DB
+and must be same as what you provided as external_id while creating the customer in flexprice.`),
     gateway_payment_method_id: string2().optional(),
     invoice_billing: InvoiceBilling$zodSchema.optional(),
-    line_item_commitments: record(string2(), DtoLineItemCommitmentConfig$zodSchema).optional(),
+    invoicing_customer_external_id: string2().optional().describe(`invoicing_customer_external_id is the external ID of the customer to use for invoicing.
+Resolved internally to an internal customer ID via external ID lookup.
+Mutually exclusive with invoicing_customer_id.`),
+    invoicing_customer_id: string2().optional().describe(`invoicing_customer_id is the FlexPrice customer ID to use for invoicing.
+This can differ from the subscription customer (e.g., a billing entity invoicing on behalf of another customer).
+Mutually exclusive with invoicing_customer_external_id.`),
+    line_item_commitments: record(string2(), DtoLineItemCommitmentConfig$zodSchema).optional().describe("LineItemCommitments allows setting commitment configuration per line item (keyed by price_id)"),
     line_item_coupons: record(string2(), array(string2())).optional(),
-    line_items: array(DtoCreateSubscriptionLineItemRequest$zodSchema).optional(),
+    line_items: array(DtoCreateSubscriptionLineItemRequest$zodSchema).optional().describe("LineItems are extra line items to add at creation (each with price_id or price), in addition to plan prices"),
     lookup_key: string2().optional(),
     metadata: record(string2(), string2()).optional(),
-    overage_factor: string2().optional(),
-    override_entitlements: array(DtoOverrideEntitlementRequest$zodSchema).optional(),
-    override_line_items: array(DtoOverrideLineItemRequest$zodSchema).optional(),
-    parent_subscription_id: string2().optional(),
+    overage_factor: string2().optional().describe("OverageFactor is a multiplier applied to usage beyond the commitment amount"),
+    override_entitlements: array(DtoOverrideEntitlementRequest$zodSchema).optional().describe("OverrideEntitlements allows customizing specific entitlements for this subscription"),
+    override_line_items: array(DtoOverrideLineItemRequest$zodSchema).optional().describe("OverrideLineItems allows customizing specific prices for this subscription"),
+    parent_subscription_id: string2().optional().describe("ParentSubscriptionID is the parent subscription ID for hierarchy (e.g. child subscription under a parent)"),
     payment_behavior: PaymentBehavior$zodSchema.optional(),
     payment_terms: PaymentTerms$zodSchema.optional(),
-    phases: array(DtoSubscriptionPhaseCreateRequest$zodSchema).optional(),
+    phases: array(DtoSubscriptionPhaseCreateRequest$zodSchema).optional().describe("Phases represents subscription phases to be created with the subscription"),
     plan_id: string2(),
     proration_behavior: ProrationBehavior$zodSchema.optional(),
     start_date: string2().optional(),
     subscription_status: SubscriptionStatus$zodSchema.optional(),
-    tax_rate_overrides: array(DtoTaxRateOverride$zodSchema).optional(),
+    tax_rate_overrides: array(DtoTaxRateOverride$zodSchema).optional().describe("tax_rate_overrides is the tax rate overrides\tto be applied to the subscription"),
     trial_end: string2().optional(),
     trial_start: string2().optional()
   });
@@ -60912,7 +61078,7 @@ var init_subscriptionsCreateSubscription2 = __esm(() => {
   init_dtocreatesubscriptionrequest();
   init_tools();
   args49 = {
-    request: DtoCreateSubscriptionRequest$zodSchema
+    request: DtoCreateSubscriptionRequest$zodSchema.describe(`Subscription Request`)
   };
   tool$subscriptionsCreateSubscription = {
     name: "create-subscription",
@@ -60954,8 +61120,8 @@ var init_dtosubscriptionlineitemresponse = __esm(() => {
   init_subscriptionlineitementitytype();
   DtoSubscriptionLineItemResponse$zodSchema = object({
     billing_period: BillingPeriod$zodSchema.optional(),
-    billing_period_count: int().optional(),
-    commitment_amount: string2().optional(),
+    billing_period_count: int().optional().describe("from price at create; default 1"),
+    commitment_amount: string2().optional().describe("Commitment fields"),
     commitment_duration: BillingPeriod$zodSchema.optional(),
     commitment_overage_factor: string2().optional(),
     commitment_quantity: string2().optional(),
@@ -61002,7 +61168,7 @@ var init_createsubscriptionlineitemop = __esm(() => {
   init_dtosubscriptionlineitemresponse();
   init_errorserrorresponse();
   CreateSubscriptionLineItemRequest$zodSchema = object({
-    body: DtoCreateSubscriptionLineItemRequest$zodSchema,
+    body: DtoCreateSubscriptionLineItemRequest$zodSchema.describe("Create Line Item Request"),
     id: string2().describe("Subscription ID")
   });
   CreateSubscriptionLineItemResponse$zodSchema = union([
@@ -61143,7 +61309,7 @@ var init_deletesubscriptionlineitemop = __esm(() => {
   init_dtosubscriptionlineitemresponse();
   init_errorserrorresponse();
   DeleteSubscriptionLineItemRequest$zodSchema = object({
-    body: DtoDeleteSubscriptionLineItemRequest$zodSchema,
+    body: DtoDeleteSubscriptionLineItemRequest$zodSchema.describe("Delete Line Item Request"),
     id: string2().describe("Line Item ID")
   });
   DeleteSubscriptionLineItemResponse$zodSchema = union([
@@ -61272,17 +61438,17 @@ var DtoProrationDetails$zodSchema;
 var init_dtoprorationdetails = __esm(() => {
   init_zod();
   DtoProrationDetails$zodSchema = object({
-    charge_amount: string2().optional(),
-    charge_description: string2().optional(),
-    credit_amount: string2().optional(),
-    credit_description: string2().optional(),
-    currency: string2().optional(),
-    current_period_end: string2().optional(),
-    current_period_start: string2().optional(),
-    days_remaining: int().optional(),
-    days_used: int().optional(),
-    net_amount: string2().optional(),
-    proration_date: string2().optional()
+    charge_amount: string2().optional().describe("charge_amount is the charge amount for the new subscription"),
+    charge_description: string2().optional().describe("charge_description describes what the charge is for"),
+    credit_amount: string2().optional().describe("credit_amount is the credit amount from the old subscription"),
+    credit_description: string2().optional().describe("credit_description describes what the credit is for"),
+    currency: string2().optional().describe("currency is the currency for all amounts"),
+    current_period_end: string2().optional().describe("current_period_end is the end of the current billing period"),
+    current_period_start: string2().optional().describe("current_period_start is the start of the current billing period"),
+    days_remaining: int().optional().describe("days_remaining is the number of days remaining in the current period"),
+    days_used: int().optional().describe("days_used is the number of days used in the current period"),
+    net_amount: string2().optional().describe("net_amount is the net amount (charge - credit)"),
+    proration_date: string2().optional().describe("proration_date is the date used for proration calculations")
   });
 });
 
@@ -61292,13 +61458,13 @@ var init_dtosubscriptionsummary = __esm(() => {
   init_zod();
   init_subscriptionstatus();
   DtoSubscriptionSummary$zodSchema = object({
-    archived_at: string2().optional(),
-    billing_anchor: string2().optional(),
-    created_at: string2().optional(),
-    current_period_end: string2().optional(),
-    current_period_start: string2().optional(),
-    id: string2().optional(),
-    plan_id: string2().optional(),
+    archived_at: string2().optional().describe("archived_at timestamp (for old subscriptions)"),
+    billing_anchor: string2().optional().describe("billing_anchor of the subscription"),
+    created_at: string2().optional().describe("created_at timestamp"),
+    current_period_end: string2().optional().describe("current_period_end of the subscription"),
+    current_period_start: string2().optional().describe("current_period_start of the subscription"),
+    id: string2().optional().describe("id of the subscription"),
+    plan_id: string2().optional().describe("plan_id of the subscription"),
     status: SubscriptionStatus$zodSchema.optional()
   });
 });
@@ -61325,16 +61491,16 @@ var init_dtosubscriptionchangeexecuteresponse = __esm(() => {
   init_subscriptionchangetype();
   DtoSubscriptionChangeExecuteResponse$zodSchema = object({
     change_type: SubscriptionChangeType$zodSchema.optional(),
-    credit_grants: array(DtoCreditGrantResponse$zodSchema).optional(),
-    effective_date: string2().optional(),
+    credit_grants: array(DtoCreditGrantResponse$zodSchema).optional().describe("credit_grants contains any credit grants created for proration credits"),
+    effective_date: string2().optional().describe("effective_date is when the change took effect"),
     invoice: DtoInvoiceResponse$zodSchema.optional(),
-    is_scheduled: boolean2().optional(),
-    metadata: record(string2(), string2()).optional(),
+    is_scheduled: boolean2().optional().describe("is_scheduled indicates if the change was scheduled or executed immediately"),
+    metadata: record(string2(), string2()).optional().describe("metadata from the request"),
     new_subscription: DtoSubscriptionSummary$zodSchema.optional(),
     old_subscription: DtoSubscriptionSummary$zodSchema.optional(),
     proration_applied: DtoProrationDetails$zodSchema.optional(),
-    schedule_id: string2().optional(),
-    scheduled_at: string2().optional()
+    schedule_id: string2().optional().describe("schedule_id is the ID of the created schedule (only if is_scheduled=true)"),
+    scheduled_at: string2().optional().describe("scheduled_at is when the change will execute (only if is_scheduled=true)")
   }).describe("Response after successfully executing a subscription plan change");
 });
 
@@ -61361,11 +61527,11 @@ var init_dtosubscriptionchangerequest = __esm(() => {
     billing_cadence: BillingCadence$zodSchema,
     billing_cycle: BillingCycle$zodSchema,
     billing_period: BillingPeriod$zodSchema,
-    billing_period_count: int().optional(),
+    billing_period_count: int().optional().describe("billing_period_count is the billing period count for the new subscription"),
     change_at: ScheduleType$zodSchema.optional(),
-    metadata: record(string2(), string2()).optional(),
+    metadata: record(string2(), string2()).optional().describe("metadata contains additional key-value pairs for storing extra information"),
     proration_behavior: ProrationBehavior$zodSchema,
-    target_plan_id: string2()
+    target_plan_id: string2().describe("target_plan_id is the ID of the new plan to change to (required)")
   }).describe("Request object for changing a subscription plan (upgrade/downgrade)");
 });
 
@@ -61377,7 +61543,7 @@ var init_executesubscriptionchangeop = __esm(() => {
   init_dtosubscriptionchangerequest();
   init_errorserrorresponse();
   ExecuteSubscriptionChangeRequest$zodSchema = object({
-    body: DtoSubscriptionChangeRequest$zodSchema,
+    body: DtoSubscriptionChangeRequest$zodSchema.describe("Subscription change request"),
     id: string2().describe("Subscription ID")
   });
   ExecuteSubscriptionChangeResponse$zodSchema = union([
@@ -62303,7 +62469,7 @@ var init_subscriptionsGetSubscriptionUsage2 = __esm(() => {
   init_dtogetusagebysubscriptionrequest();
   init_tools();
   args58 = {
-    request: DtoGetUsageBySubscriptionRequest$zodSchema
+    request: DtoGetUsageBySubscriptionRequest$zodSchema.describe(`Usage request`)
   };
   tool$subscriptionsGetSubscriptionUsage = {
     name: "get-subscription-usage",
@@ -62352,56 +62518,63 @@ var init_dtosubscriptionresponsev2 = __esm(() => {
   init_subscriptionstatus();
   init_subscriptionsubscriptionpause();
   DtoSubscriptionResponseV2$zodSchema = object({
-    active_pause_id: string2().optional(),
-    billing_anchor: string2().optional(),
+    active_pause_id: string2().optional().describe(`ActivePauseID references the current active pause configuration
+This will be null if no pause is active or scheduled`),
+    billing_anchor: string2().optional().describe(`BillingAnchor is the reference point that aligns future billing cycle dates.
+It sets the day of week for week intervals, the day of month for month and year intervals,
+and the month of year for year intervals. The timestamp is in UTC format.`),
     billing_cadence: BillingCadence$zodSchema.optional(),
     billing_cycle: BillingCycle$zodSchema.optional(),
     billing_period: BillingPeriod$zodSchema.optional(),
-    billing_period_count: int().optional(),
-    cancel_at: string2().optional(),
-    cancel_at_period_end: boolean2().optional(),
-    cancelled_at: string2().optional(),
-    collection_method: string2().optional(),
-    commitment_amount: string2().optional(),
+    billing_period_count: int().optional().describe("BillingPeriodCount is the total number units of the billing period."),
+    cancel_at: string2().optional().describe("CancelAt is the date the subscription will be canceled"),
+    cancel_at_period_end: boolean2().optional().describe("CancelAtPeriodEnd is whether the subscription was canceled at the end of the current period"),
+    cancelled_at: string2().optional().describe("CanceledAt is the date the subscription was canceled"),
+    collection_method: string2().optional().describe("CollectionMethod determines how invoices are collected"),
+    commitment_amount: string2().optional().describe("CommitmentAmount is the minimum amount a customer commits to paying for a billing period"),
     commitment_duration: BillingPeriod$zodSchema.optional(),
-    coupon_associations: array(DtoCouponAssociationResponse$zodSchema).optional(),
+    coupon_associations: array(DtoCouponAssociationResponse$zodSchema).optional().describe('CouponAssociations are included when "coupon_associations" is in expand parameter'),
     created_at: string2().optional(),
     created_by: string2().optional(),
-    credit_grants: array(DtoCreditGrantResponse$zodSchema).optional(),
-    currency: string2().optional(),
-    current_period_end: string2().optional(),
-    current_period_start: string2().optional(),
-    customer: DtoCustomerResponse$zodSchema.optional(),
-    customer_id: string2().optional(),
+    credit_grants: array(DtoCreditGrantResponse$zodSchema).optional().describe('CreditGrants are included when "credit_grants" is in expand parameter'),
+    currency: string2().optional().describe("Currency is the currency of the subscription in lowercase 3 digit ISO codes"),
+    current_period_end: string2().optional().describe(`CurrentPeriodEnd is the end of the current period that the subscription has been invoiced for.
+At the end of this period, a new invoice will be created.`),
+    current_period_start: string2().optional().describe(`CurrentPeriodStart is the end of the current period that the subscription has been invoiced for.
+At the end of this period, a new invoice will be created.`),
+    customer: DtoCustomerResponse$zodSchema.optional().describe("Customer response object containing all customer information"),
+    customer_id: string2().optional().describe("CustomerID is the identifier for the customer in our system"),
     customer_timezone: string2().optional(),
     enable_true_up: boolean2().optional(),
-    end_date: string2().optional(),
-    environment_id: string2().optional(),
-    gateway_payment_method_id: string2().optional(),
-    id: string2().optional(),
-    invoicing_customer_id: string2().optional(),
-    line_items: array(DtoSubscriptionLineItemResponse$zodSchema).optional(),
-    lookup_key: string2().optional(),
+    end_date: string2().optional().describe("EndDate is the end date of the subscription"),
+    environment_id: string2().optional().describe("EnvironmentID is the environment identifier for the subscription"),
+    gateway_payment_method_id: string2().optional().describe("GatewayPaymentMethodID is the gateway payment method ID for this subscription"),
+    id: string2().optional().describe("ID is the unique identifier for the subscription"),
+    invoicing_customer_id: string2().optional().describe(`InvoicingCustomerID is the customer ID to use for invoicing
+This can differ from the subscription customer (e.g., parent company invoicing for child company)`),
+    line_items: array(DtoSubscriptionLineItemResponse$zodSchema).optional().describe(`LineItems is expanded only if "subscription_line_items" is in expand parameter
+Each line item can optionally include expanded price data`),
+    lookup_key: string2().optional().describe("LookupKey is the key used to lookup the subscription in our system"),
     metadata: record(string2(), string2()).optional(),
-    overage_factor: string2().optional(),
-    parent_subscription_id: string2().optional(),
+    overage_factor: string2().optional().describe("OverageFactor is a multiplier applied to usage beyond the commitment amount"),
+    parent_subscription_id: string2().optional().describe("ParentSubscriptionID is the parent subscription ID for hierarchy (e.g. child subscription under a parent)"),
     pause_status: PauseStatus$zodSchema.optional(),
-    pauses: array(SubscriptionSubscriptionPause$zodSchema).optional(),
-    payment_behavior: string2().optional(),
+    pauses: array(SubscriptionSubscriptionPause$zodSchema).optional().describe("Pauses are included when subscription has pause status"),
+    payment_behavior: string2().optional().describe("PaymentBehavior determines how subscription payments are handled"),
     payment_terms: PaymentTerms$zodSchema.optional(),
-    phases: array(DtoSubscriptionPhaseResponse$zodSchema).optional(),
+    phases: array(DtoSubscriptionPhaseResponse$zodSchema).optional().describe('Phases are included when "phases" is in expand parameter'),
     plan: DtoPlanResponse$zodSchema.optional(),
-    plan_id: string2().optional(),
+    plan_id: string2().optional().describe("PlanID is the identifier for the plan in our system"),
     proration_behavior: ProrationBehavior$zodSchema.optional(),
-    start_date: string2().optional(),
+    start_date: string2().optional().describe("StartDate is the start date of the subscription"),
     status: Status$zodSchema.optional(),
     subscription_status: SubscriptionStatus$zodSchema.optional(),
     tenant_id: string2().optional(),
-    trial_end: string2().optional(),
-    trial_start: string2().optional(),
+    trial_end: string2().optional().describe("TrialEnd is the end date of the trial period"),
+    trial_start: string2().optional().describe("TrialStart is the start date of the trial period"),
     updated_at: string2().optional(),
     updated_by: string2().optional(),
-    version: int().optional()
+    version: int().optional().describe("Version is used for optimistic locking")
   });
 });
 
@@ -62677,20 +62850,20 @@ var init_dtosubscriptionpauseresponse = __esm(() => {
   DtoSubscriptionPauseResponse$zodSchema = object({
     created_at: string2().optional(),
     created_by: string2().optional(),
-    environment_id: string2().optional(),
-    id: string2().optional(),
+    environment_id: string2().optional().describe("EnvironmentID is the environment identifier for the pause"),
+    id: string2().optional().describe("ID is the unique identifier for the subscription pause"),
     metadata: record(string2(), string2()).optional(),
-    original_period_end: string2().optional(),
-    original_period_start: string2().optional(),
-    pause_end: string2().optional(),
+    original_period_end: string2().optional().describe("OriginalPeriodEnd is the end of the billing period when the pause was created"),
+    original_period_start: string2().optional().describe("OriginalPeriodStart is the start of the billing period when the pause was created"),
+    pause_end: string2().optional().describe("PauseEnd is when the pause will end (null for indefinite)"),
     pause_mode: PauseMode$zodSchema.optional(),
-    pause_start: string2().optional(),
+    pause_start: string2().optional().describe("PauseStart is when the pause actually started"),
     pause_status: PauseStatus$zodSchema.optional(),
-    reason: string2().optional(),
+    reason: string2().optional().describe("Reason is the reason for pausing"),
     resume_mode: ResumeMode$zodSchema.optional(),
-    resumed_at: string2().optional(),
+    resumed_at: string2().optional().describe("ResumedAt is when the pause was actually ended (if manually resumed)"),
     status: Status$zodSchema.optional(),
-    subscription_id: string2().optional(),
+    subscription_id: string2().optional().describe("SubscriptionID is the identifier for the subscription"),
     tenant_id: string2().optional(),
     updated_at: string2().optional(),
     updated_by: string2().optional()
@@ -62703,8 +62876,10 @@ var init_dtolistsubscriptionpausesresponse = __esm(() => {
   init_zod();
   init_dtosubscriptionpauseresponse();
   DtoListSubscriptionPausesResponse$zodSchema = object({
-    items: array(DtoSubscriptionPauseResponse$zodSchema).optional(),
-    total: int().optional()
+    items: array(DtoSubscriptionPauseResponse$zodSchema).optional().describe(`List of subscription pause objects
+@Description Array of subscription pauses`),
+    total: int().optional().describe(`Total number of pauses
+@Description Total count of subscription pauses in the response`)
   }).describe("Response object for listing subscription pauses with total count");
 });
 
@@ -62966,13 +63141,25 @@ var init_dtopausesubscriptionrequest = __esm(() => {
   init_zod();
   init_pausemode();
   DtoPauseSubscriptionRequest$zodSchema = object({
-    dry_run: boolean2().optional(),
-    metadata: record(string2(), string2()).optional(),
-    pause_days: int().optional(),
-    pause_end: string2().optional(),
+    dry_run: boolean2().optional().describe(`Whether to perform a dry run
+@Description If true, validates the request and shows impact without actually pausing the subscription
+@Example false`),
+    metadata: record(string2(), string2()).optional().describe(`Additional metadata as key-value pairs
+@Description Optional metadata for storing additional information about the pause
+@Example {"requested_by": "customer", "channel": "support_ticket"}`),
+    pause_days: int().optional().describe(`Duration of the pause in days
+@Description Number of days to pause the subscription. Cannot be used together with pause_end. Must be greater than 0
+@Example 30`),
+    pause_end: string2().optional().describe(`End date for the subscription pause
+@Description ISO 8601 timestamp when the pause should end. Cannot be used together with pause_days. Must be after pause_start
+@Example "2024-02-15T00:00:00Z"`),
     pause_mode: PauseMode$zodSchema,
-    pause_start: string2().optional(),
-    reason: string2().optional()
+    pause_start: string2().optional().describe(`Start date for the subscription pause
+@Description ISO 8601 timestamp when the pause should begin. Required when pause_mode is "scheduled"
+@Example "2024-01-15T00:00:00Z"`),
+    reason: string2().optional().describe(`Reason for pausing the subscription
+@Description Optional reason for the pause. Maximum 255 characters
+@Example "Customer requested temporary suspension"`)
   }).describe("Request object for pausing an active subscription with various pause modes and options");
 });
 
@@ -62984,7 +63171,7 @@ var init_pausesubscriptionop = __esm(() => {
   init_dtosubscriptionpauseresponse();
   init_errorserrorresponse();
   PauseSubscriptionRequest$zodSchema = object({
-    body: DtoPauseSubscriptionRequest$zodSchema,
+    body: DtoPauseSubscriptionRequest$zodSchema.describe("Pause subscription request"),
     id: string2().describe("Subscription ID")
   });
   PauseSubscriptionResponse$zodSchema = union([
@@ -63115,12 +63302,12 @@ var init_dtobillingcycleinfo = __esm(() => {
   init_billingcadence();
   init_billingperiod();
   DtoBillingCycleInfo$zodSchema = object({
-    billing_anchor: string2().optional(),
+    billing_anchor: string2().optional().describe("billing_anchor is the new billing anchor"),
     billing_cadence: BillingCadence$zodSchema.optional(),
     billing_period: BillingPeriod$zodSchema.optional(),
-    billing_period_count: int().optional(),
-    period_end: string2().optional(),
-    period_start: string2().optional()
+    billing_period_count: int().optional().describe("billing_period_count is the billing period count"),
+    period_end: string2().optional().describe("period_end is the end of the new billing period"),
+    period_start: string2().optional().describe("period_start is the start of the new billing period")
   });
 });
 
@@ -63129,13 +63316,13 @@ var DtoInvoiceLineItemPreview$zodSchema;
 var init_dtoinvoicelineitempreview = __esm(() => {
   init_zod();
   DtoInvoiceLineItemPreview$zodSchema = object({
-    amount: string2().optional(),
-    description: string2().optional(),
-    is_proration: boolean2().optional(),
-    period_end: string2().optional(),
-    period_start: string2().optional(),
-    quantity: string2().optional(),
-    unit_price: string2().optional()
+    amount: string2().optional().describe("amount for this line item"),
+    description: string2().optional().describe("description of the line item"),
+    is_proration: boolean2().optional().describe("is_proration indicates if this line item is a proration"),
+    period_end: string2().optional().describe("period_end for this line item (if applicable)"),
+    period_start: string2().optional().describe("period_start for this line item (if applicable)"),
+    quantity: string2().optional().describe("quantity for this line item"),
+    unit_price: string2().optional().describe("unit_price for this line item")
   });
 });
 
@@ -63145,12 +63332,12 @@ var init_dtoinvoicepreview = __esm(() => {
   init_zod();
   init_dtoinvoicelineitempreview();
   DtoInvoicePreview$zodSchema = object({
-    currency: string2().optional(),
-    due_date: string2().optional(),
-    line_items: array(DtoInvoiceLineItemPreview$zodSchema).optional(),
-    subtotal: string2().optional(),
-    tax_amount: string2().optional(),
-    total: string2().optional()
+    currency: string2().optional().describe("currency is the currency for all amounts"),
+    due_date: string2().optional().describe("due_date is when the invoice would be due"),
+    line_items: array(DtoInvoiceLineItemPreview$zodSchema).optional().describe("line_items contains preview of line items"),
+    subtotal: string2().optional().describe("subtotal is the subtotal amount before taxes"),
+    tax_amount: string2().optional().describe("tax_amount is the total tax amount"),
+    total: string2().optional().describe("total is the total amount including taxes")
   });
 });
 
@@ -63159,10 +63346,10 @@ var DtoPlanSummary$zodSchema;
 var init_dtoplansummary = __esm(() => {
   init_zod();
   DtoPlanSummary$zodSchema = object({
-    description: string2().optional(),
-    id: string2().optional(),
-    lookup_key: string2().optional(),
-    name: string2().optional()
+    description: string2().optional().describe("description of the plan"),
+    id: string2().optional().describe("id of the plan"),
+    lookup_key: string2().optional().describe("lookup_key of the plan"),
+    name: string2().optional().describe("name of the plan")
   });
 });
 
@@ -63178,14 +63365,14 @@ var init_dtosubscriptionchangepreviewresponse = __esm(() => {
   DtoSubscriptionChangePreviewResponse$zodSchema = object({
     change_type: SubscriptionChangeType$zodSchema.optional(),
     current_plan: DtoPlanSummary$zodSchema.optional(),
-    effective_date: string2().optional(),
-    metadata: record(string2(), string2()).optional(),
+    effective_date: string2().optional().describe("effective_date is when the change would take effect"),
+    metadata: record(string2(), string2()).optional().describe("metadata from the request"),
     new_billing_cycle: DtoBillingCycleInfo$zodSchema.optional(),
     next_invoice_preview: DtoInvoicePreview$zodSchema.optional(),
     proration_details: DtoProrationDetails$zodSchema.optional(),
-    subscription_id: string2().optional(),
+    subscription_id: string2().optional().describe("subscription_id is the ID of the subscription being changed"),
     target_plan: DtoPlanSummary$zodSchema.optional(),
-    warnings: array(string2()).optional()
+    warnings: array(string2()).optional().describe("warnings contains any warnings about the change")
   }).describe("Response showing the financial impact of a subscription plan change");
 });
 
@@ -63197,7 +63384,7 @@ var init_previewsubscriptionchangeop = __esm(() => {
   init_dtosubscriptionchangerequest();
   init_errorserrorresponse();
   PreviewSubscriptionChangeRequest$zodSchema = object({
-    body: DtoSubscriptionChangeRequest$zodSchema,
+    body: DtoSubscriptionChangeRequest$zodSchema.describe("Subscription change preview request"),
     id: string2().describe("Subscription ID")
   });
   PreviewSubscriptionChangeResponse$zodSchema = union([
@@ -63336,26 +63523,26 @@ var init_subscriptionfilter = __esm(() => {
     "desc"
   ]);
   SubscriptionFilter$zodSchema = object({
-    active_at: string2().optional(),
-    billing_cadence: array(BillingCadence$zodSchema).optional(),
-    billing_period: array(BillingPeriod$zodSchema).optional(),
-    customer_id: string2().optional(),
+    active_at: string2().optional().describe("ActiveAt filters subscriptions that are active at the given time"),
+    billing_cadence: array(BillingCadence$zodSchema).optional().describe("BillingCadence filters by billing cadence"),
+    billing_period: array(BillingPeriod$zodSchema).optional().describe("BillingPeriod filters by billing period"),
+    customer_id: string2().optional().describe("CustomerID filters by customer ID"),
     end_time: string2().optional(),
     expand: string2().optional(),
-    external_customer_id: string2().optional(),
+    external_customer_id: string2().optional().describe("ExternalCustomerID filters by external customer ID"),
     filters: array(FilterCondition$zodSchema).optional(),
-    invoicing_customer_ids: array(string2()).optional(),
+    invoicing_customer_ids: array(string2()).optional().describe("InvoicingCustomerIDs filters by invoicing customer ID"),
     limit: int().optional(),
     offset: int().optional(),
     order: SubscriptionFilterOrder$zodSchema.optional(),
-    parent_subscription_ids: array(string2()).optional(),
-    plan_id: string2().optional(),
+    parent_subscription_ids: array(string2()).optional().describe("ParentSubscriptionIDs filters by parent subscription IDs"),
+    plan_id: string2().optional().describe("PlanID filters by plan ID"),
     sort: array(SortCondition$zodSchema).optional(),
     start_time: string2().optional(),
     status: Status$zodSchema.optional(),
     subscription_ids: array(string2()).optional(),
-    subscription_status: array(SubscriptionStatus$zodSchema).optional(),
-    with_line_items: boolean2().optional()
+    subscription_status: array(SubscriptionStatus$zodSchema).optional().describe("SubscriptionStatus filters by subscription status"),
+    with_line_items: boolean2().optional().describe("WithLineItems includes line items in the response")
   });
 });
 
@@ -63439,7 +63626,7 @@ var init_subscriptionsQuerySubscription2 = __esm(() => {
   init_subscriptionfilter();
   init_tools();
   args65 = {
-    request: SubscriptionFilter$zodSchema
+    request: SubscriptionFilter$zodSchema.describe(`Filter`)
   };
   tool$subscriptionsQuerySubscription = {
     name: "query-subscription",
@@ -63558,7 +63745,7 @@ var init_subscriptionsRemoveSubscriptionAddon2 = __esm(() => {
   init_dtoremoveaddonrequest();
   init_tools();
   args66 = {
-    request: DtoRemoveAddonRequest$zodSchema
+    request: DtoRemoveAddonRequest$zodSchema.describe(`Remove Addon Request`)
   };
   tool$subscriptionsRemoveSubscriptionAddon = {
     name: "remove-subscription-addon",
@@ -63593,8 +63780,12 @@ var init_dtoresumesubscriptionrequest = __esm(() => {
   init_zod();
   init_resumemode();
   DtoResumeSubscriptionRequest$zodSchema = object({
-    dry_run: boolean2().optional(),
-    metadata: record(string2(), string2()).optional(),
+    dry_run: boolean2().optional().describe(`Whether to perform a dry run
+@Description If true, validates the request and shows impact without actually resuming the subscription
+@Example false`),
+    metadata: record(string2(), string2()).optional().describe(`Additional metadata as key-value pairs
+@Description Optional metadata for storing additional information about the resume operation
+@Example {"resumed_by": "admin", "reason": "issue_resolved"}`),
     resume_mode: ResumeMode$zodSchema
   }).describe("Request object for resuming a paused subscription");
 });
@@ -63607,7 +63798,7 @@ var init_resumesubscriptionop = __esm(() => {
   init_dtosubscriptionpauseresponse();
   init_errorserrorresponse();
   ResumeSubscriptionRequest$zodSchema = object({
-    body: DtoResumeSubscriptionRequest$zodSchema,
+    body: DtoResumeSubscriptionRequest$zodSchema.describe("Resume subscription request"),
     id: string2().describe("Subscription ID")
   });
   ResumeSubscriptionResponse$zodSchema = union([
@@ -63739,7 +63930,7 @@ var init_dtoupdatesubscriptionrequest = __esm(() => {
   DtoUpdateSubscriptionRequest$zodSchema = object({
     cancel_at: string2().optional(),
     cancel_at_period_end: boolean2().optional(),
-    parent_subscription_id: string2().optional(),
+    parent_subscription_id: string2().optional().describe('ParentSubscriptionID sets or clears the parent subscription. Omit to leave unchanged; send "" to clear.'),
     status: SubscriptionStatus$zodSchema.optional()
   });
 });
@@ -63752,7 +63943,7 @@ var init_updatesubscriptionop = __esm(() => {
   init_dtoupdatesubscriptionrequest();
   init_errorserrorresponse();
   UpdateSubscriptionRequest$zodSchema = object({
-    body: DtoUpdateSubscriptionRequest$zodSchema,
+    body: DtoUpdateSubscriptionRequest$zodSchema.describe("Update Subscription Request"),
     id: string2().describe("Subscription ID")
   });
   UpdateSubscriptionResponse$zodSchema = union([
@@ -63887,19 +64078,19 @@ var init_dtoupdatesubscriptionlineitemrequest = __esm(() => {
   init_dtocreatepricetier();
   init_pricetransformquantity();
   DtoUpdateSubscriptionLineItemRequest$zodSchema = object({
-    amount: string2().optional(),
+    amount: string2().optional().describe("Amount is the new price amount that overrides the original price"),
     billing_model: BillingModel$zodSchema.optional(),
-    commitment_amount: number2().optional(),
+    commitment_amount: number2().optional().describe("Commitment fields"),
     commitment_duration: BillingPeriod$zodSchema.optional(),
     commitment_overage_factor: number2().optional(),
     commitment_quantity: number2().optional(),
     commitment_true_up_enabled: boolean2().optional(),
     commitment_type: CommitmentType$zodSchema.optional(),
     commitment_windowed: boolean2().optional(),
-    effective_from: string2().optional(),
-    metadata: record(string2(), string2()).optional(),
+    effective_from: string2().optional().describe("EffectiveFrom for the existing line item (if not provided, defaults to now)"),
+    metadata: record(string2(), string2()).optional().describe("Metadata for the new line item"),
     tier_mode: BillingTier$zodSchema.optional(),
-    tiers: array(DtoCreatePriceTier$zodSchema).optional(),
+    tiers: array(DtoCreatePriceTier$zodSchema).optional().describe("Tiers determines the pricing tiers for this line item"),
     transform_quantity: PriceTransformQuantity$zodSchema.optional()
   });
 });
@@ -63912,7 +64103,7 @@ var init_updatesubscriptionlineitemop = __esm(() => {
   init_dtoupdatesubscriptionlineitemrequest();
   init_errorserrorresponse();
   UpdateSubscriptionLineItemRequest$zodSchema = object({
-    body: DtoUpdateSubscriptionLineItemRequest$zodSchema,
+    body: DtoUpdateSubscriptionLineItemRequest$zodSchema.describe("Update Line Item Request"),
     id: string2().describe("Line Item ID")
   });
   UpdateSubscriptionLineItemResponse$zodSchema = union([
@@ -64040,7 +64231,7 @@ Use when changing a subscription line item (e.g. quantity or price). Implemented
 function createMCPServer(deps) {
   const server = new McpServer({
     name: "Flexprice",
-    version: "2.0.10"
+    version: "2.0.12"
   });
   const getClient = deps.getSDK || (() => new FlexpriceCore({
     security: deps.security,
@@ -64054,7 +64245,7 @@ function createMCPServer(deps) {
   }));
   const scopes = new Set(deps.scopes);
   const allowedTools = deps.allowedTools && new Set(deps.allowedTools);
-  const [tool, tools, toolMap] = createRegisterTool(deps.logger, server, getClient, scopes, allowedTools, deps.dynamic);
+  const [tool, tools, toolMap] = createRegisterTool(deps.logger, server, getClient, scopes, allowedTools, deps.dynamic, deps.annotationFilter);
   const resource = createRegisterResource(deps.logger, server, getClient, scopes);
   const resourceTemplate = createRegisterResourceTemplate(deps.logger, server, getClient, scopes);
   const prompt = createRegisterPrompt(deps.logger, server, getClient, scopes);
@@ -65726,6 +65917,7 @@ async function startStreamableHTTP(cliFlags) {
       logger,
       allowedTools: cliFlags.tool,
       dynamic: cliFlags.mode === "dynamic",
+      annotationFilter: buildAnnotationFilter(cliFlags["tool-annotations"]),
       scopes: cliFlags.scope,
       serverURL: cliFlags["server-url"],
       getSDK: () => buildSDK(headers, cliFlags, cliFlags["disable-static-auth"], logger),
@@ -65767,6 +65959,7 @@ var init_impl = __esm(() => {
   init_console_logger();
   init_server2();
   init_tools();
+  init_tools();
   init_landing_page();
   import_express = __toESM(require_express(), 1);
 });
@@ -66018,6 +66211,7 @@ async function startStdio(flags) {
     logger,
     allowedTools: flags.tool,
     dynamic: flags.mode === "dynamic",
+    annotationFilter: buildAnnotationFilter(flags["tool-annotations"]),
     scopes: flags.scope,
     security: { ApiKeyAuth: flags["api-key-auth"] ?? "" },
     serverURL: flags["server-url"],
@@ -66057,6 +66251,7 @@ async function startSSE(cliFlags) {
       logger,
       allowedTools: flags.tool,
       dynamic: flags.mode === "dynamic",
+      annotationFilter: buildAnnotationFilter(flags["tool-annotations"]),
       scopes: flags.scope,
       security: { ApiKeyAuth: flags["api-key-auth"] ?? "" },
       serverURL: flags["server-url"],
@@ -66142,6 +66337,7 @@ var init_impl2 = __esm(() => {
   init_stdio2();
   init_console_logger();
   init_server2();
+  init_tools();
   init_landing_page();
   import_express2 = __toESM(require_express(), 1);
 });
@@ -67987,6 +68183,12 @@ var serveCommand = buildCommand({
         values: ["dynamic"],
         optional: true
       },
+      "tool-annotations": {
+        kind: "parsed",
+        brief: "Filter tools by annotations (comma-separated: readOnly, destructive, idempotent, openWorld). Listed = required true, unlisted = required false.",
+        optional: true,
+        parse: (value) => value.split(",").map((s) => s.trim())
+      },
       scope: {
         kind: "enum",
         brief: "Mount tools/resources that match given scope (repeatable flag)",
@@ -68087,6 +68289,12 @@ var startCommand = buildCommand({
         values: ["dynamic"],
         optional: true
       },
+      "tool-annotations": {
+        kind: "parsed",
+        brief: "Filter tools by annotations (comma-separated: readOnly, destructive, idempotent, openWorld). Listed = required true, unlisted = required false.",
+        optional: true,
+        parse: (value) => value.split(",").map((s) => s.trim())
+      },
       scope: {
         kind: "enum",
         brief: "Mount tools/resources that match given scope (repeatable flag)",
@@ -68162,7 +68370,7 @@ var routes = buildRouteMap({
 var app = buildApplication(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "2.0.10"
+    currentVersion: "2.0.12"
   }
 });
 run(app, process4.argv.slice(2), buildContext(process4));
@@ -68170,5 +68378,5 @@ export {
   app
 };
 
-//# debugId=9AE395F6C07E14E464756E2164756E21
+//# debugId=890F6D70DC5AE33C64756E2164756E21
 //# sourceMappingURL=mcp-server.js.map