MCP & API

MCP tools reference

All 23 CiteCue MCP tools with their parameters, defaults and limits, what each returns, who can call it, what each write changes, and the error codes.

13 min read

This page lists every tool the CiteCue MCP server offers, with its parameters and what it returns. Your agent reads the same tool descriptions from the server and picks tools itself, so you rarely name one. Use this page to check what a question can be answered with, and what a change will do before you ask for it.

How the tools work

  • Call list_projects first. Every other tool requires a projectId, and list_projects is where it comes from.
  • Inputs are strict. A parameter a tool doesn't define is refused, not ignored, so a misspelled name fails instead of being silently dropped. All parameters are optional unless marked required.
  • days sets the range on the tools that take it: a whole number from 1 to 365, counted back from now. Only complete scans count. The default is 30. Except on get_lost_prompts, when no complete scan falls in the range the tool uses the latest complete scan instead.
  • Timestamps are epoch milliseconds. get_lost_prompts is the exception: its dates are YYYY-MM-DD days in UTC.
  • Each result is one JSON object, sent both as text and as structured content.

Read tools

Any project role can call these (Member, Admin or Owner), and so can an API key on projects in its own organization. list_projects needs no project and works on every plan.

Tool Parameters Returns
list_projects none projects, across every organization the credential can see: projectId, orgSlug, orgName, projectSlug, name, domain, status (pending, analyzing, ready or failed), lastScanAt (latest complete scan, or null), mcpAccess (full or locked) and dashboardUrl.
get_overview days brand, hasData, visibilityScore (0–100), brandMentionRatePct, brandCitationSharePct, totalCitations, totalResponses, topCompetitor (the most-cited competitor domain, as name and citations), previousScan and visibilityTrend. The headline figures come from the latest complete scan in the range, and previousScan is the scan before it. visibilityTrend covers the last 24 complete scans, whatever the range. measurementChanges lists the scans from which CiteCue collected a platform's answers differently (scanId, at, platforms). Values on either side of one aren't directly comparable, so when the latest scan is one, previousScan is null and a note says why.
get_report_summary none The report for the latest complete scan: visibility (score and a letter grade), owners (citation shares by owner), topDomains, topicVisibility (up to 15), factorGaps, recommendations, leaderboard (up to 8) and promptHighlights (up to 15). Before the first complete scan, hasData is false.
get_competitors days sov (your share of all brand mentions, with the mention counts), entities (you and your tracked competitors, top 10 by mentions, each with name, entityType, mentionCount, responseCount, sovPct and rank), sovTrend (share per scan, last 24 complete scans), measurementChanges (as in get_overview) and suggestions. sov and entities pool every scan in the range. suggestions are the brands waiting on the Suggested tab of Competitors, up to 10, most-seen first, whatever the range: id (pass it to add_competitor), name, domain, relationship (direct, adjacent, or null on older suggestions) and responseCount (how many answers named the brand in the latest scan that suggested it).
get_topic_grid days topics, the first 20 alphabetically, counting only topics where some answer named you or a competitor. Each has brandResponses (answers naming you) and up to 8 tracked competitors, each with name, responses and a result of win, loss or tie, read from your side: win means more answers named you than that competitor.
list_prompts topic (case-insensitive match within the topic name); limit 1–50, default 25 prompts: id, text, topic, tags, enabled and brandMentionedLatest (named in an answer from the latest complete scan). Disabled prompts are included. There is no paging and no sort order, so at most 50 prompts come back; on a large project, narrow the list with topic.
get_prompt_detail promptId (required, from list_prompts; an id that isn't on the project returns not_found) prompt; from your latest complete scan: visibilityScore, which despite its name is the share of that scan's successful answers to this prompt that named your brand (null when that scan did not ask it), current (the answer counts behind it and mentionRateChange, its change in points against the previous scan that measured the prompt) and citationShare (brand, competitor and third-party shares of that scan's citations for the prompt); latestResponses, the newest answer from each platform with a shortened excerpt (its first two lines, the lines around your brand's first mention and its last two lines); and, across all complete scans, series (the share per scan, last 24), with measurementChanges for the platforms that answered this prompt (as in get_overview), byModel (that share per model) and executions, the 10 latest runs, each with model, brandMentioned, your position, mentionedEntities (the brands named, up to 8), citationCount and sentiment, without answer text.
get_lost_prompts days 1–365, default 30, or from and to as YYYY-MM-DD; includeRecovered, default true; limit 1–100, default 50 range (the days covered and the number of scans), summary (lost, stillLost, recovered and rebaselined, counted before includeRecovered and limit apply), truncated (questions left out by limit) and prompts. Each prompt has promptId, text (cut at 160 characters), topic and platforms, each with platform, lostAt, a status of still_lost, recovered, rebaselined (the platform's answers are collected differently now, so the return can't be compared) or no_longer_tracked, and recoveredAt and lossCount where they apply. includeRecovered=false keeps rebaselined.
get_citations owner (brand, competitor or third_party); limit 1–25, default 15; days owners (brandPct, competitorPct, thirdPartyPct and total, always for all owners) and topDomains, most cited first: domain, owner, count, brandMentioned (whether any answer citing it named you), influenceScore and up to 5 topics. owner filters topDomains only.
get_factor_gaps none From the latest complete scan, items with the biggest gap first: factor, label, brandAvg, competitorAvg, gap, severity (high, medium or low), recommendation, and up to 2 examples from competitors. Only factors scored for both you and your competitors appear. A score reflects how answers portrayed a brand, not a count of its reviews or links.
get_insights days Up to five insights, each with title, detail and a tone of positive, negative or neutral. They cover your mention rate, the most-cited competitor domain, cited domains whose answers name competitors but never you, topics where none of your own pages is cited, and the largest factor gap.
get_opportunities status (new, planned, in_progress or resolved); limit 1–20, default 10 items, highest priority first, from every kind of fix, readiness and usability failures included: id (pass it to update_opportunity_status), title, whyItMatters, topic, impact, effort, status and actionKinds. Open content and citation fixes past your plan's limit, which the Fixes tab under Changes also hides, are left out.
get_sentiment days headline (positivePct, neutralPct, negativePct and analyzed, the number of answers classified) and byPlatform, both pooled over the range, plus up to 8 quotes from the latest scan in the range, most concerning first.
get_referrals none (always the last 30 days) stats (totalVisits30d, weekOverWeekPct and topSource), sources (visits per AI assistant), up to 10 landing pages, and hasData.
get_ai_readiness from and to, each an ISO date or epoch milliseconds written as a string; default the 30 days up to now checks, each with checkId, a status of pass, fail, unknown or not_applicable, details, and item: the check's fix, including its id, or null if the check has never failed. Also indexCoverage (null without Search Console data), gscConnected, sitePlatform, lastCheckedScan, lastCheckedAt and meta. The range only affects meta; the checks always show the latest results.
get_agent_usability none runs (the history of agent test runs), findings (id, title, status, impact, runId and recommendations), agentActions (a score and checks shaped like readiness checks), usage and maxTasksPerRun. No tool starts a run.
list_scans limit 1–50, default 20 scans, newest first: id, status, progressDone, progressTotal, createdAt and finishedAt. Discarded scans are left out.
get_scan_status scanId (required) id, status, progressDone, progressTotal, error, startedAt and finishedAt. The status is queued, running, analyzing, batching, complete, failed, cancelled or discarded.

The metrics behind these fields are defined in How metrics are calculated.

Write tools

Project Admins and organization Owners can call these, and so can an API key on projects in its own organization. A Member gets forbidden. Each write runs the same checks and spends the same plan allowances as the matching dashboard action.

Tool Parameters Returns
start_scan none scanId and status (queued).
add_prompts prompts (required): 1–50 items, each with text (3–500 characters) and an optional topic (up to 120 characters); locale for the whole batch, a language-and-market code such as de-DE created (id, text, topic and locale of each new prompt) and skipped (text and a reason of duplicate).
update_prompt promptId (required), plus at least one of text (3–500 characters), topic (up to 120 characters) and enabled (true or false) The prompt: id, text, topic, tags, platforms, source, enabled, stage, locale and isKey.
add_competitor competitor (required): either suggestionId (from get_competitors), or name (1–200 characters) and domain (1–255 characters) added: true with the new competitor and the full competitors list, or alreadyTracked: true with competitors.
update_opportunity_status opportunityId (required), plus at least one of status (new, planned, in_progress or resolved) and skipped (true or false) id, status, resolvedByScanId, resolvedAt and skippedAt.

start_scan

Asks AI engines every enabled prompt in the project, exactly like Run scan. It is a manual scan: it counts against your organization's monthly manual-scan allowance, and you can stop it from the dashboard with Stop scan. Each successful call starts, and spends, a new scan. Poll get_scan_status with the returned scanId until the status is complete, failed, cancelled or discarded.

Code details.reason When
not_ready not_ready The project is still being set up.
not_ready setup_preparing Setup is still writing the project's prompts; its first scan starts on its own in a few minutes. No scan is started and none of your allowance is used.
not_ready no_prompts The project has no enabled prompts. No scan is started and none of your allowance is used.
not_ready domain_decision_pending Your website redirects to another domain. Choose which domain to track on Business details first.
conflict concurrent The project already has as many scans running as your plan allows at once. The message starts "A scan is already running for this project."
limit_reached manual_limit Your organization has used its manual scans for this calendar month.
conflict none A rare clash with another request at the same moment. Try again.

add_prompts

Creates each new prompt switched on, with the source User, the topic you gave (or "General") and all available platforms. Prompts are saved in your project's locale, the Language set on Business details, unless you pass locale for the batch; a project with no locale uses English (United States). created shows the locale each prompt got. A prompt is skipped as a duplicate when the same text, ignoring case and in the same locale, is already on the project or appears earlier in the same call, so re-sending a batch is safe. The batch is all or nothing: if the new prompts don't fit, none are created.

Errors: limit_reached when the new prompts would take your organization past its active-prompt allowance (details gives limit, used and remaining), past its ceiling on stored prompts, which counts switched-off prompts too, or past your plan's number of locales per project. A locale CiteCue doesn't offer is refused as invalid input.

update_prompt

Changes only the fields you send. enabled: false switches a prompt off: it is no longer scanned, it frees a slot in your active-prompt allowance, and it keeps its history. That is the only way to retire a prompt here; there is no delete tool. enabled: true switches it back on and uses a slot again. An empty topic resets the topic to "General". Key prompts, tags, locale and platforms can't be changed here; use Prompts Monitoring.

Errors: not_found ("Prompt not found"); limit_reached when switching a prompt on would go past your active-prompt allowance; conflict ("Prompt changed concurrently; retry the update").

add_competitor

Adds a brand to the project's tracked competitors in Business details, so future scans measure share of voice against it. If a competitor with the same name is already tracked (matched on the name, not the domain), nothing changes and the result says alreadyTracked. Only the dashboard can remove a competitor.

To accept a brand CiteCue suggested, pass its suggestionId from get_competitors. It is added with the suggestion's name and domain, and it leaves the Suggested tab as if you had added it there. A suggestion for a brand you already track is marked added too. There is no tool for dismissing a suggestion.

Errors: limit_reached when the project already tracks as many competitors as your plan allows; not_found ("Suggestion not found") for an id that isn't a suggestion on the project; conflict ("Suggestion has already been reviewed") for one already added or dismissed, when the project has no brand information yet, or when its competitors changed at the same moment (retry).

update_opportunity_status

Sets a fix's status, or sets it aside, as you can in the dashboard. status moves it between New, Planned, In progress and Resolved. Setting a status clears any record of a scan having resolved the fix, and resolved set this way counts as resolved by a person. skipped: true sets the fix aside from recommendations without closing it: it is badged Skipped and left out of Recommended next three and the report's recommendations. skipped: false brings it back.

Pass the id of an item from get_opportunities. The same ids also appear in get_ai_readiness (checks[].item.id, for a check that has failed) and get_agent_usability (findings[].id and agentActions.checks[].item.id).

Errors: not_found ("Opportunity not found") for an id that isn't on the project.

Errors

A tool that fails returns a result marked isError: true. The error payload appears both as JSON text and as structured content:

{
  "code": "plan_locked",
  "message": "MCP access isn't included in this organization's plan. Upgrade to connect an AI agent to this project.",
  "upgradeUrl": "https://app.citecue.com/org/your-org/billing"
}
  • code is one of the codes below.
  • message is a sentence you can show a person, never a stack trace. Plan messages match the dashboard's.
  • upgradeUrl appears only with plan_locked.
  • details is optional and only ever carries reason, limit, used and remaining.
Code Meaning
not_found The project, scan, prompt, suggestion or fix doesn't exist or isn't visible to you. A project you can't open is reported exactly like one that doesn't exist, even when its organization's plan doesn't include MCP.
forbidden Your role can't make this change ("Insufficient role"). Writes need project Admin or organization Owner.
plan_locked The organization's plan doesn't include MCP access.
invalid_input The input can't be used, such as a date range that ends in the future. The message says what to fix.
limit_reached A plan allowance is used up. Switching prompts off, deleting prompts in the dashboard, waiting for the next month, or upgrading frees room, depending on the allowance.
conflict The request clashed with the project's state, such as the project already running as many scans as your plan allows, or a change made at the same moment.
not_ready The project can't be scanned yet; details.reason says why.
rate_limited A service behind the tool asked for fewer requests. Wait and try again.
locked The organization's data is being moved or deleted, so changes are paused for a few minutes. Reading still works; try the change again shortly.
internal Something failed on CiteCue's side: "The request failed. Please try again."

A call whose parameters don't match the tool's schema (an unknown or missing parameter, or a value out of range) also comes back with isError: true, but as a plain-text "Input validation error" message with no code.

Connection problems, such as HTTP 401 or 429, are HTTP responses rather than tool errors. See the troubleshooting table in Connect an AI agent.

What no tool can do

  • Delete anything: prompts, competitors, scans, fixes or projects. Switch a prompt off instead.
  • Remove a competitor, dismiss a suggested one, or edit Business details beyond adding a competitor.
  • Star key prompts, or change an existing prompt's tags, locale or platforms.
  • Generate prompts with CiteCue's AI, import prompts, or stop a scan.
  • Start an Agent Usability run, or apply, approve or publish a fix or an AI Auto-Fix page.
  • Read crawler traffic, or the full text of an AI answer: get_prompt_detail returns a shortened excerpt of each platform's newest answer only.
  • Create reports, share links or exports.
  • Change billing, plans, team members, roles, API keys, scan schedules or alerts.

Next steps