@yoryoboy/bi-mcp 1.6.0 → 1.8.0

package/dist/src/tools/mercadolibre/get-orders-summary.js

@@ -23,8 +23,10 @@ import {
 } from "./helpers.js";
 import { resolveMercadoLibreProfileOrSelection } from "./profile-resolution.js";
 import { mercadolibreProfileIdSchemaField } from "./write-helpers.js";
-const PAGE_FETCH_CONCURRENCY = 4;
+const PAGE_FETCH_CONCURRENCY = 15;
 const PAGE_FETCH_MAX_RETRIES = 2;
+const ORDER_DETAIL_MAX_PAGES_PER_CALL = 15;
+const DEFAULT_ORDER_DETAIL_PAGE_LIMIT = 50;
 const TOP_LIMIT = 10;
 const ordersSchema = [
   "id",
@@ -142,6 +144,57 @@ function sortedCurrencyTotals(input) {
     Object.entries(input).filter(([, amount]) => amount !== 0).sort(([left], [right]) => left.localeCompare(right)).map(([currency, amount]) => [currency, roundMoney(amount)])
   );
 }
+function createCurrencyMetricBucket() {
+  return {
+    orders: 0,
+    units: 0,
+    revenue: 0,
+    paidRevenue: 0,
+    paymentTotalPaid: 0,
+    transactionAmount: 0,
+    refundedAmount: 0,
+    cancelledGmv: 0,
+    saleFee: 0,
+    shippingCost: 0,
+    couponAmount: 0,
+    paymentCouponAmount: 0,
+    discountedGmv: 0,
+    notDeliveredGmv: 0,
+    cancelledOrders: 0,
+    refundedOrders: 0,
+    ordersWithShippingCost: 0,
+    ordersWithCoupon: 0,
+    discountedOrders: 0,
+    notDeliveredOrders: 0
+  };
+}
+function incrementCurrencyMetric(map, currencyId, updater) {
+  map[currencyId] = map[currencyId] ?? createCurrencyMetricBucket();
+  updater(map[currencyId]);
+}
+function sortedCurrencyMetrics(input, mapper) {
+  return Object.fromEntries(
+    Object.entries(input).sort(([left], [right]) => left.localeCompare(right)).map(([currencyId, bucket]) => [currencyId, stripNulls(mapper(bucket))])
+  );
+}
+function topAmountBreakdownFromMap(counts, amounts, totalOrders, limit = TOP_LIMIT) {
+  const sorted = Array.from(counts.entries()).filter(([, count]) => count > 0).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+  const entries = sorted.slice(0, limit).map(([key, orders]) => ({
+    key,
+    orders,
+    rate: safeRate(orders, totalOrders),
+    amount_by_currency: sortedCurrencyTotals(amounts.get(key) ?? {})
+  }));
+  const otherOrders = sorted.slice(limit).reduce((sum, [, count]) => sum + count, 0);
+  return stripNulls({
+    entries,
+    other_orders: otherOrders > 0 ? otherOrders : void 0,
+    other_rate: otherOrders > 0 ? safeRate(otherOrders, totalOrders) : void 0
+  });
+}
+function revenueSum(input) {
+  return Object.values(input).reduce((sum, value) => sum + value, 0);
+}
 function compactFeedbackValue(value) {
   const compact = compactNestedValue(value);
   return compact.trim();
@@ -170,6 +223,14 @@ function buildCalculations(orders, metadata, failedPages) {
   const items = /* @__PURE__ */ new Map();
   const variations = /* @__PURE__ */ new Map();
   const skus = /* @__PURE__ */ new Map();
+  const dailyMetrics = /* @__PURE__ */ new Map();
+  const flowMetrics = /* @__PURE__ */ new Map();
+  const skuEconomics = /* @__PURE__ */ new Map();
+  const cancelGroupCounts = /* @__PURE__ */ new Map();
+  const cancelCodeCounts = /* @__PURE__ */ new Map();
+  const cancelRequestedByCounts = /* @__PURE__ */ new Map();
+  const cancelReasonCounts = /* @__PURE__ */ new Map();
+  const cancelReasonAmounts = /* @__PURE__ */ new Map();
   let unitsTotal = 0;
   let fulfilledOrders = 0;
   let deliveredOrders = 0;
@@ -188,9 +249,16 @@ function buildCalculations(orders, metadata, failedPages) {
   let paymentApprovedOrders = 0;
   let itemLineCount = 0;
   let ordersWithAnyPostSaleIssue = 0;
+  let ordersWithRefundedAmount = 0;
+  let ordersWithShippingCostAmount = 0;
+  let ordersWithCouponAmount = 0;
+  let notDeliveredOrders = 0;
+  let multiUnitItemLines = 0;
+  let multiUnitSaleFeeObservations = 0;
   const itemsSeen = /* @__PURE__ */ new Set();
   const buyerSeen = /* @__PURE__ */ new Set();
   const financialRaw = {};
+  const currencyMetrics = {};
   for (const order of orders) {
     const currencyId = getOrderCurrency(order);
     const totalAmount = toNumber(order.total_amount);
@@ -210,6 +278,16 @@ function buildCalculations(orders, metadata, failedPages) {
     const paymentType = normalizeString(payment.payment_type);
     const installments = normalizeScalarString(payment.installments);
     const tags = asArray(order.tags).map((tag) => normalizeScalarString(tag)).filter(Boolean);
+    const cancelDetail = asRecord(order.cancel_detail);
+    const isCancelled = normalizeString(order.status) === "cancelled";
+    const refundedAmount = toNumber(payment.transaction_amount_refunded);
+    const shippingCost = toNumber(payment.shipping_cost);
+    const paymentCouponAmount = toNumber(payment.coupon_amount);
+    const dayKey = compactDateTime(order.date_created)?.slice(0, 10) || "UNKNOWN_DATE";
+    const flows = asArray(context.flows).map((flow) => normalizeScalarString(flow)).filter(Boolean);
+    const effectiveFlows = flows.length > 0 ? flows : ["NO_FLOW"];
+    const isDiscounted = tags.includes("order_has_discount") || couponAmount > 0 || paymentCouponAmount > 0;
+    const isNotDelivered = tags.includes("not_delivered") || normalizeString(cancelDetail.group) === "shipment";
     const orderItemDistinctIds = /* @__PURE__ */ new Set();
     financialRaw[currencyId] = financialRaw[currencyId] ?? {
       orders: 0,
@@ -228,6 +306,40 @@ function buildCalculations(orders, metadata, failedPages) {
     financialRaw[currencyId].paymentTotalPaidAmount += toNumber(payment.total_paid_amount);
     financialRaw[currencyId].transactionAmount += toNumber(payment.transaction_amount);
     financialRaw[currencyId].couponAmount += couponAmount;
+    const dailyCurrencyMetrics = dailyMetrics.get(dayKey) ?? {};
+    dailyMetrics.set(dayKey, dailyCurrencyMetrics);
+    const updateOrderCurrencyMetrics = (bucket) => {
+      bucket.orders += 1;
+      bucket.revenue += totalAmount;
+      bucket.paidRevenue += paidAmount;
+      bucket.paymentTotalPaid += toNumber(payment.total_paid_amount);
+      bucket.transactionAmount += toNumber(payment.transaction_amount);
+      bucket.refundedAmount += refundedAmount;
+      bucket.shippingCost += shippingCost;
+      bucket.couponAmount += couponAmount;
+      bucket.paymentCouponAmount += paymentCouponAmount;
+      if (isCancelled) {
+        bucket.cancelledOrders += 1;
+        bucket.cancelledGmv += totalAmount;
+      }
+      if (refundedAmount > 0) {
+        bucket.refundedOrders += 1;
+      }
+      if (shippingCost > 0) {
+        bucket.ordersWithShippingCost += 1;
+      }
+      if (couponAmount > 0 || paymentCouponAmount > 0) {
+        bucket.ordersWithCoupon += 1;
+      }
+      if (isDiscounted) {
+        bucket.discountedOrders += 1;
+      }
+      if (isNotDelivered) {
+        bucket.notDeliveredOrders += 1;
+      }
+    };
+    incrementCurrencyMetric(currencyMetrics, currencyId, updateOrderCurrencyMetrics);
+    incrementCurrencyMetric(dailyCurrencyMetrics, currencyId, updateOrderCurrencyMetrics);
     incrementCount(statusCounts, normalizeString(order.status));
     incrementCount(channelCounts, normalizeString(context.channel));
     incrementCount(siteCounts, normalizeString(context.site));
@@ -269,6 +381,49 @@ function buildCalculations(orders, metadata, failedPages) {
     if (tags.includes("catalog")) {
       catalogOrders += 1;
     }
+    if (refundedAmount > 0) {
+      ordersWithRefundedAmount += 1;
+    }
+    if (shippingCost > 0) {
+      ordersWithShippingCostAmount += 1;
+    }
+    if (couponAmount > 0 || paymentCouponAmount > 0) {
+      ordersWithCouponAmount += 1;
+    }
+    if (isNotDelivered) {
+      notDeliveredOrders += 1;
+    }
+    if (isCancelled) {
+      const cancelGroup = normalizeString(cancelDetail.group, "UNKNOWN_GROUP");
+      const cancelCode = normalizeString(cancelDetail.code, "UNKNOWN_CODE");
+      const requestedBy = normalizeString(cancelDetail.requested_by, "UNKNOWN_REQUESTER");
+      const reasonKey = `${cancelGroup}:${cancelCode}:${requestedBy}`;
+      incrementCount(cancelGroupCounts, cancelGroup);
+      incrementCount(cancelCodeCounts, cancelCode);
+      incrementCount(cancelRequestedByCounts, requestedBy);
+      incrementCount(cancelReasonCounts, reasonKey);
+      const reasonAmount = cancelReasonAmounts.get(reasonKey) ?? {};
+      incrementCurrency(reasonAmount, currencyId, totalAmount);
+      cancelReasonAmounts.set(reasonKey, reasonAmount);
+    }
+    for (const flow of effectiveFlows) {
+      const flowAggregate = flowMetrics.get(flow) ?? {
+        flow,
+        orders: 0,
+        units: 0,
+        cancelled_orders: 0,
+        revenue_by_currency: {},
+        paid_revenue_by_currency: {},
+        sale_fee_by_currency: {}
+      };
+      flowAggregate.orders += 1;
+      if (isCancelled) {
+        flowAggregate.cancelled_orders += 1;
+      }
+      incrementCurrency(flowAggregate.revenue_by_currency, currencyId, totalAmount);
+      incrementCurrency(flowAggregate.paid_revenue_by_currency, currencyId, paidAmount);
+      flowMetrics.set(flow, flowAggregate);
+    }
     const feedbackBuyer = compactFeedbackValue(feedback.buyer);
     const feedbackSeller = compactFeedbackValue(feedback.seller);
     const hasFeedback = Boolean(feedbackBuyer || feedbackSeller);
@@ -321,11 +476,39 @@ function buildCalculations(orders, metadata, failedPages) {
       const stockNode = normalizeString(stock.node_id);
       const variationSummary = compactVariationAttributes(item.variation_attributes);
       const itemKey = `${itemId}::${variationSummary}::${sellerSku}`;
-      const skuKey = sellerSku || itemId || title;
+      const skuKey = sellerSku || itemId || title || "UNKNOWN_SKU";
       const variationKey = variationSummary || "NO_VARIATION";
+      const itemRevenue = unitPrice * quantity;
+      const paidRevenueApprox = totalAmount > 0 ? paidAmount * (itemRevenue / totalAmount) : itemRevenue;
+      const refundedAmountApprox = totalAmount > 0 ? refundedAmount * (itemRevenue / totalAmount) : refundedAmount;
+      if (quantity > 1) {
+        multiUnitItemLines += 1;
+        if (saleFee > 0) {
+          multiUnitSaleFeeObservations += 1;
+        }
+      }
       unitsTotal += quantity;
       financialRaw[currencyId].units += quantity;
       financialRaw[currencyId].saleFee += saleFee;
+      const updateItemCurrencyMetrics = (bucket) => {
+        bucket.units += quantity;
+        bucket.saleFee += saleFee;
+        if (isDiscounted) {
+          bucket.discountedGmv += itemRevenue;
+        }
+        if (isNotDelivered) {
+          bucket.notDeliveredGmv += itemRevenue;
+        }
+      };
+      incrementCurrencyMetric(currencyMetrics, currencyId, updateItemCurrencyMetrics);
+      incrementCurrencyMetric(dailyCurrencyMetrics, currencyId, updateItemCurrencyMetrics);
+      for (const flow of effectiveFlows) {
+        const flowAggregate = flowMetrics.get(flow);
+        if (flowAggregate) {
+          flowAggregate.units += quantity;
+          incrementCurrency(flowAggregate.sale_fee_by_currency, currencyId, saleFee);
+        }
+      }
       if (itemId) {
         itemsSeen.add(itemId);
         orderItemDistinctIds.add(itemId);
@@ -368,6 +551,32 @@ function buildCalculations(orders, metadata, failedPages) {
       skuAggregate.units += quantity;
       incrementCurrency(skuAggregate.revenue_by_currency, currencyId, unitPrice * quantity);
       skus.set(skuKey, skuAggregate);
+      const skuEconomicsAggregate = skuEconomics.get(skuKey) ?? {
+        seller_sku: sellerSku,
+        item_id: itemId,
+        title,
+        orders: 0,
+        units: 0,
+        cancelled_orders: 0,
+        refunded_orders: 0,
+        revenue_by_currency: {},
+        paid_revenue_by_currency: {},
+        sale_fee_by_currency: {},
+        refunded_amount_by_currency: {}
+      };
+      skuEconomicsAggregate.orders += 1;
+      skuEconomicsAggregate.units += quantity;
+      if (isCancelled) {
+        skuEconomicsAggregate.cancelled_orders += 1;
+      }
+      if (refundedAmount > 0) {
+        skuEconomicsAggregate.refunded_orders += 1;
+      }
+      incrementCurrency(skuEconomicsAggregate.revenue_by_currency, currencyId, itemRevenue);
+      incrementCurrency(skuEconomicsAggregate.paid_revenue_by_currency, currencyId, paidRevenueApprox);
+      incrementCurrency(skuEconomicsAggregate.sale_fee_by_currency, currencyId, saleFee);
+      incrementCurrency(skuEconomicsAggregate.refunded_amount_by_currency, currencyId, refundedAmountApprox);
+      skuEconomics.set(skuKey, skuEconomicsAggregate);
     }
     financialRaw[currencyId].distinctItems += orderItemDistinctIds.size;
   }
@@ -430,6 +639,108 @@ function buildCalculations(orders, metadata, failedPages) {
   const buyersWithMultipleOrders = Array.from(buyers.values()).filter((buyer) => buyer.orders > 1).length;
   const topVariationValues = Array.from(variationValueCounts.entries()).filter(([key]) => key && key !== "NO_VARIATION").sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).slice(0, TOP_LIMIT).map(([key, occurrences]) => ({ key, occurrences }));
   const topSingleValue = (counts) => Array.from(counts.entries()).filter(([key]) => key).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))[0]?.[0] ?? "";
+  const revenueQuality = {
+    by_currency: sortedCurrencyMetrics(currencyMetrics, (bucket) => ({
+      gross_gmv: roundMoney(bucket.revenue),
+      paid_gmv: roundMoney(bucket.paidRevenue),
+      payment_total_paid_amount: roundMoney(bucket.paymentTotalPaid),
+      transaction_amount_total: roundMoney(bucket.transactionAmount),
+      refunded_amount_total: roundMoney(bucket.refundedAmount),
+      net_after_refunds: roundMoney(bucket.transactionAmount - bucket.refundedAmount),
+      cancelled_gmv: roundMoney(bucket.cancelledGmv),
+      cancelled_rate_by_orders: safeRate(bucket.cancelledOrders, bucket.orders),
+      cancelled_rate_by_gmv: safeRate(bucket.cancelledGmv, bucket.revenue),
+      paid_rate_by_gmv: safeRate(bucket.paidRevenue, bucket.revenue)
+    }))
+  };
+  const refundsCancellations = {
+    by_currency: sortedCurrencyMetrics(currencyMetrics, (bucket) => ({
+      refunded_amount_total: roundMoney(bucket.refundedAmount),
+      refunded_orders: bucket.refundedOrders,
+      refund_rate_by_orders: safeRate(bucket.refundedOrders, bucket.orders),
+      refund_rate_by_transaction_amount: safeRate(bucket.refundedAmount, bucket.transactionAmount),
+      cancelled_orders: bucket.cancelledOrders,
+      cancelled_gmv: roundMoney(bucket.cancelledGmv),
+      cancelled_rate_by_orders: safeRate(bucket.cancelledOrders, bucket.orders),
+      cancelled_rate_by_gmv: safeRate(bucket.cancelledGmv, bucket.revenue)
+    })),
+    cancel_group_breakdown: topBreakdownFromMap(cancelGroupCounts, ordersTotal),
+    cancel_code_breakdown: topBreakdownFromMap(cancelCodeCounts, ordersTotal),
+    cancel_requested_by_breakdown: topBreakdownFromMap(cancelRequestedByCounts, ordersTotal),
+    top_cancel_reasons: topAmountBreakdownFromMap(cancelReasonCounts, cancelReasonAmounts, ordersTotal)
+  };
+  const shippingAndDiscounts = {
+    by_currency: sortedCurrencyMetrics(currencyMetrics, (bucket) => ({
+      buyer_shipping_paid_total: roundMoney(bucket.shippingCost),
+      orders_with_shipping_cost: bucket.ordersWithShippingCost,
+      avg_shipping_paid_by_order_with_cost: roundMoney(bucket.shippingCost / Math.max(1, bucket.ordersWithShippingCost)),
+      shipping_cost_rate_on_paid_gmv: safeRate(bucket.shippingCost, bucket.paidRevenue),
+      coupon_amount_total: roundMoney(bucket.couponAmount),
+      payment_coupon_amount_total: roundMoney(bucket.paymentCouponAmount),
+      orders_with_coupon: bucket.ordersWithCoupon,
+      coupon_rate_by_orders: safeRate(bucket.ordersWithCoupon, bucket.orders),
+      coupon_rate_on_gmv: safeRate(bucket.couponAmount + bucket.paymentCouponAmount, bucket.revenue),
+      discounted_orders: bucket.discountedOrders,
+      discounted_order_rate: safeRate(bucket.discountedOrders, bucket.orders),
+      discounted_gmv: roundMoney(bucket.discountedGmv),
+      not_delivered_orders: bucket.notDeliveredOrders,
+      not_delivered_gmv: roundMoney(bucket.notDeliveredGmv),
+      not_delivered_rate_by_orders: safeRate(bucket.notDeliveredOrders, bucket.orders),
+      not_delivered_rate_by_gmv: safeRate(bucket.notDeliveredGmv, bucket.revenue)
+    }))
+  };
+  const dailyTrend = Array.from(dailyMetrics.entries()).sort(([left], [right]) => left.localeCompare(right)).map(([date, byCurrency]) => ({
+    date,
+    by_currency: sortedCurrencyMetrics(byCurrency, (bucket) => ({
+      orders: bucket.orders,
+      units: bucket.units,
+      revenue: roundMoney(bucket.revenue),
+      paid_revenue: roundMoney(bucket.paidRevenue),
+      cancelled_orders: bucket.cancelledOrders,
+      refunded_amount: roundMoney(bucket.refundedAmount),
+      avg_order_value: roundMoney(bucket.revenue / Math.max(1, bucket.orders))
+    }))
+  }));
+  const flowPerformance = Array.from(flowMetrics.values()).sort((left, right) => revenueSum(right.revenue_by_currency) - revenueSum(left.revenue_by_currency) || left.flow.localeCompare(right.flow)).slice(0, TOP_LIMIT).map((flow) => ({
+    flow: flow.flow,
+    orders: flow.orders,
+    units: flow.units,
+    revenue_by_currency: sortedCurrencyTotals(flow.revenue_by_currency),
+    paid_revenue_by_currency: sortedCurrencyTotals(flow.paid_revenue_by_currency),
+    sale_fee_by_currency: sortedCurrencyTotals(flow.sale_fee_by_currency),
+    cancelled_orders: flow.cancelled_orders,
+    cancelled_rate: safeRate(flow.cancelled_orders, flow.orders),
+    fee_rate_by_currency: Object.fromEntries(
+      Object.keys(flow.revenue_by_currency).sort((left, right) => left.localeCompare(right)).map((currencyId) => [currencyId, safeRate(flow.sale_fee_by_currency[currencyId] ?? 0, flow.revenue_by_currency[currencyId] ?? 0)])
+    )
+  }));
+  const skuUnitEconomics = Array.from(skuEconomics.values()).sort((left, right) => revenueSum(right.revenue_by_currency) - revenueSum(left.revenue_by_currency) || left.seller_sku.localeCompare(right.seller_sku)).slice(0, TOP_LIMIT).map((sku) => ({
+    seller_sku: sku.seller_sku,
+    item_id: sku.item_id,
+    title: sku.title,
+    orders: sku.orders,
+    units: sku.units,
+    revenue_by_currency: sortedCurrencyTotals(sku.revenue_by_currency),
+    paid_revenue_by_currency: sortedCurrencyTotals(sku.paid_revenue_by_currency),
+    sale_fee_by_currency: sortedCurrencyTotals(sku.sale_fee_by_currency),
+    refunded_amount_by_currency: sortedCurrencyTotals(sku.refunded_amount_by_currency),
+    avg_unit_price_by_currency: Object.fromEntries(
+      Object.keys(sku.revenue_by_currency).sort((left, right) => left.localeCompare(right)).map((currencyId) => [currencyId, roundMoney((sku.revenue_by_currency[currencyId] ?? 0) / Math.max(1, sku.units))])
+    ),
+    fee_rate_by_currency: Object.fromEntries(
+      Object.keys(sku.revenue_by_currency).sort((left, right) => left.localeCompare(right)).map((currencyId) => [currencyId, safeRate(sku.sale_fee_by_currency[currencyId] ?? 0, sku.revenue_by_currency[currencyId] ?? 0)])
+    ),
+    cancelled_orders: sku.cancelled_orders,
+    cancelled_rate: safeRate(sku.cancelled_orders, sku.orders),
+    refunded_orders: sku.refunded_orders,
+    refund_rate: safeRate(sku.refunded_orders, sku.orders)
+  }));
+  const feeDiagnostics = {
+    sale_fee_assumption: "order_items.sale_fee is used as returned by MercadoLibre and is not multiplied by quantity yet.",
+    multi_unit_item_lines: multiUnitItemLines,
+    multi_unit_sale_fee_observations: multiUnitSaleFeeObservations,
+    needs_sale_fee_granularity_validation: true
+  };
   return {
     overview: {
       orders_total: ordersTotal,
@@ -445,6 +756,13 @@ function buildCalculations(orders, metadata, failedPages) {
       orders_with_return_request: ordersWithReturnRequest
     },
     financial_by_currency: financialByCurrency,
+    revenue_quality: revenueQuality,
+    refunds_cancellations: refundsCancellations,
+    shipping_and_discounts: shippingAndDiscounts,
+    daily_trend: dailyTrend,
+    flow_performance: flowPerformance,
+    sku_unit_economics: skuUnitEconomics,
+    fee_diagnostics: feeDiagnostics,
     order_mix: {
       status_breakdown: topBreakdownFromMap(statusCounts, ordersTotal),
       tags_breakdown: topBreakdownFromMap(tagCounts, ordersTotal),
@@ -518,26 +836,30 @@ function buildCalculations(orders, metadata, failedPages) {
   };
 }
 function buildOrdersSummaryMetadata(params) {
-  const hasMoreForPage = params.effectiveOffset + params.returned < params.total;
-  const universeFullyFetched = !params.paginated && params.pagesFailed === 0 && params.returned >= params.total;
+  const requestedWindowEndOffset = params.effectiveOffset + params.effectiveLimit * params.pagesRequested;
+  const nextOffset = params.responseMode === "orders_chunk" ? requestedWindowEndOffset : params.effectiveOffset + params.returned;
+  const hasMoreOrders = nextOffset < params.total;
+  const universeFullyFetched = params.responseMode === "calculations" && params.pagesFailed === 0 && params.returned >= params.total;
   let continuation = "No more pages for this query.";
-  if (params.paginated && hasMoreForPage) {
-    continuation = `Reenviar la misma tool con offset=${params.effectiveOffset + params.effectiveLimit} para continuar.`;
-  } else if (params.pagesFailed > 0) {
+  if (params.pagesFailed > 0) {
     const offsets = params.failedOffsets.slice(0, 5).join(", ");
     const moreOffsets = params.failedOffsets.length > 5 ? ` y ${params.failedOffsets.length - 5} offsets adicionales` : "";
-    continuation = `Se recuperaron paginas parciales. Reintentar la misma tool con los offsets fallidos (${offsets}${moreOffsets}) y limit=${params.effectiveLimit}.`;
-  } else if (!params.paginated) {
-    continuation = "Universe fetched successfully.";
+    continuation = params.responseMode === "orders_chunk" ? `Se recuperaron paginas parciales. Reintentar primero la misma tool con responseMode="orders_chunk", offset=${params.failedOffsets[0]} y limit=${params.effectiveLimit}. Offsets fallidos: ${offsets}${moreOffsets}. Luego continuar con offset=${nextOffset} si hace falta.` : `Calculos parciales por paginas fallidas. Reintentar la misma tool con responseMode="calculations". Offsets fallidos: ${offsets}${moreOffsets}.`;
+  } else if (params.responseMode === "orders_chunk" && hasMoreOrders) {
+    continuation = `Para continuar trayendo ordenes, volver a invocar meli_get_orders_summary con los mismos filtros, responseMode="orders_chunk", offset=${nextOffset} y limit=${params.effectiveLimit}. Repetir hasta has_more=false.`;
+  } else if (params.responseMode === "calculations") {
+    continuation = 'Calculos completos. Si el usuario pide detalle de ordenes, invocar la misma tool con responseMode="orders_chunk", offset=0 y limit=50.';
   }
   return {
     total: params.total,
     limit: params.effectiveLimit,
     offset: params.effectiveOffset,
     returned: params.returned,
-    has_more: params.paginated ? hasMoreForPage : params.pagesFailed > 0,
+    has_more: params.responseMode === "orders_chunk" ? hasMoreOrders || params.pagesFailed > 0 : params.pagesFailed > 0,
+    next_offset: params.responseMode === "orders_chunk" && hasMoreOrders ? nextOffset : void 0,
     continuation,
-    fetch_mode: params.paginated ? "page" : "full",
+    fetch_mode: params.responseMode === "orders_chunk" ? "orders_chunk" : "full_calculations",
+    pages_per_call_limit: params.responseMode === "orders_chunk" ? ORDER_DETAIL_MAX_PAGES_PER_CALL : void 0,
     pages_requested: params.pagesRequested,
     pages_succeeded: params.pagesSucceeded,
     pages_failed: params.pagesFailed,
@@ -617,8 +939,9 @@ const meliGetOrdersSummarySchema = z.object({
   status: z.string().trim().min(1).optional().describe("Optional MercadoLibre order status filter."),
   q: z.string().trim().min(1).optional().describe("Optional free-text search query supported by MercadoLibre orders search."),
   sort: z.string().trim().min(1).optional().describe("Optional MercadoLibre sort expression."),
-  offset: z.number().int().min(0).max(5e3).optional().describe("Optional pagination offset. If provided, the tool returns only that page instead of trying to fetch the full universe."),
-  limit: z.number().int().min(1).max(50).optional().describe("Optional page size (1-50). If provided, the tool returns only that page instead of trying to fetch the full universe.")
+  responseMode: z.enum(["calculations", "orders_chunk"]).optional().default("calculations").describe("Response mode. calculations (default) fetches all matching orders internally and returns only aggregate KPIs. orders_chunk returns compact order rows for up to 15 MercadoLibre pages and includes continuation metadata."),
+  offset: z.number().int().min(0).max(5e3).optional().describe("Starting offset for responseMode=orders_chunk. Use metadata.next_offset to continue."),
+  limit: z.number().int().min(1).max(50).optional().describe("MercadoLibre page size for responseMode=orders_chunk (1-50). Defaults to 50.")
 });
 async function meliGetOrdersSummaryHandler(params) {
   try {
@@ -627,6 +950,9 @@ async function meliGetOrdersSummaryHandler(params) {
       return profileResolution.response;
     }
     const profileId = profileResolution.value.profileId;
+    const responseMode = params.responseMode ?? "calculations";
+    const requestedLimit = responseMode === "orders_chunk" ? params.limit ?? DEFAULT_ORDER_DETAIL_PAGE_LIMIT : DEFAULT_ORDER_DETAIL_PAGE_LIMIT;
+    const requestedOffset = responseMode === "orders_chunk" ? params.offset ?? 0 : 0;
     const response = await searchMercadoLibreOrders(profileId, {
       seller: "",
       from: params.startDate,
@@ -634,23 +960,29 @@ async function meliGetOrdersSummaryHandler(params) {
       status: params.status,
       q: params.q,
       sort: params.sort,
-      offset: params.offset,
-      limit: params.limit
+      offset: requestedOffset,
+      limit: requestedLimit
     });
     const paging = normalizeMercadoLibrePaging(asRecord(response.paging));
     const baseOrders = asArray(response.results);
     const metricsByCurrency = {};
-    const paginatedMode = params.offset !== void 0 || params.limit !== void 0;
-    const effectiveLimit = paging.limit || params.limit || baseOrders.length;
-    const effectiveOffset = paging.offset || params.offset || 0;
+    const effectiveLimit = paging.limit || requestedLimit || baseOrders.length;
+    const effectiveOffset = paging.offset || requestedOffset || 0;
+    const maxPagesForResponse = responseMode === "orders_chunk" ? ORDER_DETAIL_MAX_PAGES_PER_CALL : Infinity;
     const allOrders = [...baseOrders];
     const failedPages = [];
     let pagesRequested = 1;
     let pagesSucceeded = 1;
-    if (!paginatedMode && effectiveLimit > 0 && paging.total > baseOrders.length) {
+    if (effectiveLimit > 0 && paging.total > baseOrders.length) {
       const nextOffsets = [];
+      const maxPagesRemaining = Math.max(0, maxPagesForResponse - 1);
+      let pagesAdded = 0;
       for (let nextOffset = effectiveOffset + effectiveLimit; nextOffset < paging.total; nextOffset += effectiveLimit) {
+        if (responseMode === "orders_chunk" && pagesAdded >= maxPagesRemaining) {
+          break;
+        }
         nextOffsets.push(nextOffset);
+        pagesAdded += 1;
       }
       pagesRequested += nextOffsets.length;
       if (nextOffsets.length > 0) {
@@ -689,27 +1021,33 @@ async function meliGetOrdersSummaryHandler(params) {
         });
       }
     }
-    const compactOrders = allOrders.map((order) => formatCompactOrder(order, metricsByCurrency));
+    const compactOrders = responseMode === "orders_chunk" ? allOrders.map((order) => formatCompactOrder(order, metricsByCurrency)) : [];
+    if (responseMode === "calculations") {
+      for (const order of allOrders) {
+        formatCompactOrder(order, metricsByCurrency);
+      }
+    }
     for (const metrics of Object.values(metricsByCurrency)) {
       metrics.revenue = roundMoney(metrics.revenue);
       metrics.avg_order_value = roundMoney(metrics.avg_order_value);
     }
+    const returned = responseMode === "orders_chunk" ? compactOrders.length : allOrders.length;
     const metadata = buildOrdersSummaryMetadata({
       total: paging.total,
       effectiveLimit,
       effectiveOffset,
-      returned: compactOrders.length,
-      paginated: paginatedMode,
+      returned,
+      responseMode,
       pagesRequested,
       pagesSucceeded,
       pagesFailed: failedPages.length,
       failedOffsets: failedPages.map((failure) => failure.offset)
     });
-    const calculations = buildCalculations(allOrders, metadata, failedPages);
+    const calculations = responseMode === "calculations" ? buildCalculations(allOrders, metadata, failedPages) : void 0;
     return object(
       stripNulls({
         profile_id: profileId,
-        metadata: paginatedMode ? {
+        metadata: responseMode === "orders_chunk" ? {
           ...buildMercadoLibrePaginationMetadata({
             total: paging.total,
             limit: effectiveLimit,
@@ -720,10 +1058,10 @@ async function meliGetOrdersSummaryHandler(params) {
           ...metadata
         } : metadata,
         metrics_by_currency: metricsByCurrency,
-        orders_schema: ordersSchema,
-        orders: compactOrders,
+        orders_schema: responseMode === "orders_chunk" ? ordersSchema : void 0,
+        orders: responseMode === "orders_chunk" ? compactOrders : void 0,
         calculations,
-        failed_pages: failedPages
+        failed_pages: failedPages.length > 0 ? failedPages : void 0
       })
     );
   } catch (err) {