@armor/zuora-mcp 0.0.0-development

package/dist/tools.js

@@ -0,0 +1,2841 @@
+/**
+ * MCP Tool Definitions for Zuora Billing Operations
+ * Provides account, invoice, subscription, payment, and ZOQL query tools
+ */
+import { z } from "zod";
+import { queryAll, escapeZoql, todayString, addDays, subtractDays, daysBetween, getString, getNumber, collectIds, queryWithBatchedIds, } from "./zoql-helpers.js";
+// ==================== Helpers ====================
+function isValidCalendarDate(dateStr) {
+    const [year, month, day] = dateStr.split("-").map(Number);
+    const date = new Date(year, month - 1, day);
+    return (date.getFullYear() === year &&
+        date.getMonth() === month - 1 &&
+        date.getDate() === day);
+}
+// ==================== Shared Schemas ====================
+/** Contact fields for account creation (name + email required) */
+const contactSchema = z.object({
+    firstName: z.string().min(1).max(100).describe("First name"),
+    lastName: z.string().min(1).max(100).describe("Last name"),
+    workEmail: z.string().email("Must be a valid email address").describe("Work email address"),
+    address1: z.string().max(255).optional().describe("Street address line 1"),
+    city: z.string().max(100).optional().describe("City"),
+    state: z.string().max(100).optional().describe("State or province"),
+    postalCode: z.string().max(20).optional().describe("Postal/ZIP code"),
+    country: z.string().max(100).optional().describe("Country (ISO 3166 name or code)"),
+});
+/** Contact fields for account updates (all fields optional for partial updates) */
+const partialContactSchema = contactSchema.partial();
+// ==================== Input Schemas ====================
+export const schemas = {
+    // Account Tools
+    getAccount: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number (e.g., 2c92c0f8..., or A00000001)"),
+    }),
+    getAccountSummary: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number"),
+    }),
+    // Invoice Tools
+    getInvoice: z.object({
+        invoiceId: z
+            .string()
+            .min(1)
+            .describe("Invoice ID (e.g., 2c92c0f8...)"),
+    }),
+    listInvoices: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number to list invoices for"),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    // Subscription Tools
+    getSubscription: z.object({
+        subscriptionKey: z
+            .string()
+            .min(1)
+            .describe("Subscription key or ID (e.g., A-S00000001)"),
+    }),
+    listSubscriptions: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number"),
+    }),
+    // Payment Tools
+    getPayment: z.object({
+        paymentId: z.string().min(1).describe("Payment ID"),
+    }),
+    listPayments: z.object({
+        accountKey: z
+            .string()
+            .optional()
+            .describe("Account key to filter payments (optional, lists all if omitted)"),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    // ZOQL Query Tools
+    executeZoqlQuery: z.object({
+        zoqlQuery: z
+            .string()
+            .min(1)
+            .max(10000)
+            .refine((q) => /^\s*SELECT\s+/i.test(q), {
+            message: "ZOQL query must begin with SELECT",
+        })
+            .describe("ZOQL (Zuora Object Query Language) query string. " +
+            "Syntax: SELECT field1, field2 FROM ObjectName WHERE condition. " +
+            "Key objects: Account, Invoice, Payment, Subscription, RatePlan, " +
+            "RatePlanCharge, Product, ProductRatePlan, Contact. " +
+            "Limitations: No JOINs. Max 2000 records per call. " +
+            "Use continue_zoql_query with queryLocator for pagination. " +
+            "Example: SELECT Id, AccountNumber, Balance FROM Account WHERE Status = 'Active'"),
+    }),
+    continueZoqlQuery: z.object({
+        queryLocator: z
+            .string()
+            .min(1)
+            .describe("Query locator from a previous ZOQL query result for pagination"),
+    }),
+    // Product Catalog Tools
+    listProducts: z.object({
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    // Phase 2: Extended Read Tools
+    getInvoiceFiles: z.object({
+        invoiceId: z
+            .string()
+            .min(1)
+            .describe("Invoice ID to retrieve associated PDF files for"),
+    }),
+    getCreditMemo: z.object({
+        creditMemoId: z
+            .string()
+            .min(1)
+            .describe("Credit memo ID (e.g., 2c92c0f8...)"),
+    }),
+    listCreditMemos: z.object({
+        accountId: z
+            .string()
+            .optional()
+            .describe("Zuora account UUID (e.g., 2c92c0f8...) to filter credit memos. " +
+            "Use get_account to retrieve the account ID from an account number. " +
+            "Optional; lists all if omitted."),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    searchAccounts: z.object({
+        field: z
+            .enum([
+            "Name",
+            "AccountNumber",
+            "Status",
+            "Currency",
+            "Balance",
+        ])
+            .describe("Account field to search by (Name, AccountNumber, Status, Currency, Balance)"),
+        value: z
+            .string()
+            .min(1)
+            .max(255)
+            .refine((v) => /[^%_]/.test(v), {
+            message: "Value must contain at least one non-wildcard character",
+        })
+            .describe("Value to search for"),
+        operator: z
+            .enum(["=", "!=", "LIKE", ">", "<", ">=", "<="])
+            .default("=")
+            .describe("Comparison operator (default: =). Use LIKE for partial name matches with % wildcard."),
+    }),
+    listUsage: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number to retrieve usage records for"),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    // User Management Tools
+    listUsers: z.object({
+        startIndex: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("1-based start index for SCIM pagination (default: 1)"),
+        count: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(100)
+            .describe("Number of users to return per page (default: 100, max: 100)"),
+        filter: z
+            .string()
+            .max(500)
+            .optional()
+            .describe("SCIM filter string (optional). " +
+            "Examples: status eq \"Active\", userName eq \"user@example.com\""),
+    }),
+    getUser: z.object({
+        userId: z
+            .string()
+            .uuid("User ID must be a valid UUID")
+            .describe("Zuora user ID (UUID format)"),
+    }),
+    // Bill Run Read Tools
+    getBillRun: z.object({
+        billRunId: z
+            .string()
+            .min(1)
+            .describe("Bill run ID (e.g., 2c92c0f8...)"),
+    }),
+    listBillRuns: z.object({
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    // Contact Read Tools
+    getContact: z.object({
+        contactId: z
+            .string()
+            .min(1)
+            .describe("Contact ID (e.g., 2c92c0f8...)"),
+    }),
+    // Describe API
+    describeObject: z.object({
+        objectType: z
+            .string()
+            .min(1)
+            .max(100)
+            .regex(/^[A-Z][a-zA-Z]*$/, "Object type must be PascalCase (e.g., Account, Invoice, Subscription)")
+            .describe("Zuora object type name in PascalCase (e.g., Account, Invoice, Subscription, " +
+            "Payment, RatePlan, RatePlanCharge, Product, ProductRatePlan, BillRun, Contact)"),
+    }),
+    // Phase 3: Write Operations
+    createPayment: z.object({
+        accountId: z
+            .string()
+            .min(1)
+            .describe("Zuora account UUID to create the payment for"),
+        amount: z
+            .number()
+            .positive()
+            .max(1_000_000)
+            .refine((n) => Math.round(n * 100) === n * 100, "Amount must have at most 2 decimal places")
+            .describe("Payment amount (positive, max 1,000,000, up to 2 decimal places)"),
+        effectiveDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .describe("Payment effective date in YYYY-MM-DD format"),
+        type: z
+            .enum(["Electronic", "External"])
+            .describe("Payment type: Electronic (gateway) or External (check, wire, etc.)"),
+        paymentMethodId: z
+            .string()
+            .optional()
+            .describe("Payment method ID. Required for Electronic type. " +
+            "Use get_account to find available payment methods."),
+        comment: z
+            .string()
+            .max(1000)
+            .optional()
+            .describe("Optional comment for the payment record"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate payments on retries. " +
+            "Generate a new UUID v4 for each distinct payment intent."),
+    }).superRefine((data, ctx) => {
+        if (data.type === "Electronic" && !data.paymentMethodId) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["paymentMethodId"],
+                message: "paymentMethodId is required when type is Electronic",
+            });
+        }
+    }),
+    applyPayment: z.object({
+        paymentId: z
+            .string()
+            .min(1)
+            .describe("ID of the unapplied payment to apply to invoices"),
+        invoices: z
+            .array(z.object({
+            invoiceId: z.string().min(1).describe("Invoice ID to apply payment to"),
+            amount: z
+                .number()
+                .positive()
+                .max(1_000_000)
+                .refine((n) => Math.round(n * 100) === n * 100, "Amount must have at most 2 decimal places")
+                .describe("Amount to apply to this invoice"),
+        }))
+            .min(1)
+            .max(50)
+            .describe("Invoice allocations: which invoices to apply the payment to and how much. " +
+            "Max 50 per call; split larger batches into multiple calls."),
+        effectiveDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Effective date for the application in YYYY-MM-DD format (optional)"),
+    }),
+    createInvoice: z.object({
+        accountId: z
+            .string()
+            .min(1)
+            .describe("Zuora account UUID to create the invoice for"),
+        invoiceDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .describe("Invoice date in YYYY-MM-DD format"),
+        dueDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Due date in YYYY-MM-DD format (optional, uses payment terms if omitted)"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate invoice creation on retries. " +
+            "Generate a new UUID v4 for each distinct invoice intent."),
+    }),
+    postInvoice: z.object({
+        invoiceId: z
+            .string()
+            .min(1)
+            .describe("ID of the draft invoice to post. " +
+            "Once posted, the invoice is immutable and affects account balance."),
+    }),
+    cancelSubscription: z.object({
+        subscriptionKey: z
+            .string()
+            .min(1)
+            .describe("Subscription key or ID (e.g., A-S00000001) to cancel"),
+        cancellationPolicy: z
+            .enum(["EndOfCurrentTerm", "EndOfLastInvoicePeriod", "SpecificDate"])
+            .describe("When the cancellation takes effect: " +
+            "EndOfCurrentTerm (cancel at term end), " +
+            "EndOfLastInvoicePeriod (cancel at end of last billed period), " +
+            "SpecificDate (cancel on a specific date, requires cancellationEffectiveDate)"),
+        cancellationEffectiveDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Required when cancellationPolicy is SpecificDate. The date cancellation takes effect."),
+        invoiceCollect: z
+            .boolean()
+            .default(false)
+            .describe("Whether to generate and collect an invoice for the cancellation charges (default: false)"),
+    }).superRefine((data, ctx) => {
+        if (data.cancellationPolicy === "SpecificDate" && !data.cancellationEffectiveDate) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["cancellationEffectiveDate"],
+                message: "cancellationEffectiveDate is required when cancellationPolicy is SpecificDate",
+            });
+        }
+    }),
+    // Phase 4: Advanced Operations
+    createSubscription: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number to create the subscription for"),
+        contractEffectiveDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .describe("Date the subscription contract takes effect in YYYY-MM-DD format"),
+        serviceActivationDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Date the subscription service is activated (optional). " +
+            "Required if the Zuora tenant has 'Require Service Activation' enabled."),
+        customerAcceptanceDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Date the customer accepted the subscription (optional). " +
+            "Required if the Zuora tenant has 'Require Customer Acceptance' enabled."),
+        termType: z
+            .enum(["TERMED", "EVERGREEN"])
+            .describe("Subscription term type: TERMED (fixed duration) or EVERGREEN (no end date)"),
+        initialTerm: z
+            .number()
+            .int()
+            .positive()
+            .max(1200)
+            .optional()
+            .describe("Initial term length (required for TERMED). Max 1200."),
+        initialTermPeriodType: z
+            .enum(["Month", "Year", "Day", "Week"])
+            .optional()
+            .describe("Period type for the initial term (required for TERMED)"),
+        renewalTerm: z
+            .number()
+            .int()
+            .positive()
+            .max(1200)
+            .optional()
+            .describe("Renewal term length (optional)"),
+        renewalTermPeriodType: z
+            .enum(["Month", "Year", "Day", "Week"])
+            .optional()
+            .describe("Period type for the renewal term"),
+        autoRenew: z
+            .boolean()
+            .default(false)
+            .describe("Whether the subscription auto-renews at term end (default: false)"),
+        subscribeToRatePlans: z
+            .array(z.object({
+            productRatePlanId: z
+                .string()
+                .min(1)
+                .describe("Product rate plan ID from the product catalog"),
+        }))
+            .min(1)
+            .max(50)
+            .describe("Rate plans to subscribe to. Use list_products to find productRatePlanIds. " +
+            "At least 1, max 50 per call."),
+        notes: z
+            .string()
+            .max(2000)
+            .optional()
+            .describe("Optional notes for the subscription"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate subscriptions on retries. " +
+            "Generate a new UUID v4 for each distinct subscription intent."),
+    }).superRefine((data, ctx) => {
+        if (data.termType === "TERMED" && !data.initialTerm) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["initialTerm"],
+                message: "initialTerm is required when termType is TERMED",
+            });
+        }
+        if (data.termType === "TERMED" && !data.initialTermPeriodType) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["initialTermPeriodType"],
+                message: "initialTermPeriodType is required when termType is TERMED",
+            });
+        }
+        if ((data.renewalTerm !== undefined) !== (data.renewalTermPeriodType !== undefined)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [data.renewalTerm !== undefined ? "renewalTermPeriodType" : "renewalTerm"],
+                message: "renewalTerm and renewalTermPeriodType must be provided together",
+            });
+        }
+    }),
+    updateSubscription: z.object({
+        subscriptionKey: z
+            .string()
+            .min(1)
+            .describe("Subscription key or ID to update (e.g., A-S00000001)"),
+        autoRenew: z
+            .boolean()
+            .optional()
+            .describe("Whether the subscription auto-renews at term end"),
+        renewalTerm: z
+            .number()
+            .int()
+            .positive()
+            .max(1200)
+            .optional()
+            .describe("Renewal term length"),
+        renewalTermPeriodType: z
+            .enum(["Month", "Year", "Day", "Week"])
+            .optional()
+            .describe("Period type for the renewal term"),
+        notes: z
+            .string()
+            .max(2000)
+            .optional()
+            .describe("Notes for the subscription"),
+    }).superRefine((data, ctx) => {
+        const { subscriptionKey: _, ...updateFields } = data;
+        const hasUpdate = Object.values(updateFields).some((v) => v !== undefined);
+        if (!hasUpdate) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [],
+                message: "At least one field to update must be provided (autoRenew, renewalTerm, renewalTermPeriodType, or notes)",
+            });
+        }
+        if ((data.renewalTerm !== undefined) !== (data.renewalTermPeriodType !== undefined)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [data.renewalTerm !== undefined ? "renewalTermPeriodType" : "renewalTerm"],
+                message: "renewalTerm and renewalTermPeriodType must be provided together",
+            });
+        }
+    }),
+    createAccount: z.object({
+        name: z
+            .string()
+            .min(1)
+            .max(255)
+            .describe("Account name"),
+        currency: z
+            .string()
+            .regex(/^[A-Z]{3}$/, "Currency must be a 3-letter ISO 4217 code (e.g., USD, EUR)")
+            .describe("ISO 4217 currency code (e.g., USD, EUR, GBP)"),
+        billCycleDay: z
+            .number()
+            .int()
+            .min(1)
+            .max(31)
+            .describe("Day of month for billing cycle (1-31). Zuora normalizes values beyond a month's last day."),
+        billToContact: contactSchema
+            .describe("Bill-to contact information (required)"),
+        soldToContact: contactSchema
+            .optional()
+            .describe("Sold-to contact information (optional, defaults to bill-to if omitted)"),
+        paymentTerm: z
+            .string()
+            .max(100)
+            .optional()
+            .describe("Payment terms (e.g., 'Net 30', 'Due Upon Receipt')"),
+        autoPay: z
+            .boolean()
+            .default(false)
+            .describe("Whether to auto-collect payments (default: false)"),
+        notes: z
+            .string()
+            .max(2000)
+            .optional()
+            .describe("Optional account notes"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate account creation on retries. " +
+            "Generate a new UUID v4 for each distinct account intent."),
+    }),
+    updateAccount: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number to update"),
+        name: z
+            .string()
+            .min(1)
+            .max(255)
+            .optional()
+            .describe("Updated account name"),
+        notes: z
+            .string()
+            .max(2000)
+            .optional()
+            .describe("Updated account notes"),
+        autoPay: z
+            .boolean()
+            .optional()
+            .describe("Whether to auto-collect payments"),
+        paymentTerm: z
+            .string()
+            .max(100)
+            .optional()
+            .describe("Updated payment terms (e.g., 'Net 30')"),
+        billToContact: partialContactSchema
+            .optional()
+            .describe("Updated bill-to contact fields (only include fields to change)"),
+        soldToContact: partialContactSchema
+            .optional()
+            .describe("Updated sold-to contact fields (only include fields to change)"),
+    }).superRefine((data, ctx) => {
+        const { accountKey: _, ...updateFields } = data;
+        const hasUpdate = Object.values(updateFields).some((v) => v !== undefined);
+        if (!hasUpdate) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [],
+                message: "At least one field to update must be provided",
+            });
+        }
+    }),
+    createRefund: z.object({
+        paymentId: z
+            .string()
+            .min(1)
+            .describe("ID of the original payment to refund. " +
+            "Use get_payment to verify the payment exists and has sufficient applied amount."),
+        amount: z
+            .number()
+            .positive()
+            .max(1_000_000)
+            .refine((n) => Math.round(n * 100) === n * 100, "Amount must have at most 2 decimal places")
+            .describe("Refund amount (positive, max 1,000,000, up to 2 decimal places)"),
+        type: z
+            .enum(["Electronic", "External"])
+            .describe("Refund type: Electronic (refund via payment gateway) or External (manual refund record)"),
+        comment: z
+            .string()
+            .max(1000)
+            .optional()
+            .describe("Optional reason/comment for the refund"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate refunds on retries. " +
+            "Generate a new UUID v4 for each distinct refund intent."),
+    }),
+    // Bill Run Write Tools
+    createBillRun: z.object({
+        targetDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .describe("Target date for the bill run in YYYY-MM-DD format. Invoices are generated for charges through this date."),
+        invoiceDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Invoice date in YYYY-MM-DD format (optional, defaults to targetDate)"),
+        autoPost: z
+            .boolean()
+            .default(false)
+            .describe("Automatically post invoices after generation (default: false)"),
+        autoEmail: z
+            .boolean()
+            .default(false)
+            .describe("Automatically email invoices after posting (default: false). Requires autoPost to be true."),
+        name: z
+            .string()
+            .max(255)
+            .optional()
+            .describe("Optional name/label for the bill run"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate bill runs on retries. " +
+            "Generate a new UUID v4 for each distinct bill run intent."),
+    }).superRefine((data, ctx) => {
+        if (data.autoEmail && !data.autoPost) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["autoEmail"],
+                message: "autoEmail requires autoPost to be true — invoices must be posted before they can be emailed",
+            });
+        }
+    }),
+    // Contact Write Tools
+    createContact: z.object({
+        accountId: z
+            .string()
+            .min(1)
+            .describe("Zuora account UUID to create the contact for"),
+        firstName: z
+            .string()
+            .min(1)
+            .max(100)
+            .describe("Contact first name"),
+        lastName: z
+            .string()
+            .min(1)
+            .max(100)
+            .describe("Contact last name"),
+        workEmail: z
+            .string()
+            .email("Must be a valid email address")
+            .optional()
+            .describe("Work email address"),
+        personalEmail: z
+            .string()
+            .email("Must be a valid email address")
+            .optional()
+            .describe("Personal email address"),
+        workPhone: z.string().max(40).optional().describe("Work phone number"),
+        homePhone: z.string().max(40).optional().describe("Home phone number"),
+        mobilePhone: z.string().max(40).optional().describe("Mobile phone number"),
+        fax: z.string().max(40).optional().describe("Fax number"),
+        address1: z.string().max(255).optional().describe("Street address line 1"),
+        address2: z.string().max(255).optional().describe("Street address line 2"),
+        city: z.string().max(100).optional().describe("City"),
+        state: z.string().max(100).optional().describe("State or province"),
+        country: z.string().max(100).optional().describe("Country (ISO 3166 name or code)"),
+        postalCode: z.string().max(20).optional().describe("Postal/ZIP code"),
+        county: z.string().max(100).optional().describe("County"),
+        taxRegion: z.string().max(100).optional().describe("Tax region"),
+        description: z.string().max(2000).optional().describe("Contact description/notes"),
+        nickname: z.string().max(100).optional().describe("Contact nickname"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate contact creation on retries. " +
+            "Generate a new UUID v4 for each distinct contact intent."),
+    }),
+    updateContact: z.object({
+        contactId: z
+            .string()
+            .min(1)
+            .describe("Contact ID to update"),
+        firstName: z.string().min(1).max(100).optional().describe("Updated first name"),
+        lastName: z.string().min(1).max(100).optional().describe("Updated last name"),
+        workEmail: z.string().email("Must be a valid email address").optional().describe("Updated work email"),
+        personalEmail: z.string().email("Must be a valid email address").optional().describe("Updated personal email"),
+        workPhone: z.string().max(40).optional().describe("Updated work phone"),
+        homePhone: z.string().max(40).optional().describe("Updated home phone"),
+        mobilePhone: z.string().max(40).optional().describe("Updated mobile phone"),
+        fax: z.string().max(40).optional().describe("Updated fax number"),
+        address1: z.string().max(255).optional().describe("Updated street address line 1"),
+        address2: z.string().max(255).optional().describe("Updated street address line 2"),
+        city: z.string().max(100).optional().describe("Updated city"),
+        state: z.string().max(100).optional().describe("Updated state or province"),
+        country: z.string().max(100).optional().describe("Updated country"),
+        postalCode: z.string().max(20).optional().describe("Updated postal/ZIP code"),
+        county: z.string().max(100).optional().describe("Updated county"),
+        taxRegion: z.string().max(100).optional().describe("Updated tax region"),
+        description: z.string().max(2000).optional().describe("Updated description/notes"),
+        nickname: z.string().max(100).optional().describe("Updated nickname"),
+    }).superRefine((data, ctx) => {
+        const { contactId: _, ...updateFields } = data;
+        const hasUpdate = Object.values(updateFields).some((v) => v !== undefined);
+        if (!hasUpdate) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [],
+                message: "At least one field to update must be provided",
+            });
+        }
+    }),
+    // ==================== Composite Tool Schemas ====================
+    findAccountsByProduct: z.object({
+        productName: z
+            .string()
+            .min(1)
+            .max(255)
+            .describe("Product name to search for (partial match supported). " +
+            "Example: 'Security Analytics Log Retention 13 Months'"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(25)
+            .describe("Maximum accounts to return (default: 25, max: 100)"),
+    }),
+    getOverdueInvoices: z.object({
+        minBalance: z
+            .number()
+            .min(0)
+            .default(0)
+            .describe("Minimum invoice balance to include (default: 0)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Maximum invoices to return (default: 50, max: 200)"),
+    }),
+    getExpiringSubscriptions: z.object({
+        daysAhead: z
+            .number()
+            .int()
+            .min(1)
+            .max(365)
+            .default(30)
+            .describe("Days to look ahead for expiring subscriptions (default: 30, max: 365)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Maximum subscriptions to return (default: 50, max: 200)"),
+    }),
+    getAccountBillingOverview: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account number or ID (e.g., A00012345)"),
+    }),
+    getRevenueByProduct: z.object({
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(50)
+            .describe("Maximum products to return (default: 50, max: 100)"),
+    }),
+    getPaymentReconciliation: z.object({
+        startDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .describe("Start date for payment period (YYYY-MM-DD)"),
+        endDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .describe("End date for payment period (YYYY-MM-DD)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(500)
+            .default(100)
+            .describe("Maximum payments to return (default: 100, max: 500)"),
+    }),
+    getRecentlyCancelledSubscriptions: z.object({
+        daysBack: z
+            .number()
+            .int()
+            .min(1)
+            .max(365)
+            .default(30)
+            .describe("Days to look back for cancellations (default: 30, max: 365)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Maximum subscriptions to return (default: 50, max: 200)"),
+    }),
+    getInvoiceAgingReport: z.object({
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(500)
+            .default(200)
+            .describe("Maximum invoices to analyze (default: 200, max: 500)"),
+    }),
+    getAccountHealthScorecard: z.object({
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(20)
+            .describe("Maximum at-risk accounts to return (default: 20, max: 100)"),
+    }),
+    findInvoicesByProduct: z.object({
+        productName: z
+            .string()
+            .min(1)
+            .max(255)
+            .describe("Product name to search for (partial match supported). " +
+            "Example: 'Security Analytics'"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Maximum invoice items to return (default: 50, max: 200)"),
+    }),
+};
+// ==================== Tool Handlers ====================
+export class ToolHandlers {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    // --- Account Handlers ---
+    async getAccount(input) {
+        try {
+            const { accountKey } = schemas.getAccount.parse(input);
+            const account = await this.client.getAccount(accountKey);
+            return {
+                success: true,
+                message: `Retrieved account ${accountKey}`,
+                data: account,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get account: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getAccountSummary(input) {
+        try {
+            const { accountKey } = schemas.getAccountSummary.parse(input);
+            const summary = await this.client.getAccountSummary(accountKey);
+            return {
+                success: true,
+                message: `Retrieved account summary for ${accountKey}`,
+                data: summary,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get account summary: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Invoice Handlers ---
+    async getInvoice(input) {
+        try {
+            const { invoiceId } = schemas.getInvoice.parse(input);
+            const invoice = await this.client.getInvoice(invoiceId);
+            return {
+                success: true,
+                message: `Retrieved invoice ${invoice.invoiceNumber ?? invoiceId}`,
+                data: invoice,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get invoice: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listInvoices(input) {
+        try {
+            const { accountKey, page, pageSize } = schemas.listInvoices.parse(input);
+            const result = await this.client.listInvoices(accountKey, page, pageSize);
+            const count = result.invoices?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} invoice(s) for account ${accountKey}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list invoices: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Subscription Handlers ---
+    async getSubscription(input) {
+        try {
+            const { subscriptionKey } = schemas.getSubscription.parse(input);
+            const subscription = await this.client.getSubscription(subscriptionKey);
+            return {
+                success: true,
+                message: `Retrieved subscription ${subscription.subscriptionNumber ?? subscriptionKey}`,
+                data: subscription,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get subscription: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listSubscriptions(input) {
+        try {
+            const { accountKey } = schemas.listSubscriptions.parse(input);
+            const result = await this.client.listSubscriptionsByAccount(accountKey);
+            const count = result.subscriptions?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} subscription(s) for account ${accountKey}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list subscriptions: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Payment Handlers ---
+    async getPayment(input) {
+        try {
+            const { paymentId } = schemas.getPayment.parse(input);
+            const payment = await this.client.getPayment(paymentId);
+            return {
+                success: true,
+                message: `Retrieved payment ${payment.paymentNumber ?? paymentId}`,
+                data: payment,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get payment: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listPayments(input) {
+        try {
+            const { accountKey, page, pageSize } = schemas.listPayments.parse(input);
+            const result = accountKey
+                ? await this.client.listPaymentsByAccount(accountKey, page, pageSize)
+                : await this.client.listPayments(page, pageSize);
+            const count = result.payments?.length ?? 0;
+            const scope = accountKey
+                ? ` for account ${accountKey}`
+                : "";
+            return {
+                success: true,
+                message: `Found ${count} payment(s)${scope}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list payments: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- ZOQL Query Handlers ---
+    async executeZoqlQuery(input) {
+        try {
+            const { zoqlQuery } = schemas.executeZoqlQuery.parse(input);
+            const result = await this.client.executeQuery(zoqlQuery);
+            const moreAvailable = result.queryLocator
+                ? " (more available via continue_zoql_query)"
+                : "";
+            return {
+                success: true,
+                message: `Query returned ${result.records?.length ?? 0} record(s)${moreAvailable}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `ZOQL query failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async continueZoqlQuery(input) {
+        try {
+            const { queryLocator } = schemas.continueZoqlQuery.parse(input);
+            const result = await this.client.queryMore(queryLocator);
+            const moreAvailable = result.queryLocator
+                ? " (more available)"
+                : "";
+            return {
+                success: true,
+                message: `Continuation returned ${result.records?.length ?? 0} record(s)${moreAvailable}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `ZOQL continuation failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Product Catalog Handlers ---
+    async listProducts(input) {
+        try {
+            const { page, pageSize } = schemas.listProducts.parse(input);
+            const result = await this.client.listProducts(page, pageSize);
+            const count = result.products?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} product(s)`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list products: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Phase 2: Extended Read Handlers ---
+    async getInvoiceFiles(input) {
+        try {
+            const { invoiceId } = schemas.getInvoiceFiles.parse(input);
+            const result = await this.client.getInvoiceFiles(invoiceId);
+            const count = result.invoiceFiles?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} file(s) for invoice ${invoiceId}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get invoice files: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getCreditMemo(input) {
+        try {
+            const { creditMemoId } = schemas.getCreditMemo.parse(input);
+            const creditMemo = await this.client.getCreditMemo(creditMemoId);
+            return {
+                success: true,
+                message: `Retrieved credit memo ${creditMemo.number ?? creditMemoId}`,
+                data: creditMemo,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get credit memo: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listCreditMemos(input) {
+        try {
+            const { accountId, page, pageSize } = schemas.listCreditMemos.parse(input);
+            const result = await this.client.listCreditMemos(accountId, page, pageSize);
+            const count = result.creditMemos?.length ?? 0;
+            const scope = accountId ? ` for account ${accountId}` : "";
+            return {
+                success: true,
+                message: `Found ${count} credit memo(s)${scope}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list credit memos: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async searchAccounts(input) {
+        try {
+            const { field, value, operator } = schemas.searchAccounts.parse(input);
+            const result = await this.client.searchAccounts(field, value, operator);
+            const count = result.records?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} account(s) matching search criteria`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to search accounts: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listUsage(input) {
+        try {
+            const { accountKey, page, pageSize } = schemas.listUsage.parse(input);
+            const result = await this.client.listUsage(accountKey, page, pageSize);
+            const count = result.usage?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} usage record(s) for account ${accountKey}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get usage: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- User Management Handlers ---
+    async listUsers(input) {
+        try {
+            const { startIndex, count, filter } = schemas.listUsers.parse(input);
+            const result = await this.client.listUsers(startIndex, count, filter);
+            const userCount = result.Resources?.length ?? 0;
+            const filterNote = filter ? ` (filter: ${filter})` : "";
+            return {
+                success: true,
+                message: `Found ${userCount} user(s) of ${result.totalResults} total${filterNote}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list users: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getUser(input) {
+        try {
+            const { userId } = schemas.getUser.parse(input);
+            const user = await this.client.getUser(userId);
+            return {
+                success: true,
+                message: `Retrieved user ${user.userName ?? userId}`,
+                data: user,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get user: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Bill Run Handlers ---
+    async getBillRun(input) {
+        try {
+            const { billRunId } = schemas.getBillRun.parse(input);
+            const billRun = await this.client.getBillRun(billRunId);
+            return {
+                success: true,
+                message: `Retrieved bill run ${billRun.billRunNumber ?? billRunId} (status: ${billRun.status})`,
+                data: billRun,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get bill run: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listBillRuns(input) {
+        try {
+            const { page, pageSize } = schemas.listBillRuns.parse(input);
+            const result = await this.client.listBillRuns(page, pageSize);
+            const count = result.billRuns?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} bill run(s)`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list bill runs: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Contact Handlers ---
+    async getContact(input) {
+        try {
+            const { contactId } = schemas.getContact.parse(input);
+            const contact = await this.client.getContact(contactId);
+            return {
+                success: true,
+                message: `Retrieved contact ${contact.firstName} ${contact.lastName} (${contactId})`,
+                data: contact,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get contact: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Describe API Handlers ---
+    async describeObject(input) {
+        try {
+            const { objectType } = schemas.describeObject.parse(input);
+            const result = await this.client.describeObject(objectType);
+            return {
+                success: true,
+                message: `Described ${result.objectName}: ${result.fieldCount} field(s)`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to describe object: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Phase 3: Write Operation Handlers ---
+    async createPayment(input) {
+        try {
+            const { idempotencyKey, ...paymentData } = schemas.createPayment.parse(input);
+            const result = await this.client.createPayment(paymentData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created payment ${result.paymentNumber} successfully`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create payment: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async applyPayment(input) {
+        try {
+            const { paymentId, invoices, effectiveDate } = schemas.applyPayment.parse(input);
+            const result = await this.client.applyPayment(paymentId, {
+                invoices,
+                effectiveDate,
+            });
+            return {
+                success: true,
+                message: `Applied payment ${paymentId} (applied: ${result.appliedAmount}) successfully`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to apply payment: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async createInvoice(input) {
+        try {
+            const { idempotencyKey, ...invoiceData } = schemas.createInvoice.parse(input);
+            const result = await this.client.createInvoice(invoiceData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created draft invoice ${result.invoiceNumber} for account ${invoiceData.accountId}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create invoice: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async postInvoice(input) {
+        try {
+            const { invoiceId } = schemas.postInvoice.parse(input);
+            const result = await this.client.postInvoice(invoiceId);
+            return {
+                success: true,
+                message: `Posted invoice ${result.invoiceNumber} (status: ${result.status})`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to post invoice: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async cancelSubscription(input) {
+        try {
+            const { subscriptionKey, ...cancellationData } = schemas.cancelSubscription.parse(input);
+            const result = await this.client.cancelSubscription(subscriptionKey, cancellationData);
+            return {
+                success: true,
+                message: `Cancelled subscription ${subscriptionKey} (id: ${result.subscriptionId}) effective ${result.cancelledDate}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to cancel subscription: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Phase 4: Advanced Operation Handlers ---
+    async createSubscription(input) {
+        try {
+            const { idempotencyKey, ...subscriptionData } = schemas.createSubscription.parse(input);
+            const result = await this.client.createSubscription(subscriptionData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created subscription ${result.subscriptionNumber} for account ${subscriptionData.accountKey}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create subscription: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async updateSubscription(input) {
+        try {
+            const { subscriptionKey, ...updateData } = schemas.updateSubscription.parse(input);
+            const result = await this.client.updateSubscription(subscriptionKey, updateData);
+            return {
+                success: true,
+                message: `Updated subscription ${subscriptionKey} (id: ${result.subscriptionId})`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to update subscription: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async createAccount(input) {
+        try {
+            const { idempotencyKey, ...accountData } = schemas.createAccount.parse(input);
+            const result = await this.client.createAccount(accountData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created account ${result.accountNumber} (id: ${result.accountId})`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create account: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async updateAccount(input) {
+        try {
+            const { accountKey, ...updateData } = schemas.updateAccount.parse(input);
+            const result = await this.client.updateAccount(accountKey, updateData);
+            return {
+                success: true,
+                message: `Updated account ${accountKey} successfully`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to update account: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async createRefund(input) {
+        try {
+            const { idempotencyKey, paymentId, ...refundData } = schemas.createRefund.parse(input);
+            const result = await this.client.createRefund(paymentId, refundData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created refund ${result.number} (status: ${result.status})`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create refund: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Bill Run Write Handlers ---
+    async createBillRun(input) {
+        try {
+            const { idempotencyKey, ...billRunData } = schemas.createBillRun.parse(input);
+            const result = await this.client.createBillRun(billRunData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created bill run ${result.billRunNumber} (status: ${result.status})`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create bill run: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Contact Write Handlers ---
+    async createContact(input) {
+        try {
+            const { idempotencyKey, ...contactData } = schemas.createContact.parse(input);
+            const result = await this.client.createContact(contactData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created contact (id: ${result.id}) for account ${contactData.accountId}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create contact: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async updateContact(input) {
+        try {
+            const { contactId, ...updateData } = schemas.updateContact.parse(input);
+            const result = await this.client.updateContact(contactId, updateData);
+            return {
+                success: true,
+                message: `Updated contact ${contactId} successfully`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to update contact: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Composite Tool Handlers ---
+    async findAccountsByProduct(input) {
+        try {
+            const { productName, limit } = schemas.findAccountsByProduct.parse(input);
+            const safeName = escapeZoql(productName);
+            // Step 1: Find ProductRatePlan IDs matching the product name
+            const productRatePlans = await queryAll(this.client, `SELECT Id, Name FROM ProductRatePlan WHERE Name LIKE '%${safeName}%'`);
+            if (productRatePlans.length === 0) {
+                // Try searching by Product.Name instead
+                const products = await queryAll(this.client, `SELECT Id, Name FROM Product WHERE Name LIKE '%${safeName}%'`);
+                if (products.length === 0) {
+                    return {
+                        success: true,
+                        message: `No products found matching "${productName}"`,
+                        data: { accounts: [], totalFound: 0 },
+                    };
+                }
+                const productIds = collectIds(products, "Id");
+                const prpFromProduct = await queryWithBatchedIds(this.client, "Id, Name", "ProductRatePlan", "ProductId", productIds);
+                if (prpFromProduct.length === 0) {
+                    return {
+                        success: true,
+                        message: `Product found but no rate plans configured for "${productName}"`,
+                        data: { accounts: [], totalFound: 0 },
+                    };
+                }
+                productRatePlans.push(...prpFromProduct);
+            }
+            const prpIds = collectIds(productRatePlans, "Id");
+            // Step 2: Find RatePlans using those ProductRatePlanIds → get SubscriptionIds
+            const ratePlans = await queryWithBatchedIds(this.client, "Id, SubscriptionId, Name", "RatePlan", "ProductRatePlanId", prpIds);
+            if (ratePlans.length === 0) {
+                return {
+                    success: true,
+                    message: `No active subscriptions found for product "${productName}"`,
+                    data: { accounts: [], totalFound: 0 },
+                };
+            }
+            const subscriptionIds = collectIds(ratePlans, "SubscriptionId");
+            // Step 3: Get Subscriptions → AccountIds
+            const subscriptions = await queryWithBatchedIds(this.client, "Id, AccountId, SubscriptionNumber, Status, TermEndDate, ContractedMrr", "Subscription", "Id", subscriptionIds, "Status = 'Active'");
+            if (subscriptions.length === 0) {
+                return {
+                    success: true,
+                    message: `No active subscriptions found for product "${productName}"`,
+                    data: { accounts: [], totalFound: 0 },
+                };
+            }
+            const accountIds = collectIds(subscriptions, "AccountId");
+            // Step 4: Get Account details
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name, Status", "Account", "Id", accountIds);
+            // Build lookup maps
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            const subsByAccount = new Map();
+            for (const sub of subscriptions) {
+                const acctId = getString(sub, "AccountId") ?? "";
+                const existing = subsByAccount.get(acctId) ?? [];
+                existing.push(sub);
+                subsByAccount.set(acctId, existing);
+            }
+            // Build rate plan name lookup by subscription
+            const rpNameBySub = new Map();
+            for (const rp of ratePlans) {
+                const subId = getString(rp, "SubscriptionId") ?? "";
+                const existing = rpNameBySub.get(subId) ?? [];
+                const name = getString(rp, "Name");
+                if (name)
+                    existing.push(name);
+                rpNameBySub.set(subId, existing);
+            }
+            // Assemble results
+            const results = [];
+            for (const [acctId, acct] of accountMap) {
+                if (!acctId)
+                    continue;
+                const acctSubs = subsByAccount.get(acctId) ?? [];
+                results.push({
+                    accountId: acctId,
+                    accountNumber: getString(acct, "AccountNumber") ?? "",
+                    accountName: getString(acct, "Name") ?? "",
+                    accountStatus: getString(acct, "Status") ?? "",
+                    subscriptions: acctSubs.map((sub) => ({
+                        subscriptionId: getString(sub, "Id") ?? "",
+                        subscriptionNumber: getString(sub, "SubscriptionNumber") ?? "",
+                        status: getString(sub, "Status") ?? "",
+                        termEndDate: getString(sub, "TermEndDate"),
+                        ratePlanName: (rpNameBySub.get(getString(sub, "Id") ?? "") ?? []).join(", "),
+                    })),
+                });
+                if (results.length >= limit)
+                    break;
+            }
+            return {
+                success: true,
+                message: `Found ${results.length} account(s) with active subscriptions for "${productName}"`,
+                data: { accounts: results, totalFound: results.length },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to find accounts by product: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getOverdueInvoices(input) {
+        try {
+            const { minBalance, limit } = schemas.getOverdueInvoices.parse(input);
+            const today = todayString();
+            // Query overdue invoices: Posted, has balance, past due date
+            const invoices = await queryAll(this.client, `SELECT Id, InvoiceNumber, AccountId, InvoiceDate, DueDate, Amount, Balance ` +
+                `FROM Invoice ` +
+                `WHERE Status = 'Posted' AND Balance > ${Number(minBalance)} AND DueDate < '${today}'`, limit);
+            if (invoices.length === 0) {
+                return {
+                    success: true,
+                    message: "No overdue invoices found",
+                    data: { invoices: [], totalFound: 0, totalOverdueBalance: 0 },
+                };
+            }
+            // Get account details for the overdue invoices
+            const accountIds = collectIds(invoices, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Build results
+            const results = invoices.map((inv) => {
+                const acctId = getString(inv, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                const dueDate = getString(inv, "DueDate") ?? today;
+                return {
+                    invoiceId: getString(inv, "Id") ?? "",
+                    invoiceNumber: getString(inv, "InvoiceNumber") ?? "",
+                    accountId: acctId,
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    invoiceDate: getString(inv, "InvoiceDate") ?? "",
+                    dueDate,
+                    amount: getNumber(inv, "Amount") ?? 0,
+                    balance: getNumber(inv, "Balance") ?? 0,
+                    daysPastDue: daysBetween(dueDate, today),
+                };
+            });
+            // Sort by days past due descending
+            results.sort((a, b) => b.daysPastDue - a.daysPastDue);
+            const totalOverdueBalance = results.reduce((sum, r) => sum + r.balance, 0);
+            return {
+                success: true,
+                message: `Found ${results.length} overdue invoice(s) totaling $${totalOverdueBalance.toFixed(2)}`,
+                data: {
+                    invoices: results.slice(0, limit),
+                    totalFound: results.length,
+                    totalOverdueBalance,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get overdue invoices: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getExpiringSubscriptions(input) {
+        try {
+            const { daysAhead, limit } = schemas.getExpiringSubscriptions.parse(input);
+            const today = todayString();
+            const futureDate = addDays(new Date(), daysAhead);
+            // Query active subscriptions expiring within the window
+            const subscriptions = await queryAll(this.client, `SELECT Id, SubscriptionNumber, AccountId, Status, TermEndDate, AutoRenew, ContractedMrr ` +
+                `FROM Subscription ` +
+                `WHERE Status = 'Active' AND TermEndDate >= '${today}' AND TermEndDate <= '${futureDate}'`, limit * 2 // fetch extra to account for filtering
+            );
+            if (subscriptions.length === 0) {
+                return {
+                    success: true,
+                    message: `No subscriptions expiring in the next ${daysAhead} days`,
+                    data: { subscriptions: [], totalFound: 0, totalMrrAtRisk: 0 },
+                };
+            }
+            // Get account details
+            const accountIds = collectIds(subscriptions, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Get rate plan names
+            const subIds = collectIds(subscriptions, "Id");
+            const ratePlans = await queryWithBatchedIds(this.client, "Id, SubscriptionId, Name", "RatePlan", "SubscriptionId", subIds);
+            const rpNamesBySub = new Map();
+            for (const rp of ratePlans) {
+                const subId = getString(rp, "SubscriptionId") ?? "";
+                const existing = rpNamesBySub.get(subId) ?? [];
+                const name = getString(rp, "Name");
+                if (name)
+                    existing.push(name);
+                rpNamesBySub.set(subId, existing);
+            }
+            // Build results
+            const results = subscriptions.map((sub) => {
+                const acctId = getString(sub, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                const termEnd = getString(sub, "TermEndDate") ?? futureDate;
+                const subId = getString(sub, "Id") ?? "";
+                return {
+                    subscriptionId: subId,
+                    subscriptionNumber: getString(sub, "SubscriptionNumber") ?? "",
+                    accountId: acctId,
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    status: getString(sub, "Status") ?? "",
+                    termEndDate: termEnd,
+                    autoRenew: getString(sub, "AutoRenew") === "true",
+                    contractedMrr: getNumber(sub, "ContractedMrr") ?? 0,
+                    ratePlanNames: rpNamesBySub.get(subId) ?? [],
+                    daysUntilExpiry: daysBetween(today, termEnd),
+                };
+            });
+            results.sort((a, b) => a.daysUntilExpiry - b.daysUntilExpiry);
+            const totalMrrAtRisk = results
+                .filter((r) => !r.autoRenew)
+                .reduce((sum, r) => sum + r.contractedMrr, 0);
+            return {
+                success: true,
+                message: `Found ${results.length} subscription(s) expiring in the next ${daysAhead} days (MRR at risk: $${totalMrrAtRisk.toFixed(2)})`,
+                data: {
+                    subscriptions: results.slice(0, limit),
+                    totalFound: results.length,
+                    totalMrrAtRisk,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get expiring subscriptions: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getAccountBillingOverview(input) {
+        try {
+            const { accountKey } = schemas.getAccountBillingOverview.parse(input);
+            // Step 1: Get account via REST API
+            const account = await this.client.getAccount(accountKey);
+            // Step 2: Get recent invoices via ZOQL
+            const invoices = await queryAll(this.client, `SELECT Id, InvoiceNumber, InvoiceDate, DueDate, Amount, Balance, Status ` +
+                `FROM Invoice WHERE AccountId = '${escapeZoql(account.id)}' ` +
+                `ORDER BY InvoiceDate DESC`, 20);
+            // Step 3: Get recent payments via ZOQL
+            const payments = await queryAll(this.client, `SELECT Id, PaymentNumber, Amount, EffectiveDate, Status ` +
+                `FROM Payment WHERE AccountId = '${escapeZoql(account.id)}' ` +
+                `ORDER BY EffectiveDate DESC`, 10);
+            // Step 4: Get subscriptions via REST API
+            const subResult = await this.client.listSubscriptionsByAccount(accountKey);
+            const subscriptions = subResult.subscriptions ?? [];
+            // Compute invoice summary
+            const today = todayString();
+            let totalOutstanding = 0;
+            let overdueCount = 0;
+            let overdueAmount = 0;
+            for (const inv of invoices) {
+                const balance = getNumber(inv, "Balance") ?? 0;
+                const status = getString(inv, "Status");
+                if (status === "Posted" && balance > 0) {
+                    totalOutstanding += balance;
+                    const dueDate = getString(inv, "DueDate") ?? "";
+                    if (dueDate && dueDate < today) {
+                        overdueCount++;
+                        overdueAmount += balance;
+                    }
+                }
+            }
+            const activeSubscriptions = subscriptions.filter((s) => s.status === "Active");
+            const totalMrr = activeSubscriptions.reduce((sum, s) => sum + (s.contractedMrr ?? 0), 0);
+            const overview = {
+                account: {
+                    id: account.id,
+                    accountNumber: account.accountNumber,
+                    name: account.name,
+                    status: account.status,
+                    balance: account.balance,
+                    currency: account.currency,
+                    autoPay: account.autoPay,
+                    paymentTerm: account.paymentTerm,
+                },
+                invoiceSummary: {
+                    totalOutstanding,
+                    overdueCount,
+                    overdueAmount,
+                    recentInvoices: invoices.slice(0, 10).map((inv) => ({
+                        invoiceNumber: getString(inv, "InvoiceNumber") ?? "",
+                        invoiceDate: getString(inv, "InvoiceDate") ?? "",
+                        dueDate: getString(inv, "DueDate") ?? "",
+                        amount: getNumber(inv, "Amount") ?? 0,
+                        balance: getNumber(inv, "Balance") ?? 0,
+                        status: getString(inv, "Status") ?? "",
+                    })),
+                },
+                paymentSummary: {
+                    recentPayments: payments.slice(0, 5).map((p) => ({
+                        paymentNumber: getString(p, "PaymentNumber") ?? "",
+                        amount: getNumber(p, "Amount") ?? 0,
+                        effectiveDate: getString(p, "EffectiveDate") ?? "",
+                        status: getString(p, "Status") ?? "",
+                    })),
+                },
+                subscriptionSummary: {
+                    activeCount: activeSubscriptions.length,
+                    totalMrr,
+                    subscriptions: activeSubscriptions.slice(0, 10).map((s) => ({
+                        subscriptionNumber: s.subscriptionNumber,
+                        status: s.status,
+                        termEndDate: s.termEndDate,
+                        contractedMrr: s.contractedMrr,
+                        ratePlanNames: s.ratePlans?.map((rp) => rp.ratePlanName) ?? [],
+                    })),
+                },
+            };
+            return {
+                success: true,
+                message: `Billing overview for ${account.name} (${account.accountNumber}): balance $${account.balance}, ${overdueCount} overdue, ${activeSubscriptions.length} active subscriptions`,
+                data: overview,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get billing overview: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getRevenueByProduct(input) {
+        try {
+            const { limit } = schemas.getRevenueByProduct.parse(input);
+            // Step 1: Get all active subscriptions with MRR
+            const subscriptions = await queryAll(this.client, `SELECT Id, AccountId, SubscriptionNumber, ContractedMrr, TotalContractedValue, Status ` +
+                `FROM Subscription WHERE Status = 'Active'`, 5000);
+            if (subscriptions.length === 0) {
+                return {
+                    success: true,
+                    message: "No active subscriptions found",
+                    data: { products: [], totalMrr: 0 },
+                };
+            }
+            // Step 2: Get rate plans for subscriptions to resolve product names
+            const subIds = collectIds(subscriptions, "Id");
+            const ratePlans = await queryWithBatchedIds(this.client, "Id, SubscriptionId, ProductRatePlanId, Name", "RatePlan", "SubscriptionId", subIds);
+            // Step 3: Get ProductRatePlan → Product mapping
+            const prpIds = collectIds(ratePlans, "ProductRatePlanId");
+            const productRatePlans = await queryWithBatchedIds(this.client, "Id, ProductId, Name", "ProductRatePlan", "Id", prpIds);
+            const productIds = collectIds(productRatePlans, "ProductId");
+            const products = await queryWithBatchedIds(this.client, "Id, Name", "Product", "Id", productIds);
+            // Build lookup maps
+            const productNameMap = new Map(products.map((p) => [getString(p, "Id"), getString(p, "Name") ?? "Unknown"]));
+            const prpToProduct = new Map(productRatePlans.map((prp) => [
+                getString(prp, "Id"),
+                productNameMap.get(getString(prp, "ProductId") ?? "") ?? getString(prp, "Name") ?? "Unknown",
+            ]));
+            // Map subscriptions to their rate plans and product names
+            const subMap = new Map(subscriptions.map((s) => [getString(s, "Id"), s]));
+            // Get account details for all subscriptions
+            const accountIds = collectIds(subscriptions, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Group by product name
+            const productData = new Map();
+            for (const rp of ratePlans) {
+                const prpId = getString(rp, "ProductRatePlanId") ?? "";
+                const productName = prpToProduct.get(prpId) ?? getString(rp, "Name") ?? "Unknown";
+                const subId = getString(rp, "SubscriptionId") ?? "";
+                const sub = subMap.get(subId);
+                if (!sub)
+                    continue;
+                const acctId = getString(sub, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                const mrr = getNumber(sub, "ContractedMrr") ?? 0;
+                const existing = productData.get(productName) ?? {
+                    subscriptionCount: 0,
+                    totalMrr: 0,
+                    totalTcv: 0,
+                    subscriptions: [],
+                };
+                existing.subscriptionCount++;
+                existing.totalMrr += mrr;
+                existing.totalTcv += getNumber(sub, "TotalContractedValue") ?? 0;
+                existing.subscriptions.push({
+                    subscriptionNumber: getString(sub, "SubscriptionNumber") ?? "",
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    mrr,
+                    status: getString(sub, "Status") ?? "",
+                });
+                productData.set(productName, existing);
+            }
+            // Convert to sorted array
+            const results = [...productData.entries()]
+                .map(([name, data]) => ({
+                productName: name,
+                subscriptionCount: data.subscriptionCount,
+                totalMrr: data.totalMrr,
+                totalTcv: data.totalTcv,
+                subscriptions: data.subscriptions,
+            }))
+                .sort((a, b) => b.totalMrr - a.totalMrr)
+                .slice(0, limit);
+            const totalMrr = results.reduce((sum, r) => sum + r.totalMrr, 0);
+            return {
+                success: true,
+                message: `Revenue breakdown across ${results.length} product(s), total MRR: $${totalMrr.toFixed(2)}`,
+                data: { products: results, totalMrr },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get revenue by product: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getPaymentReconciliation(input) {
+        try {
+            const { startDate, endDate, limit } = schemas.getPaymentReconciliation.parse(input);
+            // Query payments in the date range
+            const payments = await queryAll(this.client, `SELECT Id, PaymentNumber, AccountId, Amount, EffectiveDate, Status, PaymentMethodType ` +
+                `FROM Payment ` +
+                `WHERE EffectiveDate >= '${escapeZoql(startDate)}' AND EffectiveDate <= '${escapeZoql(endDate)}'`, limit);
+            if (payments.length === 0) {
+                return {
+                    success: true,
+                    message: `No payments found between ${startDate} and ${endDate}`,
+                    data: {
+                        period: { startDate, endDate },
+                        summary: { totalPayments: 0, totalAmount: 0, byStatus: {} },
+                        payments: [],
+                    },
+                };
+            }
+            // Get account details
+            const accountIds = collectIds(payments, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Build summary
+            const byStatus = {};
+            let totalAmount = 0;
+            const paymentResults = payments.map((p) => {
+                const amount = getNumber(p, "Amount") ?? 0;
+                const status = getString(p, "Status") ?? "Unknown";
+                const acctId = getString(p, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                totalAmount += amount;
+                const statusBucket = byStatus[status] ?? { count: 0, amount: 0 };
+                statusBucket.count++;
+                statusBucket.amount += amount;
+                byStatus[status] = statusBucket;
+                return {
+                    paymentNumber: getString(p, "PaymentNumber") ?? "",
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    amount,
+                    effectiveDate: getString(p, "EffectiveDate") ?? "",
+                    status,
+                    paymentMethodType: getString(p, "PaymentMethodType") ?? "",
+                };
+            });
+            const result = {
+                period: { startDate, endDate },
+                summary: {
+                    totalPayments: payments.length,
+                    totalAmount,
+                    byStatus,
+                },
+                payments: paymentResults,
+            };
+            return {
+                success: true,
+                message: `${payments.length} payment(s) totaling $${totalAmount.toFixed(2)} between ${startDate} and ${endDate}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get payment reconciliation: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getRecentlyCancelledSubscriptions(input) {
+        try {
+            const { daysBack, limit } = schemas.getRecentlyCancelledSubscriptions.parse(input);
+            const sinceDate = subtractDays(new Date(), daysBack);
+            const subscriptions = await queryAll(this.client, `SELECT Id, SubscriptionNumber, AccountId, Status, TermEndDate, CancelledDate, ContractedMrr ` +
+                `FROM Subscription ` +
+                `WHERE Status = 'Cancelled' AND CancelledDate >= '${sinceDate}'`, limit * 2);
+            if (subscriptions.length === 0) {
+                return {
+                    success: true,
+                    message: `No subscriptions cancelled in the last ${daysBack} days`,
+                    data: { subscriptions: [], totalFound: 0, totalLostMrr: 0 },
+                };
+            }
+            // Get account details
+            const accountIds = collectIds(subscriptions, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Get rate plan names
+            const subIds = collectIds(subscriptions, "Id");
+            const ratePlans = await queryWithBatchedIds(this.client, "Id, SubscriptionId, Name", "RatePlan", "SubscriptionId", subIds);
+            const rpNamesBySub = new Map();
+            for (const rp of ratePlans) {
+                const subId = getString(rp, "SubscriptionId") ?? "";
+                const existing = rpNamesBySub.get(subId) ?? [];
+                const name = getString(rp, "Name");
+                if (name)
+                    existing.push(name);
+                rpNamesBySub.set(subId, existing);
+            }
+            const results = subscriptions.map((sub) => {
+                const acctId = getString(sub, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                const subId = getString(sub, "Id") ?? "";
+                return {
+                    subscriptionId: subId,
+                    subscriptionNumber: getString(sub, "SubscriptionNumber") ?? "",
+                    accountId: acctId,
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    status: getString(sub, "Status") ?? "",
+                    cancelledDate: getString(sub, "CancelledDate") ?? "",
+                    termEndDate: getString(sub, "TermEndDate") ?? "",
+                    contractedMrr: getNumber(sub, "ContractedMrr") ?? 0,
+                    ratePlanNames: rpNamesBySub.get(subId) ?? [],
+                };
+            });
+            const totalLostMrr = results.reduce((sum, r) => sum + r.contractedMrr, 0);
+            return {
+                success: true,
+                message: `Found ${results.length} cancelled subscription(s) in the last ${daysBack} days (lost MRR: $${totalLostMrr.toFixed(2)})`,
+                data: {
+                    subscriptions: results.slice(0, limit),
+                    totalFound: results.length,
+                    totalLostMrr,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get cancelled subscriptions: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getInvoiceAgingReport(input) {
+        try {
+            const { limit } = schemas.getInvoiceAgingReport.parse(input);
+            const today = todayString();
+            // Query all posted invoices with outstanding balance
+            const invoices = await queryAll(this.client, `SELECT Id, InvoiceNumber, AccountId, DueDate, Amount, Balance ` +
+                `FROM Invoice ` +
+                `WHERE Status = 'Posted' AND Balance > 0`, limit);
+            if (invoices.length === 0) {
+                return {
+                    success: true,
+                    message: "No outstanding invoices found",
+                    data: { buckets: [], totalOutstanding: 0 },
+                };
+            }
+            // Get account details
+            const accountIds = collectIds(invoices, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Define aging buckets
+            const bucketDefs = [
+                { label: "Current", minDays: -999999, maxDays: 0 },
+                { label: "1-30 Days", minDays: 1, maxDays: 30 },
+                { label: "31-60 Days", minDays: 31, maxDays: 60 },
+                { label: "61-90 Days", minDays: 61, maxDays: 90 },
+                { label: "90+ Days", minDays: 91, maxDays: null },
+            ];
+            const buckets = bucketDefs.map((def) => ({
+                ...def,
+                invoiceCount: 0,
+                totalBalance: 0,
+                invoices: [],
+            }));
+            let totalOutstanding = 0;
+            for (const inv of invoices) {
+                const dueDate = getString(inv, "DueDate") ?? today;
+                const balance = getNumber(inv, "Balance") ?? 0;
+                const daysPast = daysBetween(dueDate, today);
+                const acctId = getString(inv, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                totalOutstanding += balance;
+                const invoiceEntry = {
+                    invoiceId: getString(inv, "Id") ?? "",
+                    invoiceNumber: getString(inv, "InvoiceNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    balance,
+                    dueDate,
+                    daysPastDue: Math.max(0, daysPast),
+                };
+                for (const bucket of buckets) {
+                    const inMin = daysPast >= bucket.minDays;
+                    const inMax = bucket.maxDays === null || daysPast <= bucket.maxDays;
+                    if (inMin && inMax) {
+                        bucket.invoiceCount++;
+                        bucket.totalBalance += balance;
+                        bucket.invoices.push(invoiceEntry);
+                        break;
+                    }
+                }
+            }
+            // Sort invoices within each bucket by balance descending
+            for (const bucket of buckets) {
+                bucket.invoices.sort((a, b) => b.balance - a.balance);
+            }
+            return {
+                success: true,
+                message: `AR aging report: ${invoices.length} outstanding invoice(s), total $${totalOutstanding.toFixed(2)}`,
+                data: { buckets, totalOutstanding },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get invoice aging report: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getAccountHealthScorecard(input) {
+        try {
+            const { limit } = schemas.getAccountHealthScorecard.parse(input);
+            const today = todayString();
+            const thirtyDaysAhead = addDays(new Date(), 30);
+            const thirtyDaysBack = subtractDays(new Date(), 30);
+            // Signal 1: Overdue invoices
+            const overdueInvoices = await queryAll(this.client, `SELECT Id, AccountId, Balance, DueDate ` +
+                `FROM Invoice ` +
+                `WHERE Status = 'Posted' AND Balance > 0 AND DueDate < '${today}'`, 2000);
+            // Signal 2: Expiring subscriptions (next 30 days, not auto-renewing)
+            const expiringSubscriptions = await queryAll(this.client, `SELECT Id, AccountId, ContractedMrr, TermEndDate ` +
+                `FROM Subscription ` +
+                `WHERE Status = 'Active' AND TermEndDate >= '${today}' AND TermEndDate <= '${thirtyDaysAhead}' AND AutoRenew = 'false'`, 2000);
+            // Signal 3: Recent payment failures
+            const failedPayments = await queryAll(this.client, `SELECT Id, AccountId ` +
+                `FROM Payment ` +
+                `WHERE Status = 'Error' AND EffectiveDate >= '${thirtyDaysBack}'`, 2000);
+            // Aggregate by account
+            const accountScores = new Map();
+            const ensureAccount = (acctId) => {
+                if (!accountScores.has(acctId)) {
+                    accountScores.set(acctId, {
+                        overdueCount: 0,
+                        overdueBalance: 0,
+                        expiringCount: 0,
+                        expiringMrr: 0,
+                        paymentFailures: 0,
+                    });
+                }
+                return accountScores.get(acctId);
+            };
+            for (const inv of overdueInvoices) {
+                const acctId = getString(inv, "AccountId");
+                if (!acctId)
+                    continue;
+                const score = ensureAccount(acctId);
+                score.overdueCount++;
+                score.overdueBalance += getNumber(inv, "Balance") ?? 0;
+            }
+            for (const sub of expiringSubscriptions) {
+                const acctId = getString(sub, "AccountId");
+                if (!acctId)
+                    continue;
+                const score = ensureAccount(acctId);
+                score.expiringCount++;
+                score.expiringMrr += getNumber(sub, "ContractedMrr") ?? 0;
+            }
+            for (const pmt of failedPayments) {
+                const acctId = getString(pmt, "AccountId");
+                if (!acctId)
+                    continue;
+                const score = ensureAccount(acctId);
+                score.paymentFailures++;
+            }
+            // Calculate health scores (100 = healthy, 0 = critical)
+            const accountIds = [...accountScores.keys()];
+            if (accountIds.length === 0) {
+                return {
+                    success: true,
+                    message: "No at-risk accounts found",
+                    data: { accounts: [], totalAtRisk: 0 },
+                };
+            }
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            const results = [];
+            for (const [acctId, scores] of accountScores) {
+                const acct = accountMap.get(acctId);
+                const riskFactors = [];
+                let healthScore = 100;
+                if (scores.overdueCount > 0) {
+                    healthScore -= Math.min(40, scores.overdueCount * 15);
+                    riskFactors.push(`${scores.overdueCount} overdue invoice(s), $${scores.overdueBalance.toFixed(2)} outstanding`);
+                }
+                if (scores.expiringCount > 0) {
+                    healthScore -= Math.min(30, scores.expiringCount * 10);
+                    riskFactors.push(`${scores.expiringCount} subscription(s) expiring soon, $${scores.expiringMrr.toFixed(2)} MRR at risk`);
+                }
+                if (scores.paymentFailures > 0) {
+                    healthScore -= Math.min(30, scores.paymentFailures * 15);
+                    riskFactors.push(`${scores.paymentFailures} recent payment failure(s)`);
+                }
+                results.push({
+                    accountId: acctId,
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    healthScore: Math.max(0, healthScore),
+                    riskFactors,
+                    overdueInvoices: {
+                        count: scores.overdueCount,
+                        totalBalance: scores.overdueBalance,
+                    },
+                    expiringSubscriptions: {
+                        count: scores.expiringCount,
+                        totalMrr: scores.expiringMrr,
+                    },
+                    recentPaymentFailures: scores.paymentFailures,
+                });
+            }
+            // Sort by health score ascending (worst first)
+            results.sort((a, b) => a.healthScore - b.healthScore);
+            return {
+                success: true,
+                message: `Found ${results.length} account(s) with risk signals`,
+                data: {
+                    accounts: results.slice(0, limit),
+                    totalAtRisk: results.length,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get account health scorecard: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async findInvoicesByProduct(input) {
+        try {
+            const { productName, limit } = schemas.findInvoicesByProduct.parse(input);
+            const safeName = escapeZoql(productName);
+            // Step 1: Find ProductRatePlan IDs matching the product name
+            let productRatePlans = await queryAll(this.client, `SELECT Id, Name FROM ProductRatePlan WHERE Name LIKE '%${safeName}%'`);
+            if (productRatePlans.length === 0) {
+                // Try Product name
+                const products = await queryAll(this.client, `SELECT Id, Name FROM Product WHERE Name LIKE '%${safeName}%'`);
+                if (products.length === 0) {
+                    return {
+                        success: true,
+                        message: `No products found matching "${productName}"`,
+                        data: { invoiceItems: [], totalFound: 0 },
+                    };
+                }
+                const productIds = collectIds(products, "Id");
+                productRatePlans = await queryWithBatchedIds(this.client, "Id, Name", "ProductRatePlan", "ProductId", productIds);
+                if (productRatePlans.length === 0) {
+                    return {
+                        success: true,
+                        message: `No rate plans found for product "${productName}"`,
+                        data: { invoiceItems: [], totalFound: 0 },
+                    };
+                }
+            }
+            const prpIds = collectIds(productRatePlans, "Id");
+            // Step 2: Find RatePlans → RatePlanCharges
+            const ratePlans = await queryWithBatchedIds(this.client, "Id, SubscriptionId, Name", "RatePlan", "ProductRatePlanId", prpIds);
+            if (ratePlans.length === 0) {
+                return {
+                    success: true,
+                    message: `No subscriptions found with product "${productName}"`,
+                    data: { invoiceItems: [], totalFound: 0 },
+                };
+            }
+            const rpIds = collectIds(ratePlans, "Id");
+            const ratePlanCharges = await queryWithBatchedIds(this.client, "Id, RatePlanId, Name", "RatePlanCharge", "RatePlanId", rpIds);
+            if (ratePlanCharges.length === 0) {
+                return {
+                    success: true,
+                    message: `No charges found for product "${productName}"`,
+                    data: { invoiceItems: [], totalFound: 0 },
+                };
+            }
+            const rpcIds = collectIds(ratePlanCharges, "Id");
+            // Step 3: Find InvoiceItems by RatePlanChargeId
+            const invoiceItems = await queryWithBatchedIds(this.client, "Id, InvoiceId, ChargeAmount, ChargeName, ServiceStartDate, ServiceEndDate, SubscriptionId, RatePlanChargeId", "InvoiceItem", "RatePlanChargeId", rpcIds, undefined, limit);
+            if (invoiceItems.length === 0) {
+                return {
+                    success: true,
+                    message: `No invoice items found for product "${productName}"`,
+                    data: { invoiceItems: [], totalFound: 0 },
+                };
+            }
+            // Step 4: Get Invoice details
+            const invoiceIds = collectIds(invoiceItems, "InvoiceId");
+            const invoices = await queryWithBatchedIds(this.client, "Id, InvoiceNumber, InvoiceDate, AccountId", "Invoice", "Id", invoiceIds);
+            const invoiceMap = new Map(invoices.map((i) => [getString(i, "Id"), i]));
+            // Step 5: Get Account details
+            const accountIds = collectIds(invoices, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Build rate plan name lookup
+            const rpNameMap = new Map(ratePlans.map((rp) => [getString(rp, "Id"), getString(rp, "Name") ?? ""]));
+            const rpcToRp = new Map(ratePlanCharges.map((rpc) => [getString(rpc, "Id"), getString(rpc, "RatePlanId") ?? ""]));
+            // Get subscription number lookup
+            const subIds = collectIds(invoiceItems, "SubscriptionId");
+            const subs = await queryWithBatchedIds(this.client, "Id, SubscriptionNumber", "Subscription", "Id", subIds);
+            const subNumberMap = new Map(subs.map((s) => [getString(s, "Id"), getString(s, "SubscriptionNumber") ?? ""]));
+            // Assemble results
+            const results = invoiceItems.map((item) => {
+                const invId = getString(item, "InvoiceId") ?? "";
+                const inv = invoiceMap.get(invId);
+                const acctId = getString(inv ?? {}, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                const subId = getString(item, "SubscriptionId") ?? "";
+                return {
+                    invoiceId: invId,
+                    invoiceNumber: getString(inv ?? {}, "InvoiceNumber") ?? "",
+                    invoiceDate: getString(inv ?? {}, "InvoiceDate") ?? "",
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    chargeAmount: getNumber(item, "ChargeAmount") ?? 0,
+                    chargeName: getString(item, "ChargeName") ?? "",
+                    ratePlanName: rpNameMap.get(rpcToRp.get(getString(item, "RatePlanChargeId") ?? "") ?? "") ?? "",
+                    subscriptionNumber: subNumberMap.get(subId) ?? "",
+                };
+            });
+            const totalChargeAmount = results.reduce((sum, r) => sum + r.chargeAmount, 0);
+            return {
+                success: true,
+                message: `Found ${results.length} invoice item(s) for "${productName}", total charges: $${totalChargeAmount.toFixed(2)}`,
+                data: {
+                    invoiceItems: results.slice(0, limit),
+                    totalFound: results.length,
+                    totalChargeAmount,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to find invoices by product: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+}
+export const toolRegistrations = [
+    // Account Tools
+    {
+        name: "get_account",
+        description: "Get Zuora account details by account key (ID or account number). " +
+            "Returns name, status, currency, balance, and billing info.",
+        inputSchema: schemas.getAccount,
+        invoke: (handlers, args) => handlers.getAccount(args),
+    },
+    {
+        name: "get_account_summary",
+        description: "Get a comprehensive summary of a Zuora account including balances, " +
+            "active subscriptions, recent invoices, and payments in a single call.",
+        inputSchema: schemas.getAccountSummary,
+        invoke: (handlers, args) => handlers.getAccountSummary(args),
+    },
+    // Invoice Tools
+    {
+        name: "get_invoice",
+        description: "Get full details of a Zuora invoice including line items, amount, " +
+            "due date, status, and payment status.",
+        inputSchema: schemas.getInvoice,
+        invoke: (handlers, args) => handlers.getInvoice(args),
+    },
+    {
+        name: "list_invoices",
+        description: "List invoices for a specific Zuora account with pagination. " +
+            "Returns invoice numbers, amounts, dates, and statuses.",
+        inputSchema: schemas.listInvoices,
+        invoke: (handlers, args) => handlers.listInvoices(args),
+    },
+    // Subscription Tools
+    {
+        name: "get_subscription",
+        description: "Get details of a Zuora subscription by subscription key or ID. " +
+            "Returns plan info, status, term dates, and rate plan charges.",
+        inputSchema: schemas.getSubscription,
+        invoke: (handlers, args) => handlers.getSubscription(args),
+    },
+    {
+        name: "list_subscriptions",
+        description: "List all subscriptions for a Zuora account. " +
+            "Returns subscription names, statuses, and term dates.",
+        inputSchema: schemas.listSubscriptions,
+        invoke: (handlers, args) => handlers.listSubscriptions(args),
+    },
+    // Payment Tools
+    {
+        name: "get_payment",
+        description: "Get details of a specific Zuora payment including amount, date, " +
+            "status, and which invoices it was applied to.",
+        inputSchema: schemas.getPayment,
+        invoke: (handlers, args) => handlers.getPayment(args),
+    },
+    {
+        name: "list_payments",
+        description: "List payments with optional account filter and pagination. " +
+            "Returns payment amounts, dates, methods, and statuses.",
+        inputSchema: schemas.listPayments,
+        invoke: (handlers, args) => handlers.listPayments(args),
+    },
+    // ZOQL Query Tools
+    {
+        name: "execute_zoql_query",
+        description: "Execute a ZOQL (Zuora Object Query Language) query for ad-hoc data retrieval. " +
+            "Syntax: SELECT field1, field2 FROM ObjectName WHERE condition. " +
+            "Key objects: Account, Invoice, Payment, Subscription, RatePlan, " +
+            "RatePlanCharge, Product, ProductRatePlan, Contact. " +
+            "Limitations: No JOINs supported. Max 2000 records per call. " +
+            "Use continue_zoql_query with queryLocator for pagination. " +
+            "Example: SELECT Id, AccountNumber, Name, Balance FROM Account WHERE Status = 'Active'",
+        inputSchema: schemas.executeZoqlQuery,
+        invoke: (handlers, args) => handlers.executeZoqlQuery(args),
+    },
+    {
+        name: "continue_zoql_query",
+        description: "Continue a previous ZOQL query that returned a queryLocator " +
+            "(indicates more records available). Returns the next batch of up to 2000 records.",
+        inputSchema: schemas.continueZoqlQuery,
+        invoke: (handlers, args) => handlers.continueZoqlQuery(args),
+    },
+    // Product Catalog
+    {
+        name: "list_products",
+        description: "List products from the Zuora product catalog with rate plans and charges. " +
+            "Useful for understanding available products and pricing.",
+        inputSchema: schemas.listProducts,
+        invoke: (handlers, args) => handlers.listProducts(args),
+    },
+    // Phase 2: Extended Read Tools
+    // Invoice Files
+    {
+        name: "get_invoice_files",
+        description: "Get PDF file references for a specific Zuora invoice. " +
+            "Returns file IDs and authenticated URLs for invoice PDFs. " +
+            "Note: URLs require a valid Bearer token to access.",
+        inputSchema: schemas.getInvoiceFiles,
+        invoke: (handlers, args) => handlers.getInvoiceFiles(args),
+    },
+    // Credit Memo Tools
+    {
+        name: "get_credit_memo",
+        description: "Get full details of a Zuora credit memo including amount, status, " +
+            "applied/unapplied amounts, and line items.",
+        inputSchema: schemas.getCreditMemo,
+        invoke: (handlers, args) => handlers.getCreditMemo(args),
+    },
+    {
+        name: "list_credit_memos",
+        description: "List credit memos with optional account filter and pagination. " +
+            "Returns credit memo numbers, amounts, statuses, and dates.",
+        inputSchema: schemas.listCreditMemos,
+        invoke: (handlers, args) => handlers.listCreditMemos(args),
+    },
+    // Account Search
+    {
+        name: "search_accounts",
+        description: "Search Zuora accounts by field value. Supports searching by Name, " +
+            "AccountNumber, Status, Currency, or Balance. Use LIKE operator with % " +
+            "wildcard for partial name matching (e.g., field='Name', operator='LIKE', " +
+            "value='Acme%'). Returns Id, AccountNumber, Name, Status, Balance, Currency. " +
+            "For additional fields, use execute_zoql_query directly.",
+        inputSchema: schemas.searchAccounts,
+        invoke: (handlers, args) => handlers.searchAccounts(args),
+    },
+    // Usage
+    {
+        name: "list_usage",
+        description: "List usage records for a Zuora account with pagination. " +
+            "Returns usage quantities, units of measure, dates, and status.",
+        inputSchema: schemas.listUsage,
+        invoke: (handlers, args) => handlers.listUsage(args),
+    },
+    // User Management
+    {
+        name: "list_users",
+        description: "List Zuora platform users with optional SCIM filter (e.g., status eq 'Active'). " +
+            "Uses REST API, not ZOQL — the User object is not ZOQL-queryable. " +
+            "Supports pagination via startIndex/count. " +
+            "Returns user names, emails, statuses, roles, and last login times.",
+        inputSchema: schemas.listUsers,
+        invoke: (handlers, args) => handlers.listUsers(args),
+    },
+    {
+        name: "get_user",
+        description: "Get details of a specific Zuora platform user by their user ID (UUID). " +
+            "Returns user name, email, status, role, profile, and last login time.",
+        inputSchema: schemas.getUser,
+        invoke: (handlers, args) => handlers.getUser(args),
+    },
+    // Bill Run Tools
+    {
+        name: "get_bill_run",
+        description: "Get details and status of a Zuora bill run by bill run ID. " +
+            "Returns bill run number, status (Pending/Processing/Completed/Error/Canceled/Posted), " +
+            "target date, invoice date, and auto-post/email settings.",
+        inputSchema: schemas.getBillRun,
+        invoke: (handlers, args) => handlers.getBillRun(args),
+    },
+    {
+        name: "list_bill_runs",
+        description: "List bill runs in Zuora with pagination. " +
+            "Returns bill run numbers, statuses, target dates, and settings.",
+        inputSchema: schemas.listBillRuns,
+        invoke: (handlers, args) => handlers.listBillRuns(args),
+    },
+    // Contact Tools
+    {
+        name: "get_contact",
+        description: "Get full details of a Zuora contact by contact ID. " +
+            "Returns name, emails, phone numbers, address, tax region, and timestamps. " +
+            "Use ZOQL to find contact IDs: SELECT Id, FirstName, LastName FROM Contact WHERE AccountId = '...'",
+        inputSchema: schemas.getContact,
+        invoke: (handlers, args) => handlers.getContact(args),
+    },
+    // Describe API
+    {
+        name: "describe_object",
+        description: "Get field metadata for any Zuora object type. Returns all fields with names, types, " +
+            "and properties (selectable, createable, updateable, filterable, required). " +
+            "Essential for building correct ZOQL queries — use this to discover available fields " +
+            "before writing SELECT statements. Object type must be PascalCase (e.g., Account, " +
+            "Invoice, Subscription, Payment, RatePlan, RatePlanCharge, BillRun, Contact).",
+        inputSchema: schemas.describeObject,
+        invoke: (handlers, args) => handlers.describeObject(args),
+    },
+    // Phase 3: Write Operations (require confirmation before calling)
+    // Payment Creation (HIGH risk)
+    {
+        name: "create_payment",
+        description: "FINANCIAL WRITE OPERATION (HIGH RISK): Create a payment record in Zuora. " +
+            "This charges the customer or records an external payment. " +
+            "IMPORTANT: Confirm the account ID, amount, and effective date with the user before calling. " +
+            "Requires a UUID idempotency key to prevent duplicate payments. " +
+            "Electronic payments require a paymentMethodId and process through the payment gateway. " +
+            "External payments are manual records (check, wire, etc.). " +
+            "This action cannot be easily undone - refunds require a separate operation.",
+        inputSchema: schemas.createPayment,
+        invoke: (handlers, args) => handlers.createPayment(args),
+    },
+    // Payment Application (HIGH risk)
+    {
+        name: "apply_payment",
+        description: "FINANCIAL WRITE OPERATION (HIGH RISK): Apply an unapplied payment to one or more invoices. " +
+            "This reduces invoice balances and allocates payment funds. " +
+            "IMPORTANT: Confirm the payment ID, invoice IDs, and amounts with the user before calling. " +
+            "The total applied amount across all invoices must not exceed the payment's unapplied amount. " +
+            "ALWAYS use get_payment first to verify the unapplied balance before applying.",
+        inputSchema: schemas.applyPayment,
+        invoke: (handlers, args) => handlers.applyPayment(args),
+    },
+    // Invoice Creation (MEDIUM risk)
+    {
+        name: "create_invoice",
+        description: "FINANCIAL WRITE OPERATION (MEDIUM RISK): Create a draft invoice for a Zuora account. " +
+            "The invoice is created in Draft status and must be posted separately using post_invoice. " +
+            "Requires a UUID idempotency key to prevent duplicate invoices. " +
+            "Confirm the account ID and dates with the user before calling.",
+        inputSchema: schemas.createInvoice,
+        invoke: (handlers, args) => handlers.createInvoice(args),
+    },
+    // Invoice Posting (MEDIUM risk)
+    {
+        name: "post_invoice",
+        description: "FINANCIAL WRITE OPERATION (MEDIUM RISK): Post a draft invoice, changing its status to Posted. " +
+            "IMPORTANT: Once posted, the invoice is IMMUTABLE - it cannot be edited or deleted. " +
+            "Posted invoices affect the account balance and are visible to the customer. " +
+            "ALWAYS use get_invoice to review the draft invoice before posting. " +
+            "To reverse a posted invoice, you must create a credit memo.",
+        inputSchema: schemas.postInvoice,
+        invoke: (handlers, args) => handlers.postInvoice(args),
+    },
+    // Subscription Cancellation (HIGH risk)
+    {
+        name: "cancel_subscription",
+        description: "DESTRUCTIVE FINANCIAL OPERATION (HIGH RISK): Cancel a Zuora subscription. " +
+            "IMPORTANT: This action may be irreversible depending on the cancellation policy. " +
+            "Confirm the subscription key and cancellation policy with the user before calling. " +
+            "EndOfCurrentTerm: Cancels at the end of the current billing term. " +
+            "EndOfLastInvoicePeriod: Cancels at the end of the last invoiced period. " +
+            "SpecificDate: Cancels on a specific date (requires cancellationEffectiveDate). " +
+            "ALWAYS use get_subscription to review the subscription details before cancelling.",
+        inputSchema: schemas.cancelSubscription,
+        invoke: (handlers, args) => handlers.cancelSubscription(args),
+    },
+    // Phase 4: Advanced Operations
+    // Subscription Creation (HIGH risk)
+    {
+        name: "create_subscription",
+        description: "FINANCIAL WRITE OPERATION (HIGH RISK): Create a new subscription for a Zuora account. " +
+            "IMPORTANT: Confirm the account, rate plans, term type, and effective date with the user before calling. " +
+            "Requires a UUID idempotency key to prevent duplicate subscriptions. " +
+            "Use list_products to find available productRatePlanIds before creating. " +
+            "TERMED subscriptions require initialTerm and initialTermPeriodType. " +
+            "EVERGREEN subscriptions have no fixed end date. " +
+            "This creates a binding billing relationship that affects invoicing.",
+        inputSchema: schemas.createSubscription,
+        invoke: (handlers, args) => handlers.createSubscription(args),
+    },
+    // Subscription Update (MEDIUM risk)
+    {
+        name: "update_subscription",
+        description: "FINANCIAL WRITE OPERATION (MEDIUM RISK): Update a Zuora subscription's renewal terms or settings. " +
+            "Can modify autoRenew, renewalTerm, renewalTermPeriodType, and notes. " +
+            "Confirm the subscription key and changes with the user before calling. " +
+            "ALWAYS use get_subscription to review current settings before updating. " +
+            "Changes to renewal terms take effect at the next renewal.",
+        inputSchema: schemas.updateSubscription,
+        invoke: (handlers, args) => handlers.updateSubscription(args),
+    },
+    // Account Creation (MEDIUM risk)
+    {
+        name: "create_account",
+        description: "FINANCIAL WRITE OPERATION (MEDIUM RISK): Create a new billing account in Zuora. " +
+            "Requires account name, currency, bill cycle day, and bill-to contact information. " +
+            "Confirm all details with the user before calling. " +
+            "Requires a UUID idempotency key to prevent duplicate accounts. " +
+            "The account is created in Active status and can receive subscriptions immediately. " +
+            "Currency cannot be changed after account creation.",
+        inputSchema: schemas.createAccount,
+        invoke: (handlers, args) => handlers.createAccount(args),
+    },
+    // Account Update (LOW risk)
+    {
+        name: "update_account",
+        description: "WRITE OPERATION (LOW RISK): Update a Zuora account's name, notes, payment terms, " +
+            "auto-pay setting, or contact information. " +
+            "Confirm the account key and changes with the user before calling. " +
+            "ALWAYS use get_account to review current settings before updating. " +
+            "Only include fields that need to change.",
+        inputSchema: schemas.updateAccount,
+        invoke: (handlers, args) => handlers.updateAccount(args),
+    },
+    // Refund Creation (HIGH risk)
+    {
+        name: "create_refund",
+        description: "FINANCIAL WRITE OPERATION (HIGH RISK): Create a refund against a specific payment in Zuora. " +
+            "IMPORTANT: Confirm the payment ID, amount, and refund type with the user before calling. " +
+            "ALWAYS use get_payment to verify the payment exists and has sufficient applied amount. " +
+            "The refund amount must not exceed the original payment's applied amount. " +
+            "Electronic refunds are processed through the payment gateway and may take days to settle. " +
+            "External refunds are manual records (check, wire, etc.). " +
+            "Requires a UUID idempotency key to prevent duplicate refunds. " +
+            "This action cannot be easily undone.",
+        inputSchema: schemas.createRefund,
+        invoke: (handlers, args) => handlers.createRefund(args),
+    },
+    // Bill Run Creation (MEDIUM risk)
+    {
+        name: "create_bill_run",
+        description: "FINANCIAL WRITE OPERATION (MEDIUM RISK): Create a bill run to generate invoices for a billing cycle. " +
+            "Bill runs process all eligible charges through the target date and generate draft invoices. " +
+            "Confirm the target date with the user before calling. " +
+            "Set autoPost=true to automatically post generated invoices. " +
+            "Set autoEmail=true (requires autoPost) to email invoices to customers. " +
+            "Requires a UUID idempotency key to prevent duplicate bill runs. " +
+            "The bill run starts in Pending status and progresses through Processing to Completed.",
+        inputSchema: schemas.createBillRun,
+        invoke: (handlers, args) => handlers.createBillRun(args),
+    },
+    // Contact Creation (LOW risk)
+    {
+        name: "create_contact",
+        description: "WRITE OPERATION (LOW RISK): Create a new contact for a Zuora account. " +
+            "Requires account ID, first name, and last name. " +
+            "Contacts can be used as bill-to or sold-to addresses via update_account. " +
+            "Requires a UUID idempotency key to prevent duplicate contacts.",
+        inputSchema: schemas.createContact,
+        invoke: (handlers, args) => handlers.createContact(args),
+    },
+    // Contact Update (LOW risk)
+    {
+        name: "update_contact",
+        description: "WRITE OPERATION (LOW RISK): Update an existing Zuora contact's information. " +
+            "Only include fields that need to change. " +
+            "ALWAYS use get_contact to review current details before updating.",
+        inputSchema: schemas.updateContact,
+        invoke: (handlers, args) => handlers.updateContact(args),
+    },
+    // ==================== Composite Tools (Read-Only) ====================
+    {
+        name: "find_accounts_by_product",
+        description: "Find accounts with active subscriptions for a specific product. " +
+            "Answers questions like 'Which accounts have Security Analytics?' " +
+            "Internally chains: ProductRatePlan → RatePlan → Subscription → Account. " +
+            "Returns account details with subscription info and rate plan names.",
+        inputSchema: schemas.findAccountsByProduct,
+        invoke: (handlers, args) => handlers.findAccountsByProduct(args),
+    },
+    {
+        name: "get_overdue_invoices",
+        description: "List all overdue invoices across all accounts, sorted by days past due. " +
+            "Answers 'Show overdue invoices' or 'What invoices are past due?' " +
+            "Filters: Posted invoices with balance > 0 and due date in the past. " +
+            "Returns invoice details with account info and days past due.",
+        inputSchema: schemas.getOverdueInvoices,
+        invoke: (handlers, args) => handlers.getOverdueInvoices(args),
+    },
+    {
+        name: "get_expiring_subscriptions",
+        description: "Find subscriptions expiring within a time window. " +
+            "Answers 'What subscriptions expire this month?' or 'Renewal pipeline for Q1.' " +
+            "Shows MRR at risk (non-auto-renewing subscriptions). " +
+            "Returns subscription details with account info and days until expiry.",
+        inputSchema: schemas.getExpiringSubscriptions,
+        invoke: (handlers, args) => handlers.getExpiringSubscriptions(args),
+    },
+    {
+        name: "get_account_billing_overview",
+        description: "Comprehensive billing summary for a single account in one call. " +
+            "Answers 'What's the billing status for account X?' " +
+            "Combines: account details + recent invoices + payments + active subscriptions. " +
+            "Shows outstanding balance, overdue amounts, MRR, and recent activity.",
+        inputSchema: schemas.getAccountBillingOverview,
+        invoke: (handlers, args) => handlers.getAccountBillingOverview(args),
+    },
+    {
+        name: "get_revenue_by_product",
+        description: "MRR breakdown by product across all active subscriptions. " +
+            "Answers 'What's our revenue by product?' or 'MRR breakdown.' " +
+            "Chains: Subscription → RatePlan → ProductRatePlan → Product. " +
+            "Returns products sorted by MRR with subscription details.",
+        inputSchema: schemas.getRevenueByProduct,
+        invoke: (handlers, args) => handlers.getRevenueByProduct(args),
+    },
+    {
+        name: "get_payment_reconciliation",
+        description: "Payment reconciliation report for a date range. " +
+            "Answers 'What payments were received this month?' " +
+            "Returns payment list with account details, summary stats, and status breakdown.",
+        inputSchema: schemas.getPaymentReconciliation,
+        invoke: (handlers, args) => handlers.getPaymentReconciliation(args),
+    },
+    {
+        name: "get_recently_cancelled_subscriptions",
+        description: "Find subscriptions cancelled within a recent time window. " +
+            "Answers 'What churned last month?' or 'Recent cancellations.' " +
+            "Shows lost MRR and affected products. " +
+            "Returns cancelled subscription details with account info.",
+        inputSchema: schemas.getRecentlyCancelledSubscriptions,
+        invoke: (handlers, args) => handlers.getRecentlyCancelledSubscriptions(args),
+    },
+    {
+        name: "get_invoice_aging_report",
+        description: "AR aging report: all outstanding invoices bucketed by days past due. " +
+            "Answers 'Give me an AR aging report' or 'What does our accounts receivable look like?' " +
+            "Buckets: Current, 1-30, 31-60, 61-90, 90+ days. " +
+            "Returns aging buckets with invoice and account details.",
+        inputSchema: schemas.getInvoiceAgingReport,
+        invoke: (handlers, args) => handlers.getInvoiceAgingReport(args),
+    },
+    {
+        name: "get_account_health_scorecard",
+        description: "Identify at-risk accounts using multiple signals: overdue invoices, " +
+            "expiring subscriptions (non-auto-renewing), and recent payment failures. " +
+            "Answers 'Which accounts are at risk?' " +
+            "Returns accounts sorted by health score (0=critical, 100=healthy) with risk factors.",
+        inputSchema: schemas.getAccountHealthScorecard,
+        invoke: (handlers, args) => handlers.getAccountHealthScorecard(args),
+    },
+    {
+        name: "find_invoices_by_product",
+        description: "Find invoice line items for a specific product. " +
+            "Answers 'Show invoices for Security Analytics' or 'What was billed for product X?' " +
+            "Chains: ProductRatePlan → RatePlan → RatePlanCharge → InvoiceItem → Invoice → Account. " +
+            "Returns invoice items with charge amounts, dates, and account details.",
+        inputSchema: schemas.findInvoicesByProduct,
+        invoke: (handlers, args) => handlers.findInvoicesByProduct(args),
+    },
+];
+//# sourceMappingURL=tools.js.map