Tools

Most tools are read-only. A set of write tools can also modify your project's configuration — these require an API key with the mcp:write scope (see Write tools below). Your assistant picks the right tool from your question — this reference tells you what's available and how each tool behaves.

Project selection

Every tool except list-projects takes an optional projectId:

list-projects

Lists the projects your connection can access, with their IDs, names, and types. The assistant calls this first when it doesn't know which project ID to use. No parameters.

Each project has a type:

• project — a brand Temso tracks daily.
• pitch — a one-time AI visibility snapshot of a prospective client. Pitches also return snapshotRunStartedAt (when the latest snapshot run started) and rerunsLeft.

Pitch projects

A pitch project is a one-time snapshot, not an ongoing tracker. The MCP server adapts its tools to that:

• The project's own brand is the prospect, not your brand.
• Analytics tools return only the latest snapshot run and ignore days, startDate, and endDate. There are no trends or previous periods.
• Analytics results for a pitch include a short note that tells the assistant these rules.
• Backlink, technical audit, content gap, content piece, action planner, tracked URL, and AI crawler traffic tools return an error for pitches, because a pitch does not offer these features. Convert the pitch into a full project on its Pitch page to unlock them.
• Prompt changes made with create-prompts, update-prompts, or archive-prompts run only when you start a rerun on the Prompts page in Temso.

fetch-pitch-snapshot

Fetches how far the latest snapshot run of a pitch has come: its status (collecting, ready, partial, or failed), the answers per AI platform against the target, the number of active prompts, and the reruns left. Takes only projectId.

fetch-pitch-guide

Fetches the AI-written selling points of a pitch, strongest first. Each point has a hook (one sentence to the prospect) and its proof (the data behind it). The Pitch page in Temso shows the same points. Returns no points while the snapshot is still collecting. Takes only projectId.

Analytics tools

All analytics tools share these parameters on top of projectId:

Tools marked paged additionally accept:

fetch-brand-rankings

Fetches AI visibility brand rankings within a time range — visibility, source presence, mentions, responses, and share of voice per brand, for your own brand and competitors. Paged, default limit 20.

fetch-share-of-voice

Fetches the share of voice breakdown showing your brand versus competitors within a time range.

fetch-performance-breakdown

Fetches your brand's AI visibility performance grouped by a dimension.

fetch-prompt-analytics

Fetches per-prompt performance analytics for your own brand within a time range. Paused prompts are excluded.

fetch-brand-perception

Fetches brand perception analytics — how brands are described in AI answers (e.g. reliable, innovative, affordable).

fetch-sentiment

Fetches own-brand sentiment analytics from Perception > Sentiment, including positive, neutral, and negative shares plus a breakdown by model or another dimension.

fetch-sentiment-sources

Fetches source pages for a selected sentiment bucket from Perception > Sentiment > Sources. Paged, default limit 20.

fetch-perception-sources

Fetches source pages for a selected brand-perception attribute from Perception > Attributes > Sources. Use fetch-brand-perception first to discover available attribute names. Paged, default limit 20.

fetch-top-domains

Fetches the top cited source domains with presence, brand mentions, category, and model coverage within a time range. Paged, default limit 20, sorted by response count descending.

fetch-source-urls

Fetches individual source URLs with citation analytics within a time range. Paged, default limit 50.

fetch-cited-pages

Alias of fetch-source-urls for cited-page/source-URL analytics — same parameters. Paged, default limit 50.

Backlink tools

Read the project's backlink profile: links, referring domains, and the competitor link gap. Backlink data comes from scheduled or manual scans — if a project has never completed one, fetch-backlink-overview returns neverSynced: true and the list tools return nothing.

fetch-backlink-overview

Fetches the backlink profile summary: sync status (last sync, cooldown, warnings) plus KPIs — domain rank, backlinks, referring domains, AI-cited domains, and new/lost counts. Takes only projectId.

fetch-backlink-timeseries

Fetches the backlink profile history: one snapshot per sync with rank, backlinks, referring domains, AI-cited domains, and new/lost counts.

fetch-backlinks

Lists individual backlinks (referring page → target URL) with anchor, referring-domain rank, dofollow flag, and the AI signal on the referring domain. Paged, default page size 20.

Each row carries citedInAiAnswers (the referring domain was named outright as a source) and appearedAsAiSource (it fed an AI answer at all). The second includes the first — it is the wider signal, not the uncited remainder. The response's totalMatchingFilters counts the rows matching the filters you passed, not the size of the whole profile.

fetch-backlink-domains

Lists referring domains with their rank, backlink and dofollow counts, and their AI signal. Takes the same filters as fetch-backlinks, except sortBy is rank | backlinksCount | firstSeenAt (default rank). Paged, default page size 20.

Each row carries citedInAiAnswersCount (AI answers that named the domain outright) and appearedAsAiSourceCount (AI answers it fed at all). The second already includes the first. As above, totalMatchingFilters is scoped to the filters you passed — do not report it as the project's referring-domain total.

fetch-backlink-gap

Lists domains that link to the tracked competitors but not to this project — link-building prospects, sorted by how many competitors they link to. Paged, default page size 20.

Search tools

Read organic search performance from the project's connected Google Search Console or Bing Webmaster Tools account (Project Settings › Integrations). Every result carries:

The tools return an error when no account is connected, when the account is broken and needs a reconnect, or when it has no verified property selected.

All search tools share these parameters on top of projectId:

fetch-search-performance

Total clicks, impressions, CTR, and average position for the range, the daily series, and site-wide keyword counts per ranking-position bucket (keywordsByPosition).

fetch-search-keywords

Top keywords ordered by impressions, with clicks, CTR, and average position. Default limit 50, max 500. Raise the limit before ranking keywords by clicks.

fetch-search-pages

Top pages ordered by impressions, with clicks, CTR, average position, and the page title when known. Default limit 50, max 500. Raise the limit before ranking pages by clicks.

fetch-search-movements

Winners and losers versus the previous window of equal length: the top 10 keywords or pages that gained clicks, declined, are new (impressions for the first time), or were lost (no impressions any more), plus counts per bucket and the previousRange.

fetch-search-quick-wins

Keywords already ranking in a position band, ordered by impressions — a small ranking gain would turn impressions into clicks. Default limit 50, max 200.

fetch-search-cannibalization

Keywords for which two or more of the site's pages rank, with the number of competingPages and the keyword's clicks and impressions. Web search only; searchType, country, and device are rejected. Default limit 50, max 500.

fetch-search-breakdown

Clicks, impressions, CTR, and position by country (lowercase ISO 3166-1 alpha-3 codes) or by device. Google web search only; searchType, country, and device are rejected.

fetch-search-ai-vs-organic

Compares AI citations with organic search for the site's own pages over the range. aiCitedButOrganicallyInvisible lists pages AI answers cite that get little or no organic traffic, least organic first (hasOrganicData: false means the search account has no row for the page). organicallyStrongButAiInvisible lists the top organic pages by clicks that no AI answer cites. Default limit 50 per list, max 200.

Configuration tools

These take only projectId and return the project's setup:

fetch-brand-details

Fetches the details of the brand the project tracks. In a pitch project, this is the prospect.

fetch-competitors

Fetches the competitors tracked in the project.

fetch-prompts

Fetches the prompts configured for monitoring.

fetch-personas

Fetches the configured personas.

fetch-offerings

Fetches the configured offerings/products.

fetch-monitor-settings

Fetches the monitoring settings: run frequency and which AI models are tracked.

Action planner tools

fetch-campaigns

Fetches campaigns for a project.

fetch-actions

Fetches actions with optional filters.

Tracked URL tools

fetch-tracked-urls

Lists the URLs the project tracks (Actions > Impact in Temso) with their AI visibility in the date range. The result returns the range as startDate and endDate; the counts cover only that range, not all time. Each URL returns:

• appearances — AI answers that mention your brand and list the URL as a source.
• citations — the subset of those answers that cite the URL.
• promptCoverage — the share of active prompts with at least one such answer.
• trackedAsOf — the date counting starts. A URL tracked after the date range shows zeros.
• isPattern — true for a URL that ends in /*, which also matches every page under that path.

Content pieces

Read content pieces and their per-step outputs. These tools are designed for progressive disclosure — list pieces first, inspect one piece's steps, then read a single step's output — so your assistant pulls only what it needs instead of loading whole documents.

fetch-content-pieces

Lists content pieces as compact one-line summaries (id, status, title, format, current step). No step bodies are returned.

fetch-content-piece

Returns one piece's header and a per-step table (label, kind, human-input policy, current revision, quality/brandkit/factcheck outcomes, size). Metadata only — no step bodies.

read-content-piece-step

Reads a single step's output, rendered to markdown (doc/markdown steps) or pretty JSON (json steps) and length-capped. Image steps have no readable artifact.

fetch-publishable-article

Returns a ready article in full, with everything needed to publish it in a CMS such as Shopify, WordPress, or Webflow: title, URL slug, the complete body as HTML (not length-capped), SEO title and meta description, social metadata, featured image URL and alt text, author, target keywords (usable as tags), and the planned publish date. A warnings list flags missing or outdated page metadata, links to pages that are not published yet, and a missing featured image. Only article pieces with status ready or published qualify. Once the article is live, your assistant can record its URL with mark-content-piece-published (a write tool).

Write tools

These tools modify your project's configuration and mirror the write capabilities of the in-app Project Manager Agent. They apply changes immediately — your AI assistant is the approval surface, so review proposed changes before confirming.

Each write tool takes the optional projectId parameter described above. Competitors, offerings, personas, prompt tags, and prompts each have a create-*, an update-*, and a delete-* tool (archive-prompts for prompts). Each tool works on a list, so one call can change several items:

Each call returns a summary with per-item results (succeeded, failed, total, and a results array), so a failure on one item does not stop the rest.

update-brand-details

Updates your own brand's details. All fields optional: name, description, website, aliases (string[]), domainAliases (string[]).

create-competitors, update-competitors, delete-competitors

Manage tracked competitors. Create fields: name, website (URL), optional description. Update fields: _id plus any of name, website, description.

create-offerings, update-offerings, delete-offerings

Manage offerings (products/services). Create fields: name, optional description. Update fields: _id plus any of name, description.

create-personas, update-personas, delete-personas

Manage personas. Create fields: name, description. Update fields: _id plus any of name, description.

create-prompt-tags, update-prompt-tags, delete-prompt-tags

Manage prompt tags. Create fields: name, color. Update fields: _id plus any of name, color.

create-prompts, update-prompts, archive-prompts

Manage prompts. Create fields: text, language, country, and optional tagIds, personaId, offeringId. Update fields: _id plus any of language, type, isPaused, tagIds (replaces the existing tags), personaId, offeringId (pass null to clear a link). Prompts are archived, not deleted.

add-manual-backlink

Registers a backlink you know about but the provider's index is missing. The target URL must be a page on this project's own site and the referring page must be on another site. Free — it makes no third-party call and does not count against your scan allowance.

mark-content-piece-published

Marks a content piece as published after your assistant published it on your site itself (for example in Shopify, using the output of fetch-publishable-article), and records its live URL. Temso then tracks the page and stops asking you to publish it by hand. Call it only once the article is live — not for drafts or posts scheduled for later. Only article pieces with status ready or published qualify.

create-tracked-url

Starts tracking a URL's visibility in AI answers, for example a page you published or updated. End the URL with /* to track every page under that path. Returns an error if the URL is already tracked.

delete-tracked-url

Stops tracking a URL. Its AI visibility no longer shows on Actions > Impact. You can track it again later.

trigger-backlink-sync

Starts a manual backlink scan.

Call it without confirm first: that returns the current sync status (target domain, last scan time, cooldown, any warnings) without starting anything. Show that to the user, and call again with confirm: true only after they explicitly approve.