@ar-agents/mercadopago 0.13.0 → 0.14.0

package/dist/index.d.cts

@@ -365,6 +365,12 @@ interface CreatePreapprovalParams {
     backUrl: string;
     /** Optional client-side identifier for the subscription. */
     externalReference?: string;
+    /**
+     * Optional explicit idempotency key. If omitted, the client auto-generates
+     * a UUID v4 per call. Pass a deterministic key (e.g., hash of inputs) when
+     * you need cross-retry idempotency from the agent layer.
+     */
+    idempotencyKey?: string;
 }
 /**
  * The shape of an MP webhook notification body for `topic=preapproval`. MP's
@@ -734,6 +740,13 @@ interface CreatePreferenceParams {
     marketplaceFee?: number;
     /** Seller's MP user_id. Funds route here when set. */
     collectorId?: string | number;
+    /**
+     * Optional explicit idempotency key. If omitted, the client auto-generates
+     * a UUID v4 per call. Pass a deterministic key (e.g., hash of items +
+     * external_reference) when you need cross-retry idempotency from the
+     * agent layer.
+     */
+    idempotencyKey?: string;
 }
 declare const CustomerSchema: z.ZodObject<{
     id: z.ZodString;
@@ -1332,6 +1345,14 @@ interface CreatePointPaymentIntentParams {
 interface MercadoPagoClientOptions {
     /** Access token. TEST- prefix for sandbox, APP_USR- for production. */
     accessToken: string;
+    /**
+     * Escape hatch for browser-context tests (e.g., jsdom). MUST NOT be set
+     * in production code — the constructor's browser-context check exists
+     * specifically to prevent the access token from being bundled into a
+     * client-side JavaScript bundle. The `__` prefix and explicit boolean
+     * are deliberate friction so this never gets typed by accident.
+     */
+    __allowBrowser?: boolean;
     /**
      * Override the API base URL. Mostly useful for tests against MSW or for
      * pointing at a regional MP host. Defaults to https://api.mercadopago.com.

package/dist/index.d.ts

@@ -365,6 +365,12 @@ interface CreatePreapprovalParams {
     backUrl: string;
     /** Optional client-side identifier for the subscription. */
     externalReference?: string;
+    /**
+     * Optional explicit idempotency key. If omitted, the client auto-generates
+     * a UUID v4 per call. Pass a deterministic key (e.g., hash of inputs) when
+     * you need cross-retry idempotency from the agent layer.
+     */
+    idempotencyKey?: string;
 }
 /**
  * The shape of an MP webhook notification body for `topic=preapproval`. MP's
@@ -734,6 +740,13 @@ interface CreatePreferenceParams {
     marketplaceFee?: number;
     /** Seller's MP user_id. Funds route here when set. */
     collectorId?: string | number;
+    /**
+     * Optional explicit idempotency key. If omitted, the client auto-generates
+     * a UUID v4 per call. Pass a deterministic key (e.g., hash of items +
+     * external_reference) when you need cross-retry idempotency from the
+     * agent layer.
+     */
+    idempotencyKey?: string;
 }
 declare const CustomerSchema: z.ZodObject<{
     id: z.ZodString;
@@ -1332,6 +1345,14 @@ interface CreatePointPaymentIntentParams {
 interface MercadoPagoClientOptions {
     /** Access token. TEST- prefix for sandbox, APP_USR- for production. */
     accessToken: string;
+    /**
+     * Escape hatch for browser-context tests (e.g., jsdom). MUST NOT be set
+     * in production code — the constructor's browser-context check exists
+     * specifically to prevent the access token from being bundled into a
+     * client-side JavaScript bundle. The `__` prefix and explicit boolean
+     * are deliberate friction so this never gets typed by accident.
+     */
+    __allowBrowser?: boolean;
     /**
      * Override the API base URL. Mostly useful for tests against MSW or for
      * pointing at a regional MP host. Defaults to https://api.mercadopago.com.

package/dist/index.js

@@ -253,6 +253,12 @@ var MercadoPagoClient = class {
   circuitBreaker;
   traceContext;
   constructor(options) {
+    const w = globalThis.window;
+    if (typeof w !== "undefined" && !options.__allowBrowser) {
+      throw new Error(
+        "MercadoPagoClient must NEVER be instantiated in a browser context \u2014 the access token would be exposed in the JavaScript bundle and visible to anyone in DevTools. Use a Server Component, Route Handler, Server Action, or any server-only execution context. If you're running in jsdom for tests and KNOW this is safe, pass `__allowBrowser: true`."
+      );
+    }
     if (!options.accessToken) {
       throw new Error(
         "MercadoPagoClient requires an accessToken. Get one from https://www.mercadopago.com.ar/developers/panel/credentials"
@@ -451,7 +457,10 @@ var MercadoPagoClient = class {
           currency_id: params.currency
         }
       },
-      { classifyContext: { payerEmail: params.payerEmail } }
+      {
+        ...params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : {},
+        classifyContext: { payerEmail: params.payerEmail }
+      }
     );
   }
   async getPreapproval(id) {
@@ -647,7 +656,12 @@ var MercadoPagoClient = class {
     if (params.marketplace) body.marketplace = params.marketplace;
     if (params.marketplaceFee !== void 0) body.marketplace_fee = params.marketplaceFee;
     if (params.collectorId !== void 0) body.collector_id = params.collectorId;
-    return this.request("POST", "/checkout/preferences", body);
+    return this.request(
+      "POST",
+      "/checkout/preferences",
+      body,
+      params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : void 0
+    );
   }
   async getPreference(id) {
     return this.request("GET", `/checkout/preferences/${id}`);
@@ -3028,10 +3042,10 @@ var DEFAULT_DESCRIPTIONS = {
   create_payment: "Create a one-time payment. Two flows: (a) with a card token from MP frontend Cardform \u2014 for transparent checkout; (b) without token, for non-card methods like 'account_money', 'rapipago', 'pagofacil'. For most agent flows where you only have a payer email and want to send them a payment link, use create_payment_preference instead (Checkout Pro hosted form). Returns the Payment object with status \u2014 typically 'approved' for account_money and 'pending' for tickets.",
   get_payment: "Fetch a single payment by ID. Use to confirm status after webhook arrives, or to inspect details (status_detail explains rejections).",
   search_payments: "Search payments with filters. Most common: by external_reference (your-system identifier) to find all payments for an order, or by status='approved' to list successful charges in a date range. Returns paginated results.",
-  cancel_payment: "Cancel a pending or in_process payment (only works before approval). Once approved, use refund_payment instead. Common use: cancel an unpaid ticket payment that's still pending.",
-  capture_payment: "Capture an authorized credit-card payment that was created with capture=false. Use for hold-then-capture flows (e.g., authorize on order, capture on shipment). Optional partial amount.",
+  cancel_payment: "Cancel a pending or in_process payment (only works before approval). Once approved, use refund_payment instead. Common use: cancel an unpaid ticket payment that's still pending. **IRREVERSIBLE \u2014 confirm with the user before calling. Surface the payment_id, amount, payer_email, and current status, ask 's\xED, cancel\xE1' (or equivalent), then proceed.**",
+  capture_payment: "Capture an authorized credit-card payment that was created with capture=false. Use for hold-then-capture flows (e.g., authorize on order, capture on shipment). Optional partial amount. **MOVES MONEY \u2014 confirm the amount with the user before calling.**",
   // ── Refunds ──────────────────────────────────────────────────────────────
-  refund_payment: "Refund an approved payment. Pass amount for partial refund; omit for full refund. Idempotency key is auto-generated based on paymentId+amount to prevent double-refunds on retries.",
+  refund_payment: "Refund an approved payment. Pass amount for partial refund; omit for full refund. Idempotency key is auto-generated based on paymentId+amount to prevent double-refunds on retries. **IRREVERSIBLE AND MOVES MONEY \u2014 confirm with the user before calling. Restate the payment_id, the refund amount (full vs partial), and ask explicit confirmation. Mercado Pago does not support 'undo refund' \u2014 once issued, the buyer's bank releases the funds.**",
   list_refunds: "List all refunds for a given payment. Returns array of Refund objects. Useful to confirm a refund was processed or to inspect partial-refund history.",
   // ── Checkout Pro ─────────────────────────────────────────────────────────
   create_payment_preference: "Create a Mercado Pago Checkout Pro preference and get back a payment URL (init_point) to send to the customer. THIS is the recommended way for an agent to take a payment when you only have a payer email \u2014 the buyer enters card data on MP's hosted form (no PCI scope needed). Supports cuotas configuration, payment method exclusions, back URLs after success/failure/pending. In sandbox, use sandbox_init_point from the response.",
@@ -3040,7 +3054,7 @@ var DEFAULT_DESCRIPTIONS = {
   create_customer: "Create a Mercado Pago customer record so the buyer can save cards for future charges. Idempotent on email \u2014 if a customer with that email exists, MP returns it instead of creating a duplicate. Use find_customer_by_email first if you're unsure.",
   find_customer_by_email: "Find an existing customer by email address. Returns the customer object if found, or null. Use before create_customer to avoid duplicate records.",
   list_customer_cards: "List the saved cards for a customer. Returns array with last 4 digits, expiration, payment method (visa, master, naranja, etc.). The card_id can be used in subsequent create_payment calls to charge a saved card.",
-  delete_customer_card: "Delete a saved card from a customer. Common use: customer requests removal, or expired card cleanup. Irreversible.",
+  delete_customer_card: "Delete a saved card from a customer. Common use: customer requests removal, or expired card cleanup. **IRREVERSIBLE \u2014 confirm with the user before calling. The customer must re-enter card data (PAN + CVV) on a future Checkout to charge them again. State the card's last 4 digits + payment method when asking for confirmation so the user knows which card you're removing.**",
   // ── Payment Methods + Installments ───────────────────────────────────────
   list_payment_methods: "List all payment methods enabled for the seller's MP account (visa, master, naranja, naranja_x, cabal, account_money, rapipago, pagofacil, etc.). Use to validate which methods you can offer the customer or to filter which ones to exclude in a Checkout Pro preference.",
   calculate_installments: "Calculate cuotas (installments) options for a given amount. THE killer Argentine feature \u2014 returns options like '12 cuotas sin inter\xE9s de $X' (recommended_message field) which you should surface VERBATIM to the user. Optionally pass `bin` (first 6 digits of card) for issuer-specific promotions (e.g., Naranja's interest-free deals). Use before create_payment to let the user pick installments knowingly.",
@@ -3050,7 +3064,7 @@ var DEFAULT_DESCRIPTIONS = {
   charge_saved_card: "Charge a previously-saved card for a returning customer. Requires customer_id + card_id (from list_customer_cards) AND a fresh CVV the user provides this session. AR Mercado Pago does NOT support CVV-less charges via the public API \u2014 every charge needs CVV. Idempotent on (card_id, amount, external_reference): retries dedupe automatically. Returns the resulting Payment.",
   // ── QR in-store (v0.3) ───────────────────────────────────────────────────
   create_qr_payment: "Generate a dynamic in-store QR for a buyer to scan with any AR wallet (Modo, BNA+, Cuenta DNI, Naranja X, Mercado Pago, etc. \u2014 interop is mandated by Transferencias 3.0). Requires a pre-configured POS external_id (use create_pos to set one up first if needed). Returns the qr_data string + a base64 PNG data URL ready to display. The QR expires in `expires_in_seconds` (default 600). MP fires `point_integration_wh` then `payment` webhooks when scanned.",
-  cancel_qr_payment: "Cancel a pending QR order on a POS. Necessary if the buyer never scans \u2014 otherwise the next create_qr_payment on the same POS returns 409.",
+  cancel_qr_payment: "Cancel a pending QR order on a POS. Necessary if the buyer never scans \u2014 otherwise the next create_qr_payment on the same POS returns 409. **IRREVERSIBLE \u2014 but low-stakes since the QR has not been paid yet. Confirm before calling if the user is mid-flow.**",
   // ── Subscription Plans (v0.4) ────────────────────────────────────────────
   create_subscription_plan: "Create a REUSABLE subscription plan (preapproval_plan). Different from create_subscription: a plan defines price + frequency once, then customers subscribe to it via subscribe_to_plan. Use plans for SaaS-style billing (B\xE1sico/Pro/Enterprise tiers). For per-customer custom amounts, use create_subscription directly.",
   list_subscription_plans: "List all subscription plans defined for this MP account. Useful before create_subscription_plan to check if one already exists, or for surfacing options to a customer.",
@@ -3072,7 +3086,7 @@ var DEFAULT_DESCRIPTIONS = {
   list_webhooks: "List all webhook subscriptions configured for this MP application. Use to see what topics + URLs are wired before adding new ones.",
   create_webhook: "Subscribe a webhook URL to a MP topic (payment, subscription_authorized_payment, subscription_preapproval, merchant_order, point_integration_wh). MP will POST to this URL when events of that topic fire.",
   update_webhook: "Update a webhook's URL or topic. Useful when you change deployment URLs without resubscribing from scratch.",
-  delete_webhook: "Delete a webhook subscription. MP stops POSTing to it immediately.",
+  delete_webhook: "Delete a webhook subscription. MP stops POSTing to it immediately. **IRREVERSIBLE \u2014 confirm before calling. State the webhook URL + topic so the user knows which subscription is being removed. Re-subscribing requires a new create_webhook call.**",
   // ── Webhook handler combo (v0.5) ─────────────────────────────────────────
   handle_webhook: "Process an incoming MP webhook in ONE call: verify the HMAC-SHA256 signature, parse the event, and (optionally) auto-fetch the underlying resource (Payment, Subscription, Order). Returns the structured event PLUS the full resource. USE THIS in your webhook endpoint INSTEAD of chaining verify_webhook_signature + parse_webhook_event + get_payment manually. Pass the raw request body, x-signature header, x-request-id header, and your MP webhook secret. SAFE: returns { verified: false } when signature mismatches \u2014 caller should respond 401 and stop processing. WHEN auto_fetch is true (default), the resource is fetched as the SAME MP user the client is configured for (so for marketplace integrations, instantiate a per-seller client).",
   // ── OAuth Marketplace (v0.5) ─────────────────────────────────────────────
@@ -3084,7 +3098,7 @@ var DEFAULT_DESCRIPTIONS = {
   get_order: "Fetch an Order by ID. Returns the Order with its lifecycle status and any attached payments/refunds.",
   update_order: "Patch an existing Order before it's captured/canceled. Common use: update items or external_reference.",
   capture_order: "Capture a previously-authorized Order (only for orders created with capture_mode='manual'). Captures up to the originally-authorized amount; pass amount for partial capture. Common use: ride-share marks ride complete \u2192 capture; hotel checks-out guest \u2192 capture.",
-  cancel_order: "Cancel an Order. Releases any auth-holds and marks the Order as canceled. For orders that have already been CAPTURED, use refund_payment instead \u2014 cancel only works pre-capture.",
+  cancel_order: "Cancel an Order. Releases any auth-holds and marks the Order as canceled. For orders that have already been CAPTURED, use refund_payment instead \u2014 cancel only works pre-capture. **IRREVERSIBLE \u2014 confirm with the user. State the order_id, total_amount, and current status before asking 's\xED, cancel\xE1'. The buyer's hold is released to their bank within 24-72h depending on issuer.**",
   // ── Account / Balance / Movements / Settlements (v0.6) ───────────────────
   get_account_balance: "Get the seller's current MP wallet balance. Returns { available_balance, unavailable_balance, total_amount, currency_id }. The available balance is what the seller can withdraw or pay with right now; unavailable is in retention (typically 14-21 days for new sellers or risk-flagged transactions). For per-seller marketplace setups, instantiate the client AS THE SELLER first.",
   list_account_movements: "List wallet movements (incoming payments, transfers, refunds, holdings) for the active MP account. Filter by date range with `from`/`to` (ISO 8601). Useful for monthly conciliation or 'show me what came in this month' workflows.",
@@ -3124,7 +3138,7 @@ var DEFAULT_DESCRIPTIONS = {
   update_point_device_mode: "Switch a Point device's operating_mode between 'PDV' (bound to a logical POS, takes payments triggered through that POS) and 'STANDALONE' (works independently, accepts any payment). PDV is for cash-register integrations; STANDALONE is for free-form retail. Affects how payments hit the device.",
   create_point_payment_intent: "Create a payment intent on a physical Point device \u2014 the device prompts the buyer to tap/insert/swipe their card. Returns immediately with intent_id; query state via get_point_payment_intent or wait for point_integration_wh webhook. **AMOUNT IS IN CENTAVOS**, NOT pesos (Point API differs from Payments API): 100 = $1, 1000 = $10, 10000 = $100.",
   get_point_payment_intent: "Get the current state of a Point payment intent (OPEN, PROCESSING, FINISHED, CANCELED, ERROR). USE in polling loops if you can't wait for the webhook. When state=FINISHED, the intent.payment.id is the resulting Payment id usable with get_payment.",
-  cancel_point_payment_intent: "Cancel an OPEN point payment intent before the buyer interacts with the device. ONLY WORKS while state='OPEN' \u2014 once the buyer taps, you can't cancel; refund_payment after the fact instead.",
+  cancel_point_payment_intent: "Cancel an OPEN point payment intent before the buyer interacts with the device. ONLY WORKS while state='OPEN' \u2014 once the buyer taps, you can't cancel; refund_payment after the fact instead. **IRREVERSIBLE \u2014 confirm with the cashier/operator before calling. State the device_id and amount.**",
   // ── Pure helpers (v0.7) ──────────────────────────────────────────────────
   compute_marketplace_fee: "PURE HELPER (no network) \u2014 given a transaction amount + fee rule (% or flat ARS, with optional min/max floors), returns the exact `marketplace_fee` value in ARS to pass to create_order or create_payment_preference. USE WHEN your platform takes a commission and you need to compute the exact fee per transaction. Examples: { percent: 5, minArs: 50, maxArs: 5000 } for percentage with floor + cap; { flatArs: 200, percent: 2 } for fixed + percentage.",
   explain_payment_status: "PURE HELPER (no network) \u2014 given a Payment object (from get_payment / create_payment / handle_webhook), returns { summary, recommendedAction, final, paid, retryable } in Spanish. Translates MP's cryptic status_detail codes to plain Spanish + actionable guidance ('reintentar con otra tarjeta' vs 'esperar webhook' vs 'estado final'). USE THIS instead of having to memorize 30+ status_detail codes \u2014 surface summary + recommendedAction directly to the user.",
@@ -3156,16 +3170,28 @@ function mercadoPagoTools(client, options) {
         external_reference: z.string().optional().describe("Optional id from your system to track this subscription")
       }),
       execute: async ({ customer_email, amount_ars, frequency_months, reason, external_reference }) => {
-        const created = await client.createPreapproval({
-          reason,
-          payerEmail: customer_email,
-          amount: amount_ars,
-          currency: "ARS",
-          frequency: frequency_months,
-          frequencyType: "months",
-          backUrl: options.backUrl,
-          ...external_reference !== void 0 ? { externalReference: external_reference } : {}
-        });
+        const created = await client.createPreapproval(
+          {
+            reason,
+            payerEmail: customer_email,
+            amount: amount_ars,
+            currency: "ARS",
+            frequency: frequency_months,
+            frequencyType: "months",
+            backUrl: options.backUrl,
+            ...external_reference !== void 0 ? { externalReference: external_reference } : {},
+            // Deterministic idempotency — if the LLM retries this tool call
+            // with the same inputs (e.g., timeout + retry), MP returns the
+            // EXISTING subscription instead of creating a duplicate.
+            idempotencyKey: await deterministicIdempotencyKey(
+              "create_subscription",
+              customer_email,
+              amount_ars,
+              frequency_months,
+              external_reference
+            )
+          }
+        );
         await options.state.set(created.id, {
           status: created.status,
           payerEmail: customer_email,
@@ -3372,9 +3398,9 @@ function mercadoPagoTools(client, options) {
       inputSchema: z.object({
         external_reference: z.string().optional(),
         status: z.string().optional().describe("'approved' | 'pending' | 'rejected' | 'cancelled' | 'refunded' etc."),
-        payer_email: z.string().optional(),
-        begin_date: z.string().optional().describe("ISO 8601, e.g. 2026-01-01T00:00:00Z"),
-        end_date: z.string().optional().describe("ISO 8601"),
+        payer_email: z.string().email().optional().describe("Filter by payer email (exact match)."),
+        begin_date: z.string().datetime().optional().describe("ISO 8601, e.g. 2026-01-01T00:00:00Z"),
+        end_date: z.string().datetime().optional().describe("ISO 8601"),
         limit: z.number().int().min(1).max(100).optional().describe("Default 30, max 100"),
         offset: z.number().int().min(0).optional().describe("Pagination offset (default 0)")
       }),
@@ -3492,28 +3518,36 @@ function mercadoPagoTools(client, options) {
         excluded_payment_types: z.array(z.enum(["credit_card", "debit_card", "ticket", "atm", "bank_transfer"])).optional().describe("Block payment types \u2014 e.g., ['ticket'] to disable Rapipago/Pago F\xE1cil")
       }),
       execute: async (input) => {
-        const pref = await client.createPreference({
-          items: input.items.map((it) => ({
-            title: it.title,
-            quantity: it.quantity,
-            unit_price: it.unit_price,
-            currency_id: "ARS",
-            ...it.description !== void 0 ? { description: it.description } : {},
-            ...it.picture_url !== void 0 ? { picture_url: it.picture_url } : {}
-          })),
-          ...input.payer_email !== void 0 ? { payer: { email: input.payer_email } } : {},
-          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
-          ...input.statement_descriptor !== void 0 ? { statementDescriptor: input.statement_descriptor } : {},
-          backUrls: { success: options.backUrl, failure: options.backUrl, pending: options.backUrl },
-          autoReturn: "approved",
-          ...options.notificationUrl !== void 0 ? { notificationUrl: options.notificationUrl } : {},
-          ...input.max_installments !== void 0 || input.excluded_payment_types !== void 0 ? {
-            paymentMethods: {
-              ...input.max_installments !== void 0 ? { installments: input.max_installments } : {},
-              ...input.excluded_payment_types !== void 0 ? { excluded_payment_types: input.excluded_payment_types.map((id) => ({ id })) } : {}
-            }
-          } : {}
-        });
+        const idemKey = await deterministicIdempotencyKey(
+          "create_payment_preference",
+          input.external_reference ?? input.payer_email ?? "",
+          input.items.map((it) => `${it.title}:${it.quantity}:${it.unit_price}`).join("|")
+        );
+        const pref = await client.createPreference(
+          {
+            items: input.items.map((it) => ({
+              title: it.title,
+              quantity: it.quantity,
+              unit_price: it.unit_price,
+              currency_id: "ARS",
+              ...it.description !== void 0 ? { description: it.description } : {},
+              ...it.picture_url !== void 0 ? { picture_url: it.picture_url } : {}
+            })),
+            ...input.payer_email !== void 0 ? { payer: { email: input.payer_email } } : {},
+            ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
+            ...input.statement_descriptor !== void 0 ? { statementDescriptor: input.statement_descriptor } : {},
+            backUrls: { success: options.backUrl, failure: options.backUrl, pending: options.backUrl },
+            autoReturn: "approved",
+            ...options.notificationUrl !== void 0 ? { notificationUrl: options.notificationUrl } : {},
+            ...input.max_installments !== void 0 || input.excluded_payment_types !== void 0 ? {
+              paymentMethods: {
+                ...input.max_installments !== void 0 ? { installments: input.max_installments } : {},
+                ...input.excluded_payment_types !== void 0 ? { excluded_payment_types: input.excluded_payment_types.map((id) => ({ id })) } : {}
+              }
+            } : {},
+            idempotencyKey: idemKey
+          }
+        );
         return {
           preference_id: pref.id,
           init_point_url: pref.init_point ?? null,
@@ -4733,8 +4767,17 @@ function mercadoPagoTools(client, options) {
     update_merchant_order: tool({
       description: desc("update_merchant_order"),
       inputSchema: z.object({
-        merchant_order_id: z.string(),
-        patch: z.record(z.string(), z.unknown())
+        merchant_order_id: z.string().min(1),
+        // Narrow to MP's documented merchant_order PATCH fields. Previously
+        // this was z.record(z.string(), z.unknown()) which let the LLM pass
+        // arbitrary JSON; MP would silently ignore unknown keys, masking
+        // typos. Strict schema = LLM gets a clear validation error instead.
+        patch: z.object({
+          external_reference: z.string().max(256).optional().describe("Your system's id for this order. Updateable while order is open."),
+          notification_url: z.string().url().optional().describe("Where MP sends webhook notifications for this order."),
+          additional_info: z.string().max(600).optional().describe("Free-form metadata stored alongside the order."),
+          status: z.enum(["opened", "closed", "expired"]).optional().describe("Open orders can be closed (final) or expired (cleanup).")
+        }).strict().describe("Subset of merchant_order fields to update. Unknown keys rejected.")
       }),
       execute: async ({ merchant_order_id, patch }) => {
         return client.updateMerchantOrder(merchant_order_id, patch);
@@ -4953,8 +4996,24 @@ function mercadoPagoTools(client, options) {
     explain_payment_status: tool({
       description: desc("explain_payment_status"),
       inputSchema: z.object({
-        payment_id: z.string().optional().describe("If provided, fetches the Payment first."),
-        payment: z.record(z.string(), z.unknown()).optional().describe("Alternatively, pass a Payment object directly (saves a network round-trip).")
+        payment_id: z.string().min(1).optional().describe(
+          "If provided, fetches the Payment first. RECOMMENDED PATH for agents \u2014 pass the id and let the lib fetch."
+        ),
+        // Loose object kept for advanced manual callers that have already
+        // fetched a Payment from another path. LLMs should prefer payment_id.
+        // We don't strictly type the Payment shape here because MP's actual
+        // response includes 100+ optional fields; the helper consumes only
+        // status / status_detail / payment_method_id / etc. Exposed loosely
+        // for ergonomic interop, NOT for LLM use.
+        payment: z.object({
+          id: z.union([z.string(), z.number()]).optional(),
+          status: z.string().optional(),
+          status_detail: z.string().optional(),
+          payment_method_id: z.string().optional(),
+          transaction_amount: z.number().optional()
+        }).passthrough().optional().describe(
+          "ADVANCED \u2014 pass a pre-fetched Payment object to skip the network call. LLMs: use payment_id instead."
+        )
       }),
       execute: async ({ payment_id, payment }) => {
         let p;