# ACO: agent guide

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.

## Connect
- MCP: `https://daas-aco.listeningmind.ai/mcp` (Streamable HTTP). Start with `app_guide`.
- Browser agents: tools are registered on every page through WebMCP (`document.modelContext`).
- REST: `https://daas-aco.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. `list_jobs` (read): Check whether the page was already diagnosed.
2. `diagnose_pdp` (run): Start the diagnosis with a URL or HTML and get a job_id.
3. `get_job` (read): Poll until status is done, then read the result.
4. `translate_result` (run): Optionally translate the analysis into another language.
5. `build_ontology` (run): If no ontology was found, build one for the keyword (spends credits).
6. `get_ontology_job` (read): Poll the build until it finishes.
7. `reanalyze_job` (run): Reanalyze with the ontology or image OCR.
8. `get_job` (read): Read the reanalysis result.
9. `download_feed_csv` (read): Download the PIM feed CSV.
10. `record_outcome` (action): Record that the fixes were applied.
11. `list_stores` (read): See the per-domain rollup and feed URLs.
12. `get_product_feed` (read): Fetch the store product feed.
13. `start_batch_scan` (run): Use the batch scan to choose which pages to fix first.
14. `scan_agent_readiness` (run): Use the domain scan for site-wide agent readiness.
15. `delete_job` (delete): Delete a diagnosis that is no longer needed.

## 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 and time
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.

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

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

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

## Run stages
- `시작`: Starting
- `캐시 적중`: Cache hit
- `페이지 파싱·점검`: Parsing and checking the page
- `이미지 비전 분석(OCR)`: Image vision analysis (OCR)
- `에이전트 실행 가능성 점검`: Checking agent operability
- `Agent Readiness 25항목 채점`: Scoring 25 Agent Readiness items
- `검색 인텔리전스 수집`: Collecting search intelligence
- `온톨로지 확인`: Checking ontology (an automatic build shows its percent)
- `참조 상품군 탐색(다축)`: Finding reference products
- `의사결정 인텐트 분해`: Breaking down decision intents
- `소비자 프롬프트 합성`: Synthesizing consumer prompts
- `스펙 조건 번역·답변 가능성 검증`: Translating spec conditions and checking answerability
- `데이터 귀속 리프트 측정`: Measuring data attribution lift
- `GSC 인텔리전스`: GSC intelligence
- `개선안·수정 산출물 생성`: Generating fixes and deliverables
- `인용 시뮬레이션 (현재 vs 개선, 심층)`: Citation simulation (current vs improved)
- `인용 차단 요인 기반 개선안 재계획`: Replanning fixes from citation blockers
- `전문가 해설 생성`: Writing expert commentary
- `고정 문구 현지화`: Localizing fixed text
- `사이트맵 수집`: Reading sitemap (batch)
- `스캔 {i}/{n}`: Scanning page i of n (batch)
- `완료`: Done

## All tools
### check_page
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. Read only, free. Usually followed by: diagnose_pdp.
`POST /api/precheck`
- `url`: Product page URL (http or https).
- `html`: Rendered HTML of the page, instead of fetching url.

### diagnose_pdp
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. 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: Data API credits (keyword_info, cluster_finder, intent_finder, path_finder) plus several LLM calls. Cost follows the main keyword's search volume (the cluster and path lookups grow with it): about 10,500 credits (137 Lima) when the keyword has little or no search data, up to about 23,000 credits (299 Lima) at 3,000+ searches a month. The free precheck (/api/precheck) works out the main keyword, checks its volume (1 credit, cached 7 days) or reuses the measured use of the last run of the same product, and the start response carries that estimate_credits (the same value the confirm dialog shows); without a precheck the start assumes the high end. 0 when this member's own recent result is reused, the original cost for someone else's; 0 for pages that are not product pages (the run stops). Charged by actual use (credits.spent), with no cap; the estimate is multiplied by the hub's calibration factor from recent actual charges (estimate_calib in the start answer).. Usually followed by: get_job.
`POST /api/diagnose`
- `url`: Public product page URL (http or https). Required unless html is given. With html, it is only used to resolve images and links and to name the project.
- `html`: Rendered HTML of the product page (paste-HTML tab or bookmarklet), for pages the server cannot fetch. When given, it is analysed instead of a fresh fetch. Required unless url is given.
- `locale`: Market for all search data (demand, intents, CEPs, reference products, consumer prompts): kr, us or jp. Default kr. Changes keyword volumes, prompts and the citation simulation.
- `lang`: Language of the generated analysis, diagnosis and commentary text: ko, en or ja. Default ko. Publishable copy follows content_lang instead.
- `content_lang`: Language of publishable copy (rewritten copy, FAQ, JSON-LD text). ko, ja or en; any other value or omitted = detected from the page and market. Changes the fixes text, not the scores.
- `vision`: Read text inside product images with OCR/vision (ingredients, specs, nutrition locked in images). Adds facts that can change readiness, fixes and citation results; adds LLM cost. Default false. The UI shows this only on the URL tab.
- `gsc_rows`: Optional Google Search Console query rows (objects with query, clicks, impressions, ctr, position) added as real query evidence (GSC intelligence stage). Not exposed in the web UI.
- `allow_non_pdp`: Diagnose a page that looks like a home, listing or non-product page anyway (charged as a normal run). Error pages are never diagnosed. Default false.

### start_batch_scan
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. 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 Data API keyword_info call per page; no LLM. Usually followed by: get_job.
`POST /api/batch`
- `sitemap_url`: Sitemap URL. Product-like <loc> URLs are picked from it. Used only when urls is empty.
- `urls`: List of product page URLs.
- `locale`: Market for the per-page keyword_info demand used to rank pages: kr, us or jp. Default kr.
- `lang`: UI language (ko, en, ja). Accepted but not used by the batch scan.
- `limit`: Maximum pages to scan, 1-50 (values outside are clamped). Default 20; the web UI always sends 20.

### scan_agent_readiness
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. 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, no LLM); sends HTTP requests to the target site.
`POST /api/agent_scan`
- `url` (required): Domain or URL of the store, e.g. www.example.com. https:// is added if missing.

### get_job
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. Read only, free. Waits up to about 45 s for 'status' to reach done, error; call again if not done. Usually followed by: translate_result, build_ontology, record_outcome, download_feed_csv.
`GET /api/job/{jid}`
- `jid` (required): Job id returned by diagnose_pdp, start_batch_scan or reanalyze_job (12 hex characters, e.g. 671bc1e9d902).

### resolve_project
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. Read only, free. Usually followed by: get_job.
`GET /api/resolve`
- `project` (required): Project slug from the permalink, e.g. coupang-com-vp-products-9274162564.
- `seq`: Run number (e.g. 1 or 01) or latest. Omit for the latest run.

### translate_result
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. 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: LLM calls only (no Data API credits).
`POST /api/job/{jid}/translate`
- `jid` (required): Job id returned by diagnose_pdp, start_batch_scan or reanalyze_job (12 hex characters, e.g. 671bc1e9d902).
- `lang`: Target language.

### get_diag_translation
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. Read only, free.
`POST /api/job/{jid}/diag_i18n`
- `jid` (required): Job id (12 hex characters).
- `lang` (required): Screen language.

### 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. 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 40,000 Data API finder credits for a new topic; free when an ontology already exists. Time: about 2 minutes. Usually followed by: get_ontology_job, reanalyze_job.
`POST /api/job/{jid}/build_ontology`
- `jid` (required): Job id returned by diagnose_pdp, start_batch_scan or reanalyze_job (12 hex characters, e.g. 671bc1e9d902).

### get_ontology_job
Reads an ontology build started by build_ontology: {status, pct, msg, error}. 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: reanalyze_job.
`GET /api/ontology_job/{oid}`
- `oid` (required): ontology_job id returned by build_ontology.

### reanalyze_job
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. 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: same as diagnose_pdp (Data API credits and LLM calls). Usually followed by: get_job.
`POST /api/job/{jid}/reanalyze`
- `jid` (required): Job id returned by diagnose_pdp, start_batch_scan or reanalyze_job (12 hex characters, e.g. 671bc1e9d902).
- `vision`: Add image OCR/vision extraction. Default false.

### record_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}. Changes saved data in the app; no credits.
`POST /api/job/{jid}/outcome`
- `jid` (required): Job id returned by diagnose_pdp, start_batch_scan or reanalyze_job (12 hex characters, e.g. 671bc1e9d902).
- `applied`: True when the fixes were applied to the page.
- `note`: Optional free-text note.
- `metrics`: Optional observed metrics, GSC/GA shaped: clicks, impressions, ctr, position, conversions.

### get_source_snapshot
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. Read only, free.
`GET /api/job/{jid}/source.html`
- `jid` (required): Job id returned by diagnose_pdp, start_batch_scan or reanalyze_job (12 hex characters, e.g. 671bc1e9d902).

### download_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. Read only, free.
`GET /api/job/{jid}/feed.csv`
- `jid` (required): Job id returned by diagnose_pdp, start_batch_scan or reanalyze_job (12 hex characters, e.g. 671bc1e9d902).

### list_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. Read only, free. Usually followed by: get_job.
`GET /api/jobs`

### list_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. Read only, free. Usually followed by: get_product_feed.
`GET /api/stores`

### get_product_feed
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. Read only, free.
`GET /feed/{store_id}/products.json`
- `store_id` (required): Store domain, e.g. www.oliveyoung.co.kr.
- `token` (required): Feed token: the token query value in feed_url from list_stores.

### delete_job
Deletes a stored diagnosis and its files. Returns {ok, deleted}. Needs the app token header when the server has one set (see auth). Deletes data. A person approves it first.
`DELETE /api/job/{jid}`
- `jid` (required): Job id returned by diagnose_pdp, start_batch_scan or reanalyze_job (12 hex characters, e.g. 671bc1e9d902).

### get_report_robots
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. Read only, free.
`GET /_lm/report-robots/{run_id}`
- `run_id` (required): The report's run id: the id in the report address (for ACO the project id, or project~step).