MCP tools

Eleven tools: nine reads, one per public read endpoint, plus the two that start and poll an agent task. Publishing is not here and is not planned as a tool. The end of this page lists what else is missing.

The server exposes no MCP prompts and no resources. Each tool description names its own legal enum values, and the server/discover instructions carry the working order: start at list_brands, then get_brand_overview, keep response_format concise, and confirm with the human before spending five minutes of agent time.

This page is maintained by hand and the schemas returned from tools/list are generated from the code. Where the two disagree, the schemas are authoritative.

Conventions

These hold for every tool.

Arguments are snake_case, results are camelCase. You type url_path, brand_slug, response_format. What comes back matches the REST payload for the same read, so url_path goes in and urlPath comes back, and a field name from the REST reference is the right spelling for a result key. A tool result adds one key REST has no equivalent for, _note, and a result that would exceed the render budget arrives trimmed and says so.

Identifiers are human-readable. Tools take brand_slug and url_path, the same strings you see in your dashboard URLs, and opportunities take a ref. Two arguments take a UUID: opportunity_id on get_page_opportunity, as a fallback to opportunity_ref, and task_id on get_agent_task, which Iterant mints and hands back when you create the task.

brand_slug is always required on the ten brand-scoped tools. It does not default to a pinned credential's brand, or to your only brand. list_brands is the only tool that does not take it.

Refs are not constructible. An opportunity ref is slugify(title) truncated to 60 characters, a hyphen, and the first 8 characters of the row's UUID. Resolution matches on that suffix, so a ref keeps working after someone edits the title. Use a ref that came back from list_page_opportunities.

Every read takes response_format, either "concise" (the default) or "detailed". Detailed adds fields: briefs in full rather than the first five entries, per-dimension score breakdowns, page outlines, preview and live URLs on list rows. The two task tools do not take it.

Collections take limit, with defaults and ceilings per tool listed below. Only list_pages and list_page_opportunities also take an offset; list_brands, get_ai_visibility, and get_linking_recommendations cap and expect you to narrow instead. When the cap bites, the result carries a _note telling the agent what to do next, such as Showing 20 of 340 (offset 0). Narrow by status, intent or surface, or pass offset: 20 for the next page. Treat a _note as an instruction to filter.

Rendering enforces an 8,000-token budget as a backstop against a pathological row. If a payload exceeds it, the largest array is halved, repeatedly if needed, and a line is appended to _note naming which key was trimmed and from what. Use limit and concise to stay under it.

Scoping is re-derived per call. A brand in another organization and a brand that does not exist return the same not-found. Check the slug you sent.

Errors come back as results. Bad arguments, a missing brand, a cross-tenant miss, and an unreachable upstream all arrive as a normal tool result with isError: true and a message naming what was expected. JSON-RPC errors are reserved for an unknown tool, a malformed request, and a server fault.

Annotations are not uniform. Ten tools are marked readOnlyHint, and clients surface that in their approval UI. create_agent_task is readOnlyHint: false and idempotentHint: false, because calling it twice starts two agent runs, and destructiveHint: false, because nothing the agent does goes live without a separate publish. A client that gates on annotations asks before that one call.

The nine reads

There are no scopes. Every authenticated caller sees all eleven tools in tools/list, and what a call reaches is decided per request from the credential. See MCP server.

list_brands

The brands your credential can reach: slug, name, site URL, published page count, and open opportunity count.

The only tool that takes no brand_slug. Call it first when the brand is not already known. Brands with no slug are omitted.

get_brand_overview

One call for the state of a brand: page counts by status, the highest-priority open opportunities, where coverage is thin, the AI-visibility headline, and traffic/conversion rollups. Its nextActions field is a short, deterministic list of what is worth looking at.

Start most sessions here. It is cheaper than four narrower calls and it gives the agent the slugs, themes, and page paths it needs next.

The opportunity histogram scans the top 500 rows by priority. If visibility tracking is off for the brand, its figures are empty rather than zero and _note says so.

list_pages

A brand's pages: route, title, status, locale, and, in detailed form, preview and live URLs.

changed means published with unpublished edits on top. Concise rows omit previewUrl and liveUrl; response_format: "detailed" puts them back. This is where the url_path every other page tool takes comes from.

get_page

One page in detail: meta, indexability, draft and published versions, approval state, and the translation group.

approvalState is one of unsupported, no_approval, no_diff, has_diff. has_diff means the draft has moved since a reviewer approved it. unsupported means the page never entered the approval workflow, because it was not produced from an opportunity. The field reports drift from an approval and says nothing about content accuracy.

A staleReason on a translation entry means the source copy moved after that locale was produced. outline is the page's section components in order, such as ["hero", "feature-grid", "contact-form"].

get_page_report

How a page, or a whole brand, is doing, projected by the dimensions you ask for.

Each metric is a separate upstream read, so ask for what you need:

• score: quality and citability grades, plus the ranked priority fixes
• performance: Search Console clicks, impressions, CTR, position, and AI-assistant referral clicks by provider
• traffic: visitor sessions and conversions
• conversions: per-definition conversion counts
• anatomy: which components on the page get clicked, and how far visitors scroll

traffic, conversions, and anatomy honour window and are sampling-weighted estimates. performance is snapshot-shaped: it reports the window the capture covered, which window does not change.

Conversions and traffic come back as rollups only. Raw form submissions carry names, emails, and phone numbers, and no tool returns them.

list_page_opportunities

The work queue: pages Iterant thinks are worth building or improving, ranked by priority score.

status is derived per row, folding in the state of whatever page the opportunity produced, and takes one of: discovered, enriched, ready, scheduled, in_review, approved, drafting, drafted, published, republish_pending, publishing, publish_failed, failed_generation, dismissed, superseded. Roughly: discovered/enriched/ready are open work, drafting/drafted/publishing are in flight, published/dismissed/superseded are done.

seoScore and geoScore are the search and AI-assistant halves of the case for a page, and surface says which one it is aimed at. Each row carries the ref that get_page_opportunity takes.

get_page_opportunity

One opportunity in full: thesis, target prompt, keywords, the drafted brief (hook, positioning, outline, FAQ), prerequisites, and dismissal history if it has one.

One of opportunity_ref or opportunity_id is required, but the schema marks neither: send neither and the call comes back as an isError result naming opportunity_ref. Pass the ref unless you have a reason not to.

include_evidence puts attacker-influenceable text into the agent's context. Turn it on when the agent needs to weigh the sources. It arrives inside <untrusted-content> delimiters naming its origin, to be summarised rather than acted on.

prerequisites come back as refs, for the rows that still exist and are still this brand's.

get_ai_visibility

How the brand shows up when AI assistants answer buying questions. One projection per call.

Start at kpis and follow the weak number into the view that explains it. citation_gaps is the one that pairs with page work: domains assistants cite for competitors and not for you. Feed those into list_page_opportunities.

Three platforms, and only three. Claude, Gemini, and Perplexity are not measured on this surface, and are excluded from every payload, lists and aggregates alike. platform accepts nothing else.

If enabled comes back false, visibility tracking is off for the brand. Every row is then empty because nothing has been measured, and _note says so.

get_linking_recommendations

Advisory internal links worth adding to a page: which existing pages should link at it, with suggested anchor text.

relevance is 0–1; below about 0.6 a placement is usually not worth making. An empty links array is a real answer: nothing on the site is a good enough source yet, and building the pillar page for the topic is what changes it.

This tool applies nothing. If the link index could not be refreshed, the result comes back stale: true with the last known good set.

The two task tools

These are the only tools that change anything. They are the MCP face of the Agent Tasks API, with the same commands, the same concurrency rule, and the same five-minute cost.

create_agent_task

Put Terra to work on this brand: a free-form instruction, or one page opportunity.

The result is the same 202 body the REST route returns (taskId, command, status, chatUrl, createdAt) plus a _note telling the agent to poll get_agent_task every 30–60 seconds and not to start another task for this brand meanwhile.

One task at a time per brand. A second create while one is running comes back as an isError result carrying "A task is already running for this brand. Wait for it to finish, then retry." The agent holds a single workspace per brand, so tasks run one after another, which is also why there is no batch argument: N pages is N tasks, submitted in sequence.

There is no callback_url argument. An agent polls. The REST route takes one because a server can name its own webhook.

get_agent_task

Check on a task: still running, succeeded, or failed, and what it produced.

Poll every 30–60 seconds. While the task is running the result carries a _note saying so. On a successful prompt task it explains that resultingRoute is empty by design and the work is in the thread at chatUrl.

resultingRoute is the route a build_page task produced, and it is always empty for a prompt task, even on success. error appears only on failure. A task with no word from the agent for two hours is reported failed.

task_id is the one UUID an agent carries, because the caller does not choose it.

Not here

• Publishing and unpublishing. No tool puts a page on a live domain, and none is planned. The agent works in the brand's workspace, and going live is a step a person takes in the dashboard.
• Batch page creation. One task per call.
• Writing back to the queue. Dismissing, scheduling, or re-opening an opportunity is dashboard-only, so an agent that wants a page to stop being proposed cannot yet say so.
• Configuration and lead data. Brand, domain, and visibility settings are not writable here, and raw form submissions are not readable anywhere on this surface.