daiso 1.0.5 → 1.0.6

package/dist/pages/openapiSpecPathsOliveyoung.js

@@ -44,6 +44,13 @@ export const OPENAPI_PATHS_OLIVEYOUNG = {
                     description: '품절 포함 여부 (true/false)',
                     schema: { type: 'boolean', default: false },
                 },
+                {
+                    name: 'timeoutMs',
+                    in: 'query',
+                    required: false,
+                    description: '요청 제한 시간(ms)',
+                    schema: { type: 'integer', default: 15000, minimum: 1 },
+                },
             ],
             responses: {
                 '200': {
@@ -115,6 +122,13 @@ export const OPENAPI_PATHS_OLIVEYOUNG = {
                     description: '최대 결과 수',
                     schema: { type: 'integer', default: 20, minimum: 1, maximum: 100 },
                 },
+                {
+                    name: 'timeoutMs',
+                    in: 'query',
+                    required: false,
+                    description: '요청 제한 시간(ms)',
+                    schema: { type: 'integer', default: 15000, minimum: 1 },
+                },
             ],
             responses: {
                 '200': {
@@ -199,6 +213,27 @@ export const OPENAPI_PATHS_OLIVEYOUNG = {
                     description: '품절 포함 여부 (true/false)',
                     schema: { type: 'boolean', default: false },
                 },
+                {
+                    name: 'storeLimit',
+                    in: 'query',
+                    required: false,
+                    description: '반환할 주변 매장 최대 수',
+                    schema: { type: 'integer', default: 10, minimum: 1, maximum: 100 },
+                },
+                {
+                    name: 'stockCheckLimit',
+                    in: 'query',
+                    required: false,
+                    description: '주변 매장별 재고를 보강할 상품 수. 낮출수록 빠르게 응답합니다.',
+                    schema: { type: 'integer', default: 5, minimum: 0, maximum: 20 },
+                },
+                {
+                    name: 'timeoutMs',
+                    in: 'query',
+                    required: false,
+                    description: '요청 제한 시간(ms)',
+                    schema: { type: 'integer', default: 15000, minimum: 1 },
+                },
             ],
             responses: {
                 '200': {

package/dist/pages/promptReferenceText.js

@@ -81,16 +81,22 @@ export function buildPromptReferenceText(baseUrl) {
    - 결과에서 원하는 제품의 id 확인
    - /api/daiso/inventory에 해당 id로 재고 조회
    - 진열 위치가 필요하면 재고 응답의 storeCode를 확인한 뒤 /api/daiso/display-location에 productId + storeCode로 조회
-6. **상품명 단계 검색**:
+   - 다이소 재고 조회는 storeCode가 필요하지 않습니다.
+6. **최소 정보 요청 처리**:
+   - 사용자가 상품명만 주면 먼저 상품 검색 도구로 후보를 찾고, 응답의 productId/itemCode/pluCd를 다음 단계에 전달합니다.
+   - 사용자가 위치를 대강 말하면 keyword/storeKeyword에 그대로 넣어 먼저 조회하고, 결과가 없을 때만 공백 제거, 역/점 접미어 제거 같은 변형을 시도합니다.
+   - 도구가 productId, itemCode, storeCode 같은 내부 ID를 요구하면 사용자에게 바로 ID를 요구하지 말고, 검색/재고 응답에서 먼저 확인합니다.
+   - "근처", "주변"처럼 위치가 없는 표현만 있으면 기본 좌표 결과를 단정하지 말고 사용자의 지역/역명/좌표를 물어봅니다.
+7. **상품명 단계 검색**:
    - 재고 검색은 어떤 서비스이든 검색어 전체를 먼저 그대로 조회하고, 실패할 때만 공백/브랜드어 제거, 표기 변형, 더 짧은 핵심어 순으로 단계적으로 넓혀서 다시 시도합니다.
    - 너무 넓은 축약어로만 매칭된 경우에는 확정 상품처럼 단정하지 말고, 추정 매칭임을 짧게 밝힌 뒤 재고를 안내합니다.
    - 위치/브랜드/상품명은 한 인자에 섞지 말고 가능한 한 분리해서 도구에 전달합니다.
-7. **위치 기반 재고**: lat, lng 파라미터로 가까운 매장 우선 조회
-8. **롯데마트 상품 조회**: /api/lottemart/products는 keyword와 함께 storeCode 또는 storeName이 필요합니다.
-9. **세븐일레븐 재고 조회**: /api/seveneleven/inventory에 keyword + storeKeyword를 함께 주면 매장별 수량을 바로 확인할 수 있습니다.
-10. **이마트24 재고 조회**: /api/emart24/inventory는 pluCd + storeKeyword 조합도 지원하므로, 상품 선택 뒤 매장 코드를 다시 모으지 않아도 됩니다.
-11. **올리브영 재고 해석**: inventory.products[].storeInventory.stores[]가 있으면 그 매장별 stockLabel과 remainQuantity를 우선 사용하고, inStock는 그 주변 매장 기준 결과로 해석합니다.
-12. **올리브영 상품 이미지 표시**: /api/oliveyoung/products 또는 oliveyoung_search_products 결과에 imageUrl이 있으면 목록형 답변에서도 각 상품 이미지를 생략하지 말고 모두 렌더링합니다. 특히 \`?l=ko\` 같은 query string을 삭제하지 말고 전체 URL 그대로 마크다운 이미지 src에 넣습니다.
+8. **위치 기반 재고**: lat, lng 파라미터로 가까운 매장 우선 조회
+9. **롯데마트 상품 조회**: /api/lottemart/products는 keyword와 함께 storeCode 또는 storeName이 필요합니다.
+10. **세븐일레븐 재고 조회**: /api/seveneleven/inventory에 keyword + storeKeyword를 함께 주면 매장별 수량을 바로 확인할 수 있습니다.
+11. **이마트24 재고 조회**: /api/emart24/inventory는 pluCd + storeKeyword 조합도 지원하므로, 상품 선택 뒤 매장 코드를 다시 모으지 않아도 됩니다.
+12. **올리브영 재고 해석**: inventory.products[].storeInventory.stores[]가 있으면 그 매장별 stockLabel과 remainQuantity를 우선 사용하고, inStock는 그 주변 매장 기준 결과로 해석합니다.
+13. **올리브영 상품 이미지 표시**: /api/oliveyoung/products 또는 oliveyoung_search_products 결과에 imageUrl이 있으면 목록형 답변에서도 각 상품 이미지를 생략하지 말고 모두 렌더링합니다. 특히 \`?l=ko\` 같은 query string을 삭제하지 말고 전체 URL 그대로 마크다운 이미지 src에 넣습니다.
 
 ---
 

package/dist/pages/promptRetailCinemaText.js

@@ -18,12 +18,13 @@ export function buildPromptRetailCinemaText(baseUrl) {
 - limit: 최대 결과 수 (기본값: 20)
 - storeCode 또는 storeName: 상품 검색 대상 매장
 - pageLimit: 추가 조회할 최대 페이지 수 (기본값: 3)
+- source: 상품 검색 경로 (auto, legacy, zetta). 빠른 검색이나 헬스체크에는 zetta 권장
 
 **예시**:
 - ${baseUrl}/api/lottemart/stores?keyword=잠실&area=서울&limit=10
 - ${baseUrl}/api/lottemart/stores?area=경기&brandVariant=lottemart&limit=10
 - ${baseUrl}/api/lottemart/products?keyword=콜라&storeName=강변점&area=서울
-- ${baseUrl}/api/lottemart/products?keyword=우유&storeCode=2301&pageLimit=2
+- ${baseUrl}/api/lottemart/products?keyword=우유&storeCode=2301&pageLimit=2&source=zetta
 
 ---
 

package/dist/services/daiso/client.js

@@ -11,6 +11,10 @@ const DAISO_DEFAULT_HEADERS = {
     Accept: 'application/json, text/html, */*',
     'Accept-Language': 'ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7',
 };
+const DAISO_DEFAULT_FETCH_OPTIONS = {
+    retries: 1,
+    retryDelayMs: 250,
+};
 function withDaisoHeaders(headers = {}) {
     return {
         ...DAISO_DEFAULT_HEADERS,
@@ -19,18 +23,21 @@ function withDaisoHeaders(headers = {}) {
 }
 export async function daisoFetch(url, options = {}) {
     return fetchWithTimeout(url, {
+        ...DAISO_DEFAULT_FETCH_OPTIONS,
         ...options,
         headers: withDaisoHeaders(options.headers),
     });
 }
 export async function fetchDaisoJson(url, options = {}) {
     return fetchJson(url, {
+        ...DAISO_DEFAULT_FETCH_OPTIONS,
         ...options,
         headers: withDaisoHeaders(options.headers),
     });
 }
 export async function fetchDaisoHtml(url, options = {}) {
     return fetchText(url, {
+        ...DAISO_DEFAULT_FETCH_OPTIONS,
         ...options,
         headers: withDaisoHeaders(options.headers),
     });
@@ -83,6 +90,7 @@ export async function createDaisoAuthContext() {
 export async function fetchDaisoJsonWithAuth(url, options = {}) {
     const auth = await createDaisoAuthContext();
     return fetchJson(url, {
+        ...DAISO_DEFAULT_FETCH_OPTIONS,
         ...options,
         headers: withDaisoHeaders({
             ...options.headers,

package/dist/services/daiso/index.js

@@ -6,6 +6,7 @@
 import { createSearchProductsTool } from './tools/searchProducts.js';
 import { createFindStoresTool } from './tools/findStores.js';
 import { createCheckInventoryTool } from './tools/checkInventory.js';
+import { createFindInventoryByNameTool } from './tools/findInventoryByName.js';
 import { createGetPriceInfoTool } from './tools/getPriceInfo.js';
 import { createGetDisplayLocationTool } from './tools/getDisplayLocation.js';
 /**
@@ -27,6 +28,7 @@ class DaisoService {
             createSearchProductsTool(),
             createFindStoresTool(),
             createCheckInventoryTool(),
+            createFindInventoryByNameTool(),
             createGetPriceInfoTool(),
             createGetDisplayLocationTool(),
         ];

package/dist/services/daiso/tools/checkInventory.js

@@ -142,9 +142,11 @@ export function createCheckInventoryTool() {
         name: 'daiso_check_inventory',
         metadata: {
             title: '재고 확인',
-            description: '특정 제품의 매장별 재고를 확인합니다. 매장명/주소 검색 또는 위치 기반으로 조회합니다.',
+            description: '특정 제품의 매장별 재고를 확인합니다. 상품명만 아는 경우 daiso_search_products로 후보를 먼저 찾은 뒤 productId를 전달하세요. 매장명/주소 검색 또는 위치 기반으로 조회합니다. "근처/주변"처럼 위치가 모호하면 storeQuery, latitude/longitude 또는 사용자 위치를 먼저 확인하세요.',
             inputSchema: {
-                productId: z.string().describe('제품 ID (daiso_search_products로 조회한 상품의 id)'),
+                productId: z
+                    .string()
+                    .describe('제품 ID. 상품명만 알면 먼저 daiso_search_products로 상품의 id를 확인하세요.'),
                 storeQuery: z.string().optional().describe('매장 검색어 (매장명 또는 주소, 예: 안산 중앙역)'),
                 latitude: z.number().optional().default(37.5665).describe('위도 (기본값: 서울 시청 37.5665)'),
                 longitude: z.number().optional().default(126.978).describe('경도 (기본값: 서울 시청 126.978)'),

package/dist/services/daiso/tools/findInventoryByName.js

@@ -0,0 +1,222 @@
+/**
+ * 상품명 기반 재고 통합 조회 도구
+ *
+ * 상품명과 위치만 아는 사용자를 위해 상품 검색과 재고 조회를 한 번에 수행합니다.
+ */
+import * as z from 'zod';
+import { fetchProducts } from './searchProducts.js';
+import { fetchOnlineStock, fetchStoreInventory } from './checkInventory.js';
+import { fetchStores } from './findStores.js';
+function buildTextResponse(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+    };
+}
+function buildEmptySummary(query, storeQuery) {
+    return {
+        headline: `"${query}" 상품 후보를 찾지 못했습니다.`,
+        selectedProduct: '',
+        storeQuery: storeQuery || '미지정',
+        inventorySummary: '상품 후보가 없어 온라인/매장 재고 조회를 건너뛰었습니다.',
+        displayLocationHint: '상품 후보를 먼저 확인한 뒤 daiso_get_display_location을 사용할 수 있습니다.',
+    };
+}
+async function resolveInventoryLocation(args) {
+    if (typeof args.latitude === 'number' && typeof args.longitude === 'number') {
+        return {
+            latitude: args.latitude,
+            longitude: args.longitude,
+            source: 'input',
+        };
+    }
+    if (args.storeQuery.trim().length > 0) {
+        const stores = await fetchStores(args.storeQuery);
+        const firstStore = stores[0];
+        if (firstStore) {
+            return {
+                latitude: firstStore.lat,
+                longitude: firstStore.lng,
+                source: 'storeQuery',
+                storeName: firstStore.name,
+                storeAddress: firstStore.address,
+            };
+        }
+    }
+    return {
+        latitude: args.latitude ?? 37.5665,
+        longitude: args.longitude ?? 126.978,
+        source: 'default',
+    };
+}
+function buildInventorySummary(args) {
+    const storeScope = args.storeQuery || '기본 위치 주변';
+    return {
+        headline: `"${args.query}" 조회 결과, "${args.selectedProductName}" 상품을 기준으로 재고를 확인했습니다.`,
+        selectedProduct: args.selectedProductName,
+        storeQuery: args.storeQuery || '미지정',
+        inventorySummary: `${storeScope} 매장 ${args.totalStores}곳 중 ${args.inStockCount}곳에서 재고가 확인되었습니다. 온라인 재고는 ${args.onlineStock}개입니다.`,
+        displayLocationHint: '진열 위치가 필요하면 storeInventory.stores[].storeCode로 daiso_get_display_location을 호출하세요.',
+    };
+}
+function toSummary(product) {
+    return {
+        id: product.id,
+        name: product.name,
+        imageUrl: product.imageUrl,
+        brand: product.brand,
+        soldOut: product.soldOut,
+        isNew: product.isNew,
+    };
+}
+function normalizeProductName(value) {
+    return value.toLowerCase().replace(/\s+/g, '');
+}
+function scoreProductCandidate(query, candidate, index) {
+    const normalizedQuery = normalizeProductName(query);
+    const normalizedName = normalizeProductName(candidate.name);
+    const exactMatchScore = normalizedName === normalizedQuery ? 100 : 0;
+    const availabilityScore = candidate.soldOut ? 0 : 20;
+    const startsWithScore = normalizedName.startsWith(normalizedQuery) ? 10 : 0;
+    const containsScore = normalizedName.includes(normalizedQuery) ? 5 : 0;
+    return exactMatchScore + availabilityScore + startsWithScore + containsScore - index / 1000;
+}
+function selectProductCandidate(query, candidates) {
+    return (candidates
+        .map((candidate, index) => ({
+        candidate,
+        score: scoreProductCandidate(query, candidate, index),
+    }))
+        .sort((a, b) => b.score - a.score)[0]?.candidate ?? null);
+}
+async function findInventoryByName(args) {
+    const { query, storeQuery = '', latitude, longitude, page = 1, pageSize = 30, productLimit = 5, } = args;
+    if (!query || query.trim().length === 0) {
+        throw new Error('상품명(query)을 입력해주세요.');
+    }
+    const productResult = await fetchProducts(query, 1, productLimit);
+    const productCandidates = productResult.products.map(toSummary);
+    const selectedProduct = selectProductCandidate(query, productCandidates);
+    if (!selectedProduct) {
+        return buildTextResponse({
+            query,
+            storeQuery,
+            summary: buildEmptySummary(query, storeQuery),
+            productCandidates: [],
+            selectedProduct: null,
+            onlineStock: 0,
+            storeInventory: {
+                totalStores: 0,
+                inStockCount: 0,
+                outOfStockCount: 0,
+                page,
+                pageSize,
+                stores: [],
+            },
+            nextSteps: {
+                productSearchTool: 'daiso_search_products',
+                inventoryTool: 'daiso_check_inventory',
+                note: '상품 후보가 없어서 재고 조회를 진행하지 않았습니다.',
+            },
+        });
+    }
+    const resolvedLocation = await resolveInventoryLocation({
+        storeQuery,
+        latitude,
+        longitude,
+    });
+    const [onlineStock, storeResult] = await Promise.all([
+        fetchOnlineStock(selectedProduct.id),
+        fetchStoreInventory(selectedProduct.id, resolvedLocation.latitude, resolvedLocation.longitude, page, pageSize, storeQuery),
+    ]);
+    const stores = storeResult.stores;
+    const inStockCount = stores.filter((store) => store.quantity > 0).length;
+    const result = {
+        query,
+        storeQuery,
+        location: resolvedLocation,
+        summary: buildInventorySummary({
+            query,
+            storeQuery,
+            selectedProductName: selectedProduct.name,
+            onlineStock,
+            inStockCount,
+            totalStores: storeResult.totalCount,
+        }),
+        productCandidates,
+        selectedProduct,
+        onlineStock,
+        storeInventory: {
+            totalStores: storeResult.totalCount,
+            inStockCount,
+            outOfStockCount: stores.filter((store) => store.quantity === 0).length,
+            page,
+            pageSize,
+            stores,
+        },
+        nextSteps: {
+            productSearchTool: 'daiso_search_products',
+            inventoryTool: 'daiso_check_inventory',
+            displayLocationTool: 'daiso_get_display_location',
+            storeCodeSource: '진열 위치가 필요하면 storeInventory.stores[].storeCode를 사용하세요.',
+        },
+    };
+    return buildTextResponse(result);
+}
+const inventoryByNameOutputSchema = {
+    query: z.string().describe('사용자가 입력한 상품 검색어'),
+    storeQuery: z.string().describe('사용자가 입력한 위치 키워드'),
+    location: z
+        .object({
+        latitude: z.number(),
+        longitude: z.number(),
+        source: z.enum(['input', 'storeQuery', 'default']),
+        storeName: z.string().optional(),
+        storeAddress: z.string().optional(),
+    })
+        .optional()
+        .describe('재고 조회에 사용한 위치와 위치 해석 출처'),
+    summary: z
+        .object({
+        headline: z.string(),
+        selectedProduct: z.string(),
+        storeQuery: z.string(),
+        inventorySummary: z.string(),
+        displayLocationHint: z.string(),
+    })
+        .describe('사용자에게 바로 보여줄 요약'),
+    productCandidates: z.array(z.unknown()).describe('검색된 상품 후보 목록'),
+    selectedProduct: z.unknown().nullable().describe('재고 조회 기준으로 선택한 상품'),
+    onlineStock: z.number().describe('온라인 재고 수량'),
+    storeInventory: z
+        .object({
+        totalStores: z.number(),
+        inStockCount: z.number(),
+        outOfStockCount: z.number(),
+        page: z.number(),
+        pageSize: z.number(),
+        stores: z.array(z.unknown()),
+    })
+        .describe('매장별 재고 조회 결과'),
+    nextSteps: z.record(z.string(), z.unknown()).describe('후속 도구 호출 안내'),
+};
+export function createFindInventoryByNameTool() {
+    return {
+        name: 'daiso_find_inventory_by_name',
+        metadata: {
+            title: '상품명 기반 재고 통합 조회',
+            description: '상품명과 대강의 위치만 아는 사용자를 위해 제품 검색부터 재고 조회까지 한 번에 수행합니다. 결과의 storeInventory.stores[].storeCode는 진열 위치 조회에 사용할 수 있습니다.',
+            inputSchema: {
+                query: z.string().describe('검색할 상품명 또는 키워드'),
+                storeQuery: z.string().optional().describe('역명, 동네, 매장명 같은 대강의 위치'),
+                latitude: z.number().optional().describe('위도 (생략 시 서울 시청 37.5665)'),
+                longitude: z.number().optional().describe('경도 (생략 시 서울 시청 126.978)'),
+                page: z.number().optional().default(1).describe('재고 매장 페이지 번호 (기본값: 1)'),
+                pageSize: z.number().optional().default(30).describe('재고 매장 페이지 크기 (기본값: 30)'),
+                productLimit: z.number().optional().default(5).describe('상품 후보 수 (기본값: 5)'),
+            },
+            outputSchema: inventoryByNameOutputSchema,
+        },
+        handler: findInventoryByName,
+    };
+}

package/dist/services/daiso/tools/getDisplayLocation.js

@@ -62,12 +62,12 @@ export function createGetDisplayLocationTool() {
         name: 'daiso_get_display_location',
         metadata: {
             title: '진열 위치 조회',
-            description: '다이소 매장 내 상품의 진열 위치(구역/층)를 조회합니다. 상품 ID와 매장 코드가 필요합니다.',
+            description: '다이소 매장 내 상품의 진열 위치(구역/층)를 조회합니다. 상품 ID와 매장 코드가 필요합니다. storeCode를 모르면 먼저 daiso_check_inventory로 재고를 조회하고 storeInventory.stores[].storeCode를 사용하세요.',
             inputSchema: {
                 productId: z.string().describe('상품 ID (daiso_search_products로 조회한 상품의 id)'),
                 storeCode: z
                     .string()
-                    .describe('매장 코드 (daiso_check_inventory로 조회한 매장의 storeCode)'),
+                    .describe('매장 코드. storeCode를 모르면 먼저 daiso_check_inventory 결과의 storeInventory.stores[].storeCode를 확인하세요.'),
             },
         },
         handler: getDisplayLocation,

package/dist/services/emart24/client.js

@@ -12,6 +12,10 @@ const EMART24_FORM_HEADERS = {
     Accept: 'application/json, text/javascript, */*; q=0.01',
     'X-Requested-With': 'XMLHttpRequest',
 };
+const EMART24_DEFAULT_FETCH_OPTIONS = {
+    retries: 1,
+    retryDelayMs: 250,
+};
 function buildKeywordVariants(keyword) {
     const trimmed = keyword.trim();
     if (trimmed.length === 0) {
@@ -101,6 +105,7 @@ export async function fetchEmart24Stores(params = {}, options = {}) {
             endpoint.searchParams.set('SVR_24', '1');
         }
         const body = await fetchJson(endpoint.toString(), {
+            ...EMART24_DEFAULT_FETCH_OPTIONS,
             method: 'GET',
             timeout,
             headers: EMART24_JSON_HEADERS,
@@ -131,7 +136,9 @@ export async function searchEmart24Products(params, options = {}) {
     form.set('saleProductYn', saleProductYn);
     form.set('searchWord', keyword.trim());
     const body = await fetchJson(`${EMART24_API.EVERSE_BASE_URL}${EMART24_API.PRODUCT_SEARCH_PATH}`, {
+        ...EMART24_DEFAULT_FETCH_OPTIONS,
         method: 'POST',
+        retryUnsafeMethods: true,
         timeout,
         headers: EMART24_FORM_HEADERS,
         body: form.toString(),
@@ -158,6 +165,7 @@ export async function searchEmart24StockByStores(params, options = {}) {
     endpoint.searchParams.set('searchPluCode', pluCd);
     endpoint.searchParams.set('bizNoArr', filteredBizNos.join(','));
     return fetchJson(endpoint.toString(), {
+        ...EMART24_DEFAULT_FETCH_OPTIONS,
         method: 'GET',
         timeout,
         headers: EMART24_JSON_HEADERS,
@@ -166,6 +174,7 @@ export async function searchEmart24StockByStores(params, options = {}) {
 export async function fetchEmart24StoreDetail(bizNo, options = {}) {
     const { timeout = 15000 } = options;
     return fetchJson(`${EMART24_API.EVERSE_BASE_URL}${EMART24_API.STORE_DETAIL_PATH_PREFIX}${encodeURIComponent(bizNo)}`, {
+        ...EMART24_DEFAULT_FETCH_OPTIONS,
         method: 'GET',
         timeout,
         headers: EMART24_JSON_HEADERS,

package/dist/services/emart24/tools/searchProducts.js

@@ -3,6 +3,12 @@
  */
 import * as z from 'zod';
 import { searchEmart24Products } from '../client.js';
+function buildTextResponse(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+    };
+}
 async function searchProducts(args) {
     const { keyword, page = 1, pageSize = 10, sortType = 'SALE', saleProductYn = 'N', timeoutMs = 15000, } = args;
     if (!keyword || keyword.trim().length === 0) {
@@ -17,24 +23,27 @@ async function searchProducts(args) {
     }, {
         timeout: timeoutMs,
     });
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify({
-                    keyword,
-                    page,
-                    pageSize,
-                    sortType,
-                    saleProductYn,
-                    totalCount: result.totalCount,
-                    count: result.products.length,
-                    products: result.products,
-                }, null, 2),
-            },
-        ],
-    };
+    return buildTextResponse({
+        keyword,
+        page,
+        pageSize,
+        sortType,
+        saleProductYn,
+        totalCount: result.totalCount,
+        count: result.products.length,
+        products: result.products,
+    });
 }
+const searchProductsOutputSchema = {
+    keyword: z.string().describe('검색어'),
+    page: z.number().describe('조회 페이지'),
+    pageSize: z.number().describe('페이지당 결과 수'),
+    sortType: z.string().describe('정렬 기준'),
+    saleProductYn: z.string().describe('행사 상품 여부 필터'),
+    totalCount: z.number().describe('검색된 전체 상품 수'),
+    count: z.number().describe('반환된 상품 수'),
+    products: z.array(z.unknown()).describe('이마트24 상품 검색 결과'),
+};
 export function createSearchProductsTool() {
     return {
         name: 'emart24_search_products',
@@ -57,6 +66,7 @@ export function createSearchProductsTool() {
                     .describe('행사 상품 여부 필터 (기본값: N)'),
                 timeoutMs: z.number().optional().default(15000).describe('요청 제한 시간(ms, 기본값: 15000)'),
             },
+            outputSchema: searchProductsOutputSchema,
         },
         handler: searchProducts,
     };

package/dist/services/gs25/client.js

@@ -9,6 +9,10 @@ export { attachDistanceToGs25Stores, calculateDistanceM, extractGs25ProductCandi
 const GS25_DEFAULT_HEADERS = {
     Accept: 'application/json, text/plain, */*',
 };
+const GS25_DEFAULT_FETCH_OPTIONS = {
+    retries: 1,
+    retryDelayMs: 250,
+};
 const GS25_STORES_CACHE_TTL_MS = 60 * 5 * 1000;
 const gs25StoresCache = new Map();
 function buildCacheKey(params) {
@@ -34,6 +38,7 @@ export async function geocodeGs25Address(address, options = {}) {
     endpoint.searchParams.set('address', keyword);
     endpoint.searchParams.set('key', apiKey);
     const body = await fetchJson(endpoint.toString(), {
+        ...GS25_DEFAULT_FETCH_OPTIONS,
         method: 'GET',
         timeout,
         headers: {
@@ -109,6 +114,7 @@ export async function fetchGs25Stores(params = {}, options = {}) {
         endpoint.searchParams.set('isGs25DlvyStoreSelected', 'N');
     }
     const body = await fetchJson(endpoint.toString(), {
+        ...GS25_DEFAULT_FETCH_OPTIONS,
         method: 'GET',
         timeout,
         headers: GS25_DEFAULT_HEADERS,
@@ -134,7 +140,9 @@ export async function fetchGs25NormalizedKeyword(keyword, options = {}) {
     const { timeout = 20000 } = options;
     const endpoint = new URL(GS25_API.TOTAL_SEARCH_PATH, GS25_API.APIGW_BASE_URL);
     const body = await fetchJson(endpoint.toString(), {
+        ...GS25_DEFAULT_FETCH_OPTIONS,
         method: 'POST',
+        retryUnsafeMethods: true,
         timeout,
         headers: {
             Accept: 'application/json, text/plain, */*',
@@ -164,7 +172,9 @@ export async function fetchGs25SearchProducts(keyword, options = {}) {
     const { timeout = 20000 } = options;
     const endpoint = new URL(GS25_API.TOTAL_SEARCH_PATH, GS25_API.APIGW_BASE_URL);
     const body = await fetchJson(endpoint.toString(), {
+        ...GS25_DEFAULT_FETCH_OPTIONS,
         method: 'POST',
+        retryUnsafeMethods: true,
         timeout,
         headers: {
             Accept: 'application/json, text/plain, */*',

package/dist/services/gs25/tools/searchProducts.js

@@ -3,6 +3,12 @@
  */
 import * as z from 'zod';
 import { fetchGs25SearchProducts } from '../client.js';
+function buildTextResponse(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+    };
+}
 async function searchProducts(args) {
     const { keyword, limit = 20, timeoutMs = 20000 } = args;
     if (!keyword || keyword.trim().length === 0) {
@@ -10,29 +16,29 @@ async function searchProducts(args) {
     }
     const products = await fetchGs25SearchProducts(keyword, { timeout: timeoutMs });
     const limitedProducts = products.slice(0, limit);
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify({
-                    keyword,
-                    count: limitedProducts.length,
-                    products: limitedProducts.map((p) => ({
-                        itemCode: p.itemCode,
-                        itemName: p.itemName,
-                        shortItemName: p.shortItemName,
-                        imageUrl: p.imageUrl,
-                        rating: p.rating,
-                        stockCheckEnabled: p.stockCheckEnabled,
-                    })),
-                    note: limitedProducts.length === 0
-                        ? '검색 결과가 없습니다. 다른 키워드로 검색해보세요.'
-                        : '재고 확인 시 itemCode를 gs25_check_inventory에 전달하면 정확한 상품 재고를 조회할 수 있습니다.',
-                }, null, 2),
-            },
-        ],
+    const payload = {
+        keyword,
+        count: limitedProducts.length,
+        products: limitedProducts.map((p) => ({
+            itemCode: p.itemCode,
+            itemName: p.itemName,
+            shortItemName: p.shortItemName,
+            imageUrl: p.imageUrl,
+            rating: p.rating,
+            stockCheckEnabled: p.stockCheckEnabled,
+        })),
+        note: limitedProducts.length === 0
+            ? '검색 결과가 없습니다. 다른 키워드로 검색해보세요.'
+            : '재고 확인 시 itemCode를 gs25_check_inventory에 전달하면 정확한 상품 재고를 조회할 수 있습니다.',
     };
+    return buildTextResponse(payload);
 }
+const searchProductsOutputSchema = {
+    keyword: z.string().describe('검색어'),
+    count: z.number().describe('반환된 상품 수'),
+    products: z.array(z.unknown()).describe('GS25 상품 검색 결과'),
+    note: z.string().describe('후속 재고 조회 안내'),
+};
 export function createSearchProductsTool() {
     return {
         name: 'gs25_search_products',
@@ -44,6 +50,7 @@ export function createSearchProductsTool() {
                 limit: z.number().optional().default(20).describe('반환할 최대 상품 수 (기본값: 20)'),
                 timeoutMs: z.number().optional().default(20000).describe('요청 제한 시간(ms, 기본값: 20000)'),
             },
+            outputSchema: searchProductsOutputSchema,
         },
         handler: searchProducts,
     };