MCP tool reference

Updated 31 October 2026 · 10 min read
On this page

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:

{
  "schema_version": "v1",
  "generated_at": "2026-10-03T09:00:00Z",
  "data": { }
}
  • 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

ToolWhat it does
search_docsSearches these docs by keyword. Works before you accept the terms.
get_docFetches one docs page by slug, such as brand/opportunities. Links inside a page are slugs it takes.

Brands and plan

ToolWhat it does
list_brandsThe 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_overviewThe 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_settingsThe primary brand, competitors, segments with their market, language and models, site and CMS status, and brand voice. Gives the IDs other tools take.
get_planThe 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

ToolWhat it does
list_promptsTracked prompts, highest AI search demand first, with how many answers in the period mention the brand
list_answersAnswers, 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_answerOne 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_perceptionHow 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_citationsCited sources. view is overview (totals by ownership and source type, by week), domains (with source gaps) or pages (ranked by influence).
get_citation_sourceOne cited domain or page: its citations, models, the brands named alongside it, snippets and trend
get_ai_trafficAI 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.

Reputation

On Business and above. See Reputation.

ToolWhat it does
get_reputationWhat 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_narrativeOne 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

ToolWhat it does
get_readinessThe latest site scan. view is summary, action_plan (open findings and questions no page answers), pages, history or competitors.
get_readiness_findingOne check: why it matters, its drafted fix and the pages where it fails. Follows a verify_readiness_fix re-check.

Opportunities and Content Studio

ToolWhat it does
list_opportunitiesThe opportunity inbox, with each item's kind, score, demand, stage and assignee, and counts by stage
get_opportunityOne opportunity with its evidence, its play and the tool call that carries it out, before-and-after proof, timeline and comments
list_pagesContent Studio pages with their status: drafting, sent, live or revising
get_pageOne 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_factsThe brand's facts: confirmed ones it stands behind and proposed ones waiting for it, searched by words and meaning
search_sitePassages from the brand's own website that match a query, from the pages its latest site readiness scan found
list_reportsSaved reports with their date ranges and public links

Following up

ToolWhat it does
get_brand_setupA brand setup's progress and, once it's ready, its proposals for approval
get_operationA write's live status, progress and when to check again. Only the member and connection that made the write can read it.
suggest_promptsSuggests 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

ToolWhat it doesCost
update_opportunitiesMoves up to 100 opportunities to a stage, assigns, snoozes, dismisses or restores them, all together or noneFree
act_on_opportunityRecords a play and moves the item to Watching: fix_shipped, pitched, optimised, track_prompts or draft_outreachtrack_prompts: an active prompt per question and their first answers. draft_outreach: one from the Content Studio allowance. Others free.
comment_on_opportunityAdds a comment as youFree

Content Studio

ToolWhat it doesCost
create_pageStarts 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_pageTalks 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_pageChanges 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_cmsSends the page to the brand's only ready CMS destination as a new draft; never publishesFree
mark_page_publishedRecords the live URL of a page published outside a connected CMS. The page locks and its results start.Free
revise_pageUnlocks a live page for changes; results keep counting from when it first went liveFree
update_brand_voiceSets the default tone for the brand's next draftsFree
save_factAdds 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

ToolWhat it doesCost
run_readiness_scanStarts 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_fixRe-checks one fix without a full scan, by inbox opportunity_id or by check_idBy opportunity: free, once every 10 minutes. By check: one of the plan's monthly re-checks.

Brands and setup

ToolWhat it doesCost
start_brand_setupReads a website and proposes the brand, competitors, a segment and promptsModel budget
approve_brand_setupCreates the brand from the proposals you keep, in the market you confirmA brand, a segment and the kept prompts of plan capacity; model budget for first answers and the first readiness scan
update_brandRenames a brand or study, or pauses or resumes itResuming restarts collection, using plan capacity and model budget
set_primary_brandCreates or edits the tracked brand's name, domain or aliases. aliases replaces the list. A naming change re-reads existing answers.Free
save_competitorAdds a competitor, or edits, pauses or resumes oneA new competitor is one tracked brand of capacity
save_segmentAdds a segment, or edits, pauses or resumes oneAn active segment is plan capacity and collects on every plan model
save_promptAdds 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

ToolWhat it doesCost
create_reportSaves a shareable report for a date range and returns its public linkOne report of capacity; model budget for its summary where the plan includes one
revoke_reportKills a report's public link for good. The report stays listed as revoked.Free
delete_itemDeletes 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:

{ "error": { "code": "invalid_input", "message": "…", "data": { "argument": "view" } } }
CodeMeaning
invalid_inputAn argument wasn't accepted. data names it and, where they're fixed, the valid values.
invalid_date_windowfrom is after today or after to, or the window is longer than 180 days
brand_not_foundNo brand you can access matches, or a write was given a partial name
ambiguous_brand_name, ambiguous_segment_nameSeveral match. data.matches lists them.
resource_not_foundAn ID, page or operation doesn't exist or isn't yours to read. The message says which tool lists valid IDs.
auth_requiredThe connection isn't signed in
unsupported_toolThe tool doesn't exist or isn't available on this connection
terms_requiredAccept Cleotic's current terms in the app
forbiddenYour role or brand access doesn't allow the action
conflictThe idempotency_key was used for a different action, or that write is still in progress
plan_limitThe plan has no capacity left for it
plan_feature_unavailableThe plan doesn't include the feature
content_studio_quota_exhaustedThe month's Content Studio allowance is used
budget_exceededThe month's model budget is used
trial_lockdownThe trial or subscription has ended, so data is read-only
rate_limitedCleotic is limiting requests for this work; wait and retry
scheduled_only, run_activeA full scan can't be started by hand now, or one is already running
verify_cooldown, cooldown, monthly_cap, check_in_progress, already_resolvedA readiness re-check can't run yet; data.next_available_at says when
response_too_largeThe response would be over 32 KB. Narrow it with filters or a smaller limit.
internal_errorSomething went wrong on Cleotic's side. For a write, check get_operation before retrying.

Calls over the hourly limit of 600 fail before they reach a tool, with HTTP 429 and a Retry-After header.