MCP tool reference

On this page

Responses
Arguments
Writes
Read tools
Write tools
Plan a page prompt
Error codes
Related

Cleotic's MCP server has 44 tools: 23 that read and 21 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, perplexity, muse-spark, 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 drafting a page, returns status: "pending" with poll_after_seconds. Follow it with get_operation.
Cost. A write that uses plan capacity, a Content Studio generation, 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
`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.
`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).

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 by lane: in progress, live or needs a refresh
`get_page`	One page: its question, interview, plan, the draft as Markdown, its checks and, once live, its results
`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 Content Studio generation. Others free.
`comment_on_opportunity`	Adds a comment as you	Free

Content Studio

Tool	What it does	Cost
`create_page`	Starts a page from a content gap or a question. Pending while its interview questions are written.	Model budget
`answer_page_questions`	Answers or skips the interview; the plan is built once every question is done	Model budget
`draft_page`	Writes the draft from a ready plan, section by section	One Content Studio generation and model budget
`redraft_page_section`	Rewrites one section, optionally with an instruction such as "shorter"	Model budget
`mark_page_published`	Records the live URL of a page published outside a connected CMS, so Cleotic tracks its results	Free
`update_brand_voice`	Sets the default tone for the brand's next drafts	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, answering missed prompts straight away with 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, create the page, ask you the interview questions, and confirm with you before drafting, because drafting uses a Content Studio generation.

Error codes

A refused call returns isError: true and an error object instead of the envelope:

{ "error": { "code": "invalid_input", "message": "…", "data": { "argument": "view" } } }

Code	Meaning
`invalid_input`	An argument wasn't accepted. `data` names it and, where they're fixed, the valid values.
`invalid_date_window`	`from` is after today or after `to`, or the window is longer than 180 days
`brand_not_found`	No brand you can access matches, or a write was given a partial name
`ambiguous_brand_name`, `ambiguous_segment_name`	Several match. `data.matches` lists them.
`resource_not_found`	An ID, page or operation doesn't exist or isn't yours to read. The message says which tool lists valid IDs.
`auth_required`	The connection isn't signed in
`unsupported_tool`	The tool doesn't exist or isn't available on this connection
`terms_required`	Accept Cleotic's current terms in the app
`forbidden`	Your role or brand access doesn't allow the action
`conflict`	The `idempotency_key` was used for a different action, or that write is still in progress
`plan_limit`	The plan has no capacity left for it
`plan_feature_unavailable`	The plan doesn't include the feature
`content_studio_quota_exhausted`	The month's Content Studio generations are used
`budget_exceeded`	The month's model budget is used
`trial_lockdown`	The trial or subscription has ended, so data is read-only
`rate_limited`	Cleotic is limiting requests for this work; wait and retry
`scheduled_only`, `run_active`	A full scan can't be started by hand now, or one is already running
`verify_cooldown`, `cooldown`, `monthly_cap`, `check_in_progress`, `already_resolved`	A readiness re-check can't run yet; `data.next_available_at` says when
`response_too_large`	The response would be over 32 KB. Narrow it with filters or a smaller `limit`.
`internal_error`	Something 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.

Updated 3 October 2026

MCP tool reference

Responses

Arguments

Writes

Read tools

Documentation

Brands and plan

Answers and evidence

Site readiness

Opportunities and Content Studio

Following up

Write tools

Opportunities

Content Studio

Site readiness

Brands and setup

Reports and deleting

Plan a page prompt

Error codes

Related