@ar-agents/mercadopago 0.18.0 → 0.18.2

package/dist/index.js

@@ -3047,126 +3047,126 @@ async function deterministicIdempotencyKey(...parts) {
 }
 var DEFAULT_DESCRIPTIONS = {
   // ── Subscriptions ────────────────────────────────────────────────────────
-  create_subscription: "Create a Mercado Pago recurring subscription. Returns an init_point URL where the customer must complete the FIRST payment with their card and CVV (this is a hard MP requirement; agents cannot bypass it). After they pay, MP will auto-charge at the configured frequency without further intervention.",
-  get_subscription_status: "Check the current status of a Mercado Pago subscription. Use this to confirm the customer completed the first payment (status becomes 'authorized') or to inspect the next charge date.",
-  cancel_subscription: "Cancel an active Mercado Pago subscription. After cancellation, MP will not charge the customer again. This action is irreversible \u2014 confirm with the user before calling.",
-  pause_subscription: "Pause an authorized Mercado Pago subscription. Charges stop until resumed. Only works on subscriptions in 'authorized' status.",
-  resume_subscription: "Resume a paused Mercado Pago subscription. Charges resume on the next scheduled date. Only works on subscriptions in 'paused' status.",
+  create_subscription: "Create a Mercado Pago recurring subscription (crear suscripci\xF3n, cobro recurrente con Mercado Pago). Returns an init_point URL where the customer must complete the FIRST payment with their card and CVV (this is a hard MP requirement; agents cannot bypass it). After they pay, MP will auto-charge at the configured frequency without further intervention.",
+  get_subscription_status: "Check the status of a Mercado Pago subscription (consultar estado de una suscripci\xF3n). Use this to confirm the customer completed the first payment (status becomes 'authorized') or to inspect the next charge date.",
+  cancel_subscription: "Cancel an active Mercado Pago subscription (cancelar suscripci\xF3n, dar de baja). After cancellation, MP will not charge the customer again. This action is irreversible, confirm with the user before calling.",
+  pause_subscription: "Pause an authorized Mercado Pago subscription (pausar suscripci\xF3n). Charges stop until resumed. Only works on subscriptions in 'authorized' status.",
+  resume_subscription: "Resume a paused Mercado Pago subscription (reactivar suscripci\xF3n). Charges resume on the next scheduled date. Only works on subscriptions in 'paused' status.",
   // ── Payments ─────────────────────────────────────────────────────────────
-  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. **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.**",
+  create_payment: "Create a one-time Mercado Pago payment (crear un pago, cobrar con Mercado Pago). Two flows: (a) with a card token from MP frontend Cardform, 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, typically 'approved' for account_money and 'pending' for tickets.",
+  get_payment: "Fetch a Mercado Pago payment by ID (consultar un pago). Use to confirm status after webhook arrives, or to inspect details (status_detail explains rejections).",
+  search_payments: "Search Mercado Pago payments with filters (buscar pagos). 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 Mercado Pago payment (cancelar un pago pendiente); only works before approval. Once approved, use refund_payment instead. Common use: cancel an unpaid ticket payment that's still pending. **IRREVERSIBLE, 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 (capturar un pago autorizado) 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, 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. **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.",
+  refund_payment: "Refund an approved Mercado Pago payment (reembolsar un pago, hacer una devoluci\xF3n). 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, 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', once issued, the buyer's bank releases the funds.**",
+  list_refunds: "List all refunds for a payment (listar reembolsos de un pago). 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.",
-  get_payment_preference: "Fetch a Checkout Pro preference by ID. Returns the preference config and current init_point URLs. Use to inspect a previously-created link.",
+  create_payment_preference: "Create a Mercado Pago Checkout Pro payment link (crear link de pago, cobrar por Mercado Pago) 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, 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.",
+  get_payment_preference: "Fetch a Checkout Pro preference / payment link by ID (consultar un link de pago). Returns the preference config and current init_point URLs. Use to inspect a previously-created link.",
   // ── Customers + Cards ────────────────────────────────────────────────────
-  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 \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.**",
+  create_customer: "Create a Mercado Pago customer record (crear cliente en Mercado Pago) so the buyer can save cards for future charges. Idempotent on email, 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 Mercado Pago customer by email (buscar cliente por email). Returns the customer object if found, or null. Use before create_customer to avoid duplicate records.",
+  list_customer_cards: "List a customer's saved cards (listar tarjetas guardadas). 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 (eliminar tarjeta guardada). Common use: customer requests removal, or expired card cleanup. **IRREVERSIBLE, 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.",
+  list_payment_methods: "List the payment methods enabled for the seller's Mercado Pago account (medios de pago disponibles) (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 installment options for an amount (calcular cuotas, cuotas sin inter\xE9s). THE killer Argentine feature, 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.",
   // ── Account ──────────────────────────────────────────────────────────────
-  get_account_info: "Get info about the Mercado Pago account that owns the access token: site_id (MLA=Argentina), country_id, user_type (registered, partial, etc.). Useful to verify the agent is connected to the right account before taking actions.",
+  get_account_info: "Get info about the connected Mercado Pago account (informaci\xF3n de la cuenta): site_id (MLA=Argentina), country_id, user_type (registered, partial, etc.). Useful to verify the agent is connected to the right account before taking actions.",
   // ── Saved-card charging (v0.3) ───────────────────────────────────────────
-  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.",
+  charge_saved_card: "Charge a previously-saved card (cobrar con tarjeta guardada) 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, 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. **IRREVERSIBLE \u2014 but low-stakes since the QR has not been paid yet. Confirm before calling if the user is mid-flow.**",
+  create_qr_payment: "Generate a dynamic in-store payment QR (cobrar con QR de Mercado Pago) for a buyer to scan with any AR wallet (Modo, BNA+, Cuenta DNI, Naranja X, Mercado Pago, etc., 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 (cancelar un QR pendiente). Necessary if the buyer never scans, otherwise the next create_qr_payment on the same POS returns 409. **IRREVERSIBLE, 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.",
+  create_subscription_plan: "Create a reusable subscription plan (crear plan de suscripci\xF3n; 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.",
-  update_subscription_plan: "Update a subscription plan's reason / amount / status / back_url. Existing customer subscriptions to the plan are NOT automatically updated \u2014 only NEW subscribers get the new pricing.",
-  subscribe_to_plan: "Subscribe a customer to an existing reusable plan. Returns a Preapproval with init_point URL where the customer completes first payment. Cleaner than create_subscription when you have fixed tiers.",
-  list_subscription_payments: "List the auto-charge attempts (authorized_payments) under a subscription. Useful for 'show me the cobros del \xFAltimo mes for this client' or to debug a failing recurring charge.",
+  update_subscription_plan: "Update a subscription plan's reason / amount / status / back_url. Existing customer subscriptions to the plan are NOT automatically updated, only NEW subscribers get the new pricing.",
+  subscribe_to_plan: "Subscribe a customer to an existing plan (suscribir un cliente a un plan). Returns a Preapproval with init_point URL where the customer completes first payment. Cleaner than create_subscription when you have fixed tiers.",
+  list_subscription_payments: "List the auto-charges under a subscription (cobros de una suscripci\xF3n; authorized_payments). Useful for 'show me the cobros del \xFAltimo mes for this client' or to debug a failing recurring charge.",
   // ── Stores + POS (v0.4) ──────────────────────────────────────────────────
   create_store: "Create a store under the seller's MP account. Stores are the parent entity for POSes (which generate QR payments). Required ONE-TIME setup before create_pos. Pass a unique external_id and a display name.",
   list_stores: "List all stores configured for this MP account. Use this to find an existing store_id before create_pos, or to surface store options to the agent.",
   create_pos: "Create a POS (Point of Sale) under a store. The POS's external_id is what create_qr_payment uses. Each physical checkout / counter / agent typically has its own POS. Categories are MP-defined (default 621102 = Other Food and Beverage Services).",
   list_pos: "List all POSes for the seller (or filtered by store_id). Use to find an existing POS before create_qr_payment, or to surface options.",
-  // ── Disputes (v0.4 — read-only) ──────────────────────────────────────────
-  list_payment_disputes: "List all disputes / chargebacks raised against a payment. Read-only \u2014 resolution is dashboard-only. Surface the dashboard URL `https://www.mercadopago.com.ar/disputes/{dispute_id}` to the user when they need to respond.",
+  // ── Disputes (v0.4, read-only) ──────────────────────────────────────────
+  list_payment_disputes: "List all disputes / chargebacks raised against a payment. Read-only, resolution is dashboard-only. Surface the dashboard URL `https://www.mercadopago.com.ar/disputes/{dispute_id}` to the user when they need to respond.",
   get_dispute: "Get details of a specific dispute including reason, amount, resolution status. Read-only.",
   // ── Lookup helpers (v0.4) ────────────────────────────────────────────────
   list_identification_types: "List valid identification types for the seller's site. AR returns: DNI, CI, LE, LC, Otro, Pasaporte, CUIT, CUIL with their min/max length. Useful to validate an identification before passing to create_payment.",
-  list_issuers: "List card issuers (banks) that support a payment_method_id. Optionally filter by `bin` (first 6 digits of the card) for accurate issuer detection. Useful with calculate_installments \u2014 issuer-specific promos (e.g., Naranja Galicia 6 cuotas sin inter\xE9s) only appear when the issuer is identified.",
+  list_issuers: "List card issuers (banks) that support a payment_method_id. Optionally filter by `bin` (first 6 digits of the card) for accurate issuer detection. Useful with calculate_installments, issuer-specific promos (e.g., Naranja Galicia 6 cuotas sin inter\xE9s) only appear when the issuer is identified.",
   // ── Webhooks management (v0.4) ───────────────────────────────────────────
   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. **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.**",
+  delete_webhook: "Delete a webhook subscription. MP stops POSTing to it immediately. **IRREVERSIBLE, 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).",
+  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, 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) ─────────────────────────────────────────────
-  oauth_authorize_url: "Build the URL the SELLER (third-party MP account) visits to authorize your marketplace app. Pass the seller's redirect uri (must be whitelisted in MP dev panel) and an opaque state token (CSRF protection \u2014 bind it to the user's session). PURE FUNCTION: no network. The seller approves, MP redirects them to your `redirect_uri?code=...&state=...`. Then call oauth_exchange_code with the code.",
-  oauth_exchange_code: "Exchange the authorization code (from the OAuth redirect) for an `OAuthToken`. Returns access_token, refresh_token, user_id, and expires_in. **PERSIST the entire response** \u2014 refresh_token is long-lived and the only way to keep the integration alive past 6h. Use the access_token to instantiate a per-seller MercadoPagoClient for marketplace flows.",
-  oauth_refresh_token: "Refresh a per-seller access_token using the saved refresh_token. Call PROACTIVELY before expires_in elapses, or REACTIVELY on a 401 from a per-seller MercadoPagoClient. Returns a fresh OAuthToken \u2014 persist the new refresh_token (MP often returns the same value, but always replace).",
-  // ── Order Management API (v0.5 — modern Order API) ───────────────────────
-  create_order: "Create a new Order via MP's modern Order Management API. DIFFERENT from create_payment_preference: Order is a transactional entity with explicit lifecycle (created \u2192 processed \u2192 captured/canceled), supports MANUAL CAPTURE (auth-only, capture later \u2014 for ride-share, hotels, marketplaces) and aggregates multiple payments into one Order. Use Preference (Checkout Pro) for simple hosted pay-links; use Order when you need auth-only or multi-payment-per-order semantics. For marketplace splits, set marketplace + marketplace_fee + collector_id (the SELLER's MP user_id from oauth_exchange_code).",
+  oauth_authorize_url: "Build the URL the SELLER (third-party MP account) visits to authorize your marketplace app. Pass the seller's redirect uri (must be whitelisted in MP dev panel) and an opaque state token (CSRF protection, bind it to the user's session). PURE FUNCTION: no network. The seller approves, MP redirects them to your `redirect_uri?code=...&state=...`. Then call oauth_exchange_code with the code.",
+  oauth_exchange_code: "Exchange the authorization code (from the OAuth redirect) for an `OAuthToken`. Returns access_token, refresh_token, user_id, and expires_in. **PERSIST the entire response**, refresh_token is long-lived and the only way to keep the integration alive past 6h. Use the access_token to instantiate a per-seller MercadoPagoClient for marketplace flows.",
+  oauth_refresh_token: "Refresh a per-seller access_token using the saved refresh_token. Call PROACTIVELY before expires_in elapses, or REACTIVELY on a 401 from a per-seller MercadoPagoClient. Returns a fresh OAuthToken, persist the new refresh_token (MP often returns the same value, but always replace).",
+  // ── Order Management API (v0.5, modern Order API) ───────────────────────
+  create_order: "Create a new Order via MP's modern Order Management API. DIFFERENT from create_payment_preference: Order is a transactional entity with explicit lifecycle (created \u2192 processed \u2192 captured/canceled), supports MANUAL CAPTURE (auth-only, capture later, for ride-share, hotels, marketplaces) and aggregates multiple payments into one Order. Use Preference (Checkout Pro) for simple hosted pay-links; use Order when you need auth-only or multi-payment-per-order semantics. For marketplace splits, set marketplace + marketplace_fee + collector_id (the SELLER's MP user_id from oauth_exchange_code).",
   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. **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.**",
+  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, cancel only works pre-capture. **IRREVERSIBLE, 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.",
-  list_settlements: "List settlements (release_money) \u2014 i.e. transfers from the MP wallet to the seller's registered bank account (CBU). USE WHEN the user asks 'cu\xE1ndo me deposita MP' or for monthly bank-conciliation reports. Filter by date range and status.",
+  list_settlements: "List settlements (release_money), i.e. transfers from the MP wallet to the seller's registered bank account (CBU). USE WHEN the user asks 'cu\xE1ndo me deposita MP' or for monthly bank-conciliation reports. Filter by date range and status.",
   get_settlement: "Get details of a single settlement: amount, date_scheduled, date_processed, bank_account info (CBU + bank name).",
-  // ── 3DS analyzer (v0.6 — pure) ───────────────────────────────────────────
+  // ── 3DS analyzer (v0.6, pure) ───────────────────────────────────────────
   analyze_payment_3ds: "Pure local analyzer for a Payment's 3DS (Strong Customer Authentication) state. Pass a payment_id (string) and the tool fetches the Payment then derives { status: 'not_required'|'frictionless'|'challenge_required'|'rejected'|'unknown', mode, challengeUrl, description }. USE THIS after every create_payment for credit cards: when challengeUrl !== null, you MUST redirect the buyer there before the payment can complete. Without 3DS, payments stay in 'pending' indefinitely if the issuer demanded a challenge.",
-  // ── Test cards (v0.6 — pure) ─────────────────────────────────────────────
-  get_test_cards: "Pure helper that returns the official MP test cards for AR (MLA): VISA/Mastercard/Amex credit + debit, with the 'magic' holder names that route the payment to specific status_detail values (APRO=approved, OTHE=rejected, CONT=pending, FUND=insufficient_amount, etc.). USE WHEN you need to demo a payment flow without a real card, or to script integration tests. Pure data \u2014 no network call.",
+  // ── Test cards (v0.6, pure) ─────────────────────────────────────────────
+  get_test_cards: "Pure helper that returns the official MP test cards for AR (MLA): VISA/Mastercard/Amex credit + debit, with the 'magic' holder names that route the payment to specific status_detail values (APRO=approved, OTHE=rejected, CONT=pending, FUND=insufficient_amount, etc.). USE WHEN you need to demo a payment flow without a real card, or to script integration tests. Pure data, no network call.",
   // ── Customer + Card extensions (v0.7) ────────────────────────────────────
   get_customer: "Get a customer by id. Returns full Customer object: email, first_name, last_name, identification, address, default_card, registered cards. PURE READ. USE WHEN you have the customer_id from a previous create_customer / find_customer_by_email / payment.payer.id and want the full record.",
-  update_customer: "Update a customer's profile (first_name, last_name, phone, identification, address, default_card). MP merges the patch \u2014 fields you don't send remain unchanged. Use to keep customer records in sync (e.g., shipping address changes) or to set a default card for charge_saved_card.",
-  create_customer_card: "Add a saved card to an existing customer using a card_token (one-time token from MP frontend Cardform \u2014 agents should NEVER take raw card data, that's a PCI violation). Returns the saved CustomerCard with id usable in charge_saved_card. Persists across charges (no need to re-tokenize each time).",
-  get_customer_card: "Get details of a single saved card by (customer_id, card_id). Returns last 4 digits, expiration, brand, issuer. PURE READ \u2014 useful before charge_saved_card to confirm the card is still valid.",
+  update_customer: "Update a customer's profile (first_name, last_name, phone, identification, address, default_card). MP merges the patch, fields you don't send remain unchanged. Use to keep customer records in sync (e.g., shipping address changes) or to set a default card for charge_saved_card.",
+  create_customer_card: "Add a saved card to an existing customer using a card_token (one-time token from MP frontend Cardform, agents should NEVER take raw card data, that's a PCI violation). Returns the saved CustomerCard with id usable in charge_saved_card. Persists across charges (no need to re-tokenize each time).",
+  get_customer_card: "Get details of a single saved card by (customer_id, card_id). Returns last 4 digits, expiration, brand, issuer. PURE READ, useful before charge_saved_card to confirm the card is still valid.",
   // ── Subscription / Plan / Refund / Preference extensions (v0.7) ─────────
   get_subscription_plan: "Fetch a subscription plan by id. Returns plan config: amount, frequency, status, init_point. Use to inspect a plan before subscribing customers, or to display plan details to the user.",
   update_subscription: "Update a subscription's amount, status, reason, external_reference, OR card_token_id (to switch payment method when the buyer's card is expired/declined). For card swap: pass card_token_id from a fresh tokenization. CONSTRAINTS: status changes only support 'paused' | 'cancelled' (use authorize via init_point flow to re-activate).",
   search_subscriptions: "Search subscriptions across the seller's account. Filter by status (pending/authorized/paused/cancelled), payer_email, external_reference, or preapproval_plan_id (to find all subscribers of a plan). Paginated. USE WHEN you need to enumerate active subscribers, audit cancellations, or find a subscription by external reference.",
-  get_refund: "Fetch a single refund by (payment_id, refund_id). Returns the Refund object with amount, status, date_created. PURE READ \u2014 useful to verify a refund processed or to reconcile partial-refund history.",
+  get_refund: "Fetch a single refund by (payment_id, refund_id). Returns the Refund object with amount, status, date_created. PURE READ, useful to verify a refund processed or to reconcile partial-refund history.",
   update_payment_preference: "Update a Checkout Pro preference (notification_url, back_urls, items, payer info, payment_methods exclusion list). Only works on preferences NOT yet paid. Common use: regenerate the link with a new notification_url after deployment, or change items if the buyer requested adjustments before paying.",
   // ── Merchant Orders (v0.7) ────────────────────────────────────────────────
-  get_merchant_order: "Get a merchant_order with all its associated payments + shipments. MerchantOrder is the parent entity for Payments associated with a single Preference \u2014 one Order can have multiple partial Payments (retries, installments). USE THIS in webhooks with topic='merchant_order' to get the aggregate paid_amount, refunded_amount, and shipping status in one call.",
+  get_merchant_order: "Get a merchant_order with all its associated payments + shipments. MerchantOrder is the parent entity for Payments associated with a single Preference, one Order can have multiple partial Payments (retries, installments). USE THIS in webhooks with topic='merchant_order' to get the aggregate paid_amount, refunded_amount, and shipping status in one call.",
   search_merchant_orders: "Search merchant_orders by preference_id, external_reference, or status. Paginated. Returns up to 50 per page. USE WHEN you have a preference_id and want all its derived merchant_orders, or when reconciling 'which payments belong to which preference'.",
-  update_merchant_order: "Update a merchant_order \u2014 typically to add items or shipping info. Most agent flows don't need this; use only when integrating with a custom shipping flow that requires updating the MO mid-lifecycle.",
+  update_merchant_order: "Update a merchant_order, typically to add items or shipping info. Most agent flows don't need this; use only when integrating with a custom shipping flow that requires updating the MO mid-lifecycle.",
   // ── Stores + POS CRUD completion (v0.7) ──────────────────────────────────
   get_store: "Fetch a single store by (user_id, store_id). Returns store details: name, location, business_hours, external_id. PURE READ.",
   update_store: "Update a store's properties (name, location, business_hours, external_id). MP merges the patch.",
-  delete_store: "Delete a store. IRREVERSIBLE. Confirm with user before calling. Will fail if the store has associated POSes \u2014 delete those first.",
+  delete_store: "Delete a store. IRREVERSIBLE. Confirm with user before calling. Will fail if the store has associated POSes, delete those first.",
   get_pos: "Fetch a POS by id. Returns: name, store_id, category, external_id, qr_template (if configured). PURE READ. Use when you need to find the external_id for create_qr_payment.",
   update_pos: "Update a POS's properties (name, category, external_id). MP merges the patch.",
   delete_pos: "Delete a POS. IRREVERSIBLE. Cancels any pending QR orders attached to it. Confirm with user before calling.",
   // ── Bank Accounts (v0.7) ─────────────────────────────────────────────────
-  list_bank_accounts: "List the bank accounts (CBUs) the seller has registered with MP for receiving payouts. Returns an array \u2014 the one with `is_default: true` is where settlements (release_money) go. USE BEFORE list_settlements when the user asks 'a qu\xE9 cuenta me deposita MP'.",
-  register_bank_account: "Register a new bank account (CBU) for the seller. NOTE: MP usually requires this through the dashboard for compliance \u2014 this endpoint may not work for all accounts. If it fails with 403, redirect the user to https://www.mercadopago.com.ar/banking/dashboard.",
+  list_bank_accounts: "List the bank accounts (CBUs) the seller has registered with MP for receiving payouts. Returns an array, the one with `is_default: true` is where settlements (release_money) go. USE BEFORE list_settlements when the user asks 'a qu\xE9 cuenta me deposita MP'.",
+  register_bank_account: "Register a new bank account (CBU) for the seller. NOTE: MP usually requires this through the dashboard for compliance, this endpoint may not work for all accounts. If it fails with 403, redirect the user to https://www.mercadopago.com.ar/banking/dashboard.",
   // ── Point Devices físicos (v0.7) ─────────────────────────────────────────
-  list_point_devices: "List the physical Point devices (Smart, Tap to Pay, etc.) linked to the seller's MP account. Distinct from logical POS \u2014 these are actual terminals at brick-and-mortar shops. Returns each device's id (serial), operating_mode (PDV vs STANDALONE), and pos_id (when bound to a logical POS). Filter by pos_id to find devices for a specific cash register.",
+  list_point_devices: "List the physical Point devices (Smart, Tap to Pay, etc.) linked to the seller's MP account. Distinct from logical POS, these are actual terminals at brick-and-mortar shops. Returns each device's id (serial), operating_mode (PDV vs STANDALONE), and pos_id (when bound to a logical POS). Filter by pos_id to find devices for a specific cash register.",
   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.",
+  create_point_payment_intent: "Create a payment intent on a physical Point device, 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. **IRREVERSIBLE \u2014 confirm with the cashier/operator before calling. State the device_id and amount.**",
+  cancel_point_payment_intent: "Cancel an OPEN point payment intent before the buyer interacts with the device. ONLY WORKS while state='OPEN', once the buyer taps, you can't cancel; refund_payment after the fact instead. **IRREVERSIBLE, 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.",
-  // ── v0.9 — Health check + observability ──────────────────────────────────
-  mp_health_check: "Liveness probe against MP. Returns { ok, latencyMs, userId, circuit }. USE THIS as the first call in long-running agent workflows to verify (a) network path to MP is up, (b) accessToken is valid, (c) MP is responding. Circuit-breaker state included when configured \u2014 surface to ops dashboards. Returns ok=false instead of throwing \u2014 safe to call in monitoring loops without try/catch.",
-  // ── v0.10 — AR issuer cuotas promos (pure) ───────────────────────────────
-  find_applicable_promos: "PURE HELPER (no network, sub-ms) \u2014 returns the 'cuotas sin inter\xE9s' promotions applicable to a given (issuer, paymentMethodId, amount, category, date) tuple. Includes the federal Ahora 3/6/12/18/24/30 program AND issuer-specific deals (Naranja con Galicia los jueves, Santander Amex en supermercados los martes, etc.). USE THIS BEFORE checkout to surface 'pag\xE1 en 12 cuotas sin inter\xE9s con tu Galicia' hints to the buyer \u2014 drives conversion. Returns an array of CuotasPromo objects; the `description` field is in Spanish and ALWAYS surface verbatim. Catalog updated quarterly.",
-  // ── v0.10 — 3DS challenge resolution ────────────────────────────────────
+  compute_marketplace_fee: "PURE HELPER (no network), 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), 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, surface summary + recommendedAction directly to the user.",
+  // ── v0.9, Health check + observability ──────────────────────────────────
+  mp_health_check: "Liveness probe against MP. Returns { ok, latencyMs, userId, circuit }. USE THIS as the first call in long-running agent workflows to verify (a) network path to MP is up, (b) accessToken is valid, (c) MP is responding. Circuit-breaker state included when configured, surface to ops dashboards. Returns ok=false instead of throwing, safe to call in monitoring loops without try/catch.",
+  // ── v0.10, AR issuer cuotas promos (pure) ───────────────────────────────
+  find_applicable_promos: "PURE HELPER (no network, sub-ms), returns the 'cuotas sin inter\xE9s' promotions applicable to a given (issuer, paymentMethodId, amount, category, date) tuple. Includes the federal Ahora 3/6/12/18/24/30 program AND issuer-specific deals (Naranja con Galicia los jueves, Santander Amex en supermercados los martes, etc.). USE THIS BEFORE checkout to surface 'pag\xE1 en 12 cuotas sin inter\xE9s con tu Galicia' hints to the buyer, drives conversion. Returns an array of CuotasPromo objects; the `description` field is in Spanish and ALWAYS surface verbatim. Catalog updated quarterly.",
+  // ── v0.10, 3DS challenge resolution ────────────────────────────────────
   confirm_3ds_challenge: "After the buyer completes a 3DS challenge (redirected back from challengeUrl), call this to poll MP and confirm whether the payment is now resolved. Polls get_payment up to N times with exponential backoff. Returns { payment, threeDs, resolved, attempts }. USE THIS as the FINAL step in the 3DS flow (after analyze_payment_3ds detected a challenge_required). Without confirming, the payment stays in 'pending' indefinitely from the buyer's perspective.",
-  // ── v0.10 — Auto-paginate variants ──────────────────────────────────────
-  search_payments_all: "Collect ALL payments matching a filter \u2014 auto-paginates under the hood. Returns an array (NOT paginated) so the agent doesn't have to manage offset/limit loops manually. SAFETY: pass `max_items` to cap; without it, MP traversal is bounded by the toolkit's internal max (10,000 items) to prevent runaway iterations. USE WHEN the agent needs to enumerate everything (e.g., monthly reconciliation 'all approved payments in March'). For agent flows that only need 'first N matches', pass `max_items` directly.",
-  list_settlements_all: "Collect ALL settlements matching a filter \u2014 auto-paginates. Pass `max_items` to cap. Use for monthly bank-conciliation reports.",
-  // ── v0.11 — TaxID validation cross-LATAM (pure) ──────────────────────────
-  validate_tax_id: "PURE HELPER (no network, sub-ms) \u2014 validates a tax ID against the appropriate country algorithm. Supports AR (DNI/CUIT/CUIL with modulo-11), BR (CPF/CNPJ with two-step weighted modulo), MX (RFC structure), CL (RUT with K digit), CO (NIT modulo-11), UY (RUT 12-digit checksum), PE (RUC 11-digit + prefix validation). Returns { valid, normalized, formatted, type, country, error }. USE THIS BEFORE submitting buyer identification to MP \u2014 invalid tax IDs cause 4xx rejections. Surface the Spanish error verbatim."
+  // ── v0.10, Auto-paginate variants ──────────────────────────────────────
+  search_payments_all: "Collect ALL payments matching a filter, auto-paginates under the hood. Returns an array (NOT paginated) so the agent doesn't have to manage offset/limit loops manually. SAFETY: pass `max_items` to cap; without it, MP traversal is bounded by the toolkit's internal max (10,000 items) to prevent runaway iterations. USE WHEN the agent needs to enumerate everything (e.g., monthly reconciliation 'all approved payments in March'). For agent flows that only need 'first N matches', pass `max_items` directly.",
+  list_settlements_all: "Collect ALL settlements matching a filter, auto-paginates. Pass `max_items` to cap. Use for monthly bank-conciliation reports.",
+  // ── v0.11, TaxID validation cross-LATAM (pure) ──────────────────────────
+  validate_tax_id: "PURE HELPER (no network, sub-ms), validates a tax ID against the appropriate country algorithm. Supports AR (DNI/CUIT/CUIL with modulo-11), BR (CPF/CNPJ with two-step weighted modulo), MX (RFC structure), CL (RUT with K digit), CO (NIT modulo-11), UY (RUT 12-digit checksum), PE (RUC 11-digit + prefix validation). Returns { valid, normalized, formatted, type, country, error }. USE THIS BEFORE submitting buyer identification to MP, invalid tax IDs cause 4xx rejections. Surface the Spanish error verbatim."
 };
 function mercadoPagoTools(client, options) {
   const desc = (name) => options.descriptions?.[name] ?? DEFAULT_DESCRIPTIONS[name];
@@ -3176,7 +3176,7 @@ function mercadoPagoTools(client, options) {
 function buildAllTools(client, options, desc) {
   return {
     // ─────────────────────────────────────────────────────────────────────────
-    // Subscriptions (v0.1 — kept identical for backward compatibility)
+    // Subscriptions (v0.1, kept identical for backward compatibility)
     // ─────────────────────────────────────────────────────────────────────────
     create_subscription: tool({
       description: desc("create_subscription"),
@@ -3198,7 +3198,7 @@ function buildAllTools(client, options, desc) {
             frequencyType: "months",
             backUrl: options.backUrl,
             ...external_reference !== void 0 ? { externalReference: external_reference } : {},
-            // Deterministic idempotency — if the LLM retries this tool call
+            // 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(
@@ -3309,12 +3309,12 @@ function buildAllTools(client, options, desc) {
         identification: z.object({
           type: z.enum(["DNI", "CUIT", "CUIL"]),
           number: z.string()
-        }).optional().describe("Payer identification \u2014 required for some payment types in AR"),
+        }).optional().describe("Payer identification, required for some payment types in AR"),
         statement_descriptor: z.string().max(13).optional().describe("Shows on buyer's card statement (max 13 chars)"),
-        // v0.11 — fraud scoring enrichment fields
+        // v0.11, fraud scoring enrichment fields
         additional_info: z.object({
           ip_address: z.string().optional().describe(
-            "Buyer's IP address (from req.headers X-Forwarded-For). STRONGLY RECOMMENDED for card payments \u2014 improves MP fraud scoring confidence and reduces false-positive rejections (3-5x lower per RG 5286/2023)."
+            "Buyer's IP address (from req.headers X-Forwarded-For). STRONGLY RECOMMENDED for card payments, improves MP fraud scoring confidence and reduces false-positive rejections (3-5x lower per RG 5286/2023)."
           ),
           referral_url: z.string().url().optional().describe("Page the buyer came from"),
           payer: z.object({
@@ -3326,7 +3326,7 @@ function buildAllTools(client, options, desc) {
               street_name: z.string().optional(),
               street_number: z.number().optional()
             }).optional(),
-            registration_date: z.string().optional().describe("ISO 8601 \u2014 when the buyer registered on YOUR platform"),
+            registration_date: z.string().optional().describe("ISO 8601, when the buyer registered on YOUR platform"),
             authentication_type: z.string().optional(),
             is_prime_user: z.boolean().optional(),
             is_first_purchase_online: z.boolean().optional(),
@@ -3363,7 +3363,7 @@ function buildAllTools(client, options, desc) {
           ...input.statement_descriptor !== void 0 ? { statementDescriptor: input.statement_descriptor } : {},
           ...input.additional_info !== void 0 ? { additionalInfo: input.additional_info } : {},
           ...options.notificationUrl !== void 0 ? { notificationUrl: options.notificationUrl } : {},
-          // Deterministic idempotency key — safe to retry, same inputs always
+          // Deterministic idempotency key, safe to retry, same inputs always
           // produce the same key (MP dedupes on its side).
           idempotencyKey: await deterministicIdempotencyKey(
             "create_payment",
@@ -3533,7 +3533,7 @@ function buildAllTools(client, options, desc) {
         external_reference: z.string().optional(),
         max_installments: z.number().int().min(1).max(24).optional().describe("Limit max cuotas offered. Defaults to MP account config."),
         statement_descriptor: z.string().max(13).optional(),
-        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")
+        excluded_payment_types: z.array(z.enum(["credit_card", "debit_card", "ticket", "atm", "bank_transfer"])).optional().describe("Block payment types, e.g., ['ticket'] to disable Rapipago/Pago F\xE1cil")
       }),
       execute: async (input) => {
         const idemKey = await deterministicIdempotencyKey(
@@ -3745,7 +3745,7 @@ function buildAllTools(client, options, desc) {
       inputSchema: z.object({
         customer_id: z.string().describe("MP customer id (from create_customer / find_customer_by_email)"),
         card_id: z.string().describe("Saved card id (from list_customer_cards)"),
-        security_code: z.string().regex(/^\d{3,4}$/).describe("CVV \u2014 3 digits (Visa/Master) or 4 (Amex). User must provide this each charge in AR."),
+        security_code: z.string().regex(/^\d{3,4}$/).describe("CVV, 3 digits (Visa/Master) or 4 (Amex). User must provide this each charge in AR."),
         amount_ars: z.number().positive(),
         description: z.string().min(1).max(255),
         installments: z.number().int().min(1).max(24).optional().describe("Default 1. Use calculate_installments first to pick a valid count."),
@@ -3794,7 +3794,7 @@ function buildAllTools(client, options, desc) {
         title: z.string().min(1).max(80).describe("Display title shown when scanning"),
         description: z.string().max(255).optional(),
         external_reference: z.string().optional(),
-        notification_url: z.string().url().optional().describe("Webhook URL \u2014 falls back to dashboard config if omitted"),
+        notification_url: z.string().url().optional().describe("Webhook URL, falls back to dashboard config if omitted"),
         expires_in_seconds: z.number().int().min(60).max(3600).optional().describe("Default 600 (10 min)")
       }),
       execute: async (input) => {
@@ -4077,7 +4077,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // Disputes (v0.4 — read-only)
+    // Disputes (v0.4, read-only)
     // ─────────────────────────────────────────────────────────────────────────
     list_payment_disputes: tool({
       description: desc("list_payment_disputes"),
@@ -4225,7 +4225,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.5 — Webhook handler combo
+    // v0.5, Webhook handler combo
     // ─────────────────────────────────────────────────────────────────────────
     handle_webhook: tool({
       description: desc("handle_webhook"),
@@ -4337,7 +4337,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.5 — OAuth Marketplace flow
+    // v0.5, OAuth Marketplace flow
     // ─────────────────────────────────────────────────────────────────────────
     oauth_authorize_url: tool({
       description: desc("oauth_authorize_url"),
@@ -4365,7 +4365,7 @@ function buildAllTools(client, options, desc) {
         return {
           available: true,
           url,
-          next_step: "Redirect the seller to `url`. After approval MP sends them to redirect_uri?code=...&state=... \u2014 verify state matches, then call oauth_exchange_code with the code."
+          next_step: "Redirect the seller to `url`. After approval MP sends them to redirect_uri?code=...&state=..., verify state matches, then call oauth_exchange_code with the code."
         };
       }
     }),
@@ -4440,7 +4440,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.5 — Order Management API
+    // v0.5, Order Management API
     // ─────────────────────────────────────────────────────────────────────────
     create_order: tool({
       description: desc("create_order"),
@@ -4459,7 +4459,7 @@ function buildAllTools(client, options, desc) {
         ).optional(),
         payer_email: z.string().email().optional(),
         capture_mode: z.enum(["automatic", "manual"]).optional().describe(
-          "'automatic' charges immediately; 'manual' authorizes only \u2014 capture later via capture_order."
+          "'automatic' charges immediately; 'manual' authorizes only, capture later via capture_order."
         ),
         notification_url: z.string().url().optional(),
         marketplace: z.string().optional().describe(
@@ -4554,7 +4554,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.6 — Account / Balance / Movements / Settlements
+    // v0.6, Account / Balance / Movements / Settlements
     // ─────────────────────────────────────────────────────────────────────────
     get_account_balance: tool({
       description: desc("get_account_balance"),
@@ -4608,7 +4608,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.6 — 3DS analyzer (combined: fetch payment + analyze)
+    // v0.6, 3DS analyzer (combined: fetch payment + analyze)
     // ─────────────────────────────────────────────────────────────────────────
     analyze_payment_3ds: tool({
       description: desc("analyze_payment_3ds"),
@@ -4627,7 +4627,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.6 — Test cards (pure)
+    // v0.6, Test cards (pure)
     // ─────────────────────────────────────────────────────────────────────────
     get_test_cards: tool({
       description: desc("get_test_cards"),
@@ -4641,7 +4641,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.7 — Customer + Card extensions
+    // v0.7, Customer + Card extensions
     // ─────────────────────────────────────────────────────────────────────────
     get_customer: tool({
       description: desc("get_customer"),
@@ -4695,7 +4695,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.7 — Subscription / Plan / Refund / Preference extensions
+    // v0.7, Subscription / Plan / Refund / Preference extensions
     // ─────────────────────────────────────────────────────────────────────────
     get_subscription_plan: tool({
       description: desc("get_subscription_plan"),
@@ -4770,7 +4770,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.7 — Merchant Orders
+    // v0.7, Merchant Orders
     // ─────────────────────────────────────────────────────────────────────────
     get_merchant_order: tool({
       description: desc("get_merchant_order"),
@@ -4818,7 +4818,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.7 — Stores + POS CRUD completion
+    // v0.7, Stores + POS CRUD completion
     // ─────────────────────────────────────────────────────────────────────────
     get_store: tool({
       description: desc("get_store"),
@@ -4889,7 +4889,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.7 — Bank Accounts
+    // v0.7, Bank Accounts
     // ─────────────────────────────────────────────────────────────────────────
     list_bank_accounts: tool({
       description: desc("list_bank_accounts"),
@@ -4914,7 +4914,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.7 — Point Devices físicos
+    // v0.7, Point Devices físicos
     // ─────────────────────────────────────────────────────────────────────────
     list_point_devices: tool({
       description: desc("list_point_devices"),
@@ -4984,7 +4984,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────────
-    // v0.7 — Pure helpers
+    // v0.7, Pure helpers
     // ─────────────────────────────────────────────────────────────────────────
     compute_marketplace_fee: tool({
       description: desc("compute_marketplace_fee"),
@@ -5031,7 +5031,7 @@ function buildAllTools(client, options, desc) {
       description: desc("explain_payment_status"),
       inputSchema: z.object({
         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."
+          "If provided, fetches the Payment first. RECOMMENDED PATH for agents, 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.
@@ -5046,7 +5046,7 @@ function buildAllTools(client, options, desc) {
           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."
+          "ADVANCED, pass a pre-fetched Payment object to skip the network call. LLMs: use payment_id instead."
         )
       }),
       execute: async ({ payment_id, payment }) => {
@@ -5071,7 +5071,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────
-    // v0.10 — AR issuer promos (pure)
+    // v0.10, AR issuer promos (pure)
     // ─────────────────────────────────────────────────────────────────────
     find_applicable_promos: tool({
       description: desc("find_applicable_promos"),
@@ -5105,7 +5105,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────
-    // v0.10 — 3DS challenge resolution (poll-and-confirm)
+    // v0.10, 3DS challenge resolution (poll-and-confirm)
     // ─────────────────────────────────────────────────────────────────────
     confirm_3ds_challenge: tool({
       description: desc("confirm_3ds_challenge"),
@@ -5122,7 +5122,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────
-    // v0.10 — Auto-paginate variants (collect-all)
+    // v0.10, Auto-paginate variants (collect-all)
     // ─────────────────────────────────────────────────────────────────────
     search_payments_all: tool({
       description: desc("search_payments_all"),
@@ -5166,7 +5166,7 @@ function buildAllTools(client, options, desc) {
       }
     }),
     // ─────────────────────────────────────────────────────────────────────
-    // v0.11 — TaxID validation cross-LATAM (pure)
+    // v0.11, TaxID validation cross-LATAM (pure)
     // ─────────────────────────────────────────────────────────────────────
     validate_tax_id: tool({
       description: desc("validate_tax_id"),