Skip to content

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.

docs(skills): cover all MCP tools and the AI Visibility Score in the AEO coach skills (#1033)

Cihan02551dc5c442
diff --git a/skills/README.md b/skills/README.md
index 2f6555422..b0b8ac4ed 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. 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). 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?
@@ -86,10 +86,15 @@ Once installed, just ask in plain English:
- _"How is my brand doing this week?"_
- _"Why did visibility drop on ChatGPT?"_
- _"Who are my biggest competitors right now?"_
+- _"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."_
Claude picks the right tools / endpoints, fills in filters, interprets
-the numbers, and answers with action items.
+the numbers, and answers with action items. Tools that change your
+account (accepting a suggestion, updating a task, sending Improve
+suggestions to Action Center, running a page audit) are only used when
+you ask for that specific change.
## Contributing
diff --git a/skills/ansvisor-aeo-coach-standalone/SKILL.md b/skills/ansvisor-aeo-coach-standalone/SKILL.md
index cdd9f14b2..c144893b6 100644
--- a/skills/ansvisor-aeo-coach-standalone/SKILL.md
+++ b/skills/ansvisor-aeo-coach-standalone/SKILL.md
@@ -5,10 +5,11 @@ description: |
when the user's Claude client cannot connect to the Ansvisor MCP
server (e.g. claude.ai web without a Connector configured). Fetches
live data from the Ansvisor REST API directly with the user's API
- key via code execution. 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.
+ key 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.
---
# Ansvisor AEO Coach — Standalone
@@ -30,6 +31,8 @@ Activate this skill when the user asks anything in the shape of:
- _"What's my visibility on ChatGPT this week?"_
- _"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?"_
+- _"What should we work on next?" / "Did last month's work pay off?"_
- _"Give me a daily / weekly standup on `<brand name>`."_
## Setup (first use)
@@ -48,73 +51,90 @@ You need two things from the user, in this order:
acknowledge receipt and **do not echo it back** in subsequent responses.
Hold it in execution memory for the session.
-## Endpoints available
-
-All requests go to `{base_url}/api/mcp/...` with header
-`Authorization: Bearer {api_key}`.
-
-### `GET /api/mcp/brands`
-
-Returns the brands the authenticated user can access.
-
-```json
-{ "brands": [
- { "id": "uuid", "name": "Acme", "slug": "acme",
- "industry": "saas", "region": "US", "created_at": "..." }
-] }
-```
-
-### `GET /api/mcp/visibility-summary`
-
-Required query: `brand_id`. Optional: `date_from`, `date_to` (ISO
-timestamps), `model` (slug or comma-separated slugs), `region`.
-
-```json
-{
- "brand": { "id": "uuid", "name": "Acme" },
- "totals": {
- "resultCount": 142,
- "avgVisibility": 58.3,
- "totalMentions": 311,
- "totalCitations": 47
- },
- "topCompetitors": [
- { "name": "CompetitorX", "mentions": 184, "avgVisibility": 62.1 }
- ]
-}
-```
-
-### `GET /api/mcp/topics`
-
-Required query: `brand_id`. Returns topics on the brand with prompt
-counts. Use for coverage audits.
-
-```json
-{ "topics": [
- { "id": "uuid", "name": "Pricing", "is_active": true,
- "prompt_count": 6, "created_at": "..." }
-] }
-```
-
-### `GET /api/mcp/prompts`
+## The numbers that matter
+
+- **Visibility** is `totals.aiVisibilityScore` from
+ `GET /visibility-summary`: a 0–100 score, the same number the
+ dashboard shows everywhere. Quote it **without a % sign**. It blends
+ three shares of the tracked answers: how often the brand is
+ **mentioned** (60%), how often its own domain is **cited** (25%), and
+ how **early** it is named (15%). See
+ [`references/visibility-scoring.md`](references/visibility-scoring.md).
+- Its components come with it: `totals.mentionAnswers`,
+ `totals.citationAnswers` and `totals.positionFactor` (1 = always named
+ first), out of `totals.resultCount` answers.
+- **Coverage** is `totals.visibilityRatePct`: the share of tracked
+ prompts the brand appeared in at all (`visiblePrompts / promptCount`).
+ It is a percentage — quote it with `%`.
+- **Competitors** in `topCompetitors[]` carry a `score` on the same
+ scale and denominator as the brand's `aiVisibilityScore`, so the two
+ compare directly.
+- `totals.avgVisibility` and each competitor's `avgVisibility` are
+ **deprecated** legacy averages. Don't quote them.
-Required query: `brand_id`. Optional: `topic_id`, `is_active`
-(`true`/`false`), `limit` (default 100, max 500).
-
-```json
-{ "prompts": [
- { "id": "uuid", "text": "best ai for ...",
- "topic_id": "uuid", "topic_name": "Comparisons",
- "platforms": ["chatgpt", "perplexity"],
- "models": ["gpt-5-5"], "regions": ["US", "TR"],
- "is_active": true, "created_at": "..." }
-] }
-```
-
-### `GET /api/mcp/whoami` (optional sanity check)
+## Endpoints available
-Returns `{ userId, email, organizationId }`. Use to confirm the key
-works if a call fails unexpectedly.
+All paths below are under `{base_url}/api/mcp` and need the header
+`Authorization: Bearer {api_key}`. GET filters go in the query string;
+POST / PATCH bodies are JSON. Dates are ISO timestamps. Each endpoint
+mirrors the MCP tool of the same purpose and returns the same data.
+
+**Brand & visibility**
+
+| Endpoint | Query / body | Returns |
+| --- | --- | --- |
+| `GET /brands` | — | `{ brands: [...] }` — always call first to resolve a `brand_id` |
+| `GET /visibility-summary` | `brand_id`, `date_from`, `date_to`, `model`, `region` | `{ brand, totals, topCompetitors }` (see above) |
+| `GET /visibility-trend` | `brand_id`, `granularity` (`day`/`week`), dates, `model`, `region`, `topic_id` | buckets over time, with an average competitor score |
+| `GET /competitor-comparison` | `brand_id`, dates, `model`, `region`, `topic_id` | per-entry `visibility_rate_pct`, mentions, citations, share of voice, split per model and platform |
+| `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 |
+
+**Prompts & topics**
+
+| Endpoint | Query / body | Returns |
+| --- | --- | --- |
+| `GET /topics` | `brand_id` | `{ topics: [...] }` with `prompt_count` |
+| `GET /prompts` | `brand_id`, `topic_id`, `is_active`, `limit` (default 100, max 500) | `{ prompts: [...] }` |
+| `GET /prompt-performance` | `brand_id`, dates, `topic_id`, `sort_by` (`visibility`/`mentions`/`citations`/`appearances`), `order`, `limit`, `model`, `region` | per-prompt visibility, mentions, citations, competitor score |
+| `GET /prompt-volumes` | `brand_id`, `limit` | `{ volumes: [...] }` — Google volumes, `est_ai_volume`, competition |
+| `GET /topic-suggestions` | `brand_id` | `{ suggestions: [...] }` pending topic ideas |
+| `POST /topic-suggestions/{id}/accept` *(write)* | — | creates one topic |
+| `POST /topic-suggestions/{id}/dismiss` *(write)* | — | hides the suggestion |
+
+**Content & pages**
+
+| Endpoint | Query / body | Returns |
+| --- | --- | --- |
+| `GET /content-opportunities` | `brand_id`, `status`, `impact`, `type`, `limit` | `{ opportunities: [...] }` ranked by score |
+| `GET /content-opportunities/{id}` | — | `{ opportunity }` incl. an existing brief |
+| `POST /content-opportunities/{id}/brief` *(write, LLM call)* | — | a fresh brief, overwriting the old one |
+| `PATCH /content-opportunities/{id}/status` *(write)* | `{ status }`: `new`, `reviewed`, `sent`, `in_progress`, `done`, `dismissed` | the updated row |
+| `GET /site-audits/quota` | — | `{ used, limit, remaining }` (`-1` = unlimited) |
+| `GET /site-audits` | `brand_id` | recent audits |
+| `GET /site-audits/{id}` | — | one audit: scores, signals, fixes |
+| `POST /site-audits` *(write, uses a credit)* | `{ brand_id, url }` | a `running` audit; poll `GET /site-audits/{id}` (~30s) |
+
+**Shopping**
+
+| Endpoint | Query / body | Returns |
+| --- | --- | --- |
+| `GET /shopping-cards` | `brand_id`, `role` (`own`/`competitor`/`other`), `platform`, `region`, `limit`, `cursor` | products shown in shopping answers |
+| `GET /product-visibility` | `brand_id`, `product_title` | `{ visibility }` for one product |
+
+**Action Center**
+
+| Endpoint | Query / body | Returns |
+| --- | --- | --- |
+| `GET /actions` | `brand_id`, `status`, `category`, `limit` | `{ actions: [...] }` open work with impact and task progress |
+| `GET /actions/{id}` | — | one action: payload, signals, tasks (`mode`, `permission`), events |
+| `GET /signals` | `brand_id`, `status`, `kind`, `limit` | `{ signals: [...] }` detected changes |
+| `GET /action-history` | `brand_id`, `limit` | `{ actions: [...] }` closed, with `outcome` and `results` |
+| `PATCH /action-tasks/{id}/status` *(write)* | `{ status, skip_reason }`: `in_progress`, `completed`, `skipped` (reason required), `failed` | the updated task |
+| `POST /prompts/{id}/improve-action` *(write)* | `{ range: { preset, from, to, region }, idempotency_key, suggestions: [...] }` — see workflow 8 | `{ actionId, actionNo, created, taskCount }` |
+
+**Other:** `GET /whoami` returns `{ userId, email, organizationId }`.
+Use it to confirm the key works if a call fails unexpectedly.
## How to make the calls
@@ -127,56 +147,68 @@ import urllib.request, urllib.parse, json
BASE_URL = "https://app.ansvisor.com" # ask the user if self-hosted
API_KEY = "ans_..." # from user, do not log
-def call(path, params=None):
- url = f"{BASE_URL}{path}"
+def call(path, params=None, method="GET", body=None):
+ url = f"{BASE_URL}/api/mcp{path}"
if params:
url += "?" + urllib.parse.urlencode(
{k: v for k, v in params.items() if v is not None}
)
+ data = json.dumps(body).encode() if body is not None else None
req = urllib.request.Request(
- url, headers={"Authorization": f"Bearer {API_KEY}"}
+ url, data=data, method=method,
+ headers={"Authorization": f"Bearer {API_KEY}",
+ "Content-Type": "application/json"},
)
- with urllib.request.urlopen(req, timeout=15) as r:
+ with urllib.request.urlopen(req, timeout=30) as r:
return json.loads(r.read())
```
Then for example:
```python
-brands = call("/api/mcp/brands")["brands"]
-summary = call("/api/mcp/visibility-summary",
+brands = call("/brands")["brands"]
+summary = call("/visibility-summary",
{"brand_id": brands[0]["id"], "date_from": "2026-05-09T00:00:00Z"})
```
If a request returns a non-2xx status, the response body usually has an
`error` field — relay it to the user instead of guessing.
+## Writes need explicit intent
+
+Endpoints marked *(write)* change the user's account, spend a credit or run
+an LLM. Call one **only** when the user asked for that specific change
+(this suggestion, this task, this URL) — never while exploring, never
+"to be helpful". Say what you are about to do in one line first. The
+change is logged under the API key's user.
+
## Core workflows
### 1. Brand snapshot ("how am I doing?")
When the user asks for a general status check:
-1. If they didn't name a brand, call `/api/mcp/brands`. If there's only
+1. If they didn't name a brand, call `GET /brands`. If there's only
one, use it silently. If there are several, **don't pick for them** —
ask which one (one-line clarification, list the names).
-2. Call `/api/mcp/visibility-summary` with **no date filter first** —
- this gives the all-time baseline.
-3. Call it again with `date_from` set to **7 days ago** in ISO format
- (`datetime.now(timezone.utc) - timedelta(days=7)` then `.isoformat()`)
- to get "this week's" view.
-4. Compute the delta yourself: this week's `avgVisibility` minus
- all-time `avgVisibility`. Same for mentions.
+2. Call `GET /visibility-summary` with `date_from` set to **7 days ago**
+ (ISO format, e.g. `new Date(Date.now() - 7*24*60*60*1000).toISOString()`)
+ for "this week".
+3. Call it again for the **previous 7 days** (`date_from` 14 days ago,
+ `date_to` 7 days ago).
+4. Compute the deltas yourself: `aiVisibilityScore`, then the
+ components that moved it (`mentionAnswers` / `resultCount`,
+ `citationAnswers` / `resultCount`, `positionFactor`).
5. Report it like a standup, not a spreadsheet. Template:
> **`<brand_name>` — last 7 days**
>
- > Visibility: **`<score>`** (Δ `<+/- n>` pts vs. all-time)
- > Mentions: **`<n>`** across **`<resultCount>`** tracked responses
- > Citations: **`<n>`**
+ > Visibility: **`<score>`** (Δ `<+/- n>` vs. the week before)
+ > Mentioned in **`<n>%`** of **`<resultCount>`** tracked answers,
+ > cited in **`<n>%`**
+ > Coverage: **`<visibilityRatePct>%`** of tracked prompts
>
- > Top competitor: **`<name>`** with `<mentions>` mentions
- > (their score: `<avgVisibility>`)
+ > Top competitor: **`<name>`** at **`<score>`**
>
> **What it means:** `<one sentence>`
> **Next:** `<one suggestion>`
@@ -184,64 +216,80 @@ When the user asks for a general status check:
6. **"What it means"** is where you earn your keep. See
[`references/visibility-scoring.md`](references/visibility-scoring.md)
for how to read a score. Examples:
- - Score 65 with 4 mentions per response → strong, brand is a default
- answer
- - Score 35 with 2 mentions but only 0 citations → mentioned but no
- source authority — content gap
- - Score 20 with 1 mention → fringe — competitors are eating the
- answer
+ - Mentioned in most answers and cited often → the brand is a
+ default answer
+ - Mentioned often but rarely cited → known, but no source authority
+ — content gap
+ - Rarely mentioned → fringe — competitors are eating the answer
+7. If `GET /actions` has open high-impact actions, end with one of them
+ as the **Next** step instead of inventing your own.
### 2. Visibility deep-dive ("why did it drop?")
When the user notices a change and wants the cause:
-1. Get the **current 7-day window** with `/api/mcp/visibility-summary`.
-2. Get the **previous 7-day window** (set `date_from` to 14 days ago,
- `date_to` to 7 days ago). Compare.
-3. Slice by **model**: run the same query with `model=chatgpt`, then
- `gemini`, `claude`, `perplexity`, `copilot`. Look for the model with
- the biggest drop — that's usually where the story is.
-4. Slice by **region** if the brand operates in multiple. A drop only
- in one region usually points to a localized content or competitor
- change.
-5. Report in this order:
- 1. Headline: where the drop was concentrated ("dropped 14 pts,
- mostly on Perplexity")
- 2. Root cause hypothesis: did mentions fall, citations fall, or
- sentiment shift? Pull the numbers to back it up.
+1. Call `GET /visibility-trend` over the last 30 days (`granularity=day`) to see **when** it moved.
+2. Compare the windows before and after with `GET /visibility-summary`.
+ Did mentions fall, citations fall, or did the brand get named later
+ (`positionFactor`)?
+3. Find **where**: `GET /competitor-comparison` returns the split per
+ model and platform. Use the model values it returns as the `model`
+ filter on `GET /visibility-summary` — don't guess model names. The
+ model with the biggest drop is usually where the story is.
+4. Slice by **region** if the brand operates in several. A drop in one
+ region usually points to a localized content or competitor change.
+5. Find **which prompts**: `GET /prompt-performance` with
+ `sort_by=visibility&order=asc` for the recent window.
+6. Check `GET /signals` — the Action Center may already have detected
+ and explained the change.
+7. Report in this order:
+ 1. Headline: where the drop was concentrated ("down 14, mostly on
+ Perplexity")
+ 2. Root cause hypothesis, backed by the components.
3. Two concrete things to try (see
[`references/prompt-writing-tips.md`](references/prompt-writing-tips.md)).
-
-6. **Never speculate about competitor moves** unless you have data.
+8. **Never speculate about competitor moves** unless you have data.
Stick to "your numbers say X, here's what that usually means."
### 3. Competitor watch
When the user asks who they're up against:
-1. Pull `/api/mcp/visibility-summary` with no filters for the brand.
-2. The `topCompetitors` array is sorted by mention count. Report it as
- a ranked list with one delta per row:
+1. Call `GET /competitor-comparison` for the window they care about
+ (default: last 30 days).
+2. Report a ranked list by `visibility_rate_pct`, plus share of voice:
- > 1. **`<name>`** — `<mentions>` mentions, avg visibility `<score>`
+ > Share of voice: **`<n>%`**
+ >
+ > 1. **`<name>`** — in `<rate>%` of prompts, `<mentions>` mentions
> 2. ...
-3. If the user's `avgVisibility` is below a competitor's, **say so
- directly**. Don't soften it. Example:
- _"Acme is currently outranking you on visibility (62 vs. your 48).
- They're being mentioned in 31% more responses."_
+3. If a competitor is ahead of the user, **say so directly**. Don't
+ soften it. Example:
+ _"Acme appears in 62% of your tracked prompts; you appear in 48%."_
+4. Optionally run the previous window too and flag who is surging or
+ fading.
+
+### 4. Citation sources ("who cites us?")
-4. Optionally compare with last week's data (same date trick as
- workflow 2) to flag whether a competitor is surging or fading.
+1. Call `GET /citations` for the window.
+2. Lead with the source-type breakdown (how much is owned, competitor,
+ news, review, forum…), then the top domains and URLs.
+3. With `source_filter=competitor`, show which competitor pages AI
+ pulls instead of the user's — those are the pages to out-write.
+4. Low owned share means AI isn't treating the user's site as a source;
+ point at `GET /content-opportunities` or a `POST /site-audits` on the
+ page that should be cited (ask first — it uses a credit).
-### 4. Prompt coverage audit
+### 5. Prompt coverage audit
When the user asks _"what am I tracking?"_, _"are my topics balanced?"_,
or any "do I have gaps" question:
-1. Call `/api/mcp/topics?brand_id=...`.
-2. Read `prompt_count` per topic. Healthy band is **3–8 prompts per
- topic**; anything outside is worth flagging.
+1. Call `GET /topics?brand_id=…`.
+2. Read the `prompt_count` per topic. A healthy brand usually has
+ **3–8 prompts per topic** — anything outside that band is worth
+ flagging.
3. Report shape, not raw dump. Template:
> **Topic coverage — `<brand_name>`**
@@ -259,25 +307,29 @@ or any "do I have gaps" question:
> **Next:** `<one concrete suggestion>`
4. Empty topics are often the biggest unlock — point at them first.
- See [`references/prompt-writing-tips.md`](references/prompt-writing-tips.md)
- for what kinds of prompts to add.
+ `GET /topic-suggestions` may already hold ideas; offer to accept one
+ rather than inventing topics.
+5. `GET /prompt-volumes` tells you which prompts carry real demand —
+ use it to say which gaps matter most.
-### 5. Prompt deep-dive
+### 6. Prompt deep-dive
When the user asks _"what prompts are in topic X?"_ or _"show me my
prompts for `<theme>`"_:
-1. If they named a topic by name, call `/api/mcp/topics?brand_id=...`
- first to resolve the topic name to its `id`.
-2. Call `/api/mcp/prompts?brand_id=...&topic_id=...`.
-3. Report as a short list with operational signals (platforms, models,
- active status), not a wall of text:
+1. If they named a topic by name, call `GET /topics?brand_id=…` first
+ to resolve the topic name to its `id`.
+2. Call `GET /prompts?brand_id=…&topic_id=…`, and
+ `GET /prompt-performance` with the same `topic_id` for how each one
+ is doing.
+3. Report as a short list with the operational signals (visibility,
+ platforms, active status), not a wall of text:
> **`<topic_name>` — `<n>` prompts**
>
- > 1. _"`<prompt text>`"_
- > → `<platforms.length>` platforms, `<models.length>` models,
- > `<regions.length>` regions, **active**
+ > 1. _"`<prompt text>`"_ — visibility **`<score>`**
+ > → `<platforms.length>` platforms, `<regions.length>` regions,
+ > **active**
> 2. ...
>
> **Inactive:** `<n>` prompts (paused)
@@ -285,15 +337,62 @@ prompts for `<theme>`"_:
4. Flag inactive prompts explicitly — users often forget they paused
something and that's why visibility on that slice is flat.
-5. If a prompt has zero `platforms` or zero `models`, it's effectively
- silent — surface that as a misconfiguration.
+5. If a prompt has zero platforms, it's effectively silent — surface
+ that as a misconfiguration.
+
+### 7. What to do next ("what should we work on?")
+
+1. Call `GET /actions` with `status=new` (and `in_progress` if they
+ ask what's underway). Rank by `impact`.
+2. For the top one or two, call `GET /actions/{id}` and explain the **why**
+ from its payload and signals in one sentence each.
+3. Mention open content gaps from `GET /content-opportunities` only if
+ no action already covers them.
+4. When the user says they did, started or skipped a task, offer to
+ record it with `PATCH /action-tasks/{id}/status` — and only call it after they
+ confirm. A skip needs a reason.
+
+### 8. Sending Improve suggestions to Action Center
+
+The dashboard's Positions panel has an **Improve** tab that generates
+platform-specific suggestions for one prompt and range. When the user
+wants those (or suggestions you wrote together) turned into tracked
+work:
+
+1. Confirm the prompt (`GET /prompts` → the prompt `id`) and the range the
+ suggestion set was generated for: `preset` (`24h`, `7d`, `30d`,
+ `90d` or `custom`), `from`, optional `to` and `region`.
+2. Call `POST /prompts/{id}/improve-action` with the body `{ range,
+ idempotency_key, suggestions }`, each suggestion as `{ id, platform,
+ title, body, sources }`. `platform` is one of
+ `chatgpt-web`, `perplexity-web`, `google-aio`, `google-aimode`,
+ `gemini-web`, `copilot-web`, `grok-web`, `claude`.
+3. Pass a fresh `idempotency_key` (a UUID) for each send, and reuse it
+ only when retrying the same send — a retry then returns the same
+ action (`created: false`) instead of a duplicate.
+4. If it fails with "Generate suggestions for this range first", the
+ prompt has no Improve set for that range: tell the user to generate
+ one in the Improve tab. You can't generate it over the API.
+5. Report the action number (`AC-<actionNo>`) and task count.
+
+### 9. Did it work? ("did last month's work pay off?")
+
+1. Call `GET /action-history`.
+2. For each closed action, report the `outcome` and the before/after
+ from `results` in one line. `pending_measurement` means the
+ after-window is still open — say when to check back, don't judge
+ early.
+3. Summarise: how many improved, how many didn't move, and what the
+ improved ones had in common.
## Formatting principles
- **Lead with the number, then the meaning.** Don't bury the score in a
paragraph of context.
-- **Use deltas, not raw counts when comparing periods.** "+12 pts" is
- more useful than "now 65 vs. previously 53."
+- **Use deltas, not raw counts when comparing periods.** "+12" is more
+ useful than "now 65 vs. previously 53."
+- **Visibility has no % sign; rates and shares do.** "Visibility 48,
+ mentioned in 61% of answers."
- **One concrete next step per answer, max two.** AEO is a slow lever;
don't drown the user in todos.
- **Plain text > tables for short answers.** Tables for >3 rows only.
@@ -305,24 +404,29 @@ prompts for `<theme>`"_:
- **Don't average over too small a sample.** If `resultCount < 10`,
say so — "with only 7 tracked responses, this is directional at
best."
-- **Don't mix all-time and date-filtered scores in the same sentence.**
- Pick one frame per claim.
+- **Don't mix windows in the same sentence.** Pick one frame per claim.
+- **Don't quote deprecated fields.** `avgVisibility` is not the
+ dashboard's Visibility number; `aiVisibilityScore` is.
- **Don't claim a citation count is good or bad in isolation.** It
only matters relative to mentions (see scoring reference).
+- **Don't call a write endpoint to "check" something.** Read
+ endpoints exist for every write; use them.
+- **Don't log or repeat the API key.** If a code block needs to show
+ the auth header, redact the token (`Bearer ans_***`).
- **Don't recommend "improve SEO" — this is not SEO.** AEO is about
being cited inside AI-generated answers. Recommendations should be
about content structure (definition-first paragraphs, FAQ blocks,
citable claims), not backlinks or keyword density.
-- **Don't log or repeat the API key.** If a code block needs to show
- the auth header, redact the token (`Bearer ans_***`).
## Error handling
- `401 Invalid API key` → ask the user to regenerate from Settings →
API Keys.
-- `404 Brand not found` → the brand_id doesn't belong to the
- authenticated user's organization. Re-run `/api/mcp/brands` to get
- the right id.
+- `404 ... not found` → the id doesn't belong to the authenticated
+ user's organization. Re-run `GET /brands` (or the matching list
+ endpoint) to get the right id.
+- `500` with a message (e.g. a plan limit, "Generate suggestions for
+ this range first") → relay the message as is.
- Network timeout → retry once. If it still fails, surface it and stop.
## References
diff --git a/skills/ansvisor-aeo-coach-standalone/references/sentiment-interpretation.md b/skills/ansvisor-aeo-coach-standalone/references/sentiment-interpretation.md
index 0cbbd81a7..48f24fb9d 100644
--- a/skills/ansvisor-aeo-coach-standalone/references/sentiment-interpretation.md
+++ b/skills/ansvisor-aeo-coach-standalone/references/sentiment-interpretation.md
@@ -1,8 +1,9 @@
# Sentiment interpretation
Each tracked AI response is tagged `positive`, `neutral`, or `negative`.
-Sentiment is the smallest component of the visibility score (max 15
-points) but it's the loudest **signal** about why a number changed.
+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.
## Three rules of thumb
diff --git a/skills/ansvisor-aeo-coach-standalone/references/visibility-scoring.md b/skills/ansvisor-aeo-coach-standalone/references/visibility-scoring.md
index 45ca5fa39..174c53227 100644
--- a/skills/ansvisor-aeo-coach-standalone/references/visibility-scoring.md
+++ b/skills/ansvisor-aeo-coach-standalone/references/visibility-scoring.md
@@ -1,80 +1,99 @@
# Visibility scoring reference
-The Ansvisor visibility score (0–100, per prompt × platform result) is a
-weighted sum of four signals. Knowing the breakdown lets you tell the
-user **why** a score is what it is, not just what it is.
+The Ansvisor **AI Visibility Score** (0–100) is the Visibility number the
+dashboard shows everywhere. Over the MCP server it is
+`totals.aiVisibilityScore` in `get_visibility_summary`, and each
+competitor's `score`. Knowing the breakdown lets you tell the user
+**why** a score is what it is, not just what it is.
## The formula
+The score is computed over a set of tracked AI answers — brand-wide, per
+prompt, per topic, per platform or per day. The same formula applies to
+every scope, which is why the numbers agree across the dashboard.
+
```
-score = mention_pts + citation_pts + citation_ratio_pts + sentiment_pts
- ≤ 100
+score = 100 × ( 0.60 × mention rate
+ + 0.25 × citation rate
+ + 0.15 × position factor × position support )
```
-| Component | Max | Formula | Caps at |
+| Component | Weight | What it is | MCP field |
| --- | --- | --- | --- |
-| Mentions | 40 | `min(mention_count × 10, 40)` | 4 mentions in one response |
-| Citations | 30 | `min(citation_count × 15, 30)` | 2 citations in one response |
-| Citation ratio | 15 | `(brand_citations / total_citations) × 15` | 100% of cites are yours |
-| Sentiment | 15 | positive: +15 · neutral (w/ mentions): +7 · negative or none: 0 | — |
+| Mention rate | 60% | Share of answers that name the brand | `mentionAnswers / resultCount` |
+| Citation rate | 25% | Share of answers that cite the brand's own domain | `citationAnswers / resultCount` |
+| Position factor | 15% | Mean of 1/position over answers that name the brand (1 = always named first) | `positionFactor` |
+
+**Position support** damps the position term on thin evidence:
+`mentionAnswers / (mentionAnswers + 20)`. A brand named first in 5
+answers out of thousands does not get the full 15 points; one named in
+hundreds of answers does.
-Total clamps to 100.
+The score is `null` when the scope has no answers. Sentiment is **not**
+part of it.
## How to read a score
-The dashboard shows the **average** score across all tracked results. So
-"average visibility 50" can mean very different shapes:
-
-- **Score ≈ 100 (rare):** brand is mentioned 4+ times, cited 2+ times,
- all citations point to brand-owned domains, positive tone. Default
- answer territory.
-- **Score 65–80:** strong. Probably 3–4 mentions, 1–2 citations,
- positive sentiment. The brand is part of the recommended set.
-- **Score 40–65:** present but not dominant. Either mentioned with no
- citations (no source authority) or cited without much body mention.
-- **Score 20–40:** fringe. Showing up once per response, no citations,
- neutral tone. Competitors are eating the spotlight.
-- **Score 0–20:** the brand is barely surfacing — either prompts aren't
- matching brand territory, or competitors fully own the answer.
+- **80+:** the brand is named in almost every answer, usually early, and
+ its site is cited often. Default answer territory.
+- **60–80:** strong. Named in most answers; citations or position leave
+ some room.
+- **35–60:** present but not dominant. Typically named in about half the
+ answers, or named often but rarely cited.
+- **15–35:** fringe. Named now and then, rarely cited. Competitors own
+ the answer.
+- **Below 15:** barely surfacing — prompts may not match the brand's
+ territory, or competitors fully own it.
## Component diagnoses
-When you see a low score, the breakdown tells you the lever to pull:
-
-- **Low on mentions (`mention_count < 2` typical):** the brand isn't
- even being named. Probably a content/positioning problem — there's no
- source the AI is pulling from that connects this prompt to the brand.
-- **Mentions OK, low on citations:** the AI knows the brand exists but
- is citing competitors as sources. The brand needs publishable,
- citable content on the topic (definition-first paragraphs, primary
- research, original data).
-- **Mentions OK, citations OK, low on citation ratio:** competitors are
- also being cited heavily. The brand needs to **own more of the
- citable surface** for this topic — more pages, more depth, or
- acquiring 3rd-party authority that points to it.
-- **Sentiment negative:** rare, but when it happens, ignore SEO and go
- fix the brand reputation issue surfaced in the response text.
+When you see a low score, the components tell you the lever to pull:
+
+- **Low mention rate:** the brand isn't being named. A content or
+ positioning problem — no source the AI uses connects this prompt to
+ the brand. This is the heaviest weight, so it moves the score most.
+- **Mentions OK, low citation rate:** the AI knows the brand but cites
+ other sites as sources. The brand needs citable content on the topic
+ (definition-first paragraphs, primary research, original data).
+ `list_citations` shows who gets cited instead.
+- **Mentions OK, low position factor:** the brand is listed, but after
+ competitors. Comparison pages and clear "best for" positioning help.
+
+## Coverage is a different number
+
+`totals.visibilityRatePct` is **coverage**: the share of tracked prompts
+the brand appeared in at all (`visiblePrompts / promptCount × 100`). It
+is a percentage and answers "in how many of my prompts do I show up?",
+not "how strongly?". `get_competitor_comparison` ranks entries by the
+same kind of rate (`visibility_rate_pct`).
+
+`avgVisibility` (on the brand and on competitors) is a **deprecated**
+legacy average from an older formula. Don't quote it.
## What NOT to say
-- _"Aim for 100."_ — 100 requires every response to mention the brand
- 4× with 2 citations of which 100% are owned, positive tone. It is
- almost never the right target. Aim for category leadership (~65+).
+- _"Aim for 100."_ — 100 needs every answer to name the brand first and
+ cite its site. It is almost never the right target. Aim for category
+ leadership.
- _"Score went down 5 points, panic."_ — single-digit movement on small
- sample sizes is noise. Always check `resultCount` before reacting.
-- _"Mentions are good, score should be higher."_ — mentions max out at
- 40 points. Without citations and sentiment, that's the ceiling.
+ samples is noise. Always check `resultCount` before reacting.
+- _"Visibility is 48%."_ — the score has no % sign. Rates and coverage
+ do.
## Math sanity checks
-If you ever need to verify, here are reference shapes:
+Reference shapes (answers = `resultCount`):
-| Mentions | Citations | Total cites | Sentiment | Score |
+| Answers | Mentioned in | Cited in | Position factor | Score |
| --- | --- | --- | --- | --- |
-| 0 | 0 | 0 | none | 0 |
-| 1 | 0 | 0 | neutral | 17 |
-| 2 | 0 | 0 | neutral | 27 |
-| 4 | 0 | 0 | positive | 55 |
-| 4 | 2 | 2 | positive | 100 |
-| 4 | 2 | 5 | positive | 91 |
-| 2 | 1 | 1 | positive | 65 |
+| 100 | 0 | 0 | — | 0 |
+| 100 | 10 | 0 | 1.0 | 11.0 |
+| 100 | 50 | 0 | 0.33 | 33.5 |
+| 100 | 50 | 10 | 0.5 | 37.9 |
+| 100 | 80 | 0 | 0.5 | 54.0 |
+| 100 | 80 | 40 | 1.0 | 70.0 |
+| 100 | 100 | 100 | 1.0 | 97.5 |
+| 10 | 10 | 0 | 1.0 | 65.0 |
+
+The last row is why small samples mislead: 10 answers, all naming the
+brand first, already score 65.
diff --git a/skills/ansvisor-aeo-coach/SKILL.md b/skills/ansvisor-aeo-coach/SKILL.md
index d46aa6b79..f7002b273 100644
--- a/skills/ansvisor-aeo-coach/SKILL.md
+++ b/skills/ansvisor-aeo-coach/SKILL.md
@@ -3,14 +3,16 @@ name: ansvisor-aeo-coach
description: |
Acts as an Answer Engine Optimization (AEO) analyst for users running
Ansvisor. Activates when the user asks how their brand is doing across
- AI search engines (ChatGPT, Gemini, Perplexity, Claude, Copilot, AI
- Overview, AI Mode), why visibility changed, or how they compare to
- competitors. Uses the Ansvisor MCP server tools (`list_brands`,
- `get_visibility_summary`) to fetch the data, then interprets it the
- way a marketing analyst would — not just dumping 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
+ AI search engines (ChatGPT, Gemini, Perplexity, Claude, Copilot, Grok,
+ Google AI Overviews, AI Mode), why visibility changed, how they compare
+ to 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,
+ then interprets it the way a marketing analyst would — not just
+ dumping 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.
---
@@ -34,6 +36,8 @@ Activate this skill when the user asks anything in the shape of:
- _"What's my visibility on ChatGPT this week?"_
- _"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?"_
+- _"What should we work on next?" / "Did last month's work 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
@@ -42,33 +46,123 @@ tools, the user hasn't connected the MCP server yet. Point them at the
and stop — do not invent numbers, and do not attempt to call the REST
API directly from this skill (that's a different skill).
+## The numbers that matter
+
+- **Visibility** is `totals.aiVisibilityScore` from
+ `get_visibility_summary`: a 0–100 score, the same number the dashboard
+ shows everywhere. Quote it **without a % sign**. It blends three
+ shares of the tracked answers: how often the brand is **mentioned**
+ (60%), how often its own domain is **cited** (25%), and how **early**
+ it is named (15%). See
+ [`references/visibility-scoring.md`](references/visibility-scoring.md).
+- Its components come with it: `totals.mentionAnswers`,
+ `totals.citationAnswers` and `totals.positionFactor` (1 = always named
+ first), out of `totals.resultCount` answers.
+- **Coverage** is `totals.visibilityRatePct`: the share of tracked
+ prompts the brand appeared in at all (`visiblePrompts / promptCount`).
+ It is a percentage — quote it with `%`.
+- **Competitors** in `topCompetitors[]` carry a `score` on the same
+ scale and denominator as the brand's `aiVisibilityScore`, so the two
+ compare directly.
+- `totals.avgVisibility` and each competitor's `avgVisibility` are
+ **deprecated** legacy averages. Don't quote them.
+
## Tools available (from the Ansvisor MCP server)
-- **`list_brands`** — lists brands the user can access. Returns `id`,
- `name`, `slug`, `industry`, `region`, `created_at`.
-- **`get_visibility_summary`** — given a `brand_id` (and optional
- `date_from`, `date_to`, `model`, `region`), returns:
- - `totals.resultCount` — how many tracked AI responses were analyzed
- - `totals.avgVisibility` — average visibility score 0–100 (see scoring
- reference below)
- - `totals.totalMentions` — total brand mentions across all responses
- - `totals.totalCitations` — total citations to the brand's domains
- - `topCompetitors[]` — up to 5 competitors with `name`, `mentions`,
- `avgVisibility`
-- **`list_topics`** — given a `brand_id`, returns the topics on that
- brand with `prompt_count` per topic. Use this for coverage audits
- (empty topics, lopsided distribution) and as the first call before
- drilling into prompts.
-- **`list_prompts`** — given a `brand_id` (and optional `topic_id`,
- `is_active`, `limit`), returns prompts with `text`, `topic_name`,
- `platforms[]`, `models[]`, `regions[]`, `is_active`, `created_at`.
- Default limit 100, max 500. Use this when the user wants to see
- what's actually being tracked, or to spot inactive / mis-targeted
- prompts.
+Every tool except `list_brands` and `get_site_audit_quota` needs a
+`brand_id` or an id that came from another tool. Dates are ISO
+timestamps (`date_from` / `date_to`).
+
+**Brand & visibility**
+
+- **`list_brands`** — brands the user can access. Always call this
+ first to resolve a `brand_id`.
+- **`get_visibility_summary`** — one window's headline numbers (see
+ above). Filters: `date_from`, `date_to`, `model`, `region`.
+- **`get_visibility_trend`** — the same over time, bucketed by `day` or
+ `week`, with an average competitor score per bucket. Use for "how has
+ it changed?".
+- **`get_competitor_comparison`** — competitor benchmark for a window:
+ per-entry `visibility_rate_pct` on a shared denominator, mentions and
+ citations, overall **share of voice**, and the same split per model
+ and platform. Filters: dates, `model`, `region`, `topic_id`.
+- **`list_citations`** — which domains and URLs AI cites alongside the
+ brand, 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.
+
+**Prompts & topics**
+
+- **`list_topics`** — topics with `prompt_count` each. First call for
+ coverage audits.
+- **`list_prompts`** — tracked prompts with text, topic, platforms,
+ models, regions and active flag. Filters: `topic_id`, `is_active`,
+ `limit` (default 100, max 500).
+- **`get_prompt_performance`** — per-prompt visibility, mentions,
+ citations and competitor score for a window. Sort with `sort_by`
+ (`visibility`, `mentions`, `citations`, `appearances`) and `order`.
+ Use for "best / worst prompt this week?".
+- **`get_prompt_volumes`** — per-prompt search demand: Google volumes,
+ `est_ai_volume` and competition. Use to prioritise.
+- **`list_topic_suggestions`** — pending AI topic suggestions.
+ **`accept_topic_suggestion`** / **`dismiss_topic_suggestion`** act on
+ one *(writes)*.
+
+**Content & pages**
+
+- **`list_content_opportunities`** — content gaps ranked by opportunity
+ score. Filters: `status`, `impact`, `type`.
+- **`get_content_opportunity`** — one gap in full, including an
+ existing brief.
+- **`generate_content_brief`** — writes a fresh AI brief, overwriting
+ the old one. Costs an LLM call *(write)*.
+- **`update_opportunity_status`** — move a gap through `new`,
+ `reviewed`, `sent`, `in_progress`, `done`, `dismissed` *(write)*.
+- **`get_site_audit_quota`**, **`list_site_audits`**,
+ **`get_site_audit`** — page audit allowance, past audits, one audit's
+ scores and fixes.
+- **`run_site_audit`** — audit a URL. Uses a monthly credit and runs
+ ~30s; poll `get_site_audit` *(write)*.
+
+**Shopping**
+
+- **`list_shopping_cards`** — products AI engines show in shopping
+ answers, by role (`own`, `competitor`, `other`), platform and region.
+- **`get_product_visibility`** — one product title across platforms,
+ regions and dates.
+
+**Action Center**
+
+- **`list_actions`** — open work: what the product thinks should be
+ done, with impact, status and task progress. Filters: `status`,
+ `category`.
+- **`get_action`** — one action in full: payload, triggering signals,
+ tasks and events. Each task has `mode` (system, agent, human,
+ human_or_agent) and `permission` (read, write, execute).
+- **`list_signals`** — detected changes with before/after values and
+ the `action_id` they fed.
+- **`list_action_history`** — closed actions with their measured
+ `outcome` (improved, no_meaningful_change, declined, not_measurable,
+ pending_measurement) and before/after `results`.
+- **`update_task_status`** — record that a task is `in_progress`,
+ `completed`, `skipped` (with `skip_reason`) or `failed` *(write)*.
+- **`create_improve_action`** — send a prompt's Improve suggestions to
+ Action Center as one action, one task per suggestion *(write; see
+ workflow 8)*.
More tools land regularly. If a tool you'd want isn't here, say so out
loud rather than faking it.
+## Writes need explicit intent
+
+Tools marked *(write)* change the user's account, spend a credit or run
+an LLM. Call one **only** when the user asked for that specific change
+(this suggestion, this task, this URL) — never while exploring, never
+"to be helpful". Say what you are about to do in one line first. The
+change is logged under the API key's user.
+
## Core workflows
### 1. Brand snapshot ("how am I doing?")
@@ -78,23 +172,24 @@ When the user asks for a general status check:
1. If they didn't name a brand, call `list_brands`. If there's only
one, use it silently. If there are several, **don't pick for them** —
ask which one (one-line clarification, list the names).
-2. Call `get_visibility_summary` with **no filters first** — this gives
- the all-time baseline.
-3. Then call it again with `date_from` set to **7 days ago** (ISO
- format, e.g. `new Date(Date.now() - 7*24*60*60*1000).toISOString()`)
- to get "this week's" view.
-4. Compute the delta yourself: this week's `avgVisibility` minus
- all-time `avgVisibility`. Same for mentions.
+2. Call `get_visibility_summary` with `date_from` set to **7 days ago**
+ (ISO format, e.g. `new Date(Date.now() - 7*24*60*60*1000).toISOString()`)
+ for "this week".
+3. Call it again for the **previous 7 days** (`date_from` 14 days ago,
+ `date_to` 7 days ago).
+4. Compute the deltas yourself: `aiVisibilityScore`, then the
+ components that moved it (`mentionAnswers` / `resultCount`,
+ `citationAnswers` / `resultCount`, `positionFactor`).
5. Report it like a standup, not a spreadsheet. Template:
> **`<brand_name>` — last 7 days**
>
- > Visibility: **`<score>`** (Δ `<+/- n>` pts vs. all-time)
- > Mentions: **`<n>`** across **`<resultCount>`** tracked responses
- > Citations: **`<n>`**
+ > Visibility: **`<score>`** (Δ `<+/- n>` vs. the week before)
+ > Mentioned in **`<n>%`** of **`<resultCount>`** tracked answers,
+ > cited in **`<n>%`**
+ > Coverage: **`<visibilityRatePct>%`** of tracked prompts
>
- > Top competitor: **`<name>`** with `<mentions>` mentions
- > (their score: `<avgVisibility>`)
+ > Top competitor: **`<name>`** at **`<score>`**
>
> **What it means:** `<one sentence>`
> **Next:** `<one suggestion>`
@@ -102,57 +197,73 @@ When the user asks for a general status check:
6. **"What it means"** is where you earn your keep. See
[`references/visibility-scoring.md`](references/visibility-scoring.md)
for how to read a score. Examples:
- - Score 65 with 4 mentions per response → strong, brand is a default
- answer
- - Score 35 with 2 mentions but only 0 citations → mentioned but no
- source authority — content gap
- - Score 20 with 1 mention → fringe — competitors are eating the
- answer
+ - Mentioned in most answers and cited often → the brand is a
+ default answer
+ - Mentioned often but rarely cited → known, but no source authority
+ — content gap
+ - Rarely mentioned → fringe — competitors are eating the answer
+7. If `list_actions` has open high-impact actions, end with one of them
+ as the **Next** step instead of inventing your own.
### 2. Visibility deep-dive ("why did it drop?")
When the user notices a change and wants the cause:
-1. Get the **current 7-day window** with `get_visibility_summary`.
-2. Get the **previous 7-day window** (set `date_from` to 14 days ago,
- `date_to` to 7 days ago). Compare.
-3. Slice by **model**: run the same query with `model: "chatgpt"`,
- then `gemini`, `claude`, `perplexity`, `copilot`. Look for the model
- with the biggest drop — that's usually where the story is.
-4. Slice by **region** if the brand operates in multiple. A drop only
- in one region usually points to a localized content or competitor
- change.
-5. Report in this order:
- 1. Headline: where the drop was concentrated ("dropped 14 pts,
- mostly on Perplexity")
- 2. Root cause hypothesis: did mentions fall, citations fall, or
- sentiment shift? Pull the numbers to back it up.
+1. Call `get_visibility_trend` over the last 30 days (`granularity:
+ "day"`) to see **when** it moved.
+2. Compare the windows before and after with `get_visibility_summary`.
+ Did mentions fall, citations fall, or did the brand get named later
+ (`positionFactor`)?
+3. Find **where**: `get_competitor_comparison` returns the split per
+ model and platform. Use the model values it returns as the `model`
+ filter on `get_visibility_summary` — don't guess model names. The
+ model with the biggest drop is usually where the story is.
+4. Slice by **region** if the brand operates in several. A drop in one
+ region usually points to a localized content or competitor change.
+5. Find **which prompts**: `get_prompt_performance` sorted by
+ `visibility`, `order: "asc"`, for the recent window.
+6. Check `list_signals` — the Action Center may already have detected
+ and explained the change.
+7. Report in this order:
+ 1. Headline: where the drop was concentrated ("down 14, mostly on
+ Perplexity")
+ 2. Root cause hypothesis, backed by the components.
3. Two concrete things to try (see
[`references/prompt-writing-tips.md`](references/prompt-writing-tips.md)).
-
-6. **Never speculate about competitor moves** unless you have data.
+8. **Never speculate about competitor moves** unless you have data.
Stick to "your numbers say X, here's what that usually means."
### 3. Competitor watch
When the user asks who they're up against:
-1. Pull `get_visibility_summary` with no filters for the brand.
-2. The `topCompetitors` array is sorted by mention count. Report it as
- a ranked list with one delta per row:
+1. Call `get_competitor_comparison` for the window they care about
+ (default: last 30 days).
+2. Report a ranked list by `visibility_rate_pct`, plus share of voice:
- > 1. **`<name>`** — `<mentions>` mentions, avg visibility `<score>`
+ > Share of voice: **`<n>%`**
+ >
+ > 1. **`<name>`** — in `<rate>%` of prompts, `<mentions>` mentions
> 2. ...
-3. If the user's `avgVisibility` is below a competitor's, **say so
- directly**. Don't soften it. Example:
- _"Acme is currently outranking you on visibility (62 vs. your 48).
- They're being mentioned in 31% more responses."_
+3. If a competitor is ahead of the user, **say so directly**. Don't
+ soften it. Example:
+ _"Acme appears in 62% of your tracked prompts; you appear in 48%."_
+4. Optionally run the previous window too and flag who is surging or
+ fading.
+
+### 4. Citation sources ("who cites us?")
-4. Optionally compare with last week's data (same date trick as
- workflow 2) to flag whether a competitor is surging or fading.
+1. Call `list_citations` for the window.
+2. Lead with the source-type breakdown (how much is owned, competitor,
+ news, review, forum…), then the top domains and URLs.
+3. With `source_filter: "competitor"`, show which competitor pages AI
+ pulls instead of the user's — those are the pages to out-write.
+4. Low owned share means AI isn't treating the user's site as a source;
+ point at `list_content_opportunities` or a `run_site_audit` on the
+ page that should be cited (ask first — it uses a credit).
-### 4. Prompt coverage audit
+### 5. Prompt coverage audit
When the user asks _"what am I tracking?"_, _"are my topics balanced?"_,
or any "do I have gaps" question:
@@ -178,25 +289,29 @@ or any "do I have gaps" question:
> **Next:** `<one concrete suggestion>`
4. Empty topics are often the biggest unlock — point at them first.
- See [`references/prompt-writing-tips.md`](references/prompt-writing-tips.md)
- for what kinds of prompts to add.
+ `list_topic_suggestions` may already hold ideas; offer to accept one
+ rather than inventing topics.
+5. `get_prompt_volumes` tells you which prompts carry real demand —
+ use it to say which gaps matter most.
-### 5. Prompt deep-dive
+### 6. Prompt deep-dive
When the user asks _"what prompts are in topic X?"_ or _"show me my
prompts for `<theme>`"_:
1. If they named a topic by name, call `list_topics(brand_id)` first
to resolve the topic name to its `id`.
-2. Call `list_prompts(brand_id, topic_id)`.
-3. Report as a short list with the operational signals (platforms,
- models, active status), not a wall of text:
+2. Call `list_prompts(brand_id, topic_id)`, and
+ `get_prompt_performance` with the same `topic_id` for how each one
+ is doing.
+3. Report as a short list with the operational signals (visibility,
+ platforms, active status), not a wall of text:
> **`<topic_name>` — `<n>` prompts**
>
- > 1. _"`<prompt text>`"_
- > → `<platforms.length>` platforms, `<models.length>` models,
- > `<regions.length>` regions, **active**
+ > 1. _"`<prompt text>`"_ — visibility **`<score>`**
+ > → `<platforms.length>` platforms, `<regions.length>` regions,
+ > **active**
> 2. ...
>
> **Inactive:** `<n>` prompts (paused)
@@ -204,15 +319,61 @@ prompts for `<theme>`"_:
4. Flag inactive prompts explicitly — users often forget they paused
something and that's why visibility on that slice is flat.
-5. If a prompt has zero platforms or zero models, it's effectively
- silent — surface that as a misconfiguration.
+5. If a prompt has zero platforms, it's effectively silent — surface
+ that as a misconfiguration.
+
+### 7. What to do next ("what should we work on?")
+
+1. Call `list_actions` with `status: "new"` (and `in_progress` if they
+ ask what's underway). Rank by `impact`.
+2. For the top one or two, call `get_action` and explain the **why**
+ from its payload and signals in one sentence each.
+3. Mention open content gaps from `list_content_opportunities` only if
+ no action already covers them.
+4. When the user says they did, started or skipped a task, offer to
+ record it with `update_task_status` — and only call it after they
+ confirm. A skip needs a reason.
+
+### 8. Sending Improve suggestions to Action Center
+
+The dashboard's Positions panel has an **Improve** tab that generates
+platform-specific suggestions for one prompt and range. When the user
+wants those (or suggestions you wrote together) turned into tracked
+work:
+
+1. Confirm the prompt (`list_prompts` → `prompt_id`) and the range the
+ suggestion set was generated for: `preset` (`24h`, `7d`, `30d`,
+ `90d` or `custom`), `from`, optional `to` and `region`.
+2. Call `create_improve_action` with the suggestions, each as `{ id,
+ platform, title, body, sources }`. `platform` is one of
+ `chatgpt-web`, `perplexity-web`, `google-aio`, `google-aimode`,
+ `gemini-web`, `copilot-web`, `grok-web`, `claude`.
+3. Pass a fresh `idempotency_key` (a UUID) for each send, and reuse it
+ only when retrying the same send — a retry then returns the same
+ action (`created: false`) instead of a duplicate.
+4. If it fails with "Generate suggestions for this range first", the
+ prompt has no Improve set for that range: tell the user to generate
+ one in the Improve tab. You can't generate it over MCP.
+5. Report the action number (`AC-<actionNo>`) and task count.
+
+### 9. Did it work? ("did last month's work pay off?")
+
+1. Call `list_action_history`.
+2. For each closed action, report the `outcome` and the before/after
+ from `results` in one line. `pending_measurement` means the
+ after-window is still open — say when to check back, don't judge
+ early.
+3. Summarise: how many improved, how many didn't move, and what the
+ improved ones had in common.
## Formatting principles
- **Lead with the number, then the meaning.** Don't bury the score in a
paragraph of context.
-- **Use deltas, not raw counts when comparing periods.** "+12 pts" is
- more useful than "now 65 vs. previously 53."
+- **Use deltas, not raw counts when comparing periods.** "+12" is more
+ useful than "now 65 vs. previously 53."
+- **Visibility has no % sign; rates and shares do.** "Visibility 48,
+ mentioned in 61% of answers."
- **One concrete next step per answer, max two.** AEO is a slow lever;
don't drown the user in todos.
- **Plain text > tables for short answers.** Tables for >3 rows only.
@@ -224,10 +385,13 @@ prompts for `<theme>`"_:
- **Don't average over too small a sample.** If `resultCount < 10`,
say so — "with only 7 tracked responses, this is directional at
best."
-- **Don't mix all-time and date-filtered scores in the same sentence.**
- Pick one frame per claim.
+- **Don't mix windows in the same sentence.** Pick one frame per claim.
+- **Don't quote deprecated fields.** `avgVisibility` is not the
+ dashboard's Visibility number; `aiVisibilityScore` is.
- **Don't claim a citation count is good or bad in isolation.** It
only matters relative to mentions (see scoring reference).
+- **Don't call a write tool to "check" something.** Read tools exist
+ for every write; use them.
- **Don't recommend "improve SEO" — this is not SEO.** AEO is about
being cited inside AI-generated answers. Recommendations should be
about content structure (definition-first paragraphs, FAQ blocks,
diff --git a/skills/ansvisor-aeo-coach/references/sentiment-interpretation.md b/skills/ansvisor-aeo-coach/references/sentiment-interpretation.md
index 0cbbd81a7..48f24fb9d 100644
--- a/skills/ansvisor-aeo-coach/references/sentiment-interpretation.md
+++ b/skills/ansvisor-aeo-coach/references/sentiment-interpretation.md
@@ -1,8 +1,9 @@
# Sentiment interpretation
Each tracked AI response is tagged `positive`, `neutral`, or `negative`.
-Sentiment is the smallest component of the visibility score (max 15
-points) but it's the loudest **signal** about why a number changed.
+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.
## Three rules of thumb
diff --git a/skills/ansvisor-aeo-coach/references/visibility-scoring.md b/skills/ansvisor-aeo-coach/references/visibility-scoring.md
index 45ca5fa39..174c53227 100644
--- a/skills/ansvisor-aeo-coach/references/visibility-scoring.md
+++ b/skills/ansvisor-aeo-coach/references/visibility-scoring.md
@@ -1,80 +1,99 @@
# Visibility scoring reference
-The Ansvisor visibility score (0–100, per prompt × platform result) is a
-weighted sum of four signals. Knowing the breakdown lets you tell the
-user **why** a score is what it is, not just what it is.
+The Ansvisor **AI Visibility Score** (0–100) is the Visibility number the
+dashboard shows everywhere. Over the MCP server it is
+`totals.aiVisibilityScore` in `get_visibility_summary`, and each
+competitor's `score`. Knowing the breakdown lets you tell the user
+**why** a score is what it is, not just what it is.
## The formula
+The score is computed over a set of tracked AI answers — brand-wide, per
+prompt, per topic, per platform or per day. The same formula applies to
+every scope, which is why the numbers agree across the dashboard.
+
```
-score = mention_pts + citation_pts + citation_ratio_pts + sentiment_pts
- ≤ 100
+score = 100 × ( 0.60 × mention rate
+ + 0.25 × citation rate
+ + 0.15 × position factor × position support )
```
-| Component | Max | Formula | Caps at |
+| Component | Weight | What it is | MCP field |
| --- | --- | --- | --- |
-| Mentions | 40 | `min(mention_count × 10, 40)` | 4 mentions in one response |
-| Citations | 30 | `min(citation_count × 15, 30)` | 2 citations in one response |
-| Citation ratio | 15 | `(brand_citations / total_citations) × 15` | 100% of cites are yours |
-| Sentiment | 15 | positive: +15 · neutral (w/ mentions): +7 · negative or none: 0 | — |
+| Mention rate | 60% | Share of answers that name the brand | `mentionAnswers / resultCount` |
+| Citation rate | 25% | Share of answers that cite the brand's own domain | `citationAnswers / resultCount` |
+| Position factor | 15% | Mean of 1/position over answers that name the brand (1 = always named first) | `positionFactor` |
+
+**Position support** damps the position term on thin evidence:
+`mentionAnswers / (mentionAnswers + 20)`. A brand named first in 5
+answers out of thousands does not get the full 15 points; one named in
+hundreds of answers does.
-Total clamps to 100.
+The score is `null` when the scope has no answers. Sentiment is **not**
+part of it.
## How to read a score
-The dashboard shows the **average** score across all tracked results. So
-"average visibility 50" can mean very different shapes:
-
-- **Score ≈ 100 (rare):** brand is mentioned 4+ times, cited 2+ times,
- all citations point to brand-owned domains, positive tone. Default
- answer territory.
-- **Score 65–80:** strong. Probably 3–4 mentions, 1–2 citations,
- positive sentiment. The brand is part of the recommended set.
-- **Score 40–65:** present but not dominant. Either mentioned with no
- citations (no source authority) or cited without much body mention.
-- **Score 20–40:** fringe. Showing up once per response, no citations,
- neutral tone. Competitors are eating the spotlight.
-- **Score 0–20:** the brand is barely surfacing — either prompts aren't
- matching brand territory, or competitors fully own the answer.
+- **80+:** the brand is named in almost every answer, usually early, and
+ its site is cited often. Default answer territory.
+- **60–80:** strong. Named in most answers; citations or position leave
+ some room.
+- **35–60:** present but not dominant. Typically named in about half the
+ answers, or named often but rarely cited.
+- **15–35:** fringe. Named now and then, rarely cited. Competitors own
+ the answer.
+- **Below 15:** barely surfacing — prompts may not match the brand's
+ territory, or competitors fully own it.
## Component diagnoses
-When you see a low score, the breakdown tells you the lever to pull:
-
-- **Low on mentions (`mention_count < 2` typical):** the brand isn't
- even being named. Probably a content/positioning problem — there's no
- source the AI is pulling from that connects this prompt to the brand.
-- **Mentions OK, low on citations:** the AI knows the brand exists but
- is citing competitors as sources. The brand needs publishable,
- citable content on the topic (definition-first paragraphs, primary
- research, original data).
-- **Mentions OK, citations OK, low on citation ratio:** competitors are
- also being cited heavily. The brand needs to **own more of the
- citable surface** for this topic — more pages, more depth, or
- acquiring 3rd-party authority that points to it.
-- **Sentiment negative:** rare, but when it happens, ignore SEO and go
- fix the brand reputation issue surfaced in the response text.
+When you see a low score, the components tell you the lever to pull:
+
+- **Low mention rate:** the brand isn't being named. A content or
+ positioning problem — no source the AI uses connects this prompt to
+ the brand. This is the heaviest weight, so it moves the score most.
+- **Mentions OK, low citation rate:** the AI knows the brand but cites
+ other sites as sources. The brand needs citable content on the topic
+ (definition-first paragraphs, primary research, original data).
+ `list_citations` shows who gets cited instead.
+- **Mentions OK, low position factor:** the brand is listed, but after
+ competitors. Comparison pages and clear "best for" positioning help.
+
+## Coverage is a different number
+
+`totals.visibilityRatePct` is **coverage**: the share of tracked prompts
+the brand appeared in at all (`visiblePrompts / promptCount × 100`). It
+is a percentage and answers "in how many of my prompts do I show up?",
+not "how strongly?". `get_competitor_comparison` ranks entries by the
+same kind of rate (`visibility_rate_pct`).
+
+`avgVisibility` (on the brand and on competitors) is a **deprecated**
+legacy average from an older formula. Don't quote it.
## What NOT to say
-- _"Aim for 100."_ — 100 requires every response to mention the brand
- 4× with 2 citations of which 100% are owned, positive tone. It is
- almost never the right target. Aim for category leadership (~65+).
+- _"Aim for 100."_ — 100 needs every answer to name the brand first and
+ cite its site. It is almost never the right target. Aim for category
+ leadership.
- _"Score went down 5 points, panic."_ — single-digit movement on small
- sample sizes is noise. Always check `resultCount` before reacting.
-- _"Mentions are good, score should be higher."_ — mentions max out at
- 40 points. Without citations and sentiment, that's the ceiling.
+ samples is noise. Always check `resultCount` before reacting.
+- _"Visibility is 48%."_ — the score has no % sign. Rates and coverage
+ do.
## Math sanity checks
-If you ever need to verify, here are reference shapes:
+Reference shapes (answers = `resultCount`):
-| Mentions | Citations | Total cites | Sentiment | Score |
+| Answers | Mentioned in | Cited in | Position factor | Score |
| --- | --- | --- | --- | --- |
-| 0 | 0 | 0 | none | 0 |
-| 1 | 0 | 0 | neutral | 17 |
-| 2 | 0 | 0 | neutral | 27 |
-| 4 | 0 | 0 | positive | 55 |
-| 4 | 2 | 2 | positive | 100 |
-| 4 | 2 | 5 | positive | 91 |
-| 2 | 1 | 1 | positive | 65 |
+| 100 | 0 | 0 | — | 0 |
+| 100 | 10 | 0 | 1.0 | 11.0 |
+| 100 | 50 | 0 | 0.33 | 33.5 |
+| 100 | 50 | 10 | 0.5 | 37.9 |
+| 100 | 80 | 0 | 0.5 | 54.0 |
+| 100 | 80 | 40 | 1.0 | 70.0 |
+| 100 | 100 | 100 | 1.0 | 97.5 |
+| 10 | 10 | 0 | 1.0 | 65.0 |
+
+The last row is why small samples mislead: 10 answers, all naming the
+brand first, already score 65.