@armor/zuora-mcp 1.1.0 → 1.3.0

package/dist/tools.js

@@ -79,6 +79,12 @@ export const schemas = {
             .string()
             .min(1)
             .describe("Account ID or account number"),
+        maxResults: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("Maximum number of subscriptions to return. When specified, results are truncated server-side. Omit to return all subscriptions for the account."),
     }),
     // Payment Tools
     getPayment: z.object({
@@ -116,15 +122,27 @@ export const schemas = {
             "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. " +
+            "Limitations: No JOINs supported. Max 2000 records per call. " +
             "Use continue_zoql_query with queryLocator for pagination. " +
             "Example: SELECT Id, AccountNumber, Balance FROM Account WHERE Status = 'Active'"),
+        maxResults: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("Maximum records to return. When specified, results are truncated server-side to exactly this count. ZOQL has no LIMIT clause, so this parameter handles it at the application layer. Omit to return all records from the first page (up to 2000)."),
     }),
     continueZoqlQuery: z.object({
         queryLocator: z
             .string()
             .min(1)
             .describe("Query locator from a previous ZOQL query result for pagination"),
+        maxResults: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("Maximum records to return from this continuation page. When specified, results are truncated server-side. Omit to return all records from the page (up to 2000)."),
     }),
     // Product Catalog Tools
     listProducts: z.object({
@@ -198,6 +216,12 @@ export const schemas = {
             .enum(["=", "!=", "LIKE", ">", "<", ">=", "<="])
             .default("=")
             .describe("Comparison operator (default: =). Use LIKE for partial name matches with % wildcard."),
+        maxResults: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("Maximum number of accounts to return. When specified, results are truncated server-side to exactly this count. Supports any count including values beyond the 2000-per-page ZOQL limit via auto-pagination. Omit to return all matching records."),
     }),
     listUsage: z.object({
         accountKey: z
@@ -218,6 +242,73 @@ export const schemas = {
             .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
@@ -597,6 +688,126 @@ export const schemas = {
             .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
@@ -648,6 +859,27 @@ export const schemas = {
             .string()
             .min(1)
             .describe("Account number or ID (e.g., A00012345)"),
+        maxInvoices: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .default(20)
+            .describe("Maximum number of recent invoices to fetch (default: 20)."),
+        maxPayments: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .default(10)
+            .describe("Maximum number of recent payments to fetch (default: 10)."),
+        maxSubscriptions: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .default(10)
+            .describe("Maximum number of active subscriptions to include (default: 10)."),
     }),
     getRevenueByProduct: z.object({
         limit: z
@@ -824,13 +1056,23 @@ export class ToolHandlers {
     }
     async listSubscriptions(input) {
         try {
-            const { accountKey } = schemas.listSubscriptions.parse(input);
+            const { accountKey, maxResults } = schemas.listSubscriptions.parse(input);
             const result = await this.client.listSubscriptionsByAccount(accountKey);
-            const count = result.subscriptions?.length ?? 0;
+            const allSubs = result.subscriptions ?? [];
+            const subscriptions = maxResults !== undefined
+                ? allSubs.slice(0, maxResults)
+                : allSubs;
             return {
                 success: true,
-                message: `Found ${count} subscription(s) for account ${accountKey}`,
-                data: result,
+                message: maxResults !== undefined && allSubs.length > maxResults
+                    ? `Returning ${subscriptions.length} of ${allSubs.length} subscription(s) for account ${accountKey}`
+                    : `Found ${subscriptions.length} subscription(s) for account ${accountKey}`,
+                data: {
+                    subscriptions,
+                    ...(maxResults !== undefined && allSubs.length > maxResults
+                        ? { totalAvailable: allSubs.length }
+                        : {}),
+                },
             };
         }
         catch (error) {
@@ -884,7 +1126,22 @@ export class ToolHandlers {
     // --- ZOQL Query Handlers ---
     async executeZoqlQuery(input) {
         try {
-            const { zoqlQuery } = schemas.executeZoqlQuery.parse(input);
+            const { zoqlQuery, maxResults } = schemas.executeZoqlQuery.parse(input);
+            if (maxResults !== undefined) {
+                // Auto-paginate and truncate to exact count requested
+                const allRecords = await this.client.queryAll(zoqlQuery, maxResults);
+                const records = allRecords.slice(0, maxResults);
+                return {
+                    success: true,
+                    message: `Returning ${records.length} record(s)`,
+                    data: {
+                        size: records.length,
+                        records,
+                        done: true,
+                    },
+                };
+            }
+            // No maxResults — return first page as before
             const result = await this.client.executeQuery(zoqlQuery);
             const moreAvailable = result.queryLocator
                 ? " (more available via continue_zoql_query)"
@@ -904,8 +1161,25 @@ export class ToolHandlers {
     }
     async continueZoqlQuery(input) {
         try {
-            const { queryLocator } = schemas.continueZoqlQuery.parse(input);
+            const { queryLocator, maxResults } = schemas.continueZoqlQuery.parse(input);
             const result = await this.client.queryMore(queryLocator);
+            if (maxResults !== undefined) {
+                const allRecords = result.records ?? [];
+                const records = allRecords.slice(0, maxResults);
+                const moreAvailable = (allRecords.length > maxResults || result.queryLocator)
+                    ? " (more available)"
+                    : "";
+                return {
+                    success: true,
+                    message: `Continuation returned ${records.length} record(s)${moreAvailable}`,
+                    data: {
+                        size: records.length,
+                        records,
+                        queryLocator: result.queryLocator,
+                        done: result.done,
+                    },
+                };
+            }
             const moreAvailable = result.queryLocator
                 ? " (more available)"
                 : "";
@@ -998,7 +1272,21 @@ export class ToolHandlers {
     }
     async searchAccounts(input) {
         try {
-            const { field, value, operator } = schemas.searchAccounts.parse(input);
+            const { field, value, operator, maxResults } = schemas.searchAccounts.parse(input);
+            if (maxResults !== undefined) {
+                // Use queryAll for auto-pagination, then truncate to exact count
+                const allRecords = await this.client.searchAccountsWithLimit(field, value, operator, maxResults);
+                return {
+                    success: true,
+                    message: `Returning ${allRecords.length} account(s) matching search criteria`,
+                    data: {
+                        size: allRecords.length,
+                        records: allRecords,
+                        done: true,
+                    },
+                };
+            }
+            // No maxResults — return full result as before
             const result = await this.client.searchAccounts(field, value, operator);
             const count = result.records?.length ?? 0;
             return {
@@ -1032,6 +1320,115 @@ export class ToolHandlers {
             };
         }
     }
+    // --- 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 {
@@ -1059,7 +1456,7 @@ export class ToolHandlers {
             });
             return {
                 success: true,
-                message: `Applied payment ${result.paymentNumber} successfully`,
+                message: `Applied payment ${paymentId} (applied: ${result.appliedAmount}) successfully`,
                 data: result,
             };
         }
@@ -1207,6 +1604,59 @@ export class ToolHandlers {
             };
         }
     }
+    // --- 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 {
@@ -1319,7 +1769,7 @@ export class ToolHandlers {
             // 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 > ${minBalance} AND DueDate < '${today}'`, limit);
+                `WHERE Status = 'Posted' AND Balance > ${Number(minBalance)} AND DueDate < '${today}'`, limit);
             if (invoices.length === 0) {
                 return {
                     success: true,
@@ -1416,7 +1866,7 @@ export class ToolHandlers {
                     accountName: getString(acct ?? {}, "Name") ?? "",
                     status: getString(sub, "Status") ?? "",
                     termEndDate: termEnd,
-                    autoRenew: sub.AutoRenew === true,
+                    autoRenew: getString(sub, "AutoRenew") === "true",
                     contractedMrr: getNumber(sub, "ContractedMrr") ?? 0,
                     ratePlanNames: rpNamesBySub.get(subId) ?? [],
                     daysUntilExpiry: daysBetween(today, termEnd),
@@ -1445,17 +1895,17 @@ export class ToolHandlers {
     }
     async getAccountBillingOverview(input) {
         try {
-            const { accountKey } = schemas.getAccountBillingOverview.parse(input);
+            const { accountKey, maxInvoices, maxPayments, maxSubscriptions } = 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);
+                `ORDER BY InvoiceDate DESC`, maxInvoices);
             // 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);
+                `ORDER BY EffectiveDate DESC`, maxPayments);
             // Step 4: Get subscriptions via REST API
             const subResult = await this.client.listSubscriptionsByAccount(accountKey);
             const subscriptions = subResult.subscriptions ?? [];
@@ -1493,7 +1943,7 @@ export class ToolHandlers {
                     totalOutstanding,
                     overdueCount,
                     overdueAmount,
-                    recentInvoices: invoices.slice(0, 10).map((inv) => ({
+                    recentInvoices: invoices.slice(0, maxInvoices).map((inv) => ({
                         invoiceNumber: getString(inv, "InvoiceNumber") ?? "",
                         invoiceDate: getString(inv, "InvoiceDate") ?? "",
                         dueDate: getString(inv, "DueDate") ?? "",
@@ -1503,7 +1953,7 @@ export class ToolHandlers {
                     })),
                 },
                 paymentSummary: {
-                    recentPayments: payments.slice(0, 5).map((p) => ({
+                    recentPayments: payments.slice(0, maxPayments).map((p) => ({
                         paymentNumber: getString(p, "PaymentNumber") ?? "",
                         amount: getNumber(p, "Amount") ?? 0,
                         effectiveDate: getString(p, "EffectiveDate") ?? "",
@@ -1513,7 +1963,7 @@ export class ToolHandlers {
                 subscriptionSummary: {
                     activeCount: activeSubscriptions.length,
                     totalMrr,
-                    subscriptions: activeSubscriptions.slice(0, 10).map((s) => ({
+                    subscriptions: activeSubscriptions.slice(0, maxSubscriptions).map((s) => ({
                         subscriptionNumber: s.subscriptionNumber,
                         status: s.status,
                         termEndDate: s.termEndDate,
@@ -1539,7 +1989,7 @@ export class ToolHandlers {
         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, Status ` +
+            const subscriptions = await queryAll(this.client, `SELECT Id, AccountId, SubscriptionNumber, ContractedMrr, TotalContractedValue, Status ` +
                 `FROM Subscription WHERE Status = 'Active'`, 5000);
             if (subscriptions.length === 0) {
                 return {
@@ -1588,6 +2038,7 @@ export class ToolHandlers {
                 };
                 existing.subscriptionCount++;
                 existing.totalMrr += mrr;
+                existing.totalTcv += getNumber(sub, "TotalContractedValue") ?? 0;
                 existing.subscriptions.push({
                     subscriptionNumber: getString(sub, "SubscriptionNumber") ?? "",
                     accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
@@ -1693,9 +2144,9 @@ export class ToolHandlers {
         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, UpdatedDate, ContractedMrr ` +
+            const subscriptions = await queryAll(this.client, `SELECT Id, SubscriptionNumber, AccountId, Status, TermEndDate, CancelledDate, ContractedMrr ` +
                 `FROM Subscription ` +
-                `WHERE Status = 'Cancelled' AND UpdatedDate >= '${sinceDate}'`, limit * 2);
+                `WHERE Status = 'Cancelled' AND CancelledDate >= '${sinceDate}'`, limit * 2);
             if (subscriptions.length === 0) {
                 return {
                     success: true,
@@ -1730,7 +2181,7 @@ export class ToolHandlers {
                     accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
                     accountName: getString(acct ?? {}, "Name") ?? "",
                     status: getString(sub, "Status") ?? "",
-                    cancelledDate: getString(sub, "UpdatedDate") ?? "",
+                    cancelledDate: getString(sub, "CancelledDate") ?? "",
                     termEndDate: getString(sub, "TermEndDate") ?? "",
                     contractedMrr: getNumber(sub, "ContractedMrr") ?? 0,
                     ratePlanNames: rpNamesBySub.get(subId) ?? [],
@@ -1845,7 +2296,7 @@ export class ToolHandlers {
             // 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);
+                `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 ` +
@@ -1997,7 +2448,7 @@ export class ToolHandlers {
             }
             const rpcIds = collectIds(ratePlanCharges, "Id");
             // Step 3: Find InvoiceItems by RatePlanChargeId
-            const invoiceItems = await queryWithBatchedIds(this.client, "Id, InvoiceId, ChargeAmount, ChargeName, ServiceStartDate, ServiceEndDate, SubscriptionId", "InvoiceItem", "RatePlanChargeId", rpcIds, undefined, limit);
+            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,
@@ -2100,7 +2551,8 @@ export const toolRegistrations = [
     {
         name: "list_subscriptions",
         description: "List all subscriptions for a Zuora account. " +
-            "Returns subscription names, statuses, and term dates.",
+            "Returns subscription names, statuses, and term dates. " +
+            "Use the maxResults parameter when the user requests a specific number of subscriptions.",
         inputSchema: schemas.listSubscriptions,
         invoke: (handlers, args) => handlers.listSubscriptions(args),
     },
@@ -2126,8 +2578,9 @@ export const toolRegistrations = [
             "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. " +
+            "Limitations: No JOINs supported. ZOQL has no LIMIT clause — use the maxResults " +
+            "parameter to control how many records are returned (e.g., maxResults=10). " +
+            "Use continue_zoql_query with queryLocator for manual pagination when maxResults is not set. " +
             "Example: SELECT Id, AccountNumber, Name, Balance FROM Account WHERE Status = 'Active'",
         inputSchema: schemas.executeZoqlQuery,
         invoke: (handlers, args) => handlers.executeZoqlQuery(args),
@@ -2135,7 +2588,8 @@ export const toolRegistrations = [
     {
         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.",
+            "(indicates more records available). Returns the next batch of up to 2000 records. " +
+            "Use the maxResults parameter to return fewer records from the continuation page.",
         inputSchema: schemas.continueZoqlQuery,
         invoke: (handlers, args) => handlers.continueZoqlQuery(args),
     },
@@ -2179,6 +2633,8 @@ export const toolRegistrations = [
             "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. " +
+            "Use the maxResults parameter when the user requests a specific number of records " +
+            "(e.g., 'get 10 active accounts' → maxResults=10). " +
             "For additional fields, use execute_zoql_query directly.",
         inputSchema: schemas.searchAccounts,
         invoke: (handlers, args) => handlers.searchAccounts(args),
@@ -2191,6 +2647,59 @@ export const toolRegistrations = [
         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)
     {
@@ -2312,6 +2821,38 @@ export const toolRegistrations = [
         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",