Citation Optimizer tools
Ask ChatGPT
Ask Claude
Ask Perplexity
Ask CopilotThe Citation Optimizer tools let a connected assistant drive the full score → revise → re-score loop: pick a query to optimize for, find the right page, score it for AI citation readiness, generate an improved draft, and re-score to measure the lift — repeating until the content is publish-ready.
This is the one place in the MCP server that writes to your account — but only in a contained way. It creates your own scoring runs and draft revisions so you can iterate. It never publishes anything, never edits your live pages, and never changes your existing reports or data. For the scoring model itself, see the Citation Optimizer methodology.
Only the ChatGPT pipeline can be scored today. Fan-outs for other platforms (Claude, Google AI Overviews) are tracked but return scoreable: false — use ChatGPT to optimize. The tools tell you this via a scoreable flag.
Fire-and-poll
Scoring and revising run as background jobs, so three tools are fire-and-poll: they enqueue work and return an id immediately, and you poll a companion tool until it's done.
| Kick off (returns an id) | Poll until done |
|---|---|
score_citation_pipeline → runId | get_pipeline_run(runId) until completed / stopped |
revise_content → revisionId | get_revision(revisionId) until completed |
rescore_revision → runId | get_pipeline_run(runId) until completed / stopped |
Step 1 — Pick what to optimize for
You need a query and a target (a page, URL, or draft).
list_tracked_fanouts — start here
Lists a property's real tracked fan-out queries — the queries the platform's pipeline actually generated (from the property's latest AI Visibility report), highest-impact first. Starting here beats inventing a keyword: you optimize for queries the platform is observed to produce. Each fan-out carries an isGap flag (the brand doesn't rank for it yet).
| Parameter | Type | Notes |
|---|---|---|
propertyId | string | From list_properties. |
platform | chatgpt | claude | google_aio | google_aim (optional) | Default chatgpt — the only scoreable pipeline today. |
limit | number (optional) | Max fan-outs (default 25, max 100). |
You can also score a free-text query the user brings (a target from another SEO tool, a phrase they want to rank for) — that's fully supported. A tracked fan-out just adds confidence because the platform was observed generating it.
Find the target page
| Tool | Use it to |
|---|---|
match_pages_for_fanout | Rank a property's pages by content similarity to a fan-out query — pick the closest existing page so two of your pages don't compete for the same citation. Returns candidates with a match score and an overlap flag. |
list_property_pages | List / search a property's pages by path or title, to resolve a page the user names ("optimize my pricing page") into a propertyPageId. |
list_placements | List a property's PR placements (with PQS and a hasContent flag) to find one to optimize. |
get_placement | Read a placement's content so you can score it as a draft — feed its content to score_citation_pipeline as draftMarkdown. |
Step 2 — Score
score_citation_pipeline
Scores a page, URL, or pasted draft against a fan-out query for AI citation readiness (ChatGPT pipeline). Runs in the background — returns a runId; poll get_pipeline_run(runId). Provide exactly one of propertyPageId, url, or draftMarkdown.
| Parameter | Type | Notes |
|---|---|---|
propertyId | string | The property id. |
fanOutQuery | string | The query to score against, used verbatim. A tracked fan-out or any keyword the user brings. |
groundingSearchId | string (optional) | The id from list_tracked_fanouts when scoring a tracked fan-out — marks it verified and lets the SERP gate reuse stored standings. Omit for a custom keyword. |
pageType | enum (optional) | product, homepage, informational, press_release, general, unknown (default informational). Drives the revise template. |
propertyPageId | string (optional) | Score one of the property's pages (from match_pages_for_fanout). |
url | string (optional) | Score an arbitrary URL (may be earned media). |
draftMarkdown | string (optional) | Score pasted markdown (no live URL). |
metaTitle / metaDescription | string (optional) | Optional page meta. |
get_pipeline_run
The poll target: a run's status, overall score, per-gate results, recommendations, and — crucially — a readiness verdict.
| Parameter | Type | Notes |
|---|---|---|
runId | string | The run id. |
readiness.recommendation is one of:
| Verdict | What it means | What to do |
|---|---|---|
revise_again | There's meaningful headroom. | Call revise_content. |
publish_ready | The content is citation-ready. | Stop — readiness.assistantInstruction says so. |
plateaued | Further revisions aren't moving the score. | Stop revising. |
The readiness verdict is what keeps the loop from running forever — the assistant revises only while it says revise_again.
Step 3 — Revise
revise_content
Generates a revised draft that improves the scored run's citation readiness, grounded in the gate recommendations and the page-type template. Background job — returns a revisionId; poll get_revision. Only call this when get_pipeline_run readiness is revise_again.
| Parameter | Type | Notes |
|---|---|---|
runId | string | The scored run to revise. |
get_revision
The poll target: when completed, returns the revised markdown, revised meta, JSON-LD, and a change log tracing each edit back to the recommendation that motivated it.
| Parameter | Type | Notes |
|---|---|---|
revisionId | string | The revision id. |
Step 4 — Re-score (close the loop)
rescore_revision
Re-scores a completed revision to measure the improvement: creates a new draft run from the revised content and scores it. Returns a new runId — poll get_pipeline_run(runId) for the new score and readiness verdict.
| Parameter | Type | Notes |
|---|---|---|
revisionId | string | The completed revision to re-score. |
From the new run's readiness verdict, the loop either revises again or stops.
The loop end-to-end
Choose a query. list_tracked_fanouts (or a keyword the user brings).
Find the target. match_pages_for_fanout / list_property_pages / list_placements + get_placement.
Score. score_citation_pipeline → poll get_pipeline_run until it completes.
Check readiness. If revise_again, continue. If publish_ready or plateaued, stop.
Revise. revise_content → poll get_revision.
Re-score. rescore_revision → poll get_pipeline_run. Loop back to Check readiness.
Related
- Citation Optimizer methodology — how the gates and readiness verdict work
- Citation Optimizer dashboard — the same loop in the app
- Scoring tools — AIPVS / PQS scoring for publishers and placements