Cleotic's MCP server has 50 tools: 27 that read and 23 that change something. Your assistant gets each tool's full arguments and response schema when it connects, so this page covers what each tool is for, what it costs, and the conventions they share. To connect, see Connected Agents.
Responses
Every tool returns the same envelope, as structured content and as text:
Keys are snake_case and use the app's names: brand, segment, page, answer.
Times are RFC 3339 in UTC and days are YYYY-MM-DD.
Lists are [] when empty, never null.
Visibility, share of voice and recommendation come as a metric with their basis: value, the likely range low to high, change on the previous period, changed when the change is larger than normal variation, calibrating when fewer than 10 answers back it, and the answers, models_collecting, models_expected and period behind it. See Visibility metrics.
The resource cleotic://mcp/v1/schema repeats these conventions for the assistant.
Arguments
brand takes a brand or study ID from list_brands, or its name. Reads accept an exact name or a unique prefix, ignoring case; writes take the ID or the exact name and refuse a partial one.
segment takes a segment ID or its exact name, from get_brand_settings.
model takes a model family: chatgpt, claude, gemini, google-ai-overviews or google-ai-mode, as the plan tracks them. gemini doesn't include Google's AI Overviews or AI Mode.
from and to are days, YYYY-MM-DD. The default is the 30 days to today. A window is at most 180 days, from can't be after today, and a to after today counts as today.
limit and cursor page through lists: up to 100 rows a page, 25 by default. A page can hold fewer rows to stay within the 32 KB response limit, so pass next_cursor until it's empty.
An argument a tool doesn't take, or a value it can't use, is refused with invalid_input, naming the argument and the valid choices.
Writes
Every write takes an idempotency_key: a unique string, up to 128 characters, for the action you intend.
Retrying. Send the same key with the same arguments. The write isn't made again; the reply is the first call's result with replayed: true and the current status.
A new action needs a new key. The same key with different arguments is refused with conflict.
Work that takes time, such as reading a website, a readiness scan or a turn of the page agent, returns status: "pending" with poll_after_seconds. Follow it with get_operation.
Cost. A write that uses plan capacity, a Content Studio page, a readiness scan or check, or model budget says so in its description and reports what it used as cost. An assistant should confirm these with you first.
Each write returns operation_id, status, brand, the saved resource, any progress, and cost.
Read tools
Documentation
Tool
What it does
search_docs
Searches these docs by keyword. Works before you accept the terms.
get_doc
Fetches one docs page by slug, such as brand/opportunities. Links inside a page are slugs it takes.
Brands and plan
Tool
What it does
list_brands
The brands and studies you can access, with visibility, share of voice, recommendation, citations, readiness, collection health, AI traffic and the inbox's Now stage. Start here to find a brand ID.
get_brand_overview
The brand's Overview in one call: its metrics and change, how it stands against its main competitors, and headline readiness, traffic, inbox and Content Studio status. A segment filters the answer metrics.
get_brand_settings
The primary brand, competitors, segments with their market, language and models, site and CMS status, and brand voice. Gives the IDs other tools take.
get_plan
The plan's limits and what's used, included features, the Content Studio allowance, the model budget and the models segments collect from.
Answers and evidence
Tool
What it does
list_prompts
Tracked prompts, highest AI search demand first, with how many answers in the period mention the brand
list_answers
Answers, newest first. With prompt_id, that prompt's answers across models; without it, the answers that mention the brand, with the mention in context.
get_answer
One answer in full, with the brands it mentions and recommends, its ranked list, outcome and citations. On plans with Reputation it adds the claims the answer makes about the brand, each with its verdict, kind and narrative.
get_perception
How answers describe the brand and its competitors: scores out of 10 on each dimension, by model, with evidence quotes and trend. Not on every plan. For what answers claim about the brand, use get_reputation.
list_citations
Cited sources. view is overview (totals by ownership and source type, by week), domains (with source gaps) or pages (ranked by influence).
get_citation_source
One cited domain or page: its citations, models, the brands named alongside it, snippets and trend
get_ai_traffic
AI crawler visits and referrals from the site's tracking. view is summary, pages or evidence (individual visits). The summary also lists search engines such as Googlebot, which no total counts.
What answers claim about the brand: open narratives with their severity, state, the engines carrying each as "k of n" answers, first sighting, a quote, the confirmed fact it contradicts and the top cited source. Also how many answers naming the brand carried a risky claim, with strengths listed apart.
get_narrative
One narrative from get_reputation: the questions it appears in, the latest quotes from each engine with answer IDs for get_answer, its alerts, and any decision your team made on it
Site readiness
Tool
What it does
get_readiness
The latest site scan. view is summary, action_plan (open findings and questions no page answers), pages, history or competitors.
get_readiness_finding
One check: why it matters, its drafted fix and the pages where it fails. Follows a verify_readiness_fix re-check.
Opportunities and Content Studio
Tool
What it does
list_opportunities
The opportunity inbox, with each item's kind, score, demand, stage and assignee, and counts by stage
get_opportunity
One opportunity with its evidence, its play and the tool call that carries it out, before-and-after proof, timeline and comments
list_pages
Content Studio pages with their status: drafting, sent, live or revising
get_page
One page: its brief, target questions, outline, the page as Markdown, the latest conversation with Cleotic's page agent (including any question it's waiting on), suggestions, authority notes and, once live, its results
search_facts
The brand's facts: confirmed ones it stands behind and proposed ones waiting for it, searched by words and meaning
search_site
Passages from the brand's own website that match a query, from the pages its latest site readiness scan found
list_reports
Saved reports with their date ranges and public links
Following up
Tool
What it does
get_brand_setup
A brand setup's progress and, once it's ready, its proposals for approval
get_operation
A write's live status, progress and when to check again. Only the member and connection that made the write can read it.
suggest_prompts
Suggests prompts for a segment about a topic, ranked by AI search demand where there's data for it. Saves nothing. Cost: one model call from the model budget.
Write tools
Opportunities
Tool
What it does
Cost
update_opportunities
Moves up to 100 opportunities to a stage, assigns, snoozes, dismisses or restores them, all together or none
Free
act_on_opportunity
Records a play and moves the item to Watching: fix_shipped, pitched, optimised, track_prompts or draft_outreach
track_prompts: an active prompt per question and their first answers. draft_outreach: one from the Content Studio allowance. Others free.
comment_on_opportunity
Adds a comment as you
Free
Content Studio
Tool
What it does
Cost
create_page
Starts a page and hands it to Cleotic's page agent: from a content gap, an idea, a Markdown draft or a page to import. Pending while the agent works.
One Content Studio page, counted once the agent first writes it, and model budget
message_page
Talks to a page's agent as you: answer its question, ask for a change or approve its outline. Pending while it works.
Model budget
edit_page
Changes the page yourself: its Markdown, exact find-and-replace edits, or its title, goal, reader or angle. Needs the page's current version.
Free
send_page_to_cms
Sends the page to the brand's only ready CMS destination as a new draft; never publishes
Free
mark_page_published
Records the live URL of a page published outside a connected CMS. The page locks and its results start.
Free
revise_page
Unlocks a live page for changes; results keep counting from when it first went live
Free
update_brand_voice
Sets the default tone for the brand's next drafts
Free
save_fact
Adds a fact, or edits, confirms or rejects one. A fact the user told the assistant is confirmed; one it found is proposed with its source.
Free
Site readiness
Tool
What it does
Cost
run_readiness_scan
Starts a full scan. Owners and admins only, and only until the first scan completes; later scans run weekly, and the call is refused with scheduled_only.
One scan
verify_readiness_fix
Re-checks one fix without a full scan, by inbox opportunity_id or by check_id
By opportunity: free, once every 10 minutes. By check: one of the plan's monthly re-checks.
Brands and setup
Tool
What it does
Cost
start_brand_setup
Reads a website and proposes the brand, competitors, a segment and prompts
Model budget
approve_brand_setup
Creates the brand from the proposals you keep, in the market you confirm
A brand, a segment and the kept prompts of plan capacity; model budget for first answers and the first readiness scan
update_brand
Renames a brand or study, or pauses or resumes it
Resuming restarts collection, using plan capacity and model budget
set_primary_brand
Creates or edits the tracked brand's name, domain or aliases. aliases replaces the list. A naming change re-reads existing answers.
Free
save_competitor
Adds a competitor, or edits, pauses or resumes one
A new competitor is one tracked brand of capacity
save_segment
Adds a segment, or edits, pauses or resumes one
An active segment is plan capacity and collects on every plan model
save_prompt
Adds a prompt, or edits one. New text replaces the prompt and keeps the old one's answers.
An active prompt of capacity and its first answers
Reports and deleting
Tool
What it does
Cost
create_report
Saves a shareable report for a date range and returns its public link
One report of capacity; model budget for its summary where the plan includes one
revoke_report
Kills a report's public link for good. The report stays listed as revoked.
Free
delete_item
Deletes one competitor, segment, prompt, page or report. It can't be restored; deleting a segment deletes its prompts and their answers.
Free, and frees the capacity
To stop tracking something but keep its history, pause it instead of deleting it.
Plan a page prompt
Clients that support MCP prompts can offer Plan a page. Given a brand, it walks the assistant through the strongest content gap: read it, confirm with you before creating the page (it uses one of the plan's Content Studio pages), relay the page agent's questions to you, and offer to send the finished page to your CMS.
Error codes
A refused call returns isError: true and an error object instead of the envelope: