# Smart Store Suite: agent guide

Smart Store Suite joins three checks for Naver Smart Store sellers into one flow. Step 1, store check, collects products from a store URL (Smart Store, Brand Store, Shopping Window, Naver+) or from product, sales and margin CSVs and combines search demand with margin or reviews and sales to show which products to grow and which to drop. Step 2 rewrites a product title in the words searchers actually use, and step 3 scores how well a detail page covers the buying criteria searchers look for and suggests fixes. Smart Store sellers, brand managers and commerce MDs use it. Data comes from the ListeningMind Data API (keyword_info, intent_finder, cluster_finder, path_finder), maistro-lmpipe and LLMs (MiniMax, Claude); the market is Korea (Naver Shopping).

## Connect
- MCP: `https://daas-store.listeningmind.ai/mcp` (Streamable HTTP). Start with `app_guide`.
- Browser agents: tools are registered on every page through WebMCP (`document.modelContext`).
- REST: `https://daas-store.listeningmind.ai/.well-known/openapi.json`

## Approval
- read and action tools run at once.
- run and delete tools need a person's approval. Over MCP the tool returns `confirm_url`; show it to the person, then call `confirmation_status` with the token until state is done.
- In the browser the page shows the person a confirm box.

## Workflow
1. `collect_store_products` (run): Collect the store's products from its URL (replaces the current product set). Own-store CSVs are uploaded in the web page /portfolio/upload.
2. `preview_dormant_products` (read): For a large catalog, preview dormant products and exclude them with exclude_dormant_products to save credits.
3. `start_store_check` (run): Start the store check.
4. `get_store_check` (read): Poll until run.status is completed, then read classes and priorities.
5. `get_store_check_product` (read): Read the detail of the chosen product; fix a wrong keyword with rescore_store_check_product.
6. `download_store_check_csv` (read): Download the result as CSV.
7. `start_title_analysis` (run): Step 2: start a title rewrite with the chosen product's name (plus category path and tags).
8. `get_title_analysis` (read): Poll until status is done and read the A/B titles and scores.
9. `select_title_identity` (run): Optionally recompose the title around another identity candidate.
10. `start_detail_page_analysis` (run): Step 3: start the detail page intent check with the product URL or typed page data.
11. `get_detail_page_analysis` (read): Poll until status is done and read the missed criteria and recommendations.
12. `rescore_detail_page` (run): After editing the detail page, re-check it to see what changed.
13. `add_watch` (run): Optionally register the store for periodic tracking so sales momentum appears from the next collection (each later run spends credits).
14. `list_store_checks` (read): Find earlier store checks; title and detail page history are in list_title_analyses and list_detail_page_analyses.

## Inputs
Store check: a Naver store URL (50/100/200/500 products, optional tracking every 7/14/30 days) or product, sales and margin CSVs (uploaded in the web page), dormant product rules, a corrected representative keyword per product. Title rewrite: current product name (up to 200 characters, required), category path, product note, tags, seed category word. Detail page intent: a Smart Store product URL or typed data (name, price, category, options, detail text, reviews and Q&A, detail images, bookmarklet capture) and a seed keyword.

## Outputs
Store check: a class per product (margin mode: grow, improve margin, niche intent, reduce or exit; sales-power mode: proven, opportunity, niche, slow; demand only: high or low demand), demand, margin, sales power, momentum, portfolio and risk scores, recommended actions with reasons, priority, counts per class and action, product detail (volume, trend, intents and SERP features of the representative keyword), CSV. Title rewrite: title score (TIS) and grade, word breakdown, identity candidates with fit, front 3 word sets, category fit, noise words, A/B titles with predicted scores, tag and option plan, policy check. Detail page intent: coverage score (ICS) and page score (CPS), grade, 6 axis scores, verdict and evidence per buying criterion, missed opportunities, recommendations (structure, title, FAQ, review prompts, comparison frame) and changes after a re-check.

## Cost and time
Store check uses keyword_info (about 10 credits per keyword) and one intent_finder call (limit 100) per new representative keyword. For 100 products with all-new keywords that is about 1,000 keyword_info credits plus 100 intent_finder calls; the app does not record the intent_finder price, so the exact total is unknown. Keywords fetched in the last 7 days are free, and with a MiniMax key one LLM call is added per 30 products. Title rewrite and detail page intent, for a category not seen before, call path_finder (limit 300, about 8,450 credits at the Funnel Leak Finder rate), cluster_finder, intent_finder, keyword_info for 150-190 keywords and a maistro-lmpipe analysis, which can exceed 10,000 credits; with the 30-day category cache they need only a few hundred keyword_info credits or less. LLM calls: 1-4 per title analysis; a detail page check makes several to more than 20 depending on images and intent items. Collecting a store URL spends no credits. When the server runs in mock mode, store check search data is synthetic and spends no credits.

## Limits
Market: Korea (Naver) only. Detail page URLs must be on smartstore.naver.com, brand.naver.com or shopping.naver.com; store collection accepts Smart Store, Brand Store, Shopping Window and Naver+ store URLs. The store check module holds a single product set, so collect_store_products (without append) and clear_store_products remove the current products, and start_store_check returns the run already in progress (a run stuck for more than 10 minutes is marked failed and a new one starts). Smart Store often blocks server fetches, so pass tier3 data (typed or captured) with a detail page check. Title and detail page analyses each run 3 at a time and return 429 above 12 queued or running. Category data is cached 30 days, store check keyword metrics 7 days. The app has no accounts: history and deletes are shared by everyone. History lists return the 30 newest title or detail page analyses and up to 100 store checks.

## Method (how the analysis works)
1. Collect the store's products from its URL (or CSVs uploaded in the web page) and exclude dormant products if needed.
2. Pick a representative search keyword per product and read keyword_info and intent_finder for it.
3. Score search demand, margin or sales power, momentum and risk, classify each product and recommend actions in priority order.
4. For a chosen product, split the title into words, rank the category's identity candidates and compose A/B titles with predicted scores (TIS).
5. For the detail page, build the category's buying criteria on 6 axes, judge each covered, partial or missing with evidence, and score ICS and CPS with recommendations.

## Reading the result
- Store check items are ordered by priority; classification, recommendedAction and reason say which products to grow and which to reduce.
- dataBasis per product shows which data the score used (margin, sales power or demand only).
- tis and grade score the current title; title_variants are the A/B titles with predicted_tis, and noise_keywords are words to drop.
- category_fit and the policy check flag titles that do not fit the category or break policy.
- For the detail page, ics is the coverage of buying criteria and cps the page score; cards.missed and recommendations show what to add.

## Requests this app answers well
- Pick which products in our Smart Store to grow and which to drop
- Rewrite this product title into A/B versions using the words searchers actually use
- Score how well this Smart Store detail page covers searchers' buying criteria and suggest fixes
- I edited the detail page; check it again and tell me how much the score changed

## Continue in another app
- [Demand Forecast](https://daas-forecast.listeningmind.ai/llms.txt) (MCP `https://daas-forecast.listeningmind.ai/mcp`): When products are classed to grow and you need their season timing. Carry: Their representative keywords as seeds (up to 5), with market kr.
- [ACO](https://daas-aco.listeningmind.ai/llms.txt) (MCP `https://daas-aco.listeningmind.ai/mcp`): When you also want to check whether the product page can be cited by AI answers and used by shopping agents. Carry: The Smart Store product URL with market kr; Smart Store often blocks server fetches, so pass pasted HTML as well.

## Using the screens (browser agents)
- `describe_screen`: menus, tabs, fields and buttons of the current screen, and what the page is for
- `go_to`: open a menu or page of this app by its label or path
- `fill_field`: type a value into a field by its label (never presses run; runs go through the run tools, which ask the person)
- `read_this_page`: the text and ids of what the person is looking at

## The ListeningMind apps (same account, same tools, call any of them)
Each app has `/mcp`, `/llms.txt`, `/agents.md` and WebMCP on its pages. `family_apps` and `recommend_app` return this list with addresses.
- [ACO](https://daas-aco.listeningmind.ai/llms.txt): Diagnoses whether a product detail page can be cited by AI answers and used by shopping agents (MCP `https://daas-aco.listeningmind.ai/mcp`)
- [AOO](https://daas-aoo.listeningmind.ai/llms.txt): Measures whether AI agents can get real tasks done on a website (MCP `https://daas-aoo.listeningmind.ai/mcp`)
- [Brand Finder](https://daas-brand.listeningmind.ai/llms.txt): Which brands lead search by generation or field, and what their brand assets are (MCP `https://daas-brand.listeningmind.ai/mcp`)
- [Brand Naming Agent](https://daas-naming.listeningmind.ai/llms.txt): Creates and checks brand name candidates grounded in search data (MCP `https://daas-naming.listeningmind.ai/mcp`)
- [Brand Wiki](https://daas-wiki.listeningmind.ai/llms.txt): Turns a brand website into the entities, wiki pages and evidence AI assistants read (MCP `https://daas-wiki.listeningmind.ai/mcp`)
- [CEP Finder](https://daas-cep.listeningmind.ai/llms.txt): In which situations do people start looking for this category (category entry point map) (MCP `https://daas-cep.listeningmind.ai/mcp`)
- [Creative Finder](https://daas-creative.listeningmind.ai/llms.txt): Finds purchase situations (CEP) in search data and drafts a creative, an image and a video for each (MCP `https://daas-creative.listeningmind.ai/mcp`)
- [Demand Forecast](https://daas-forecast.listeningmind.ai/llms.txt): What category demand looks like in the next 3-6 months and when to launch or campaign (MCP `https://daas-forecast.listeningmind.ai/mcp`)
- [Funnel Leak Finder](https://daas-funnel.listeningmind.ai/llms.txt): Where category search journeys leak to competitors (MCP `https://daas-funnel.listeningmind.ai/mcp`)
- [GEO Audit](https://daas-geo.listeningmind.ai/llms.txt): Checks whether a web page is ready to be read and cited by search engines and AI answer engines (MCP `https://daas-geo.listeningmind.ai/mcp`)
- [ICSS](https://daas-icss.listeningmind.ai/llms.txt): Synthetic consumer panel conditioned on search intent, for surveys and FGDs (MCP `https://daas-icss.listeningmind.ai/mcp`)
- [Intent KG](https://daas-intent.listeningmind.ai/llms.txt): What people look for about a topic, why, and how they choose (Intent Knowledge Graph) (MCP `https://daas-intent.listeningmind.ai/mcp`)
- [Prompt Builder](https://daas-prompt.listeningmind.ai/llms.txt): Finds what consumers ask AI and builds managed brand prompts with AI visibility (MCP `https://daas-prompt.listeningmind.ai/mcp`)
- [Pulse Finder](https://daas-pulse.listeningmind.ai/llms.txt): What is rising in search for a gender and age segment right now (MCP `https://daas-pulse.listeningmind.ai/mcp`)
- [Taste Finder](https://daas-taste.listeningmind.ai/llms.txt): In what sensory and emotional words do people choose this (consumer taste report from search data) (MCP `https://daas-taste.listeningmind.ai/mcp`)
- [ListeningMind Data API](https://daas.listeningmind.ai/llms.txt): the search data behind every app (MCP `https://daas.listeningmind.ai/mcp`) · [glossary](https://daas.listeningmind.ai/en/glossary) · [all apps](https://daas.listeningmind.ai/en/apps)

## Run stages
- `pending`: Store check waiting
- `running`: Running
- `completed`: Store check completed
- `failed`: Store check failed
- `queued`: Title or detail page analysis queued
- `done`: Title or detail page analysis done
- `error`: Title or detail page analysis error

## All tools
### collect_store_products
Collects the products of a Naver store (smartstore.naver.com/{id}, brand.naver.com/{id}, shopping.naver.com/window/{vertical}/store/{channelId} or a Naver+ store shopping.naver.com/{slug}) by popularity order, with price, category, review count, rating, sales count (Shopping Window) and rank, and stores a review snapshot for momentum. By default it first REMOVES the current product set (past results stay). Returns {ok, store{name, storeId, host}, imported, totalAvailable, via (http or browser), note, watching}. Uses a headless browser when Naver blocks plain requests; can take tens of seconds to a few minutes. Then call start_store_check. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: free: no Data API credits or LLM calls (Naver pages only); it replaces the product set unless append is true. Time: tens of seconds to a few minutes (server limit 300 seconds). Usually followed by: preview_dormant_products, start_store_check.
`POST /portfolio/api/uploads/store-url`
- `url` (required): Store URL. Sub paths (a product page of the store too) are allowed; only the store id is used.
- `limit`: How many top products (popularity order) to collect, capped at 1000. The UI offers 50, 100, 200 and 500. More products mean more keywords for start_store_check and therefore more credits.
- `watch`: Also register the store for periodic re-collection and re-analysis (see add_watch); later runs spend credits automatically.
- `intervalDays`: Re-collection interval in days when watch is true (other values become 7).
- `append`: Keep the current products and add these (mixes stores). The UI never sends it; false replaces the product set.

### preview_dormant_products
Counts which current products would be excluded as dormant (no reviews or sales and in the bottom popularity share, or old) before an analysis, without changing anything. Returns {preview{totalEvaluated, totalActiveWithSales, totalNoSignalField, matchedRank, matchedAge, matchedUnion, ageApplicable, examples[]}, storeSize}. Read only, free. Usually followed by: exclude_dormant_products.
`POST /portfolio/api/products/dormant`
- `rankBottomPercent`: Rank rule: products in the bottom share of the store's popularity order (0-1, 0.3 = bottom 30%) count as dormant. Omitted or null means the default 0.3; the rule cannot be switched off through the API.
- `minAgeDays`: Age rule: products older than this many days count as dormant. Age is real only for CSV uploads with created_at or stores watched for a long time; for a fresh URL collection it is the first collection time. Omitted or null means the default 365.
- `reviewMax`: Only products whose review count (or sales count) is at most this value are candidates. The UI always sends 0.

### exclude_dormant_products
Marks the products that match the dormant rules as excluded from analysis, so start_store_check skips them and spends fewer credits. Returns {ok, excluded}. Undo with restore_dormant_products. Changes saved data in the app; no credits. Usually followed by: start_store_check.
`POST /portfolio/api/products/dormant`
- `rankBottomPercent`: Rank rule: products in the bottom share of the store's popularity order (0-1, 0.3 = bottom 30%) count as dormant. Omitted or null means the default 0.3; the rule cannot be switched off through the API.
- `minAgeDays`: Age rule: products older than this many days count as dormant. Age is real only for CSV uploads with created_at or stores watched for a long time; for a fresh URL collection it is the first collection time. Omitted or null means the default 365.
- `reviewMax`: Only products whose review count (or sales count) is at most this value are candidates. The UI always sends 0.

### restore_dormant_products
Clears the dormant exclusion on every current product. Returns {ok, restored}. Changes saved data in the app; no credits.
`POST /portfolio/api/products/dormant`

### clear_store_products
Deletes the current product set (with its sales and margin data) so a new store can be loaded. Past store check results and review snapshots are kept. Returns {ok, deleted, note}. Deletes data. A person approves it first.
`DELETE /portfolio/api/uploads/products`

### download_sample_csv
Downloads a sample CSV that shows the columns of the product, sales or margin upload used on /portfolio/upload. Uploading CSV files is done in the web page (multipart upload), not through this tool set. Read only, free.
`GET /portfolio/api/samples/{kind}`
- `kind` (required): Which sample: products (product_id, product_name, sale_price required), sales (product_id, revenue, orders or units_sold) or margins (product_id plus cost columns).

### start_store_check
Starts a store check on the current product set (from collect_store_products or CSV uploads), skipping dormant-excluded products. In the background it picks a representative search keyword per product (rules, plus an LLM when the server has a MiniMax key), reads keyword_info and intent_finder for each new keyword, scores search demand, margin (with margin CSV) or sales power (reviews, sales count), momentum (review growth since the last collection) and risk, classifies every product and recommends actions. Returns {ok, runId} (or {ok, runId, resumed: true} when a run is already in progress); 400 when there are no products or all are excluded. Poll get_store_check. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: per 100 products with new keywords about 1,000 Data API credits for keyword_info plus 100 intent_finder calls (limit 100 each; the app does not report their credit price); keywords fetched in the last 7 days are free; plus 1 MiniMax LLM call per 30 products; no credits when the server runs in mock mode. Time: usually a few minutes for 100 products; depends on product count and cache. Usually followed by: get_store_check.
`POST /portfolio/api/analysis/portfolio/start`

### get_store_check
Returns one store check: run {id, label (store name), status (pending, running, completed, failed), totalCount, doneCount, excludedCount, errorMessage, startedAt, completedAt}, summary (dominantMode margin/proxy/demand, counts per classification and per recommended action, withMargin, withReview, withMomentum, pending) and items[] per product ordered by priority (scoreId, productName, category, salePrice, revenue, reviewCount, representativeKeyword, demandQualityScore, marginScore, popularityScore, momentumScore, portfolioScore, riskScore, classification, analysisMode, recommendedAction[], reason, dataBasis[], priority). Repeat until run.status is completed or failed; progress is doneCount/totalCount. Read only, free. Waits up to about 45 s for 'run.status' to reach completed, failed; call again if not done. Usually followed by: get_store_check_product, download_store_check_csv, start_title_analysis, start_detail_page_analysis.
`GET /portfolio/api/analysis/{run_id}/portfolio`
- `run_id` (required): Store check run id returned by start_store_check or list_store_checks (shown in the page URL /portfolio/analysis/{run_id}/portfolio).

### get_store_check_product
Returns one product of a store check: product (name, category, brand, productUrl, salePrice, cost fields, reviewCount, reviewScore, collectionRank, dataSource), sales totals, score (keywords, all scores and statuses with breakdowns, classification, recommendedAction, reason, priority, dataBasis) and signal for the representative keyword (volume, Naver volume, trend, competition, CPC, intents, AI Overview, 12 monthly volumes, SERP features). preserved is true when the product was removed since and only the snapshot remains. Read only, free. Usually followed by: rescore_store_check_product, start_title_analysis, start_detail_page_analysis.
`GET /portfolio/api/analysis/{run_id}/portfolio/{score_id}`
- `run_id` (required): Store check run id returned by start_store_check or list_store_checks (shown in the page URL /portfolio/analysis/{run_id}/portfolio).
- `score_id` (required): Product result id: items[].scoreId from get_store_check (the last segment of /portfolio/analysis/{run_id}/portfolio/{score_id}). items[].productDbId is also accepted for older links.

### rescore_store_check_product
Replaces the representative keyword of one product in a store check (use when the automatic keyword is wrong or had no search data), fetches its search data and rescores the product, then recomputes priorities in the run. Overwrites the stored product result. Returns {ok}; read get_store_check_product after. Fails with 409 for products removed since the run. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: about 10 Data API credits for keyword_info plus one intent_finder call (limit 100) when the keyword was not fetched in the last 7 days; free when cached. Time: a few seconds. Usually followed by: get_store_check_product.
`PATCH /portfolio/api/analysis/{run_id}/portfolio/{score_id}`
- `run_id` (required): Store check run id returned by start_store_check or list_store_checks (shown in the page URL /portfolio/analysis/{run_id}/portfolio).
- `score_id` (required): Product result id: items[].scoreId from get_store_check (the last segment of /portfolio/analysis/{run_id}/portfolio/{score_id}). items[].productDbId is also accepted for older links.
- `keyword` (required): Search keyword that best names the product, e.g. '이유식 큐브틀'.

### download_store_check_csv
Downloads the store check as CSV (UTF-8 with BOM): priority, product_id, product_name, representative_keyword, analysis_mode, scores and statuses, review and momentum figures, classification and label, recommended_actions, data_basis, reason, revenue. Read only, free.
`GET /portfolio/api/analysis/{run_id}/portfolio/export`
- `run_id` (required): Store check run id returned by start_store_check or list_store_checks (shown in the page URL /portfolio/analysis/{run_id}/portfolio).

### list_store_checks
Lists up to 100 store check runs, newest first: {runs[{id, label, status, totalCount, analyzed, startedAt, completedAt, dominantMode, topClass, withMomentum, classCount}]}. Read only, free. Usually followed by: get_store_check.
`GET /portfolio/api/analysis/runs`

### list_watches
Lists stores registered for periodic re-collection: {watches[{id, url, label, intervalDays, productLimit, active, nextRunAt, lastRunAt, lastRunId, lastStatus, lastError, runCount}]}. lastRunId opens the latest store check. Read only, free. Usually followed by: get_store_check.
`GET /portfolio/api/watch`

### add_watch
Registers (or updates and re-activates) a store for periodic tracking. A server timer runs daily at 09:05 and, for every due store, replaces the product set with a fresh collection and runs a full store check, so momentum (review growth) appears from the second run. A new watch is due immediately. Returns {ok, watch}. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: free at call time; every scheduled run then costs the same as start_store_check. Usually followed by: list_watches.
`POST /portfolio/api/watch`
- `url` (required): Store URL in one of the formats collect_store_products accepts.
- `intervalDays`: Days between runs (other values become 7).
- `limit`: Products to collect per run (capped at 500).
- `label`: Optional display name; replaced by the store name after the first run.

### set_watch_active
Pauses (active false) or resumes (active true) a store watch. Resuming lets the daily timer spend credits again. Returns {ok, watch}. Changes saved data in the app; no credits.
`PATCH /portfolio/api/watch/{watch_id}`
- `watch_id` (required): Watch id from list_watches (watches[].id).
- `active` (required): true to resume, false to pause.

### delete_watch
Removes a store watch. Past store checks stay. Returns {ok}. Deletes data. A person approves it first.
`DELETE /portfolio/api/watch/{watch_id}`
- `watch_id` (required): Watch id from list_watches (watches[].id).

### lookup_keyword_info
Calls ListeningMind keyword_info (Korea) through the store check module for up to 50 keywords: volume, Naver volume, competition, CPC (KRW), intents, 12 monthly volumes, SERP features and AI Overview presence. Returns {ok, mode (real or mock), data[]}. mode mock means synthetic numbers. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: up to 500 Data API credits (about 10 per keyword, at most 50 keywords); free in mock mode. Time: a few seconds.
`POST /portfolio/api/listeningmind/keyword-info`
- `keywords` (required): Keywords to look up; only the first 50 are used.

### lookup_intent_keywords
Calls ListeningMind intent_finder keyword_list (Korea, volume 100 or more, sorted by volume) through the store check module: search queries that contain the keyword. Returns {ok, mode (real or mock), data[] of keyword strings}. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: one intent_finder call (the app does not report its credit price); free in mock mode. Time: a few seconds.
`POST /portfolio/api/listeningmind/intent-finder`
- `keyword` (required): Seed keyword.
- `limit`: Maximum keywords returned (capped at 300).

### start_title_analysis
Starts a background title analysis for one Smart Store product name: splits it into brand, category, attribute, spec and noise words with keyword_info (an LLM only for unclear words), builds or reuses the category's identity candidates (search modifiers that really have volume, from intent_finder, cluster_finder, path_finder, keyword_info and maistro-lmpipe), ranks them, scores the current title (TIS 0-100) and composes A/B titles, front 3 word sets, category fit, noise words and tag / option plans. Returns {analysis_id, status: queued}. Poll get_title_analysis. 429 when 12 jobs are already queued or running. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: about 11,000 Data API credits or more when the category is new (identity set not built in the last 30 days): path_finder limit 300 (about 8,450 at the Funnel Leak Finder rate), keyword_info for up to about 190 keywords (about 10 each), intent_finder limit 300 and cluster_finder hop 2 (prices not reported by the app), plus a maistro-lmpipe analysis; a cached category needs only keyword_info for the title words, word combinations and tags (a few hundred credits); 1-4 LLM calls (MiniMax for unclear words, Claude to screen brand words in a new category and to compose the A and B titles). Time: usually under 3 minutes; a new category adds about 30-90 seconds. Usually followed by: get_title_analysis.
`POST /api/v1/titles/analyses`
- `title` (required): Current product name (1-200 characters). Required.
- `category_path`: Registered category path, e.g. ['패션잡화', '운동화', '러닝화'] (up to 8). Used to pick the main category word, to detect ambiguous seeds and for the category fit diagnosis.
- `product_hint`: Short note on what the product really is (material, target, use). Without it every identity gets match 0.5; with it the B title is the identity that matches the product best.
- `tags`: Current seller tags (up to 30). Each is checked for search volume and promo words; tags that contain the seed are also tried as seed candidates.
- `seed_override`: Category word to analyze, forced (skips automatic seed choice and seed refinement). The UI sends it when a person typed the seed.
- `seed_hint`: Suggested category word (the UI fills it from the category path); used only as a fallback and as a refinement candidate, not forced.
- `gl`: Search market sent to the Data API. The UI never sends it (server default kr); the app's word rules are Korean and built for Naver, so keep kr.

### get_title_analysis
Returns one title analysis: analysis_id, raw_title, seed_keyword, gl, status (queued, running, done, error), error_code (SEED_AMBIGUOUS, NO_VALID_IDENTITY, INTERNAL), error_detail, tis, grade (S/A/B/C/D), selected_identity_id, created_at, finished_at, tokens[] and, when done, report {title_score, identity_diagnosis{candidates[], selected_identity_id, seed_refined, seed_warning}, front3_recommendations, category_diagnosis, noise_keywords, title_variants[] (A/B with predicted_tis and policy findings), tag_option_plan, policy_report, data_meta}. Repeat until status is done or error. Read only, free. Waits up to about 45 s for 'status' to reach done, error; call again if not done. Usually followed by: select_title_identity, start_detail_page_analysis.
`GET /api/v1/titles/analyses/{analysis_id}`
- `analysis_id` (required): Title analysis id (12 hex characters) returned by start_title_analysis, select_title_identity or list_title_analyses.

### select_title_identity
Re-runs the title analysis of the same product name and seed with a chosen identity candidate (report.identity_diagnosis.candidates[].identity_id), so the A title is built around it. Creates a NEW analysis and returns {analysis_id, status: queued, parent_analysis_id, identity_id}. Poll get_title_analysis with the new id. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: about 200 Data API credits or less (keyword_info for the title words; the category identity set is cached) plus 1-3 LLM calls. Time: usually under a minute. Usually followed by: get_title_analysis.
`POST /api/v1/titles/analyses/{analysis_id}/select-identity`
- `analysis_id` (required): Title analysis id (12 hex characters) returned by start_title_analysis, select_title_identity or list_title_analyses.
- `identity_id` (required): identity_id of one candidate in the earlier report. Unknown ids are rejected with the list of valid ones.
- `product_hint`: Optional product note, as in start_title_analysis.

### list_title_analyses
Lists the 30 newest title analyses: {analyses[{analysis_id, raw_title, seed_keyword, status, error_code, tis, grade, created_at, finished_at}]}. Read only, free. Usually followed by: get_title_analysis.
`GET /api/v1/titles/analyses`

### delete_title_analysis
Deletes one stored title analysis. Cannot be undone. Returns {ok, deleted}. Deletes data. A person approves it first.
`DELETE /api/v1/titles/analyses/{analysis_id}`
- `analysis_id` (required): Title analysis id (12 hex characters) returned by start_title_analysis, select_title_identity or list_title_analyses.

### start_detail_page_analysis
Starts a background check of how well one product page covers the buying criteria searchers use. It reads the page (Smart Store URL, then a reader fallback; usually blocked, so pass tier3 data), OCRs detail images, picks a seed keyword (LLM candidates checked with keyword_info, raised to a broader category under 1,000 monthly searches), builds or reuses the category's intent items on 6 axes (price, performance, use, comparison, risk, trust), judges each item covered / partial / missing with evidence (two LLM passes plus a tie-break), scores ICS and CPS and writes recommendations. Returns {analysis_id, status: queued}. Poll get_detail_page_analysis. 429 when 12 jobs are queued or running. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: about 10,000 Data API credits or more when the category is new (intent items not built in the last 30 days): path_finder limit 300 (about 8,450 at the Funnel Leak Finder rate), keyword_info for up to 150 keywords (about 10 each), intent_finder limit 300 and cluster_finder (prices not reported by the app), plus a maistro-lmpipe analysis; a cached category needs only keyword_info for up to 8 seed candidates; LLM calls: 1 per detail image (OCR), 1 to 2 for the seed, 1 to classify a new category, 2 per 10 intent items plus tie-breaks (20 to 40 items) and 1 for recommendations. Time: a few minutes; a new category adds about 60-120 seconds. Usually followed by: get_detail_page_analysis.
`POST /api/v1/analyses`
- `product_url`: Product page URL on smartstore.naver.com, brand.naver.com or shopping.naver.com (m. hosts allowed). Other hosts are rejected. Either this or tier3 data is required.
- `tier3`: Product data typed or captured by the seller, used when the server cannot read the page (Smart Store usually blocks server fetches). Any of these fields; all optional.
- `seed_override`: Category keyword to analyze, forced (skips the LLM seed choice). Changes which intent items the page is judged against.
- `gl`: Search market sent to the Data API. The UI always sends kr; the app is built for Naver Smart Store, so keep kr.

### set_detail_page_seed
Replaces the seed keyword the running analysis just proposed. Only works during the 5-second window after the seed is proposed (the web page shows it as a live prompt); later calls have no effect on the result. For agents, seed_override in start_detail_page_analysis is the reliable way. Returns {ok, seed}; 404 when the analysis is no longer running. Changes saved data in the app; no credits.
`POST /api/v1/analyses/{analysis_id}/seed`
- `analysis_id` (required): Detail page analysis id (12 hex characters) returned by start_detail_page_analysis, rescore_detail_page or list_detail_page_analyses.
- `seed` (required): Seed keyword to use instead.

### get_detail_page_analysis
Returns one detail page analysis: analysis_id, product_url, product_title, seed_keyword, status (queued, running, done, error), error_code (EXTRACT_BLOCKED, LOW_DATA, SEED_AMBIGUOUS, INTERNAL), error_detail, ics, cps, grade (S/A/B/C/D), parent_analysis_id, created_at, finished_at and, when done, report {scores{ics, cps, grade, axis_scores, cps_parts}, axes[], items[] (intent item, keywords, volume, verdict, evidence), cards{covered, missed}, recommendations{restructure, title_suggestions, faq, review_prompts, comparison_frame}, seed, data_quality, report_meta, diff (after a re-check)}. Repeat until status is done or error. Read only, free. Waits up to about 45 s for 'status' to reach done, error; call again if not done. Usually followed by: rescore_detail_page, get_category_universe.
`GET /api/v1/analyses/{analysis_id}`
- `analysis_id` (required): Detail page analysis id (12 hex characters) returned by start_detail_page_analysis, rescore_detail_page or list_detail_page_analyses.

### rescore_detail_page
Re-checks a product after its detail page was edited: reuses the earlier page data and seed, replaces it with any new tier3 data (for example the new detail text), and adds diff (score change and verdict changes) to the report. Creates a NEW analysis and returns {analysis_id, status: queued, parent_analysis_id}. Poll get_detail_page_analysis. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: about 10 Data API credits (keyword_info for the seed) when the category is still cached, else same as start_detail_page_analysis; LLM calls as in start_detail_page_analysis without the seed step. Time: a few minutes. Usually followed by: get_detail_page_analysis.
`POST /api/v1/analyses/{analysis_id}/rescore`
- `analysis_id` (required): Detail page analysis id (12 hex characters) returned by start_detail_page_analysis, rescore_detail_page or list_detail_page_analyses.
- `tier3`: New page data. Without detail_text or images, the earlier detail text is reused; title, category, options, price, reviews and Q&A carry over unless given.

### get_category_universe
Returns the cached intent items of a category seed (built by an earlier detail page check, kept 30 days): items on the 6 axes with keywords and volumes, data quality and cache info. 404 when no cached library exists for that seed. Read only, free.
`GET /api/v1/categories/{seed}/universe`
- `seed` (required): Seed keyword exactly as used by an analysis (seed_keyword).
- `gl`: Market of the cached library (kr).

### list_detail_page_analyses
Lists the 30 newest detail page analyses: {analyses[{analysis_id, product_url, product_title, seed_keyword, status, error_code, ics, cps, grade, created_at, finished_at, parent_analysis_id}]}. Read only, free. Usually followed by: get_detail_page_analysis.
`GET /api/v1/analyses`

### delete_detail_page_analysis
Deletes one stored detail page analysis. Cannot be undone. Returns {ok, deleted}. Deletes data. A person approves it first.
`DELETE /api/v1/analyses/{analysis_id}`
- `analysis_id` (required): Detail page analysis id (12 hex characters) returned by start_detail_page_analysis, rescore_detail_page or list_detail_page_analyses.

### get_i18n_strings
Returns UI strings for a language (called on language switch; no cost, no ledger entry). Read only, free.
`POST /api/v1/i18n`
- `lang`: 
- `keys`: 

### list_recent_discoveries
Seeds recently explored in keyword discovery, with counts. Signed-in members only. Read only, free.
`GET /api/v1/discover/recent`