# Demand Forecast: agent guide

Demand forecast and season calendar. From category seed keywords it collects related queries, groups them into segments, forecasts the next 3 or 6 months and the change versus last year from 48 months of monthly search volume, and derives prep, campaign, launch and peak months. Product planners, merchandisers and campaign owners use it to set season timing. Data comes from the ListeningMind Data API (intent_finder, keyword_info). Markets: Korea, Japan, US.

## Connect
- MCP: `https://daas-forecast.listeningmind.ai/mcp` (Streamable HTTP). Start with `app_guide`.
- Browser agents: tools are registered on every page through WebMCP (`document.modelContext`).
- REST: `https://daas-forecast.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. `get_config` (read): Get example seeds per market and the timing rules.
2. `suggest_seeds` (run): With one seed, get companion seeds.
3. `estimate_credits` (read): Check expected credits and tell the person.
4. `start_run` (run): Start the forecast.
5. `get_run` (read): Poll until done and read the result.
6. `get_report_markdown` (read): Get the full report as text.
7. `download_timing_ics` (read): Export the timing windows as a calendar.
8. `download_forecast_csv` (read): Export monthly forecast numbers.

## Inputs
Seed keywords (up to 5, e.g. sunscreen), market (kr/jp/us), horizon (3 or 6 months), scope (standard/wide), segment mode (auto/seed/custom with your own segments), gender and age (Korea only), credit cap.

## Outputs
Category outlook (next-period total, change vs last year, where the months sit in the season), forecast per segment with prep, campaign, launch and peak months, keyword list and excluded list, written brief, evidence. Report as HTML or Markdown, forecast CSV, keywords CSV, timing ICS calendar, result JSON.

## Cost and time
With defaults (1 seed, standard) about 400-500 Data API credits and 1-3 minutes. More seeds, wide scope, custom segments and demography add credits. Server cap 5,000. LLM calls are used for filtering, segments and the brief. Seed suggestions cost up to 600 credits.

## Limits
Up to 5 seeds and up to 12 custom segments. Gender and age only for gl=kr. Data is monthly; the forecast starts after the latest measured month. Segments with a very small base may show no year-over-year value. Languages ko/ja/en.

## Method (how the analysis works)
1. Build a keyword universe from the seed keywords with intent_finder.
2. Remove off-topic keywords with an LLM.
3. Fetch 48 months of monthly search volume with keyword_info and group the keywords into segments.
4. Forecast the next 3 or 6 months and the change versus last year, per segment and for the whole category.
5. Derive prep, campaign, launch and peak months from the timing rules, add gender and age share (Korea only) and write the brief.

## Reading the result
- category.rec.horizon_total and horizon_yoy are next-period demand and its change versus last year; momentum and regime are recorded with them.
- category.plan.peak and launch_from are the timing answer; download_timing_ics puts the prep, campaign, launch and peak windows into a calendar.
- segments holds the forecast and timing per segment, so you can see which part of the category moves first.
- category.rec.backtest_error is the forecast error tested on past data; segments with a very small base may show no year-over-year value.
- keywords and excluded show what was counted and what was dropped.

## Requests this app answers well
- How will sunscreen demand move over the next 6 months, and when should the campaign start
- Give me the peak month and the best launch timing for humidifiers in Japan as a calendar
- Forecast swimwear demand in the US for the next 3 months, split by segment
- Forecast whether padded jacket demand in Korea will be higher or lower than last year, with the gender and age share

## Continue in another app
- [CEP Finder](https://daas-cep.listeningmind.ai/llms.txt) (MCP `https://daas-cep.listeningmind.ai/mcp`): When the timing is set and you need the situations and messages to use in those months. Carry: The category seed keyword and market; read CEP Finder's time series and seasonality against the peak and launch months.
- [Pulse Finder](https://daas-pulse.listeningmind.ai/llms.txt) (MCP `https://daas-pulse.listeningmind.ai/mcp`): When you want to know which specific things are rising for a gender and age segment within the category. Carry: The seed keywords and market, and in Korea the segment (gender and age).

## 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`)
- [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
- `universe`: Building the keyword universe
- `filter`: Removing off-topic keywords (LLM)
- `series`: Fetching 48-month volume
- `segments`: Building segments
- `forecast`: Forecasting segments and category
- `demography`: Gender and age share (Korea)
- `brief`: Writing the brief (LLM)
- `done`: Done

## All tools
### get_config
Returns markets, example seed topics per category for the market, the timing rules (ramp, prep lead, launch window, peak thresholds), the default credit cap, whether the LLM is available and the account credit balance. Free. Read only, free.
`GET /api/config`
- `lang`: Language of generated text: ko, ja or en.
- `gl`: Search market: kr (Korea), jp (Japan) or us (United States).

### suggest_seeds
Proposes companion seed keywords for one category keyword: related queries from intent_finder, ranked by 12-month volume from keyword_info, then picked by an LLM. Returns {seeds, credits}. Up to 600 Data API credits (usually about 200-300), 10-30 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: up to 600 Data API credits (usually about 200-300) plus 1 LLM call. Time: 10-30 seconds. Usually followed by: estimate_credits.
`POST /api/suggest_seeds`
- `keyword` (required): One category keyword (the UI sends the first typed seed).
- `gl`: Search market: kr (Korea), jp (Japan) or us (United States).
- `lang`: Language of generated text: ko, ja or en.

### estimate_credits
Returns the expected Data API credits for the inputs: {harvest, series, demography, total, pool}. Computed locally, no API calls; cached calls in the real run are free. Read only, free. Usually followed by: start_run.
`POST /api/estimate`
- `seeds` (required): Category seed keywords, comma or newline separated; duplicates removed, up to 5 used. Each seed adds its related keywords to the universe, so seeds define what the category forecast covers. Example: '선크림, 자외선차단제'. get_config.topics lists examples per market.
- `gl`: Search market: kr (Korea), jp (Japan) or us (United States).
- `lang`: Language of generated text: ko, ja or en.
- `horizon`: Forecast horizon in months: 3 or 6 (values of 6 or more mean 6, anything lower means 3). Changes the forecast months, the horizon totals and year-over-year figures, and which timing windows fall inside the horizon.
- `scope`: Keyword universe size: standard (100 related keywords by volume plus 40 rising per seed) or wide (200 plus 40, more credits). Wider universes add long-tail keywords to segments; total pool capped at 700.
- `segment_mode`: How keywords are grouped into segments: auto (LLM groups by need), seed (one segment per seed) or custom (your own segments in custom_segments).
- `custom_segments`: Only for segment_mode=custom. One segment per line as 'Name: keyword1, keyword2'. Up to 12 segments. Example: '선스틱: 선스틱, 톤업 선스틱'.
- `demography`: Add gender and age share per segment from the top 5 keywords of each segment (Korea only; ignored for jp and us). Adds about 400 credits at most. The web form shows this only for Korea.
- `credit_cap`: Hard Data API credit cap for this run; the run stops with an error when it is reached. Default is the server cap (5,000 at the time of writing; get_config.credit_cap_default). The server does not clamp a higher value, so do not raise it without the person's consent.

### start_run
Starts a background run: builds a keyword universe from the seeds, filters off-topic keywords with an LLM, pulls 48 months of volume, groups keywords into segments, forecasts the next 3 or 6 months per segment and for the category, and derives prep, campaign, launch and peak months. Returns {run_id}. Poll get_run. About 400-1,800 Data API credits with defaults, 1-3 minutes. 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,800 Data API credits with defaults (cap 5,000) plus LLM calls for filtering, segments and the brief. Time: 1-3 minutes. Usually followed by: get_run.
`POST /api/runs`
- `seeds` (required): Category seed keywords, comma or newline separated; duplicates removed, up to 5 used. Each seed adds its related keywords to the universe, so seeds define what the category forecast covers. Example: '선크림, 자외선차단제'. get_config.topics lists examples per market.
- `gl`: Search market: kr (Korea), jp (Japan) or us (United States).
- `lang`: Language of generated text: ko, ja or en.
- `horizon`: Forecast horizon in months: 3 or 6 (values of 6 or more mean 6, anything lower means 3). Changes the forecast months, the horizon totals and year-over-year figures, and which timing windows fall inside the horizon.
- `scope`: Keyword universe size: standard (100 related keywords by volume plus 40 rising per seed) or wide (200 plus 40, more credits). Wider universes add long-tail keywords to segments; total pool capped at 700.
- `segment_mode`: How keywords are grouped into segments: auto (LLM groups by need), seed (one segment per seed) or custom (your own segments in custom_segments).
- `custom_segments`: Only for segment_mode=custom. One segment per line as 'Name: keyword1, keyword2'. Up to 12 segments. Example: '선스틱: 선스틱, 톤업 선스틱'.
- `demography`: Add gender and age share per segment from the top 5 keywords of each segment (Korea only; ignored for jp and us). Adds about 400 credits at most. The web form shows this only for Korea.
- `credit_cap`: Hard Data API credit cap for this run; the run stops with an error when it is reached. Default is the server cap (5,000 at the time of writing; get_config.credit_cap_default). The server does not clamp a higher value, so do not raise it without the person's consent.

### get_run
Returns one run: status (running, done, error), progress {stage, pct, steps}, credits, params, error and, when done, the result (meta, stats, months, category forecast and plan, segments, keywords, excluded, rules, brief, evidence). 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_report_markdown, download_timing_ics.
`GET /api/runs/{run_id}`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### list_runs
Lists recent runs with run_id, status, params, credits, created_at, updated_at, error and, for finished runs, a summary {segments, keywords, latest_month}. Read only, free.
`GET /api/runs`
- `limit`: Maximum runs to return.

### get_report_markdown
Returns the full forecast report as Markdown text (category outlook, segment plans, timing, keywords). Free. 404 until the run is done. Read only, free.
`GET /api/runs/{run_id}/report.md`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### get_report_html
Returns the full report as a self-contained HTML page. download=1 (default) sends it as a file, 0 shows it inline. Free. Read only, free.
`GET /runs/{run_id}/report.html`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).
- `download`: 1 to send as a file download, 0 to view inline.

### download_forecast_csv
Downloads monthly actual and forecast values (with lo/hi range, model and regime) per segment and for the whole category as CSV. Free. Read only, free.
`GET /runs/{run_id}/forecast.csv`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### download_keywords_csv
Downloads the keyword list with segment, volume and forecast as CSV. Free. Read only, free.
`GET /runs/{run_id}/keywords.csv`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### download_timing_ics
Downloads the prep, campaign, launch and peak windows as an iCalendar (.ics) file to import into a calendar. Free. Read only, free.
`GET /runs/{run_id}/timing.ics`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### download_run_json
Returns the raw result object of a finished run as JSON. Free. Read only, free.
`GET /runs/{run_id}/run.json`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### rerun_run
Starts a new run with the same parameters as an earlier run. Returns {run_id}. Same cost as start_run minus cached 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: same as start_run (cached calls are free). Time: 1-3 minutes. Usually followed by: get_run.
`POST /api/runs/{run_id}/rerun`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### delete_run
Deletes a run and its result. Cannot be undone. Deletes data. A person approves it first.
`DELETE /api/runs/{run_id}`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

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