# GEO Audit: agent guide

GEO Audit renders 1-5 URLs (or HTML captured in the browser) in a real browser, compares them with the pre-JS HTML and scores SEO, AEO and GEO items with rules. Only the main content (without navigation, footer and recommendation widgets) is judged, and a re-review step drops weakly supported findings. With a topic keyword it checks coverage against ListeningMind Data API search volume, intents and related keywords. Marketers and SEO staff use it for pages in Korea, Japan and the US.

## Connect
- MCP: `https://daas-geo.listeningmind.ai/mcp` (Streamable HTTP). Start with `app_guide`.
- Browser agents: tools are registered on every page through WebMCP (`document.modelContext`).
- REST: `https://daas-geo.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_queue_status` (read): Check how busy the queue is.
2. `start_audit` (run): Start the audit with URLs; use start_audit_html for private pages.
3. `get_audit` (read): Poll until state is done, at least once a minute (queued jobs are dropped after about 90 seconds without polling).
4. `download_report_pdf` (read): Download the PDF report.
5. `download_report_html` (read): Download the HTML report.
6. `rerun_audit` (run): After fixing, re-run the same URLs to compare.
7. `list_history` (read): Find earlier audits.
8. `delete_history_entry` (delete): Delete records that are no longer needed.

## Inputs
1-5 public URLs or captured HTML (up to 6 MB); optional topic keyword (up to 60 characters), market (kr/jp/us) and an earlier audit id to compare with.

## Outputs
Per URL: overall score and grade, axis scores, item verdicts with evidence, readability, before/after render comparison, re-review result, topic coverage and comparison with the previous audit. HTML and PDF report downloads.

## Cost and time
No Data API credits unless a topic is given; a topic adds one keyword_info and one intent_finder call. When the server has an LLM key, one re-review LLM call is made per page. A job is limited to 240 seconds (40 seconds per page fetch); the recent average duration is avg_s from get_queue_status.

## Limits
Markets: kr, jp, us. Up to 5 URLs per job, HTML up to 6 MB. One active audit per client IP, 20 per hour, and 503 when the queue is full. All verdicts are rule based; the LLM is used only for re-review. History and deletion are scoped by the X-GA-Owner header (a 16-64 character token per browser), so the same token must be sent to see them. POST requests need a Content-Length header.

## Method (how the analysis works)
1. Fetch 1-5 URLs, or take HTML captured in the browser, and render each page in a real browser.
2. Compare the rendered page with the pre-JS HTML.
3. Check site signals and links, then score SEO, AEO and GEO items with rules, judging only the main content (without navigation, footer and recommendation widgets).
4. With a topic keyword, check coverage against ListeningMind Data API search volume, intents and related keywords.
5. Re-review the results critically and drop weakly supported findings.

## Reading the result
- Per URL, scores.overall and grade are the summary; scores.axes splits it into SEO, AEO and GEO.
- items lists each check with its verdict and evidence; the fixes come from here.
- render_compare (ratio) compares the rendered page with the pre-JS HTML.
- review.flagged lists findings the re-review step questioned; readability.score and topic coverage complete the picture.
- After rerun_audit, compare shows what changed against the earlier audit.

## Requests this app answers well
- Check whether our product introduction page is ready to be cited by AI answer engines
- Compare the SEO, AEO and GEO scores of these 3 URLs and list what to fix
- Check our blog post's coverage for the topic 'vegan cosmetics'
- I fixed the page audited last week; audit it again and tell me what changed

## Continue in another app
- [ACO](https://daas-aco.listeningmind.ai/llms.txt) (MCP `https://daas-aco.listeningmind.ai/mcp`): When the audited page is a product detail page and you need product-level fixes for AI answers and shopping agents. Carry: The same URL (or the captured HTML) and market.
- [AOO](https://daas-aoo.listeningmind.ai/llms.txt) (MCP `https://daas-aoo.listeningmind.ai/mcp`): When you want to know whether AI agents can get tasks done across the whole site, not one page. Carry: The site's domain.

## 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`)
- [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
- `대기`: Waiting
- `수집·렌더링`: Fetching and rendering
- `사이트 신호·링크 점검`: Checking site signals and links
- `분석 완료`: Analysis done
- `결과 재검토(비판적 점검)`: Critical re-review of results
- `오류`: Error

## All tools
### get_queue_status
Shows how busy the audit queue is before submitting: {running, waiting, slots, avg_s}. avg_s is the recent average audit duration in seconds. Read only, free. Usually followed by: start_audit.
`GET /api/queue`

### start_audit
Starts an SEO/AEO/GEO audit of 1-5 public URLs. Each page is rendered in a headless browser, compared with the pre-JS HTML, checked against rule-based items, then re-reviewed. Returns the job status object {id, state (queued, running), urls, progress[], position, ahead, eta_s}. Poll get_audit at least once a minute: a queued job that is not polled for about 90 seconds is dropped. One active audit per client IP; 429 returns the running 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: Data API credits when topic is set (keyword_info + intent_finder, cached 24 h per member: own cache free, others' at full price) plus LLM review tokens converted to credits (USD 1 = 1,000 credits); reported as credits.spent in the result. Time: limit 240 seconds per job (40 seconds per page fetch). Usually followed by: get_audit.
`POST /api/audit`
- `urls` (required): 1-5 public page URLs (http or https), audited together; duplicates are removed. Pages in the same job are compared with each other (duplicate titles and descriptions).
- `topic`: Optional topic keyword (max 60 characters). When set, ListeningMind search volume, competition, intents and up to 25 related keywords are fetched and each report gets a topic coverage section. Blank = no topic section and no credits.
- `gl`: Market for the topic search data: kr, jp or us. Default kr. Has no effect when topic is empty.
- `parent`: Optional id of an earlier audit to compare against; the reports then include compare (score and item changes). Without it the previous audit of the same URL by the same owner is used when one exists.

### start_audit_html
Audits one page from rendered HTML captured in the user's browser (what the bookmarklet and Chrome extension send), for pages behind login, bot blocking or on a private network. The server does not fetch private hosts. Returns the job status object; poll get_audit. 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 when topic is set (keyword_info + intent_finder, cached 24 h per member: own cache free, others' at full price) plus LLM review tokens converted to credits (USD 1 = 1,000 credits); reported as credits.spent in the result. Time: limit 240 seconds. Usually followed by: get_audit.
`POST /api/audit_html`
- `url` (required): URL of the captured page (max 2048 characters).
- `html` (required): Rendered HTML of the page, 20 characters to 6 MB.
- `source`: Where the HTML came from; stored with the audit and shown in the report. Does not change scoring.
- `topic`: Optional topic keyword (max 60 characters). When set, ListeningMind search volume, competition, intents and up to 25 related keywords are fetched and each report gets a topic coverage section. Blank = no topic section and no credits.
- `gl`: Market for the topic search data: kr, jp or us. Default kr. Has no effect when topic is empty.
- `parent`: Optional id of an earlier audit to compare against; the reports then include compare (score and item changes). Without it the previous audit of the same URL by the same owner is used when one exists.

### get_audit
Reads one audit. While queued or running returns {id, state, urls, progress[] (per-URL stage), position, ahead, eta_s or elapsed_s}; when done returns state done and result {reports[{url, final_url, facts, fetch, render_compare, scores{axes, overall, grade}, readability, items[], review, topic, compare}], topic, axes_meta, cats_meta, generated_at, job}. Repeat until state is done, error or cancelled. Read only, free. Waits up to about 45 s for 'state' to reach done, error, cancelled; call again if not done. Usually followed by: download_report_pdf, download_report_html, rerun_audit.
`GET /api/audit/{jid}`
- `jid` (required): Audit id returned by start_audit, start_audit_html or rerun_audit (10-40 characters: letters, digits, _ or -).

### cancel_audit
Cancels a queued audit (a running one finishes). Returns {state}. 404 when the job is no longer in memory. Changes saved data in the app; no credits.
`DELETE /api/audit/{jid}`
- `jid` (required): Audit id returned by start_audit, start_audit_html or rerun_audit (10-40 characters: letters, digits, _ or -).

### rerun_audit
Audits the same URLs again and links the new audit to this one so the report shows what changed. Not possible for private-network pages (use start_audit_html with parent instead). Returns the new job status object; poll get_audit with its 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: Data API credits when topic is set (keyword_info + intent_finder, cached 24 h per member: own cache free, others' at full price) plus LLM review tokens converted to credits (USD 1 = 1,000 credits); reported as credits.spent in the result. Usually followed by: get_audit.
`POST /api/audit/{jid}/rerun`
- `jid` (required): Audit id returned by start_audit, start_audit_html or rerun_audit (10-40 characters: letters, digits, _ or -).

### download_report_pdf
Downloads the finished audit report as a PDF (rendered from /report/{jid}). Limited to 60 downloads per hour per IP. Read only, free.
`GET /api/audit/{jid}/report.pdf`
- `jid` (required): Audit id returned by start_audit, start_audit_html or rerun_audit (10-40 characters: letters, digits, _ or -).

### download_report_html
Downloads the finished audit report as a single static HTML file with inlined CSS. Limited to 60 downloads per hour per IP. Read only, free.
`GET /api/audit/{jid}/report.html`
- `jid` (required): Audit id returned by start_audit, start_audit_html or rerun_audit (10-40 characters: letters, digits, _ or -).

### list_history
Lists past audits of the caller: {items[{id, created, owner, source, urls, topic, parent, ...}]}, newest first, up to 200. Only audits submitted with the same X-GA-Owner header are returned; without that header the list is empty. Read only, free. Usually followed by: get_audit.
`GET /api/history`

### delete_history_entry
Deletes one stored audit result. Works only for audits owned by the X-GA-Owner token sent with the request. Returns {deleted: true} or 404. Deletes data. A person approves it first.
`DELETE /api/history/{jid}`
- `jid` (required): Audit id returned by start_audit, start_audit_html or rerun_audit (10-40 characters: letters, digits, _ or -).