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 Mentions & Sentiment tools (#1127)
Cihan5a97fee0ce2a
diff --git a/skills/README.md b/skills/README.mdindex b0b8ac4ed..42eb5e271 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). 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, 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-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?@@ -89,11 +89,13 @@ Once installed, just ask in plain English:- _"Which sites does AI cite instead of us?"_- _"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?"_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 Improve-suggestions to Action Center, running a page audit) are only used when+suggestions to Action Center, running a page audit, correcting a+response's sentiment) are only used whenyou ask for that specific change.## Contributingdiff --git a/skills/ansvisor-aeo-coach-standalone/SKILL.md b/skills/ansvisor-aeo-coach-standalone/SKILL.mdindex 9ce1e56c8..85de3db43 100644--- a/skills/ansvisor-aeo-coach-standalone/SKILL.md+++ b/skills/ansvisor-aeo-coach-standalone/SKILL.md@@ -6,10 +6,10 @@ description: |server (e.g. claude.ai web without a Connector configured). Fetcheslive data from the Ansvisor REST API directly with the user's APIkey via code execution — visibility, competitors, citations, prompts,- content gaps, page audits and the Action Center. For clients that- support MCP (Claude Desktop, Claude Code, Cursor, Zed), prefer the- `ansvisor-aeo-coach` skill — it's a cleaner UX because tool calls are- first-class instead of inline Python.+ content gaps, page audits, the Action Center, and mentions and+ sentiment. For clients that support MCP (Claude Desktop, Claude Code,+ Cursor, Zed), prefer the `ansvisor-aeo-coach` skill — it's a cleaner+ UX because tool calls are first-class instead of inline Python.---# Ansvisor AEO Coach — Standalone@@ -32,6 +32,8 @@ Activate this skill when the user asks anything in the shape of:- _"Did anything change recently?" / "Why did visibility drop?"_- _"Who are my competitors right now?" / "How do we compare?"_- _"Which sites does AI cite for us?"_+- _"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?"_- _"Give me a daily / weekly standup on `<brand name>`."_@@ -72,6 +74,32 @@ Hold it in execution memory for the session.- `totals.avgVisibility` and each competitor's `avgVisibility` are**deprecated** legacy averages. Don't quote them.+**Mentions & sentiment** (from the Mentions tools below):++- **Mentions**, as the page's _Total mentions_ counts them, are every+ time AI names the brand (`timesNamed`), twice in one response+ included: quote this one for "how many mentions". `mentions` is the+ responses naming the brand at least once: the base of the **mention+ rate** (their share of the tracked responses, `%`), net sentiment and+ `lowSample`.+- **Net sentiment** is the positive share minus the negative share of+ the responses naming the brand, from −100 to +100. Quote it as a+ signed number **without a % sign** ("net +21"). Neutral counts in the+ total.+- `changes` are taken as the page's cards take them: on the prompts+ both windows answered (`changes.basis.sharedPrompts`), so adding or+ removing prompts doesn't read as a rise or a fall. The `current` and+ `previous` figures are the whole windows', so quote `changes` rather+ than working a change out from them, and say how many prompts were+ new or dropped (`newPrompts`, `droppedPrompts`) when there were some.+ `changes.mentionsPct` is the change in times named.+- `lowSample: true` means fewer than 20 responses naming the brand.+ Say so, and don't read a change into it: `changes.netSentimentPoints`+ is already `null` there, as is the mention rate's change when either+ window has under 20 tracked responses.+- Sentiment is measured for the **brand only**. Competitors have+ mentions and co-mentions, not a tone.+## Endpoints availableAll paths below are under `{base_url}/api/mcp` and need the header@@ -90,6 +118,22 @@ mirrors the MCP tool of the same purpose and returns the same data.| `GET /citations` | `brand_id`, dates, `model`, `region`, `topic_id`, `limit`, `source_filter` (`all`/`owned`/`competitor`/`external`) | source-type breakdown, top domains and URLs || `GET /ai-traffic` | `brand_id`, dates | AI-referred visits per platform, landing pages, countries |+**Mentions & sentiment**++These take the Mentions page's filters: `brand_id`, `date_from` /+`date_to` (the last 30 days when left out), `platform` (e.g.+`gemini-web`), `region`, `topic_id` and `search` over the prompts'+text. They read the stored answers; no LLM is called.++| Endpoint | Query / body | Returns |+| --- | --- | --- |+| `GET /mentions/summary` | the filters | the Overview: `current` and `previous` (times named, mentions, mention rate, prompts with mentions, average position, `sentiment` with `net` and `lowSample`), `changes` with their `basis`, `headline` (the platform that moved net sentiment most, competitors named beside the brand), `platforms[]`, `daily[]` |+| `GET /mentions` | the filters, `sentiment`, `competitor_id` (`none` = no competitor), `sort` (`newest`/`oldest`/`co_mentions`/`negative`), `page` | `{ total, prompts, page, pageSize, mentions: [...] }`: 100 a page, each with sentiment, position, competitors in the same response and an `excerpt` |+| `GET /mentions/{id}` | — | one response in full: text, citations, competitors named, sentiment, latest correction |+| `GET /mentions/competitors` | the filters | each competitor's mentions, share of responses, change, and `sameResponseAsYou` |+| `GET /mentions/perception` | the filters | `brandTerms`, `attributes` (each entity's share, in `entities` order), `coMentions`, `biggestGap` |+| `POST /mentions/{id}/sentiment-override` *(write)* | `{ sentiment, note }`: `positive`, `neutral` or `negative` | the correction; needs an admin or manager key |+**Prompts & topics**| Endpoint | Query / body | Returns |@@ -415,6 +459,50 @@ work:3. Summarise: how many improved, how many didn't move, and what theimproved ones had in common.+### 10. Mentions & sentiment ("how is AI talking about us?")++When the user asks how AI describes the brand, why sentiment moved+(_"why did sentiment drop on Gemini?"_), or what AI associates with it:++1. Call `GET /mentions/summary` for the window (30 days when `date_from`+ is left out). Lead with `current.sentiment.net` and+ `changes.netSentimentPoints`, then times named and mention rate.+2. Find **where**: `headline.mover` names the platform that moved net+ sentiment most (with its `change`); `platforms[]` has each one's+ `netSentiment` and `netSentimentChange`. Skip platforms marked+ `lowSample`.+3. Find **why**: call `GET /mentions` with that `platform` and+ `sentiment: "negative"` (or `sort: "negative"`) and quote one or two+ `excerpt`s, so the user sees what AI actually said. Call+ `GET /mentions/{id}` for the full response and its citations when an+ excerpt isn't enough.+4. For **who AI names beside the brand**, use+ `GET /mentions/competitors` (`sameResponseAsYou`,+ `mentionsChangePct`); for **what AI associates with it**,+ `GET /mentions/perception`: `brandTerms` with their `sharePct`, and+ `biggestGap`, an attribute a competitor owns and the brand doesn't+ (null when none leads by 20+ points, or when the brand or the leading+ competitor has fewer than 20 mentions).+5. Report it like this:++ > **`<brand_name>` — how AI talks about you, last 30 days**+ >+ > Net sentiment **`<+n>`** (Δ `<±n>`), named in **`<rate>%`** of+ > **`<n>`** tracked responses+ > Most of the move is on **`<platform>`** (`<±n>`): _"`<excerpt>`"_+ >+ > **What it means:** `<one sentence>`+ > **Next:** `<one suggestion>`++6. If the user says a response's sentiment is wrong, offer+ `POST /mentions/{id}/sentiment-override` with the right sentiment and+ a short note, and call it only after they confirm. It needs an admin+ or manager key, and every figure follows the corrected tone+ *(write)*.+7. See+ [`references/sentiment-interpretation.md`](references/sentiment-interpretation.md)+ for when a sentiment move matters and when it's noise.+## Formatting principles- **Lead with the number, then the meaning.** Don't bury the score in a@@ -452,6 +540,8 @@ work:- `401 Invalid API key` → ask the user to regenerate from Settings →API Keys.+- `403` on a sentiment correction → the key's user isn't an admin or+ manager of the brand's organization. Say so; don't retry.- `404 ... not found` → the id doesn't belong to the authenticateduser's organization. Re-run `GET /brands` (or the matching listendpoint) to get the right id.diff --git a/skills/ansvisor-aeo-coach-standalone/references/sentiment-interpretation.md b/skills/ansvisor-aeo-coach-standalone/references/sentiment-interpretation.mdindex 48f24fb9d..2cbb88638 100644--- a/skills/ansvisor-aeo-coach-standalone/references/sentiment-interpretation.md+++ b/skills/ansvisor-aeo-coach-standalone/references/sentiment-interpretation.md@@ -5,6 +5,28 @@ Sentiment is **not** part of the visibility score (see[`visibility-scoring.md`](visibility-scoring.md)), but it's the loudest**signal** about why a number changed.+## Net sentiment (Mentions & Sentiment)++The Mentions tools add up the tags over the responses that name the+brand:++- **Net sentiment** = positive share − negative share, from −100 to+ +100. Quote it signed, without a % sign: "net +21". +20 with 40%+ positive and 20% negative reads very differently from +20 with 20%+ positive and 0% negative, so give the split when it matters.+- **Low sample:** under 20 responses naming the brand, a figure+ carries `lowSample: true` and its change is `null`. Say "low sample,+ n = 12" and don't compare it with another window.+- **Per platform:** each platform has its own net. A platform with a+ much lower net than the rest is where to look first. Two platforms+ 40+ points apart usually describe the brand differently, which is+ worth quoting from `list_mentions` (`GET /mentions`) excerpts.+- **Corrections:** a person can mark a response's sentiment as wrong.+ The corrected tone counts everywhere, and `get_mention`+ (`GET /mentions/{id}`) shows who corrected it and why.+- **Brand only:** competitors have no sentiment yet. Don't describe a+ competitor's tone.+## Three rules of thumb1. **No mention = no sentiment.** If `mention_count = 0`, sentiment is@@ -31,8 +53,10 @@ Sentiment is **not** part of the visibility score (see## When sentiment is noise-- **Small `resultCount` (< 10).** A single negative response moves the- average disproportionately. Caveat the answer.+- **Small samples.** Under 20 responses naming the brand+ (`lowSample`), or a `resultCount` under 10 elsewhere, a single+ negative response moves the figure disproportionately. Caveat the+ answer.- **Brand-comparison prompts.** "Should I use X or Y?" answers oftenread as neutral-negative for both brands because the AI is beingeven-handed. Don't treat that as a reputation problem.diff --git a/skills/ansvisor-aeo-coach/SKILL.md b/skills/ansvisor-aeo-coach/SKILL.mdindex 0d066f4d3..19902bcfe 100644--- a/skills/ansvisor-aeo-coach/SKILL.md+++ b/skills/ansvisor-aeo-coach/SKILL.md@@ -6,9 +6,11 @@ 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). Uses the- Ansvisor MCP server tools (`list_brands`, `get_visibility_summary`,- `get_competitor_comparison`, `list_actions`, …) to fetch the data,+ 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`,+ `get_visibility_summary`, `get_competitor_comparison`,+ `get_mentions_summary`, `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@@ -37,6 +39,8 @@ Activate this skill when the user asks anything in the shape of:- _"Did anything change recently?" / "Why did visibility drop?"_- _"Who are my competitors right now?" / "How do we compare?"_- _"Which sites does AI cite for us?"_+- _"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?"_- _"Give me a daily / weekly standup on `<brand name>`."_@@ -67,6 +71,32 @@ API directly from this skill (that's a different skill).- `totals.avgVisibility` and each competitor's `avgVisibility` are**deprecated** legacy averages. Don't quote them.+**Mentions & sentiment** (from the Mentions tools below):++- **Mentions**, as the page's _Total mentions_ counts them, are every+ time AI names the brand (`timesNamed`), twice in one response+ included: quote this one for "how many mentions". `mentions` is the+ responses naming the brand at least once: the base of the **mention+ rate** (their share of the tracked responses, `%`), net sentiment and+ `lowSample`.+- **Net sentiment** is the positive share minus the negative share of+ the responses naming the brand, from −100 to +100. Quote it as a+ signed number **without a % sign** ("net +21"). Neutral counts in the+ total.+- `changes` are taken as the page's cards take them: on the prompts+ both windows answered (`changes.basis.sharedPrompts`), so adding or+ removing prompts doesn't read as a rise or a fall. The `current` and+ `previous` figures are the whole windows', so quote `changes` rather+ than working a change out from them, and say how many prompts were+ new or dropped (`newPrompts`, `droppedPrompts`) when there were some.+ `changes.mentionsPct` is the change in times named.+- `lowSample: true` means fewer than 20 responses naming the brand.+ Say so, and don't read a change into it: `changes.netSentimentPoints`+ is already `null` there, as is the mention rate's change when either+ window has under 20 tracked responses.+- Sentiment is measured for the **brand only**. Competitors have+ mentions and co-mentions, not a tone.+## Tools available (from the Ansvisor MCP server)Every tool except `list_brands` and `get_site_audit_quota` needs a@@ -93,6 +123,36 @@ timestamps (`date_from` / `date_to`).- **`get_ai_traffic`** — visits referred by AI engines: per platform,top landing pages, countries.+**Mentions & sentiment**++These take the Mentions page's filters: `date_from` / `date_to` (the+last 30 days when left out), `platform` (e.g. `gemini-web`), `region`,+`topic_id` and `search` over the prompts' text. They read the stored+answers; no LLM is called.++- **`get_mentions_summary`** — the Overview: `current` and `previous`+ times named, mentions, mention rate, prompts with mentions, average+ position and `sentiment` (counts, shares, `net`, `lowSample`);+ `changes` with their `basis`; the+ platform that moved net sentiment most and the competitors named+ beside the brand (`headline`); `platforms[]`; `daily[]`.+- **`list_mentions`** — the responses naming the brand, 100 a page,+ each with sentiment, position, the competitors in the same response+ and an `excerpt`. Filters: `sentiment`, `competitor_id` (`none` for+ responses naming no competitor), `sort` (`newest`, `oldest`,+ `co_mentions`, `negative`), `page`.+- **`get_mention`** — one response in full by its `id`: text,+ citations, competitors named, sentiment and its latest correction.+- **`get_mention_competitors`** — each competitor's mentions, share of+ responses, change, and how often it shares a response with the brand+ (`sameResponseAsYou`).+- **`get_mentions_perception`** — what AI associates with the brand:+ `brandTerms`, `attributes` (each entity's share, in `entities`+ order), `coMentions` and `biggestGap`.+- **`override_mention_sentiment`** — "Sentiment is wrong": correct one+ response's sentiment, with an optional `note`. Needs an admin or+ manager key *(write)*.+**Prompts & topics**- **`list_topics`** — topics with `prompt_count` each. First call for@@ -411,6 +471,48 @@ work:3. Summarise: how many improved, how many didn't move, and what theimproved ones had in common.+### 10. Mentions & sentiment ("how is AI talking about us?")++When the user asks how AI describes the brand, why sentiment moved+(_"why did sentiment drop on Gemini?"_), or what AI associates with it:++1. Call `get_mentions_summary` for the window (30 days when `date_from`+ is left out). Lead with `current.sentiment.net` and+ `changes.netSentimentPoints`, then times named and mention rate.+2. Find **where**: `headline.mover` names the platform that moved net+ sentiment most (with its `change`); `platforms[]` has each one's+ `netSentiment` and `netSentimentChange`. Skip platforms marked+ `lowSample`.+3. Find **why**: call `list_mentions` with that `platform` and+ `sentiment: "negative"` (or `sort: "negative"`) and quote one or two+ `excerpt`s, so the user sees what AI actually said. Call+ `get_mention` for the full response and its citations when an excerpt+ isn't enough.+4. For **who AI names beside the brand**, use `get_mention_competitors`+ (`sameResponseAsYou`, `mentionsChangePct`); for **what AI associates+ with it**, `get_mentions_perception`: `brandTerms` with their+ `sharePct`, and `biggestGap`, an attribute a competitor owns and the+ brand doesn't (null when none leads by 20+ points, or when the brand+ or the leading competitor has fewer than 20 mentions).+5. Report it like this:++ > **`<brand_name>` — how AI talks about you, last 30 days**+ >+ > Net sentiment **`<+n>`** (Δ `<±n>`), named in **`<rate>%`** of+ > **`<n>`** tracked responses+ > Most of the move is on **`<platform>`** (`<±n>`): _"`<excerpt>`"_+ >+ > **What it means:** `<one sentence>`+ > **Next:** `<one suggestion>`++6. If the user says a response's sentiment is wrong, offer+ `override_mention_sentiment` with the right sentiment and a short+ note, and call it only after they confirm. It needs an admin or+ manager key, and every figure follows the corrected tone *(write)*.+7. See+ [`references/sentiment-interpretation.md`](references/sentiment-interpretation.md)+ for when a sentiment move matters and when it's noise.+## Formatting principles- **Lead with the number, then the meaning.** Don't bury the score in adiff --git a/skills/ansvisor-aeo-coach/references/sentiment-interpretation.md b/skills/ansvisor-aeo-coach/references/sentiment-interpretation.mdindex 48f24fb9d..2cbb88638 100644--- a/skills/ansvisor-aeo-coach/references/sentiment-interpretation.md+++ b/skills/ansvisor-aeo-coach/references/sentiment-interpretation.md@@ -5,6 +5,28 @@ Sentiment is **not** part of the visibility score (see[`visibility-scoring.md`](visibility-scoring.md)), but it's the loudest**signal** about why a number changed.+## Net sentiment (Mentions & Sentiment)++The Mentions tools add up the tags over the responses that name the+brand:++- **Net sentiment** = positive share − negative share, from −100 to+ +100. Quote it signed, without a % sign: "net +21". +20 with 40%+ positive and 20% negative reads very differently from +20 with 20%+ positive and 0% negative, so give the split when it matters.+- **Low sample:** under 20 responses naming the brand, a figure+ carries `lowSample: true` and its change is `null`. Say "low sample,+ n = 12" and don't compare it with another window.+- **Per platform:** each platform has its own net. A platform with a+ much lower net than the rest is where to look first. Two platforms+ 40+ points apart usually describe the brand differently, which is+ worth quoting from `list_mentions` (`GET /mentions`) excerpts.+- **Corrections:** a person can mark a response's sentiment as wrong.+ The corrected tone counts everywhere, and `get_mention`+ (`GET /mentions/{id}`) shows who corrected it and why.+- **Brand only:** competitors have no sentiment yet. Don't describe a+ competitor's tone.+## Three rules of thumb1. **No mention = no sentiment.** If `mention_count = 0`, sentiment is@@ -31,8 +53,10 @@ Sentiment is **not** part of the visibility score (see## When sentiment is noise-- **Small `resultCount` (< 10).** A single negative response moves the- average disproportionately. Caveat the answer.+- **Small samples.** Under 20 responses naming the brand+ (`lowSample`), or a `resultCount` under 10 elsewhere, a single+ negative response moves the figure disproportionately. Caveat the+ answer.- **Brand-comparison prompts.** "Should I use X or Y?" answers oftenread as neutral-negative for both brands because the AI is beingeven-handed. Don't treat that as a reputation problem.