Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
docs(skills): teach the AEO coach the Content Editor, prompt suggestion, competitor and report tools and get_action's removed counts (AC-009) (#1548)
Cihanfffc519f1f15
diff --git a/docs/guides/mcp-server.mdx b/docs/guides/mcp-server.mdxindex eabe912fa..942debfde 100644--- a/docs/guides/mcp-server.mdx+++ b/docs/guides/mcp-server.mdx@@ -220,7 +220,7 @@ instead.## Available tools-The MCP server exposes **36 tools**. Descriptions below match+The MCP server exposes **50 tools**. Descriptions below match[`web/src/lib/mcp/server.ts`](https://github.com/ansvisor/ansvisor/blob/main/web/src/lib/mcp/server.ts).Tools that change data are marked **writes** — only call them on explicit userintent, not during exploratory queries.@@ -294,6 +294,21 @@ curl "https://app.ansvisor.com/api/mcp/mentions/summary?brand_id=<brand_id>&plat| `generate_content_brief` | Generate or overwrite an AI content brief for an opportunity (LLM cost/latency). | **yes** || `update_opportunity_status` | Move an opportunity through workflow states (`new`, `reviewed`, `sent`, `in_progress`, `done`, `dismissed`). | **yes** |+### Content Editor++Drafts are read and written as a person would in the editor. Ansvisor never publishes, and a suggestion isn't applied until a person accepts it. None of these tools calls an LLM: the assistant writes the drafts and suggestions itself.++| Tool | What it does | Writes |+| --- | --- | --- |+| `list_content_drafts` | The brand's drafts, latest changed first (up to 100), with status, method (`create` or `optimize`), author, open suggestions and the editor path; filter by `status`. | |+| `get_content_draft` | One draft: its HTML, its numbered passages (`locked` ones AI answers quote today), its Action Center action, the open suggestions and the only pages a suggestion may link to. | |+| `get_content_sources` | What the draft draws on over 30 days, as the Sources tab shows it: prompts, AI searches (fan-outs), cited pages, Search Console queries and the person's choices. | |+| `get_content_impact` | What the draft's live page earns (citations, AI visits, Google clicks, the prompts citing it) against the period before, as the Live page tab reads it. Only for a draft of a live page. | |+| `create_content_draft` | Write a new draft as the agent (`create`, or `optimize` a page on the brand's domains); it goes to the Library's In review. | **yes** |+| `add_content_source` | Add a prompt, a cited page or a Search Console query to the draft's sources. | **yes** |+| `suggest_content_changes` | Leave up to 20 suggestions (replace or insert, each with a reason) for a person to accept or reject. Refused on a published draft, while open suggestions wait, or while the Content Agent writes it. | **yes** |+| `set_content_draft_ready` | Set a draft ready, as the editor's Mark ready does, without its Before you publish check; a linked action's writing task completes once every page it names has a ready draft. A draft in review waits for a person. | **yes** |+### Site audit| Tool | What it does | Writes |diff --git a/skills/README.md b/skills/README.mdindex 42eb5e271..d96d46415 100644--- a/skills/README.md+++ b/skills/README.md@@ -18,7 +18,7 @@ behaves like an AEO analyst who's been on your account for six months.| Skill | Flavour | What it's for || --- | --- | --- |-| [`ansvisor-aeo-coach`](./ansvisor-aeo-coach) | **MCP (preferred)** | Brand snapshots, visibility deep-dives, competitor watch, citation sources, prompt coverage, Action Center (what to do next, did it work, sending Improve suggestions), mentions and sentiment (how AI talks about the brand, why sentiment moved, what AI associates it with). Use this when your client (Claude Desktop, Claude Code, Cursor, Zed) is connected to the Ansvisor MCP server. |+| [`ansvisor-aeo-coach`](./ansvisor-aeo-coach) | **MCP (preferred)** | Brand snapshots, visibility deep-dives, competitor watch, citation sources, prompt coverage and prompt suggestions, Action Center (what to do next, did it work, sending Improve suggestions), mentions and sentiment (how AI talks about the brand, why sentiment moved, what AI associates it with), Content Editor drafts (sources, suggestions for review, Mark ready, what the live page earns), saved reports. Use this when your client (Claude Desktop, Claude Code, Cursor, Zed) is connected to the Ansvisor MCP server. || [`ansvisor-aeo-coach-standalone`](./ansvisor-aeo-coach-standalone) | **REST (fallback)** | Same skill, no MCP needed. Use this when you're on claude.ai web without a Connector, or any surface where setting up MCP isn't an option. |## Which flavour should I install?@@ -90,12 +90,14 @@ Once installed, just ask in plain English:- _"What should we work on next — and did last month's actions work?"_- _"Give me a 30-second standup on the Acme brand."_- _"Why did our sentiment drop on Gemini?"_+- _"What's waiting for review in the Content Editor?"_Claude picks the right tools / endpoints, fills in filters, interpretsthe numbers, and answers with action items. Tools that change youraccount (accepting a suggestion, updating a task, sending Improvesuggestions to Action Center, running a page audit, correcting a-response's sentiment) are only used when+response's sentiment, writing a draft or suggestions in the Content+Editor, marking a draft ready) are only used whenyou ask for that specific change.## Contributingdiff --git a/skills/ansvisor-aeo-coach/SKILL.md b/skills/ansvisor-aeo-coach/SKILL.mdindex d8308e3ed..bdeb2fed3 100644--- a/skills/ansvisor-aeo-coach/SKILL.md+++ b/skills/ansvisor-aeo-coach/SKILL.md@@ -6,16 +6,17 @@ description: |AI search engines (ChatGPT, Gemini, Perplexity, Claude, Copilot, Grok,Google AI Overviews, AI Mode), why visibility changed, how they compareto competitors, which sources cite them, or what to do next (Action- Center, content gaps, Improve suggestions, page audits), or how AI- talks about the brand (mentions, sentiment, what AI associates with- it). Uses the Ansvisor MCP server tools (`list_brands`,+ Center, content gaps, Improve suggestions, page audits, prompt+ suggestions, Content Editor drafts), or how AI talks about the brand+ (mentions, sentiment, what AI associates with it). Uses the Ansvisor+ MCP server tools (`list_brands`,`get_visibility_summary`, `get_competitor_comparison`,- `get_mentions_summary`, `list_actions`, …) to fetch the data,+ `list_actions`, …) to fetch the data,then interprets it the way a marketing analyst would — not justdumping numbers, but pointing at what changed and what to do about it.- Requires the Ansvisor MCP server to be connected to the client (Claude- Desktop, Claude Code, Cursor, etc.); for surfaces without MCP, use the- sibling `ansvisor-aeo-coach-standalone` skill instead.+ Requires the Ansvisor MCP server connected to the client (Claude+ Desktop, Claude Code, Cursor, etc.); without MCP, use the sibling+ `ansvisor-aeo-coach-standalone` skill.---# Ansvisor AEO Coach@@ -42,6 +43,9 @@ Activate this skill when the user asks anything in the shape of:- _"How is AI talking about us?" / "Why did sentiment drop on Gemini?"_- _"What does AI associate us with?"_- _"What should we work on next?" / "Did last month's work pay off?"_+- _"Which prompts should we start tracking?"_+- _"What's waiting in the Content Editor?" / "Did the page we optimized+ pay off?"_- _"Give me a daily / weekly standup on `<brand name>`."_If you don't see the Ansvisor MCP tools listed below in your available@@ -136,12 +140,21 @@ timestamps (`date_from` / `date_to`).per-entry `visibility_rate_pct` on a shared denominator, mentions andcitations, overall **share of voice**, and the same split per modeland platform. Filters: dates, `model`, `region`, `topic_id`.+- **`list_competitors`** — the competitors set up for the brand: `id`,+ `name` and `domain`. A setup list, not a ranking: for how they do,+ use `get_competitor_comparison`.- **`list_citations`** — which domains and URLs AI cites alongside thebrand, classified by source type (news, review, owned, social, forum,competitor, you). Filter with `source_filter`: `all`, `owned`,`competitor` or `external`.- **`get_ai_traffic`** — visits referred by AI engines: per platform,top landing pages, countries.+- **`list_reports`** — the brand's saved reports, newest first: `id`,+ `title`, `template`, `date_from` / `date_to` and `created_at`.+ `limit` (default 50, max 100).+- **`get_report`** — one saved report in full, with its stored+ `payload`. It doesn't regenerate: the numbers are its own window's,+ as they were when it was made, so don't quote them as today's.**Mentions & sentiment**@@ -201,6 +214,20 @@ answers; no LLM is called.- **`list_topic_suggestions`** — pending AI topic suggestions.**`accept_topic_suggestion`** / **`dismiss_topic_suggestion`** act onone *(writes)*.+- **`list_prompt_suggestions`** — pending AI prompt suggestions:+ `suggested_text`, topic, `reason`, `est_volume`, `relevance`,+ `generated_at` and `expires_at`, with `stale: true` when there are+ none or all have expired. `est_volume` is an AI guess, not a+ measurement: quote it as low confidence, likely anywhere from half to+ twice the number. New suggestions are generated in the dashboard, not+ over MCP.+- **`accept_prompt_suggestion`** — tracks one as a new active prompt,+ on the platforms and models of the brand's latest active prompt+ (ChatGPT when there is none) that the plan allows, in the brand's own+ location. It uses one prompt location: with none left it fails with+ the plan-limit message *(write)*.+- **`dismiss_prompt_suggestion`** — hides one from future suggestion+ lists *(write)*.**Content & pages**@@ -218,6 +245,56 @@ answers; no LLM is called.- **`run_site_audit`** — audit a URL. Uses a monthly credit and runs~30s; poll `get_site_audit` *(write)*.+**Content Editor**++Drafts are read and written as a person would in the editor. Ansvisor+never publishes, and a suggestion is never applied until a person+accepts it.++- **`list_content_drafts`** — the brand's drafts, latest changed first+ (up to 100): `title`, `status` (`draft`, `in_review`, `ready`,+ `published`), `method` (`create` a new page, or `optimize` the live+ page at `source_url`), `page_type`, `author` (`user` or `agent`),+ `open_suggestions` (how many wait for review) and `editor_path`.+ Filter: `status`.+- **`get_content_draft`** — one draft: `body_html`, the page as+ numbered `passages` (`locked: true` = AI answers quote it today), the+ Action Center `action` it belongs to, the `open_suggestions` still+ waiting, and `link_targets` (`own_pages`, `sources`): the only URLs a+ suggestion may link to.+- **`get_content_sources`** — what the draft draws on over 30 days, as+ the Sources tab shows it: its prompts, the AI searches (fan-outs) run+ for them, the pages AI cites, Search Console queries, and the+ person's `choices` (sources left out or added).+- **`get_content_impact`** — what the draft's live page earns over+ `days` (7, 30, 90 or 365; default 30) against the period before, as+ the Live page tab reads it: `citations`, `aiVisits` and `gscClicks`+ (`cur` / `prev`), `promptCounts` (`cur`, `prev`, `lost`), the+ `prompts` citing it, and `overlap` (the brand's other pages cited for+ the same prompts). A draft of a new page, not live yet, has none.+- **`create_content_draft`** — write a new draft as the agent: `title`,+ `body_html` (starting with its H1), `method` (`create` by default, or+ `optimize` with a `source_url` on the brand's domains), optional+ `page_type` (detected when left out) and `prompt_ids`. It goes to the+ Library's **In review** for a person *(write)*.+- **`add_content_source`** — add a source, as the Sources tab's Add+ does: `kind` `prompt` (`ref` = a tracked prompt's id), `cited_page`+ (an http(s) address) or `gsc_query` (a Search Console query)+ *(write)*.+- **`suggest_content_changes`** — leave up to 20 suggestions on a draft+ for a person to accept or reject. Each names a `passage` number from+ `get_content_draft`: a `replace` (`before` copied exactly, `after` as+ plain text) or an `insert` after it (`after` as simple HTML), with a+ short `reason`. You write them: Ansvisor calls no LLM. Ones the editor+ can't apply come back in `dropped` with the reason *(write)*.+- **`set_content_draft_ready`** — sets the status as the editor's **Mark+ ready** does: a `draft` becomes `ready` and History keeps it as a+ version. It skips the editor's Before you publish check (its Trust+ warning), so point the person to it with `editor_path` first. A linked+ action's writing task completes once every page the action names has a+ ready draft (`action_tasks_done`; 0 until then). A draft `in_review`+ waits for a person to mark it ready in the editor *(write)*.+**Shopping**- **`list_shopping_cards`** — products AI engines show in shopping@@ -246,8 +323,18 @@ answers; no LLM is called.`details` also has `sent_to_content` and `sent_to_webhook`: where thetask was sent.+ When some of what the action is about was removed since it was made+ (a prompt deleted or paused, a competitor deleted), its `payload`+ reads the count left: `targetCount` (of `targetEntity`) is what is+ still there, `createdTargetCount` the count it was made with, and+ `removedCount` and `removedLabels` (up to 20 names) what went. A+ priority `reason` or task title that counted them counts what is+ left. Quote the count left, and say how many were removed.+With `format: "markdown"` it returns the action as the dashboard's- **Copy Data** writes it; `format: "csv"` returns its **Export CSV**.+ **Copy Data** writes it, its **Affected** list being what the action+ is about less what was removed since; `format: "csv"` returns its+ **Export CSV**, a row per affected item, task and signal.- **`list_signals`** — detected changes, newest first. Each signal has:- `where`: the prompt, topic, platforms, locations, domain, competitoror pages it is about;@@ -404,7 +491,8 @@ or any "do I have gaps" question:4. Empty topics are often the biggest unlock — point at them first.`list_topic_suggestions` may already hold ideas; offer to accept one- rather than inventing topics.+ rather than inventing topics. The same goes for prompts with+ `list_prompt_suggestions` (workflow 11).5. `get_prompt_volumes` tells you which prompts carry real demand —use it to say which gaps matter most. Quote the estimated range, andlean less on `low`-confidence rows.@@ -536,6 +624,50 @@ When the user asks how AI describes the brand, why sentiment moved[`references/sentiment-interpretation.md`](references/sentiment-interpretation.md)for when a sentiment move matters and when it's noise.+### 11. Prompt suggestions ("what should we start tracking?")++1. Call `list_prompt_suggestions(brand_id)`. With `stale: true` there is+ nothing current to offer: new suggestions are generated in the+ dashboard, not over MCP.+2. Show the best few: text, topic, `reason`, and `est_volume` as a+ rough AI guess, never as measured demand.+3. Call `get_prompt_usage` first: each accepted suggestion uses one+ prompt location (see workflow 5, step 6).+4. Act only on the suggestions the user names, after they confirm:+ `accept_prompt_suggestion` starts tracking one,+ `dismiss_prompt_suggestion` hides it *(writes)*. If an accept fails+ with the plan-limit message, relay it as it is.+5. Report the prompts added (`prompt_text`).++### 12. Content Editor drafts ("what's waiting in the editor?")++1. Call `list_content_drafts`. Lead with the drafts a person has to act+ on: `in_review`, or with `open_suggestions`.+2. For one draft, call `get_content_draft` (its passages and open+ suggestions) and `get_content_sources` (what it draws on).+3. When the user wants a prompt, a cited page or a Search Console query+ added to its sources, confirm it and call `add_content_source`+ *(write)*.+4. When they want changes suggested, write them from the draft and its+ sources, show them, and send them with `suggest_content_changes` only+ after they confirm *(write)*. Never touch a `locked` passage, and+ link only to `link_targets`. It is refused on a published draft,+ while a person still has open suggestions on it, or while the+ Content Agent is writing it: say so and stop. Report how many were+ kept and any `dropped`.+5. When the user says the draft is done, give them its `editor_path` to+ run Before you publish, then offer `set_content_draft_ready` and call+ it after they confirm *(write)*. A draft `in_review` is marked ready+ by a person in the editor.+6. Once the page is live, `get_content_impact` (30 days by default)+ says whether it paid off: lead with `citations` and `aiVisits`+ (`cur` vs `prev`), then `promptCounts.lost`. `gscSince` is the first+ day of Search Console data (null: none); when it falls after the+ period before began, the Google clicks don't compare. The windows are+ the last `days` against the `days` before, not before and after the+ page went live: pick the period closest to how long it has been live,+ and say so.+## Formatting principles- **Lead with the number, then the meaning.** Don't bury the score in a