mcp-zenskar 1.1.10 → 1.1.11

package/README.md

@@ -1,18 +1,17 @@
 # Zenskar MCP Server
 
-MCP server for the Zenskar API. 103 tools covering customers, contracts, invoices, payments, credit notes, accounting, products, plans, quotes, and more.
+MCP server for the Zenskar API. 103 tools covering customers, contracts, invoices, payments, credit notes, accounting, products, plans, and more.
 
 ## What it does
 
-- Customers: list, search, create, update, addresses, contacts, payment methods
-- Contracts: create, read, update, delete, amend, add phases and pricing, expire
+- Customers: list, search, create, update, delete, addresses, contacts, payment methods
+- Contracts: create, read, update, delete, amend, add phases and pricing, pause/resume, expire
 - Invoices: list, get, approve, void, generate, credit notes, download
 - Payments: create, edit, refund, delete, auto-charge
 - Credit notes: list, create against invoice, get by ID
 - Accounting: chart of accounts, journal entries and lines, balance sheet, income statement, account balances
 - Products: CRUD, pricing configurations
 - Plans: list, create, add products, preview estimates
-- Quotes: create, preview, accept (converts to contract)
 - Business entities: list, get, create, update
 - Jobs: monitor async operations
 - Custom attributes and tax categories
@@ -91,6 +90,7 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `getCustomerById` | Get a customer by ID |
 | `createCustomer` | Create a customer with address and tax info |
 | `updateCustomer` | Update customer details (partial update) |
+| `deleteCustomer` | Permanently delete a customer by ID (only allowed when they have no active contracts or unpaid invoices) |
 
 ### Contacts
 | Tool | Description |
@@ -99,6 +99,7 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `getContactById` | Get a contact by ID |
 | `createContact` | Create a contact for a customer |
 | `updateContact` | Update a contact's details |
+| `deleteContact` | Delete a contact by ID |
 
 ### Contracts
 | Tool | Description |
@@ -112,6 +113,9 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `createContractPhase` | Add a phase to a contract (add-ons, expansions) |
 | `createContractPhasePricing` | Add pricing to a contract phase |
 | `expireContract` | Expire an active contract |
+| `pauseContract` | Pause an active contract from a given start date, with an unpause-extension policy (`extend` or `overlap`) and optional end date for auto-resume |
+| `editPauseContract` | Edit an existing pause phase — set or change the resume date, shift the start, or change the unpause policy |
+| `resumeContract` | Resume a paused contract |
 | `createContractPrompt` | Create a contract prompt |
 | `extractContractFromRaw` | Extract contract data from raw text using AI |
 
@@ -133,7 +137,8 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `generateInvoicePaymentLink` | Generate a payment link for an invoice |
 | `payInvoice` | Initiate payment for an invoice |
 | `approveInvoice` | Approve an invoice for billing |
-| `voidInvoice` | Void an approved unpaid invoice |
+| `voidInvoice` | Void an invoice |
+| `deleteInvoice` | Delete a draft invoice |
 | `generateInvoice` | Generate an invoice for a contract and date range |
 | `createInvoiceCreditNote` | Create a credit note against an invoice |
 | `createInvoiceCharge` | Auto-charge an invoice via payment gateway |
@@ -171,8 +176,6 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `listPlans` | List plan templates |
 | `getPlanById` | Get a plan by ID with phases and pricing |
 | `createPlan` | Create a plan template |
-| `addProductsToPlan` | Add products to an existing plan |
-| `previewPlanEstimate` | Preview estimated billing for a plan |
 
 ### Accounting
 | Tool | Description |
@@ -189,14 +192,6 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `getAccountBalance` | Get balance for a specific GL account |
 | `recogniseRevenue` | Trigger revenue recognition up to a date |
 
-### Quotes
-| Tool | Description |
-|---|---|
-| `createQuote` | Create a quote/proposal |
-| `previewQuoteEstimate` | Preview estimated billing for a quote |
-| `getQuoteById` | Get a quote by ID |
-| `acceptQuote` | Accept a quote, converting to a contract |
-
 ### Custom Attributes and Tax
 | Tool | Description |
 |---|---|
@@ -227,6 +222,7 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `updateCustomerAddress` | Update a customer address |
 | `listPaymentMethods` | List payment methods for a customer |
 | `attachPaymentMethod` | Attach a payment method to a customer |
+| `deletePaymentMethod` | Delete a payment method from a customer |
 
 ### Metrics and Usage Events
 | Tool | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-zenskar",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "description": "Model Context Protocol (MCP) server for Zenskar API - customer management, invoicing, and billing operations",
   "main": "src/server.js",
   "bin": {

package/src/mcp-config.json

@@ -586,7 +586,18 @@
     },
     {
       "name": "payInvoice",
-      "description": "Initiate payment for an invoice using a payload.",
+      "description": "Initiate payment for an invoice using a payload. MONEY-MOVING ACTION — only call when the user explicitly authorizes payment for this specific invoice.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Pay Invoice",
+        "description": "This will initiate a payment against the invoice using the provided payload.",
+        "warningText": "Money-moving action — funds will be charged. Verify the invoice and amount before confirming.",
+        "confirmText": "Pay Invoice",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "payload"
+        ]
+      },
       "args": [
         {
           "name": "payload",
@@ -2719,7 +2730,18 @@
     },
     {
       "name": "deleteContract",
-      "description": "Delete a contract by its ID. Only works on draft contracts. Returns the deleted contract object with a deleted_at timestamp.",
+      "description": "Permanently delete a DRAFT contract. ONLY works on contracts with status='draft'. Do NOT call on ACTIVE, EXPIRED, or PAUSED contracts. DESTRUCTIVE: removes all phases, products, and pricing associations. NEVER call as automatic recovery from another failed operation (e.g., do not retry as a fallback after expireContract or voidInvoice fails). ONLY call when the user explicitly says 'delete' or 'remove' for THIS draft contract. If a non-destructive action fails, surface the error verbatim and stop.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Draft Contract",
+        "description": "This will permanently delete the draft contract along with all its phases, products, and pricing associations.",
+        "warningText": "DESTRUCTIVE — this cannot be undone. Only draft contracts may be deleted; verify status before confirming.",
+        "confirmText": "Delete Contract",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "contractId"
+        ]
+      },
       "args": [
         {
           "name": "contractId",
@@ -2956,7 +2978,19 @@
     },
     {
       "name": "expireContract",
-      "description": "Expire an active contract. Only works on contracts with status 'active'. Optionally specify an expiry_date (defaults to today). The contract expires at end of day 23:59:59.999999.",
+      "description": "Expire an ACTIVE or PAUSED contract by adjusting its end_date. Allowed status transitions: ACTIVE→EXPIRED, PAUSED→EXPIRED. EXPIRED is terminal — calling on an already-expired contract returns 400; do NOT retry, do NOT escalate to deleteContract or any other destructive tool as a fallback. Verify contract.status via getContractById before calling. Idempotency: NO. The contract expires at end of day 23:59:59.999999.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Expire Contract",
+        "description": "This will set the contract's end_date and transition status to EXPIRED. EXPIRED is terminal.",
+        "warningText": "Once expired, the contract cannot be re-activated through this endpoint. Future-dated phases beyond the expiry will be removed.",
+        "confirmText": "Expire Contract",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "contractId",
+          "expiry_date"
+        ]
+      },
       "args": [
         {
           "name": "contractId",
@@ -2967,7 +3001,7 @@
         },
         {
           "name": "expiry_date",
-          "description": "Date to expire the contract (e.g. 2026-12-31). Defaults to today if not provided.",
+          "description": "Date to expire the contract (e.g. 2026-12-31). Defaults to today if not provided. Must not be earlier than contract.start_date.",
           "type": "string",
           "required": false,
           "position": "body"
@@ -2986,7 +3020,18 @@
     },
     {
       "name": "voidInvoice",
-      "description": "Void an invoice by its ID. Only works on approved invoices that have not been fully paid. Voiding reverses the invoice and creates appropriate accounting entries.",
+      "description": "Void an invoice. ONLY works on approved or paid invoices with invoice_total == 0 (zero-balance, typically after a full credit-note offset). For non-zero approved invoices, issue a credit note via createInvoiceCreditNote first to bring the balance to zero, then void. If the call returns INVOICE_CANNOT_BE_VOIDED, surface that error verbatim — do NOT retry, do NOT escalate to deleteInvoice.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Void Invoice",
+        "description": "This will set the invoice status to 'void' and post the corresponding accounting entries. Only zero-balance approved/paid invoices are eligible.",
+        "warningText": "Voiding affects accounting records and cannot be easily undone.",
+        "confirmText": "Void Invoice",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "invoiceId"
+        ]
+      },
       "args": [
         {
           "name": "invoiceId",
@@ -3007,6 +3052,40 @@
         "prependBody": "## Invoice Voided\n\n"
       }
     },
+    {
+      "name": "deleteInvoice",
+      "description": "Permanently delete a draft invoice. ONLY works on status='draft'. For approved invoices, use voidInvoice (with caveats) or createInvoiceCreditNote — do NOT call deleteInvoice on approved invoices. DESTRUCTIVE: record removed permanently. ONLY call when the user explicitly says 'delete' for THIS invoice; never call as automatic recovery from another failed operation.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Invoice",
+        "description": "This will permanently delete the draft invoice.",
+        "warningText": "DESTRUCTIVE — invoice record will be removed and cannot be recovered.",
+        "confirmText": "Delete Invoice",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "invoiceId"
+        ]
+      },
+      "args": [
+        {
+          "name": "invoiceId",
+          "description": "The unique identifier (UUID) of the draft or upcoming invoice to delete.",
+          "type": "string",
+          "required": true,
+          "position": "path"
+        }
+      ],
+      "requestTemplate": {
+        "url": "/invoices/{invoiceId}",
+        "method": "DELETE",
+        "headers": {
+          "Content-Type": "application/json"
+        }
+      },
+      "responseTemplate": {
+        "prependBody": "## Invoice Deleted\n\n"
+      }
+    },
     {
       "name": "createInvoiceCreditNote",
       "description": "Create a credit note against a specific invoice. The credit_note_amount is in the invoice's currency (e.g. 25 for $25). The API stores amounts in cents internally. Returns the created credit note.",
@@ -3046,7 +3125,7 @@
     },
     {
       "name": "generateInvoice",
-      "description": "Generate an invoice for a customer given a contract and date range. Use this for billing replay or on-demand invoice generation.",
+      "description": "Generate ONE invoice covering ALL products active in the (contract, customer, from_date, to_date) tuple. The invoice contains every applicable product as separate line items — do NOT call once per product. Granularity is per-phase, NOT per-product. To bill a multi-phase contract, call ONCE per phase using that phase's start/end as from_date/to_date — e.g., a 2-phase contract with 2 products = 2 calls (yielding 2 invoices, each with 2 line items), NOT 4 calls. Iterating per product produces fragmented duplicate invoices and is incorrect. Use for billing replay or on-demand invoice generation.",
       "args": [
         {
           "name": "contract_id",
@@ -3302,7 +3381,18 @@
     },
     {
       "name": "deleteManualPayment",
-      "description": "Delete a manual payment. Only works on payments that are in an eligible status for deletion.",
+      "description": "Permanently delete a manual payment record. Only works on payments in an eligible status for deletion. DESTRUCTIVE — only call when the user explicitly says 'delete' for THIS payment; never as automatic recovery from another failed operation.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Manual Payment",
+        "description": "This will permanently remove the manual payment record.",
+        "warningText": "DESTRUCTIVE — payment record will be removed and cannot be recovered. Linked invoice balance may shift as a result.",
+        "confirmText": "Delete Payment",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "paymentId"
+        ]
+      },
       "args": [
         {
           "name": "paymentId",
@@ -4126,7 +4216,7 @@
     },
     {
       "name": "createProductPricing",
-      "description": "Create a new pricing configuration for a product. The pricing_data object is a discriminated union — the 'pricing_type' field determines which pricing model schema to use.",
+      "description": "Create a new pricing configuration for a product. The pricing_data object is a discriminated union — the 'pricing_type' field determines which pricing model schema. IMPORTANT: ask the user explicitly for currency, quantity_type (fixed|metered), and unit amount BEFORE calling. Do not silently default any of these. unit_amount is in MAJOR currency units (float), e.g. 3 means $3, not 300 cents.",
       "args": [
         {
           "name": "productId",
@@ -4151,11 +4241,18 @@
         },
         {
           "name": "pricing_data",
-          "description": "Pricing data object (required). Must include 'pricing_type' discriminator. Supported types: flat_fee: {pricing_type:'flat_fee', unit_amount:10000}. per_unit: {pricing_type:'per_unit', unit_amount:500}. tiered: {pricing_type:'tiered', unit_amount:[1000,500], up_to:[100,null]}. volume: {pricing_type:'volume', unit_amount:[1000,500], up_to:[100,null]}. percent: {pricing_type:'percent', percentage:5.0}. package: {pricing_type:'package', package_size:10, unit_amount:5000}. step: {pricing_type:'step', unit_amount:[...], up_to:[...]}. matrix: {pricing_type:'matrix', dimensions:[...], values:[...]}.",
+          "description": "Pricing data object (required). MUST include 'pricing_type' discriminator AND 'currency' (ISO 4217, e.g. 'USD'). 'unit_amount' is in MAJOR currency units (float) — 3 means $3, NOT 300 cents. Do NOT convert to cents. Supported pricing_type values with examples: flat_fee: {pricing_type:'flat_fee', unit_amount:100, currency:'USD'}. per_unit: {pricing_type:'per_unit', unit_amount:3, currency:'USD'}. tiered: {pricing_type:'tiered', unit_amount:[10,5], up_to:[100,null], currency:'USD'}. volume: {pricing_type:'volume', unit_amount:[10,5], up_to:[100,null], currency:'USD'}. percent: {pricing_type:'percent', percentage:5.0, currency:'USD'}. package: {pricing_type:'package', package_size:10, unit_amount:50, currency:'USD'}. step: {pricing_type:'step', unit_amount:[...], up_to:[...], currency:'USD'}. matrix: {pricing_type:'matrix', dimensions:[...], values:[...], currency:'USD'}. Optional inside pricing_data for per_unit: 'proration_type' ('day_based'|'cadence_based'), 'charge_full_amount' (bool).",
           "type": "object",
           "required": true,
           "position": "body"
         },
+        {
+          "name": "quantity",
+          "description": "Quantity configuration (REQUIRED for usage-based pricing — ask the user). Top-level object, NOT inside pricing_data. Shape: {type: 'fixed'|'metered', quantity?: number, unit?: string, aggregate_id?: UUID}. 'fixed' means a static quantity (e.g. seats). 'metered' means consumption tracked via a billable metric — set aggregate_id to the billable-metric UUID. Without a quantity object the resulting pricing has no billing_metric and renders as 0 in the UI.",
+          "type": "object",
+          "required": false,
+          "position": "body"
+        },
         {
           "name": "billing_period",
           "description": "Billing cadence for this pricing. Object with 'cadence' (ISO 8601 duration, e.g. 'P1M' for monthly, 'P3M' for quarterly, 'P1Y' for annually) and optional 'offset'. Example: {cadence: 'P1M'}.",
@@ -4191,7 +4288,7 @@
     },
     {
       "name": "listPlans",
-      "description": "Retrieve a paginated list of plans (templates v3) that define reusable contract structures.",
+      "description": "Retrieve a paginated list of plans that define reusable contract structures. Hits /plans — the same data the Zenskar app's Plans page reads.",
       "args": [
         {
           "name": "cursor",
@@ -4223,7 +4320,7 @@
         }
       ],
       "requestTemplate": {
-        "url": "/templates/plan",
+        "url": "/plans",
         "method": "GET",
         "headers": {
           "Content-Type": "application/json"
@@ -4246,7 +4343,7 @@
         }
       ],
       "requestTemplate": {
-        "url": "/templates/plan/{planId}",
+        "url": "/plans/{planId}",
         "method": "GET",
         "headers": {
           "Content-Type": "application/json"
@@ -4258,7 +4355,7 @@
     },
     {
       "name": "createPlan",
-      "description": "Create a new plan (template) that defines a reusable contract structure with products and pricing.",
+      "description": "Create a new plan — a reusable contract template with products and pricing. Hits POST /plans (same store the Zenskar app's Plans page reads).",
       "args": [
         {
           "name": "name",
@@ -4318,7 +4415,7 @@
         }
       ],
       "requestTemplate": {
-        "url": "/templates/plan",
+        "url": "/plans",
         "method": "POST",
         "headers": {
           "Content-Type": "application/json"
@@ -4328,73 +4425,6 @@
         "prependBody": "## Created Plan\n\n"
       }
     },
-    {
-      "name": "addProductsToPlan",
-      "description": "Add products with pricing to an existing plan.",
-      "args": [
-        {
-          "name": "planId",
-          "description": "The unique identifier of the plan.",
-          "type": "string",
-          "required": true,
-          "position": "path"
-        },
-        {
-          "name": "products",
-          "description": "Array of product objects to add, each with product_id and pricing configuration.",
-          "type": "array",
-          "required": true,
-          "position": "body"
-        }
-      ],
-      "requestTemplate": {
-        "url": "/templates/plan/{planId}/products",
-        "method": "POST",
-        "headers": {
-          "Content-Type": "application/json"
-        }
-      },
-      "responseTemplate": {
-        "prependBody": "## Updated Plan Products\n\n"
-      }
-    },
-    {
-      "name": "previewPlanEstimate",
-      "description": "Preview the estimated billing for a plan, showing projected charges per phase.",
-      "args": [
-        {
-          "name": "planId",
-          "description": "The unique identifier of the plan.",
-          "type": "string",
-          "required": true,
-          "position": "path"
-        },
-        {
-          "name": "start_date",
-          "description": "Start date for the estimate (YYYY-MM-DD).",
-          "type": "string",
-          "required": true,
-          "position": "body"
-        },
-        {
-          "name": "end_date",
-          "description": "End date for the estimate (YYYY-MM-DD). Optional — calculated from plan duration if omitted.",
-          "type": "string",
-          "required": false,
-          "position": "body"
-        }
-      ],
-      "requestTemplate": {
-        "url": "/templates/plan/{planId}/preview",
-        "method": "POST",
-        "headers": {
-          "Content-Type": "application/json"
-        }
-      },
-      "responseTemplate": {
-        "prependBody": "## Plan Estimate Preview\n\n"
-      }
-    },
     {
       "name": "listCustomAttributes",
       "description": "Retrieve a list of custom attribute definitions configured for the organization.",
@@ -5107,7 +5137,18 @@
     },
     {
       "name": "deleteCustomer",
-      "description": "Delete a customer by ID. This is permanent and cannot be undone. The customer must not have active contracts or unpaid invoices.",
+      "description": "Permanently delete a customer by ID. DESTRUCTIVE and cannot be undone. The customer must not have active contracts or unpaid invoices. ONLY call when the user explicitly says 'delete' for THIS customer; never as automatic recovery from another failed operation.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Customer",
+        "description": "This will permanently delete the customer and all associated records.",
+        "warningText": "DESTRUCTIVE — customer record cannot be recovered. Verify there are no active contracts or unpaid invoices first.",
+        "confirmText": "Delete Customer",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "customerId"
+        ]
+      },
       "args": [
         {
           "name": "customerId",
@@ -5130,7 +5171,18 @@
     },
     {
       "name": "deleteContact",
-      "description": "Delete a contact by ID.",
+      "description": "Permanently delete a contact by ID. DESTRUCTIVE — only call when the user explicitly says 'delete' for THIS contact; never as automatic recovery from another failed operation.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Contact",
+        "description": "This will permanently delete the contact record.",
+        "warningText": "DESTRUCTIVE — contact record will be removed and cannot be recovered.",
+        "confirmText": "Delete Contact",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "contactId"
+        ]
+      },
       "args": [
         {
           "name": "contactId",
@@ -5153,7 +5205,19 @@
     },
     {
       "name": "deletePaymentMethod",
-      "description": "Delete a payment method from a customer.",
+      "description": "Permanently delete a payment method from a customer. DESTRUCTIVE — saved card/bank details will be removed; recurring auto-charges using this method will fail. Only call when the user explicitly says 'delete' for THIS payment method.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Payment Method",
+        "description": "This will permanently delete the payment method from the customer's profile.",
+        "warningText": "DESTRUCTIVE — saved payment details will be removed. Any auto-charge or scheduled charge using this method will fail.",
+        "confirmText": "Delete Payment Method",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "customerId",
+          "paymentMethodId"
+        ]
+      },
       "args": [
         {
           "name": "customerId",
@@ -5183,7 +5247,7 @@
     },
     {
       "name": "pauseContract",
-      "description": "Pause an active contract. Requires a start_date for the pause and an unpause_extension_policy.",
+      "description": "Pause an active contract. ALWAYS ask the user explicitly for both 'start_date' and 'unpause_extension_policy' before calling — do NOT silently default. A future-dated start_date will create a scheduled pause that has not yet begun; the contract's top-level status stays 'active' until start_date passes. Use 'editPauseContract' to adjust the pause window or set a resume date afterward.",
       "args": [
         {
           "name": "contractId",
@@ -5194,14 +5258,14 @@
         },
         {
           "name": "start_date",
-          "description": "Date when the pause begins (ISO 8601 format, e.g. 2026-04-01T00:00:00).",
+          "description": "Date when the pause begins (ISO 8601 format, e.g. 2026-04-01T00:00:00). REQUIRED — ask the user; never default to today or a future date silently.",
           "type": "string",
           "required": true,
           "position": "body"
         },
         {
           "name": "unpause_extension_policy",
-          "description": "How to handle the contract end date when unpaused.",
+          "description": "How to handle the contract end date when unpaused. 'extend' pushes the end_date out by the pause duration; 'overlap' keeps end_date fixed. ASK the user.",
           "type": "string",
           "required": true,
           "position": "body",
@@ -5229,9 +5293,57 @@
         "prependBody": "## Contract Paused\n\n"
       }
     },
+    {
+      "name": "editPauseContract",
+      "description": "Edit an existing pause phase on a contract. Use this when 'resumeContract' returns 'pause phase not found' for a future-dated pause, or when the user wants to set a resume date (pause end_date), shift the pause start, or change the unpause_extension_policy. Hits PATCH /contract_v2/{contractId}/pause.",
+      "args": [
+        {
+          "name": "contractId",
+          "description": "The unique identifier (UUID) of the contract whose pause phase to edit.",
+          "type": "string",
+          "required": true,
+          "position": "path"
+        },
+        {
+          "name": "start_date",
+          "description": "New pause start date (ISO 8601). Optional.",
+          "type": "string",
+          "required": false,
+          "position": "body"
+        },
+        {
+          "name": "end_date",
+          "description": "Resume date — when the pause ends (ISO 8601). Set this to schedule a future resume.",
+          "type": "string",
+          "required": false,
+          "position": "body"
+        },
+        {
+          "name": "unpause_extension_policy",
+          "description": "How to handle the contract end date when unpaused. 'extend' or 'overlap'.",
+          "type": "string",
+          "required": false,
+          "position": "body",
+          "enum": [
+            "extend",
+            "overlap"
+          ]
+        }
+      ],
+      "requestTemplate": {
+        "url": "/contract_v2/{contractId}/pause",
+        "method": "PATCH",
+        "headers": {
+          "Content-Type": "application/json"
+        }
+      },
+      "responseTemplate": {
+        "prependBody": "## Pause Phase Updated\n\n"
+      }
+    },
     {
       "name": "resumeContract",
-      "description": "Resume a paused contract. No request body needed.",
+      "description": "Resume an actively-running pause on a contract. PRECONDITIONS: the pause's start_date must be strictly in the past (not today, not future). For pauses scheduled for a future start, or to set a future resume date, use 'editPauseContract' instead (sets the pause's end_date). The error 'pause phase not found' means no pause phase has yet started — NOT that no pause exists. If this call fails, surface the error verbatim and consider 'editPauseContract'; do NOT escalate to deleteContract or any destructive fallback.",
       "args": [
         {
           "name": "contractId",