# ACO (ListeningMind)

> ACO (Agentic Commerce Optimizer) scores one product detail page for SEO, AEO, GEO and agentic commerce and produces ready-to-paste fixes (JSON-LD, FAQ, rewritten copy, UCP templates, PIM feed). Search demand and intent come from the ListeningMind Data API, text generation and citation simulation from an LLM, and scores from a rule-based parser. E-commerce operators and consultants use it for the Korean, US and Japanese markets. It also offers a sitemap batch scan, a domain-level agent readiness scan and per-store product feeds.

Korean: 상품 상세페이지가 AI 답변과 쇼핑 에이전트에 인용·실행될 준비가 됐는지 진단합니다 · Japanese: 商品詳細ページがAI回答とショッピングエージェントに引用・実行される準備ができているか診断します

## Use it as an agent
- [MCP server](https://daas-aco.listeningmind.ai/mcp): Streamable HTTP, JSON-RPC. 19 app tools plus app_guide, result store tools (results_sync, results_list, results_get, results_compare, results_export) and settings sweeps (plan_batch, batch_status)
- WebMCP: every page of this app registers the same tools in `document.modelContext` for a browser agent; calls that spend credits ask the person on the page
- [OpenAPI](https://daas-aco.listeningmind.ai/.well-known/openapi.json): the same tools as a REST contract (operationId = tool name)
- [agents.md](https://daas-aco.listeningmind.ai/agents.md): step-by-step guide · [API catalog](https://daas-aco.listeningmind.ai/.well-known/api-catalog) · [MCP server card](https://daas-aco.listeningmind.ai/.well-known/mcp/server-card.json)
- Every page answers `Accept: text/markdown` with a markdown version
- Tools of kind run or delete spend credits or delete data: over MCP the call returns confirm_url for a person, then call confirmation_status
- Accounts: reading results and history is open. Starting a run or changing data needs a ListeningMind member: the person approving confirm_url signs in or [signs up](https://daas-aco.listeningmind.ai/_lm/auth/signup); other changes over MCP need the member's agent key (LM-User-Key header, created at https://daas-aco.listeningmind.ai/_lm/account)

## What you give and what you get
- Inputs: A product page URL or pasted HTML, market (kr/us/jp), output language (ko/en/ja), optional image OCR and GSC query rows. Batch scan: a sitemap URL or a URL list (up to 50). Domain scan: one domain.
- Outputs: Overall score and grade, per-axis scores, 25 Agent Readiness items, search intelligence (demand, intent, CEPs), consumer prompts with citation simulation (current vs improved), fixes (Product/FAQ JSON-LD, UCP checklist and template, rewritten copy), expert commentary, a PIM feed CSV and a project permalink (/p/{project}/{seq}).
- Cost: One PDP diagnosis uses Data API credits (keyword_info, cluster_finder, intent_finder, path_finder) and several LLM calls and usually takes a few minutes. The exact credit count is not in the code (unknown). For a new keyword an automatic ontology build (about 40,000 credits, about 2 minutes) may run as well. A batch scan uses one keyword_info call per page; the domain scan and history reads use no credits.

## How a result is made (in order)
1. `list_jobs`: Check whether the page was already diagnosed.
2. `diagnose_pdp`: Start the diagnosis with a URL or HTML and get a job_id.
3. `get_job`: Poll until status is done, then read the result.
4. `translate_result`: Optionally translate the analysis into another language.
5. `build_ontology`: If no ontology was found, build one for the keyword (spends credits).
6. `get_ontology_job`: Poll the build until it finishes.
7. `reanalyze_job`: Reanalyze with the ontology or image OCR.
8. `get_job`: Read the reanalysis result.
9. `download_feed_csv`: Download the PIM feed CSV.
10. `record_outcome`: Record that the fixes were applied.
11. `list_stores`: See the per-domain rollup and feed URLs.
12. `get_product_feed`: Fetch the store product feed.
13. `start_batch_scan`: Use the batch scan to choose which pages to fix first.
14. `scan_agent_readiness`: Use the domain scan for site-wide agent readiness.
15. `delete_job`: Delete a diagnosis that is no longer needed.

Run stages reported by the app: 시작 → 캐시 적중 → 페이지 파싱·점검 → 이미지 비전 분석(OCR) → 에이전트 실행 가능성 점검 → Agent Readiness 25항목 채점 → 검색 인텔리전스 수집 → 온톨로지 확인 → 참조 상품군 탐색(다축) → 의사결정 인텐트 분해 → 소비자 프롬프트 합성 → 스펙 조건 번역·답변 가능성 검증 → 데이터 귀속 리프트 측정 → GSC 인텔리전스 → 개선안·수정 산출물 생성 → 인용 시뮬레이션 (현재 vs 개선, 심층) → 인용 차단 요인 기반 개선안 재계획 → 전문가 해설 생성 → 고정 문구 현지화 → 사이트맵 수집 → 스캔 {i}/{n} → 완료

## Method (how the analysis works)
1. Fetch the product page from its URL, or take pasted HTML, then parse and check it (optional image OCR).
2. Check agent operability and score the 25 Agent Readiness items; scores come from a rule-based parser.
3. Collect search intelligence (demand, intents, CEPs) from the ListeningMind Data API and check the keyword's ontology (it may be built automatically).
4. Break down decision intents, synthesize consumer prompts and check whether the spec conditions can answer them.
5. Generate fixes (Product/FAQ JSON-LD, UCP template, rewritten copy, PIM feed) and simulate citation for the current and the improved page.
6. Replan the fixes from citation blockers and write expert commentary.

## Reading the result
- overall and grade summarise the page; scores.seo, scores.aeo, scores.geo, scores.agentic and scores.ago are the per-axis scores.
- readiness.total is the total over the 25 Agent Readiness items.
- citation.before.cited and citation.after.cited (with citation.after.avg_likelihood) compare whether the consumer prompts cite the current page and the improved page.
- fixes holds ready-to-paste product_jsonld, faq_jsonld and UCP templates; pim_csv is the PIM feed.
- In a batch scan, rows are ranked by priority from search demand and score, so fix from the top.

## Requests this app answers well
- Diagnose whether this product detail page is ready for AI shopping agents and give me the JSON-LD to paste
- From our store's sitemap, pick the product pages to fix first
- Show how AI answer citations change for this PDP after the fixes, for the US market
- Download the PIM feed of this diagnosis as CSV

## Continue in another app
- [AOO](https://daas-aoo.listeningmind.ai/llms.txt) (MCP `https://daas-aoo.listeningmind.ai/mcp`): When you need to know whether a real AI agent can finish tasks such as finding the price, contacting or checking the refund policy across the domain. Carry: The store's domain.
- [Smart Store Suite](https://daas-store.listeningmind.ai/llms.txt) (MCP `https://daas-store.listeningmind.ai/mcp`): When the product is sold on Naver Smart Store and you want the title rewrite and the detail page intent check. Carry: The Smart Store product URL and the product title.

## 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

## Tools
- `check_page` (read, POST /api/precheck): Free check before diagnose_pdp: fetches the URL (or reads the pasted html) and says whether it is a product detail page. Returns {kind: pdp|home|list|other|error|blocked|unknown, stop, override, signals[{code,ko,en,ja}], msg{ko,en,ja}, pdp_score, status}. stop true means diagnose_pdp would stop without charge; override true means allow_non_pdp may be set. Uses no Data API or LLM.
- `diagnose_pdp` (run, POST /api/diagnose): Starts a full diagnosis of one product detail page (PDP) for SEO, AEO, GEO and agentic commerce. Give a public url, or paste the rendered html (for pages that block bots or render with JS; url then only resolves images and links). Returns {job_id} at once; poll get_job until status is done. Uses ListeningMind Data API and several LLM calls; usually takes a few minutes. Identical settings (url or html, locale, lang, content_lang) within the cache period (6 hours by default) return the cached result instantly (stage 캐시 적중, result.cached true) unless vision or gsc_rows is set; use reanalyze_job for a forced fresh run. Before any paid step the page is checked: an error page (HTTP 4xx/5xx, error or blocked wording, empty page) ends with status error and error_code error_page; a home, listing or no-product page ends with error_code not_pdp and page_check (kind, signals). Neither is charged, scored or saved. Set allow_non_pdp true to diagnose a not_pdp page anyway (charged); error pages are never diagnosed. Use check_page first to see this for free.
- `start_batch_scan` (run, POST /api/batch): Quick rule-based scan of many product pages from a sitemap or a URL list, ranked by search demand and score (biggest opportunity first). Returns {job_id}; poll get_job until done, the result has rows[] with url, keyword, overall, grade, geo_audit, agentic, geo, demand, priority. Fetches every page and one keyword_info call per page.
- `scan_agent_readiness` (run, POST /api/agent_scan): Scans a whole domain (not one PDP) for agent operability with HTTP probes: discovery 20, access 30, operation 40, payment 10 points. Synchronous: returns {ok, host, score, grade, label, layers, items, priority, unmeasured, catalog}. No Data API credits, no LLM.
- `get_job` (read, GET /api/job/{jid}): Reads one job: {id, status (running, done, error), stage, progress 0-100, partial (sections already finished), result, error}. Repeat until status is done or error. For a diagnosis the result holds scores, overall, grade, analysis, fixes (product_jsonld, faq_jsonld, ucp templates), prompts, citation, readiness, pim_csv, permalink and more.
- `resolve_project` (read, GET /api/resolve): Turns a project permalink (/p/{project}/{seq}) into a job id and lists every run of that project. Returns {ok, job_id, seq, project, product, runs[{seq, id, ts, overall, grade}]}; 404 with runs[] when the run is missing.
- `translate_result` (run, POST /api/job/{jid}/translate): Translates the analysis text of a finished diagnosis into ko, en or ja and caches it. Publishable copy and measured queries are not translated. Returns {lang, patch, failed} (or identity:true when already in that language). Uses LLM calls.
- `get_diag_translation` (read, POST /api/job/{jid}/diag_i18n): Returns the code-written diagnostic sections of one result (axis checks, AI Readability, LG GEO audit, food audit, gating, publish check) in English or Japanese: {lang, diag: {checks, ai_readability, geo_audit, food_audit, gating, publish_gate}}. Uses the app's translation memory first and caches the result per language. Published copy and measured search queries are never translated.
- `build_ontology` (run, POST /api/job/{jid}/build_ontology): Builds a topic ontology for the job's keyword so the next reanalysis can use it. Reuses an existing ontology when one matches ({already: true, run_id, topic}); otherwise returns {ontology_job, topic, joined}. Poll get_ontology_job, then call reanalyze_job.
- `get_ontology_job` (read, GET /api/ontology_job/{oid}): Reads an ontology build started by build_ontology: {status, pct, msg, error}. Repeat until status is done or error.
- `reanalyze_job` (run, POST /api/job/{jid}/reanalyze): Re-runs the full diagnosis for a job's page, bypassing the cache, using the stored page snapshot (or the original URL). Use after an ontology build, or with vision true to add image OCR. Returns a new {job_id}; poll get_job. The new run is stored as the next run of the same project. Market, output language and source are taken from the original job; only vision can change.
- `record_outcome` (action, POST /api/job/{jid}/outcome): Marks a diagnosis as applied on the live page and optionally stores observed metrics, for the store rollup and feedback loop. Returns {ok, outcome}.
- `get_source_snapshot` (read, GET /api/job/{jid}/source.html): Returns the captured product page HTML used for the diagnosis (scripts removed, base href set), as shown in the before/after preview. 404 when no snapshot was stored.
- `download_feed_csv` (read, GET /api/job/{jid}/feed.csv): Downloads the product attribute (PIM) feed generated for a finished diagnosis as CSV (pim_feed.csv). 404 {error: no_feed} when the result has none.
- `list_jobs` (read, GET /api/jobs): Lists stored diagnoses, newest first: {items[{id, ts, project, project_seq, permalink, product, keyword, url, overall, grade, before_cited, after_cited, total, before_avg, after_avg, applied}]}. Shared by all users of this server.
- `list_stores` (read, GET /api/stores): Groups the history by domain: {items[{domain, count, applied, avg_overall, avg_lift, feed_url}]}. feed_url is the tokenized product feed path for get_product_feed.
- `get_product_feed` (read, GET /feed/{store_id}/products.json): Returns the JSON product feed for one store domain (latest result per URL, up to 200): {store_id, generated, count, spec, products[{url, name, brand, keyword, updated, job_id, scores, overall, structured_data, conversational}]}. Needs the token from list_stores feed_url.
- `delete_job` (delete, DELETE /api/job/{jid}): Deletes a stored diagnosis and its files. Returns {ok, deleted}. Needs the app token header when the server has one set (see auth).
- `get_report_robots` (read, GET /_lm/report-robots/{run_id}): Returns whether search engines may index this report page (index or noindex), and why: a company member's run or one set by hand is index; a customer's run, and any run that is still going, failed or came back empty, is noindex. Read only; no credits.

## Pages
- [ACO diagnosis](https://daas-aco.listeningmind.ai/): Main screen with URL, paste HTML, batch and domain scan tabs, history and the store rollup.
- [Bookmarklet](https://daas-aco.listeningmind.ai/bookmarklet): Install page for a bookmarklet that sends the rendered HTML of the open product page to ACO.

## Limits
- Markets: kr, us and jp only. Diagnose, batch, reanalyze and ontology requests are rate limited per IP and may return 429 (rate_limited). Private or disallowed URLs are refused with blocked_url; send such pages as html. History is shared by all users of this server. On a project page (/p/{project}/{seq}) call resolve_project to get the job_id before other tools.
- Auth: none, except delete_job: when the server sets an app token, DELETE /api/job/{jid} needs header X-App-Token: <app token> (or Authorization: Bearer <app token>); the web UI supplies it.

## 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.
- [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`)
- [Smart Store Suite](https://daas-store.listeningmind.ai/llms.txt): Which Smart Store products to grow, and how to rewrite their titles and detail pages in searchers' words (MCP `https://daas-store.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)

## Optional
- ListeningMind data and other apps: https://www.listeningmind.com · contact m-support@listeningmind.com