# CEP Finder: agent guide

Give one keyword (category, product, service or brand) and it finds category entry points (CEPs) from real search paths, related searches, search volumes, SERPs and AI Overviews, then ranks them in a report. Marketers and brand managers use it to choose campaign situations and messages. Data comes from ListeningMind DaaS search behavior and Google results for Korea, Japan and the US.

## Connect
- MCP: `https://daas-cep.listeningmind.ai/mcp` (Streamable HTTP). Start with `app_guide`.
- Browser agents: tools are registered on every page through WebMCP (`document.modelContext`).
- REST: `https://daas-cep.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_runs` (read): Check for an existing analysis of the same keyword first (reuse costs 0 credits).
2. `resolve_sense` (run): Fix the keyword's meaning and review or edit seeds, trigger candidates and excludes.
3. `start_build` (run): Start the analysis after the person confirms (spends credits).
4. `get_job` (read): Read progress until status is done.
5. `get_report` (read): Open the finished report.
6. `get_cep_map` (read): Read the JSON data when numbers are needed.
7. `download_report_pdf` (read): Get a PDF for sharing.
8. `prepare_rerun` (read): To re-run with the same conditions, load them and pass them to start_build.
9. `delete_run` (delete): Remove runs that are no longer needed.

## Inputs
Keyword (required), field to pin the meaning (optional), market (kr/jp/us), focal brand (optional), competitors (optional), depth (quick/standard/deep), report language (ko/ja/en). Optionally an edited meaning result (category anchor, seeds, trigger candidates, excludes).

## Outputs
HTML report (CEP map, priorities and triage, brand links, time series and seasonality, evidence, readiness verdict), cep_map.json data, PDF (A4/Letter).

## Cost and time
Data API credits (median actual use of recent Korean runs, computed by the app): quick about 19.7K (18.6K-20K, 8 runs), standard about 48.6K (40.5K-63.8K, 8 runs), deep about 61.7K (35.8K-76.8K, 8 runs), plus LLM (Gemini) calls. The meaning preview uses one LLM call only. Run time is not stored, so it is unknown (minutes; deep is slowest).

## Limits
Markets: kr, jp, us only. Report commentary in ko, ja or en; search terms stay in the market language. Runs execute one at a time; with 3 running or queued, new builds get HTTP 429. Duplicate runs of the same keyword are not blocked, so check list_runs first. Canceling does not return spent credits. Jobs live in server memory and are lost on restart; finished runs stay on disk.

## Method (how the analysis works)
1. Fix the keyword's meaning first: category anchor, seeds, entry-situation candidates and exclude terms (a person can edit them).
2. Collect related searches for the keyword and seeds, then real search paths per entry situation.
3. Fetch search volumes in bulk and collect Google SERPs and AI Overviews.
4. Synthesize category entry points (CEPs) from this evidence.
5. Score each CEP for brand links, triage, time series and seasonality, and collect its evidence.
6. Assemble and validate cep_map and render the report with a readiness verdict.

## Reading the result
- Read readiness.verdict first: it tells how far the map can be trusted.
- ceps is the CEP list with metrics and evidence; use the priorities and triage to pick the situations to act on first.
- brands and the brand links section show which CEPs the focal brand and the competitors are tied to.
- Read the contested and open groups in positions.structure_groups (contested_ceps, open_ceps) together with the brand links.
- category_timeline.yoy and the time series and seasonality section show year-over-year change and seasonal flow; meta.credits_spent records the credits used.

## Requests this app answers well
- Tell me in which situations people start looking for sunscreen
- Build a ranked category entry point map for wireless earbuds in Japan
- Show which moisturizer entry situations our brand and our competitors are each tied to
- Which situations and messages should our US camping chair campaign use, with evidence

## Continue in another app
- [ICSS](https://daas-icss.listeningmind.ai/llms.txt) (MCP `https://daas-icss.listeningmind.ai/mcp`): When you want to test hypotheses about these situations with a synthetic consumer panel before real fieldwork. Carry: The same topic and market; ICSS find_cep_run and get_cep_states load this run as its intent-state distribution at 0 credits.
- [Prompt Builder](https://daas-prompt.listeningmind.ai/llms.txt) (MCP `https://daas-prompt.listeningmind.ai/mcp`): When you need the prompts consumers would ask AI in these situations and want to measure the brand's AI visibility. Carry: The keyword, its fixed meaning (as topic), the focal brand and competitors; use the top CEPs to check that the generated prompts cover those situations.

## 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`)
- [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
- `queued`: Queued
- `start`: Started
- `resolve`: S0 fix meaning
- `collect`: S1 collect related searches
- `triggers`: Collect search paths per situation
- `volumes`: Fetch search volumes
- `serp`: Collect SERPs and AI Overviews
- `synthesize`: S3 synthesize CEPs
- `metrics`: S4 metrics (brand links, triage)
- `evidence`: Collect CEP evidence
- `assemble`: Assemble and validate cep_map
- `done`: Done
- `error`: Error
- `canceled`: Canceled

## All tools
### resolve_sense
Fixes what the keyword means before a build and proposes the category anchor, seed keywords, entry-situation (trigger) candidates and exclude terms that a person can edit. Use it before start_build when the keyword may be ambiguous or when you want to edit seeds; pass the (edited) result as `sense` to start_build. One LLM call, no Data API credits, usually 15-40 seconds. 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 LLM call (Gemini), no Data API credits. Time: 15-40 seconds. Usually followed by: start_build.
`POST /api/resolve`
- `keyword` (required): Category, product, service or brand to analyze, e.g. '유산균' or 'electric toothbrush'.
- `topic`: Optional field or domain to pin the meaning when the word has several meanings.
- `gl`: Market whose search data is used: kr (Korea), jp (Japan), us (United States).

### get_estimate
Expected Data API credits and Lima for one run, for the signed-in member: {credits, low, high, lima, lima_low, lima_high, n, basis, depth, gl}. When the same member ran the same keyword, market and depth in the last 24 hours, it subtracts the expected reuse of that result (basis=cache, the plain figure under plain); otherwise it is the median of recent actual charges for the market and depth. The same figure the run's start response returns and the hub reserves. Signed-in members only. The public plain estimate is the app's own GET /api/estimate (open to everyone, not a hub tool). Read only, free.
`GET /api/estimate/mine`
- `depth`: quick | standard | deep (default standard)
- `gl`: market: kr | jp | us (default kr)
- `keyword`: the keyword to be analyzed; needed for the cache discount

### start_build
Starts a CEP Finder run that collects related searches, search paths, volumes and SERPs for the keyword, synthesizes category entry points (CEPs) and scores them into a report. Returns job_id and status (queued or running); poll get_job until done. Runs execute one at a time; if 3 jobs are already running or queued the server answers HTTP 429. Spends many Data API credits (see cost) and LLM calls; ask the person before calling. 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,450-63,785 (median about 48,624) Data API credits for standard (the default), about 18,550-20,002 (median about 19,663) for quick, about 35,821-76,776 (median about 61,740) for deep, plus LLM calls (medians of recent Korean runs, read from the app's /api/estimate). Time: several minutes; deep takes longest. Usually followed by: get_job.
`POST /api/build`
- `keyword` (required): Category, product, service or brand to analyze. Required, must not be empty.
- `topic`: Optional field or domain that pins the meaning of an ambiguous keyword.
- `gl`: Market whose search data is used: kr (Korea), jp (Japan), us (United States).
- `focal_brand`: Optional reference brand for strength, weakness and opportunity judgments. Empty means the whole market is viewed at the same level.
- `competitors`: Optional competitor brands compared in brand links and triage. Empty means competitors are found from the data. (The UI field is comma-separated and split into this list.)
- `depth`: Amount of collection and the target number of CEPs. quick: about 6 CEPs, search paths for 1 trigger anchor, no brand links. standard: about 10 CEPs, 2 trigger anchors, brand links. deep: about 25 CEPs, 4 trigger anchors, stronger brand links; slowest and most expensive.
- `sense`: Optional confirmed Stage-0 result from resolve_sense, sent whole with the person's edits (the UI's 'run with these settings' button). When given, the run skips its own meaning step and uses exactly this meaning, anchor, seeds, triggers and excludes; when omitted the pipeline resolves the meaning itself.
- `lang`: Language of the report commentary. Search terms and data stay in the market language.
- `ui_lang`: Language of progress log messages only; does not change the result.

### get_job
Returns one job's status (queued, running, done, error, canceled), its progress log (stage, pct, msg, t), error text, and when done the run_id with report_url and json_url. Repeat until status is done, error or canceled, then read the result with get_report or get_cep_map. Read only, free. Waits up to about 45 s for 'status' to reach done, error, canceled; call again if not done. Usually followed by: get_report, get_cep_map.
`GET /api/jobs/{job_id}`
- `job_id` (required): Job id returned by start_build (12 hex chars). Jobs live in server memory and are lost on restart.

### list_jobs
Lists jobs that are running or queued plus up to 4 jobs finished in the last 10 minutes, with keyword, depth, percent, queue position, error and report_url, and the active count against the limit of 3. Use it to see whether a new build will be accepted or to find a job started elsewhere. Read only, free.
`GET /api/jobs`

### cancel_job
Cancels a job. A queued job is removed at once; a running job stops at its next progress report. Credits already spent are not returned. Returns job_id, status and cancel_requested. Changes saved data in the app; no credits.
`POST /api/jobs/{job_id}/cancel`
- `job_id` (required): Job id returned by start_build (12 hex chars). Jobs live in server memory and are lost on restart.

### get_report
Returns the saved HTML report of a finished run: CEP map, priorities, triage, brand links, time series, evidence and readiness. Pass lang to re-render the same saved data in another language at no credit cost; download=1 returns it as an attachment. Read only, free. Usually followed by: get_cep_map, download_report_pdf.
`GET /runs/{run_id}/report.html`
- `run_id` (required): Saved run id, e.g. 20261001_141110_keyword_58b6ff. Get it from get_job (run_id) or list_runs.
- `lang`: Optional. Re-render the report in this language from the saved CEP map (no credits).
- `download`: 1 returns the HTML as a file download.

### get_cep_map
Returns the machine-readable cep_map.json of a finished run: meta (keyword, topic, sense, market, credits spent), the CEP list with metrics and evidence, triage and readiness verdict. Use this instead of the HTML report when you need the numbers. Read only, free.
`GET /runs/{run_id}/cep_map.json`
- `run_id` (required): Saved run id, e.g. 20261001_141110_keyword_58b6ff. Get it from get_job (run_id) or list_runs.

### download_report_pdf
Converts the run's report to PDF with headless Chromium (cached per paper size) and returns the file. Use for sharing or printing; the first conversion can take up to about a minute. Read only, free.
`GET /runs/{run_id}/report.pdf`
- `run_id` (required): Saved run id, e.g. 20261001_141110_keyword_58b6ff. Get it from get_job (run_id) or list_runs.
- `paper`: Paper size.

### list_runs
Lists saved runs, newest first, with run_id, input keyword, topic, sense, market (gl), report language, focal brand, competitors, number of CEPs, readiness, credits spent, depth and creation time. Use it to find an existing analysis before starting a new one. Read only, free. Usually followed by: get_report, prepare_rerun.
`GET /api/runs`

### prepare_rerun
Loads the exact input conditions of a saved run without starting anything: params (keyword, topic, gl, focal_brand, competitors, depth, lang, sense) and sense_panel (the confirmed meaning) plus credits_prev. To actually re-run, pass params to start_build after the person confirms the credit cost; this is how the UI re-runs. Read only, free. Usually followed by: start_build.
`POST /api/runs/{run_id}/rerun`
- `run_id` (required): Saved run id, e.g. 20261001_141110_keyword_58b6ff. Get it from get_job (run_id) or list_runs.
- `ui_lang`: Optional language for progress log messages of the later run.

### delete_run
Permanently deletes a saved run and its report files. Returns {ok: true}, or 404 if the run does not exist. Deletes data. A person approves it first.
`DELETE /api/runs/{run_id}`
- `run_id` (required): Saved run id, e.g. 20261001_141110_keyword_58b6ff. Get it from get_job (run_id) or list_runs.

### get_validation_report
Returns the post-hoc validation report (HTML) built from all saved runs; it is regenerated when a newer run exists. Use it to judge how reliable CEP Finder outputs have been. Reads saved runs only. Read only, free.
`GET /validation`

### rerun_run
Starts a new run with the stored inputs of an earlier run (the whole pipeline again, data is fetched fresh). Spends Data API credits like start_build. Use prepare_rerun to read the inputs first; poll get_job with the returned job_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: same as start_build. Time: 5-20 minutes. Usually followed by: get_job.
`POST /api/runs/{run_id}/rerun`
- `run_id` (required): Run id from list_runs.

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