# Creative Finder: agent guide

Give one to three product lines. The app finds the moments when people think of them in ListeningMind DaaS data (related searches, real search paths, monthly volume), grades the evidence in code, and writes a 15-second creative draft with a distinct tone per moment. Images and 8-second vertical videos can be generated per draft. Markets KR, JP, US; UI ko, en, ja.

## Connect
- MCP: `https://daas-creative.listeningmind.ai/mcp` (Streamable HTTP). Start with `app_guide`.
- Browser agents: tools are registered on every page through WebMCP (`document.modelContext`).
- REST: `https://daas-creative.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. `assist_brief` (run): Fill product lines, regulatory domain and principles from one keyword
2. `check_keywords` (run): Check volume of hand-typed lines
3. `estimate_run` (read): Estimate credits before the run
4. `start_run` (run): Start the run
5. `get_run_status` (read): Poll until done
6. `get_run` (read): Read the result
7. `generate_image` (run): Image draft for a creative
8. `generate_video` (run): Video draft for a creative
9. `list_assets` (read): Check generated assets
10. `get_report_html` (read): Export the report

## Inputs
lines (1-3 product line keywords with search volume), gl (kr|jp|us), lang (ko|en|ja), depth (quick|standard|deep), audience, channel, reg_domain, principles[], exclude_topics[], fixed_elements, creatives_per_line (3-6). Brief assistant: one keyword.

## Outputs
lines, market (growing, declining, new), ceps (situations with trigger type, basket keywords and volume, evidence grade, consumer question), matrix, unobserved_paths, big_outside, creatives (scene, lines, 4 shots, format, test question, KPI, review notes, tone, image and video prompts), notes, credits. Exports: report.html, brief.md, run.json. Generated assets: image and video files.

## Cost and time
standard about 35,000-45,000 credits (7 path_finder calls), quick about 1,000-3,000, deep about 70,000. Brief assistant about 500. One image about 40-130 credits, one 8-second video about 400-1,200 credits (1 USD = 1,000 credits).

## Limits
Markets KR, JP, US. Lines need search volume. One path_finder call is about 4,600 credits. Every draft is pre-review and does not replace advertising review in regulated domains. Images never contain text.

## Method (how the analysis works)
1. Read the market from the product lines' volume and related searches (growing, falling, new queries).
2. Find the purchase situations in real search paths (path_finder).
3. Code grades each situation's evidence (path confirmed, related confirmed, hypothesis) and adds basket query volume.
4. Write a 15-second draft per situation with its own tone, a wording check, and image and video prompts.

## Reading the result
- ceps lists the purchase situations; evidence is the grade. Read hypothesis-grade ones with their test questions.
- creatives holds one draft per situation, with a softer variant and a wording check; all are pre-review drafts.
- credits.spent is what the run used; own_cache is what your own cache saved.

## Requests this app answers well
- Find the purchase situations for probiotics and draft a Reels ad for each
- Draft 15-second ads and images for each buying situation of sunscreen in Japan
- Soften this draft's wording for health supplement ad review
- Make vertical video drafts only for situations confirmed by search paths

## Continue in another app
- [CEP Finder](https://daas-cep.listeningmind.ai/llms.txt) (MCP `https://daas-cep.listeningmind.ai/mcp`): When you need the full map and priority of a category's entry points. Carry: The same product line keyword and market.
- [Demand Forecast](https://daas-forecast.listeningmind.ai/llms.txt) (MCP `https://daas-forecast.listeningmind.ai/mcp`): When you want to know when to run the ads and when each situation's demand rises. Carry: The basket queries of confirmed situations (up to 5) as seeds.

## 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`)
- [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
- `market`: Market
- `seeds`: Situation queries
- `paths`: Search paths
- `situations`: Situations
- `evidence`: Evidence
- `relations`: Relations
- `creatives`: Creatives
- `done`: Done

## All tools
### assist_brief
Measures one keyword, pulls its related searches and proposes product lines (with volume), regulatory domain, audience, channel, principles and fixed elements. Returns credits spent. About 500 Data API credits, 10-20 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: about 500 credits. Usually followed by: estimate_run, start_run.
`POST /api/assist/brief`
- `keyword` (required): one product or category name
- `gl`: market: kr, jp or us
- `lang`: language of the answer and the drafts: ko, en or ja
- `brand_notes`: free text about the brand or campaign

### check_keywords
Returns monthly search volume for up to 3 hand-typed product line keywords. 1 credit per keyword. 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 1-3 credits (1 per keyword).
`POST /api/assist/keywords`
- `keywords` (required): product line keywords to measure (search volume and trend)
- `gl`: market: kr, jp or us

### estimate_run
Estimated credits for a run with these lines and depth, plus Lima. Free. Read only, free. Usually followed by: start_run.
`POST /api/estimate`
- `lines` (required): 1-3 product line keywords that have search volume
- `depth`: quick, standard or deep (see start_run)
- `gl`: market: kr, jp or us

### start_run
Starts the full pipeline in the background and returns run_id and estimate_credits. standard depth takes 5-10 minutes and about 35,000-45,000 Data API credits plus a small LLM cost. 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 35,000-45,000 credits (standard). Time: 5-10 minutes. Usually followed by: get_run_status.
`POST /api/runs`
- `lines` (required): 1-3 product line keywords with search volume
- `gl`: market: kr, jp or us
- `lang`: language of the answer and the drafts: ko, en or ja
- `depth`: quick: related searches only; standard: one path per line plus 4 situation paths; deep: 10 situation paths
- `title`: run title shown in the list
- `audience`: who the ads are for, in plain words
- `channel`: meta_reels, meta_carousel, youtube_shorts or display
- `reg_domain`: regulatory domain for the wording check: hfs, food, cosmetic, quasidrug, device, finance or general
- `principles`: wording principles the drafts must keep
- `exclude_topics`: topics the drafts must not touch
- `fixed_elements`: elements every draft must keep, such as the product name, a claim or a closing line
- `creatives_per_line`: 0 = depth default (3 quick, 5 standard/deep)

### get_run_status
Status, stage, percent and credits spent so far. 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: get_run.
`GET /api/runs/{run_id}/status`
- `run_id` (required): run id returned by start_run

### get_run
Full result JSON of a finished run (lines, market, ceps, matrix, creatives, notes, credits) plus generated assets. Read only, free. Usually followed by: generate_image, generate_video, get_report_html.
`GET /api/runs/{run_id}`
- `run_id` (required): run id returned by start_run

### list_runs
Runs of the signed-in member (all runs for staff), newest first. Read only, free.
`GET /api/runs`
- `limit`: how many runs to list, newest first

### regenerate_creative
Rewrites one creative draft with the person's instructions (new tone allowed). Small LLM cost, reported in credits. 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-30 credits.
`POST /api/runs/{run_id}/creatives/{creative_id}/regenerate`
- `run_id` (required): run id returned by start_run
- `creative_id` (required): C1, C2, ...
- `instructions`: what to change in the draft, in plain words

### generate_image
Starts image generation for one creative in the background (Gemini image or OpenAI image). Returns the asset row; poll list_assets until status is done. About 40-130 credits per image. 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-130 credits. Time: 10-40 seconds. Usually followed by: list_assets.
`POST /api/runs/{run_id}/creatives/{creative_id}/image`
- `run_id` (required): run id returned by start_run
- `creative_id` (required): creative draft id in the run: C1, C2, ...
- `provider`: image or video model family: gemini or openai
- `quality`: fast or hq for images; fast or lite for videos
- `prompt`: optional override of the stored image prompt

### generate_video
Starts an 8-second vertical video for one creative (Veo 3.1 fast/lite or Sora 2). Poll list_assets until done. About 400-1,200 credits per clip. 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 400-1,200 credits. Time: 1-3 minutes. Usually followed by: list_assets.
`POST /api/runs/{run_id}/creatives/{creative_id}/video`
- `run_id` (required): run id returned by start_run
- `creative_id` (required): creative draft id in the run: C1, C2, ...
- `provider`: image or video model family: gemini or openai
- `quality`: fast or hq for images; fast or lite for videos
- `prompt`: optional override of the stored prompt (no text in the picture)
- `seconds`: video length in seconds, 4 to 8

### generate_media_batch
Starts images or videos for every creative that has none yet. Returns started asset ids and the estimate. 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-130 credits per image, about 400-1,200 per video.
`POST /api/runs/{run_id}/media/batch`
- `run_id` (required): run id returned by start_run
- `kind`: image or video
- `provider`: image or video model family: gemini or openai
- `quality`: fast or hq for images; fast or lite for videos
- `creative_ids`: draft ids to generate for; all drafts without media when empty

### list_assets
All generated images and videos of a run with status, file name and credits. Files are served at /api/runs/{run_id}/assets/{file}. Read only, free. Waits up to about 45 s for 'assets[].status' to reach done, error; call again if not done.
`GET /api/runs/{run_id}/assets`
- `run_id` (required): run id returned by start_run

### get_report_html
Standalone HTML report of a finished run (sections A to F and appendix). embed=1 inlines generated images. Read only, free.
`GET /api/runs/{run_id}/report.html`
- `run_id` (required): run id returned by start_run
- `embed`: 1 returns the report without the page shell, for embedding

### get_brief_md
Markdown brief of a finished run. Read only, free.
`GET /api/runs/{run_id}/brief.md`
- `run_id` (required): run id returned by start_run

### get_run_json
Downloadable JSON of the result and assets. Read only, free.
`GET /api/runs/{run_id}/run.json`
- `run_id` (required): run id returned by start_run

### delete_run
Deletes a run and its asset rows (owner or staff only). Deletes data. A person approves it first.
`DELETE /api/runs/{run_id}`
- `run_id` (required): run id returned by start_run