# Prompt Builder: agent guide

From a brand or category keyword it collects ListeningMind related keywords, People Also Ask questions and Google AI Overviews, extracts CEP, nano context, KBF, constraints, avoidance, reasons to believe and competitors, and generates managed prompts in 6 fixed groups with estimated monthly prompt volume. It can then ask ChatGPT and Gemini those prompts to measure brand visibility, and keeps history and Excel exports. Used by GEO leads and brand managers. Markets: Korea, Japan, US.

## Connect
- MCP: `https://daas-prompt.listeningmind.ai/mcp` (Streamable HTTP). Start with `app_guide`.
- Browser agents: tools are registered on every page through WebMCP (`document.modelContext`).
- REST: `https://daas-prompt.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. `preview_detection` (run): Review the auto-detected meaning, own and competitor brands and exclude words.
2. `start_analysis` (run): Start the run with the confirmed values and read the job id from the HTML.
3. `get_job_status` (read): Poll stages until done; if no data, restart with a keyword from suggest.
4. `get_run` (read): Read the insight and managed prompts as JSON.
5. `start_visibility` (run): Optionally measure brand visibility in ChatGPT and Gemini (paid calls, needs confirmation).
6. `get_visibility_status` (read): Poll until the measurement is done.
7. `get_visibility` (read): Read the visibility results.
8. `export_prompts_xlsx` (read): Download the prompts as Excel.
9. `list_history` (read): Find past runs to reopen.

## Inputs
Keyword (required), market (kr/jp/us); optional: topic to fix the meaning, number of prompts (72-300), keywords to query (3-40), PAA filter, engine (mix/Gemini/ChatGPT), own brands, competitors, exclude words. Page language ?ui=ko|en|ja.

## Outputs
Collected data (related keywords, journeys, questions, AI Overviews), insight (brands, CEP, contexts, KBF, constraints, thresholds, avoidance, RTB, competitors), managed prompts in 6 groups with interest intensity index (0-100), estimated monthly volume and gap-fill marks, AI visibility KPIs (mentions, recommendations, sources per engine), Excel file, history.

## Cost and time
One analysis spends ListeningMind finder (path, intent, cluster) credits plus SERP lookups for up to max keywords, and many LLM calls (exact amounts are not reported by the app). Usually 1-4 minutes. AI visibility measurement makes prompts x engines x 3 web-search LLM calls.

## Limits
All endpoints the UI uses are GET, and some return HTML. The job id of start_analysis is the var JID value in the returned HTML; when the run finishes it is saved to server history under the same id. Results therefore live on the server, not only in the browser. There is no JSON history list, so ids must be read from the /history HTML. run_sync_analysis and collect_data are not saved to history. Markets: kr, jp, us. Only the last 40 jobs are kept in memory. No auth.

## Method (how the analysis works)
1. Resolve the keyword's meaning and detect own brand, competitors and exclude words, then correct them in the confirm step.
2. Collect ListeningMind related keywords, journeys, People Also Ask questions and Google AI Overviews for up to max keywords.
3. Extract CEP, nano context, KBF, constraints, thresholds, avoidance, reasons to believe (RTB) and competitors.
4. Generate managed prompts in 6 fixed groups, estimate monthly prompt volume and fill demand gaps.
5. Optionally ask ChatGPT and Gemini each prompt 3 times and record brand mentions, recommendations and cited sources.

## Reading the result
- ins (insight) holds the CEPs, contexts, KBF, constraints, avoidance, RTB and competitors the prompts are built from.
- Each managed prompt has a group, brand type (non-brand, brand, comparison), interest intensity index (0-100), estimated monthly count with range and confidence, and a gap-fill mark.
- ins._pv_meta.cooc.coverage (demand_coverage_pct) shows how much of the demand the prompt set covers.
- After measurement, kpi gives mentions, recommendations and sources per engine; opportunities and sources (cited domains) show where the brand is missing and which sites AI cites.
- The Excel file has one row per prompt with evidence keywords and volume, for sharing and tracking.

## Requests this app answers well
- List the questions consumers would actually ask ChatGPT about our serum and estimate their monthly volume
- Measure how often Gemini and ChatGPT recommend our brand in the electric toothbrush category in Japan
- Build 200 managed prompts for mattresses in the US and give me the Excel file
- Tell me which questions get AI answers that name our competitors but not us, and which sites those answers cite

## Continue in another app
- [Brand Wiki](https://daas-wiki.listeningmind.ai/llms.txt) (MCP `https://daas-wiki.listeningmind.ai/mcp`): When AI answers miss or misdescribe the brand and the brand site's content needs fixing. Carry: The brand name and site URL, plus the evidence keywords with volume and CEP per prompt from the Excel file as demand data for import_demand_data.
- [GEO Audit](https://daas-geo.listeningmind.ai/llms.txt) (MCP `https://daas-geo.listeningmind.ai/mcp`): When you want to check whether your own pages are ready to be read and cited for the prompts where visibility is low. Carry: The keyword as the topic and the URLs (up to 5) of your pages that should answer those prompts.

## 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`)
- [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
- `collecting`: Collecting related keywords & SERP
- `suggesting`: Finding alternative keywords
- `analyzing`: Analyzing CEP, nano intent, KBF
- `generating`: Generating managed prompts
- `estimating`: Estimating prompt volume
- `gapfill`: Filling demand gaps
- `done`: Done

## All tools
### preview_detection
The 'AI helper' step the UI shows before a run: resolves the keyword's meaning, may switch an ambiguous or low-data brand keyword to its category, gathers related keywords and detects own brand, competitors and exclude words. Returns an HTML form pre-filled with collect keyword, focus, own, comp, exclude, gl, n, max; pass those values to start_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: 1 LLM call for sense resolution plus ListeningMind finder calls (path, intent, cluster) for the keyword. Time: 10-40 seconds. Usually followed by: start_analysis.
`GET /confirm`
- `q` (required): Brand or category keyword to analyze; related keywords, questions and SERPs are collected around it. An ambiguous or low-data brand may be switched to its category automatically (the brand is then kept as own brand).
- `gl`: Market. Default follows the UI language (ja -> jp, en -> us, else kr).
- `focus`: Optional topic that fixes the meaning of the keyword, e.g. a category for an ambiguous brand. Also steers which related keywords and prompts are kept.
- `n`: Requested number of managed prompts. The app makes round(n/3) scenarios, clamped to 3-100, so values above 300 act as 300. UI start page offers 72, 90, 120, 180, 300 (72 preselected); the confirm page allows 6-300 in steps of 6. Server default when omitted: 24.
- `max`: How many related keywords are queried for SERP, People Also Ask and AI Overview. More keywords give more questions and evidence and cost more credits.
- `prefilter`: '1' (default) queries only related keywords that have People Also Ask questions; '0' queries keywords without that filter. Accepted true values: 1, true, on, yes.
- `own`: Own brand names, comma separated (from the confirm step). Drives brand vs non-brand prompt split and visibility scoring. If own and comp are both given the server may move names between them.
- `comp`: Competitor brand names, comma separated. Used in comparison prompts and visibility scoring.
- `exclude`: Words to exclude (other meanings, noise), comma or newline separated; phrases are split into words, words of q and own brands are protected.
- `ui`: Page and label language only (result content language follows gl).
- `orig`: Original keyword when the user edited it on the confirm page.

### start_analysis
Starts a full run in the background (pass run='1'; without it the address only prefills the form): collects related keywords, People Also Ask and AI Overview from ListeningMind, analyzes CEP, nano intent, KBF, constraints, avoidance and competitors, generates managed prompts in 6 fixed groups, estimates monthly prompt volume and fills demand gaps, then saves the run to history. Returns the HTML progress page; the job id is in its poll script (var JID="<12 hex>"). Poll get_job_status with that 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: ListeningMind Data API credits for finder and SERP calls (up to max keywords) plus paid LLM calls: recent runs about 6,400-7,500 credits (about 85-100 Lima), reported as credits.spent. Time: about 1-4 minutes. Usually followed by: get_job_status.
`GET /`
- `q` (required): Brand or category keyword to analyze; related keywords, questions and SERPs are collected around it. An ambiguous or low-data brand may be switched to its category automatically (the brand is then kept as own brand).
- `gl`: Market. Default follows the UI language (ja -> jp, en -> us, else kr).
- `focus`: Optional topic that fixes the meaning of the keyword, e.g. a category for an ambiguous brand. Also steers which related keywords and prompts are kept.
- `n`: Requested number of managed prompts. The app makes round(n/3) scenarios, clamped to 3-100, so values above 300 act as 300. UI start page offers 72, 90, 120, 180, 300 (72 preselected); the confirm page allows 6-300 in steps of 6. Server default when omitted: 24.
- `max`: How many related keywords are queried for SERP, People Also Ask and AI Overview. More keywords give more questions and evidence and cost more credits.
- `prefilter`: '1' (default) queries only related keywords that have People Also Ask questions; '0' queries keywords without that filter. Accepted true values: 1, true, on, yes.
- `own`: Own brand names, comma separated (from the confirm step). Drives brand vs non-brand prompt split and visibility scoring. If own and comp are both given the server may move names between them.
- `comp`: Competitor brand names, comma separated. Used in comparison prompts and visibility scoring.
- `exclude`: Words to exclude (other meanings, noise), comma or newline separated; phrases are split into words, words of q and own brands are protected.
- `eng`: LLM engine for analysis and prompt generation: mix (Gemini and ChatGPT share work and cross-check), gemini or chatgpt. Falls back to an available engine when a key is missing. Server default mix.
- `ui`: Page and label language only (result content language follows gl).
- `run` (required): Must be '1': an explicit start. GET / with q but without run=1 only prefills the form (opening a shared or bookmarked address never starts a paid run).

### get_job_status
Returns {status (running, done, error), stage, stage_label, elapsed, error, suggest}. suggest lists alternative keywords that have data when the keyword returned nothing. Repeat until done or error. A finished run that is no longer in memory still answers done. Read only, free. Waits up to about 45 s for 'status' to reach done, error; call again if not done. Usually followed by: get_run, get_result_html.
`GET /api/status`
- `id` (required): Run id (12 hex chars), the job id shown by start_analysis.
- `ui`: Page language.

### get_run
Returns a saved run as structured JSON: {id, brand, gl, created_at, input, counts (related keywords, keywords queried, questions, AI overview items, scenarios, prompts), pkg (collected data: related keywords, journeys, aggregated questions, SERP text), ins (insight: brands, CEP, contexts, KBF, constraints, thresholds, avoidance, RTB, competitors, scenarios with prompts, estimated prompt volume _pv)}. Read only, free.
`GET /api/run`
- `id` (required): Run id (12 hex chars), the job id shown by start_analysis.

### get_result_html
Returns the rendered result section (insight cards, prompt tables, visibility card) as an HTML fragment, as the UI inserts it after the run. Answers 202 'not ready' while running. Read only, free.
`GET /api/result`
- `id` (required): Run id (12 hex chars), the job id shown by start_analysis.
- `ui`: Page language.

### start_visibility
Asks ChatGPT and Gemini (with web search) every managed prompt of a saved run 3 times and records whether the own brand and competitors appear, are recommended and which sources are cited. Returns {status, done, total}. Poll get_visibility_status. 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: paid LLM calls with web search = prompts x engines x 3 (e.g. 80 prompts x 2 x 3 = 480). Time: several minutes (about calls / 10 x 9 seconds). Usually followed by: get_visibility_status.
`GET /api/vis/start`
- `id` (required): Run id (12 hex chars), the job id shown by start_analysis.

### get_visibility_status
Returns {status (running, done, error, none), done, total, error}. none means not measured and not running. Repeat until done or error. Read only, free. Waits up to about 45 s for 'status' to reach done, error, none; call again if not done. Usually followed by: get_visibility.
`GET /api/vis/status`
- `id` (required): Run id (12 hex chars), the job id shown by start_analysis.

### get_visibility
Returns the stored visibility measurement for a run: {engines, models, runs, per_prompt (answers per prompt and engine with brand mentions), kpi, opportunities, sources (cited domains), failed, created_at}. 404 {error:'not measured'} before measuring. Read only, free.
`GET /api/vis`
- `id` (required): Run id (12 hex chars), the job id shown by start_analysis.

### export_prompts_xlsx
Downloads the managed prompts of a run as an .xlsx file: one row per prompt with group, brand type (non-brand, brand, comparison), prompt, interest intensity index (0-100), tier, question share, estimated monthly prompt count and range, confidence, trend, evidence keywords with volume, demand share, co-occurring words, gap-fill mark, topic, scenario, CEP, constraints, required KBF, avoidance, output format; plus visibility results when measured. Read only, free.
`GET /export`
- `id` (required): Run id (12 hex chars), the job id shown by start_analysis.

### list_history
Returns the history page (HTML) listing saved runs for a market with time, keyword, focus and links to view (/history/view?id=), Excel export and delete. mk filters by market (kr, jp, us, all); default is the UI language's market. Read only, free. Usually followed by: get_run.
`GET /history`
- `mk`: Market filter.
- `ui`: Page language.

### view_saved_run
Returns the full HTML result page of a saved run. Read only, free.
`GET /history/view`
- `id` (required): Run id (12 hex chars), the job id shown by start_analysis.
- `ui`: Page language.

### delete_run
Deletes one of your saved runs (POST, form or JSON body {id, back}). Signed-in members only, and only the member who ran it: 401 signed out, 403 for another member's run. A form post is answered with 303 to the back path, JSON with {ok, id}. GET is refused (405). Deletes data. A person approves it first.
`POST /history/delete`
- `id` (required): Run id (12 hex chars), the job id shown by start_analysis.
- `back`: Path to redirect to after deleting (must start with /).

### collect_data
Collects the ListeningMind data package for a keyword (related keywords from path, intent and cluster finders, journeys, People Also Ask, AI Overview and SERP text) without LLM synthesis and without saving to history. For agents that write their own prompts. Returns the pkg JSON; 503 if the data API is unreachable. 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: ListeningMind Data API credits for finder calls plus SERP for up to max keywords. Time: about 20-90 seconds.
`GET /api/collect`
- `q` (required): Brand or category keyword to analyze; related keywords, questions and SERPs are collected around it. An ambiguous or low-data brand may be switched to its category automatically (the brand is then kept as own brand).
- `gl`: Market. Default follows the UI language (ja -> jp, en -> us, else kr).
- `max`: How many related keywords are queried for SERP, People Also Ask and AI Overview. More keywords give more questions and evidence and cost more credits.
- `prefilter`: '1' (default) queries only related keywords that have People Also Ask questions; '0' queries keywords without that filter. Accepted true values: 1, true, on, yes.
- `focus`: Optional topic that fixes the meaning of the keyword, e.g. a category for an ambiguous brand. Also steers which related keywords and prompts are kept.

### run_sync_analysis
Runs collection and insight synthesis in one blocking request and returns {insight, data}. Not saved to history and no job id, so it cannot be exported or measured later; use start_analysis for that. 422 when the keyword has no ListeningMind data. 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: ListeningMind Data API credits plus many paid LLM calls. Time: about 1-2 minutes or more.
`GET /api`
- `q` (required): Brand or category keyword to analyze; related keywords, questions and SERPs are collected around it. An ambiguous or low-data brand may be switched to its category automatically (the brand is then kept as own brand).
- `gl`: Market. Default follows the UI language (ja -> jp, en -> us, else kr).
- `max`: How many related keywords are queried for SERP, People Also Ask and AI Overview. More keywords give more questions and evidence and cost more credits.
- `prefilter`: '1' (default) queries only related keywords that have People Also Ask questions; '0' queries keywords without that filter. Accepted true values: 1, true, on, yes.
- `focus`: Optional topic that fixes the meaning of the keyword, e.g. a category for an ambiguous brand. Also steers which related keywords and prompts are kept.
- `n`: Requested number of managed prompts. The app makes round(n/3) scenarios, clamped to 3-100, so values above 300 act as 300. UI start page offers 72, 90, 120, 180, 300 (72 preselected); the confirm page allows 6-300 in steps of 6. Server default when omitted: 24.

### list_history_count
Number of saved runs in the history (for the header). Signed-in members only: {n}. Read only, free.
`GET /history/count`

### list_recent_history
Your 10 most recent runs as an HTML table fragment for the home page (time, brand, market, re-run/view/export/delete). Signed-in members only; each member sees only their own runs. Read only, free.
`GET /history/recent`