MCP tool reference

The Attensira MCP server exposes 15 tools at https://mcp.attensira.com/mcp over Streamable HTTP. No tool takes a workspace id — your API key names the workspace. Eight tools are read-only, three spend credits, and two delete data permanently. This page lists every tool with its parameters, defaults, and return shape.

​

Before you start: what costs money and what destroys data

Three tools spend credits and two are destructive. Nothing else on this page changes state or produces a bill.

​

Find and measure

Ask these tools the questions you would ask an analyst: “which prompts am I losing on Perplexity?”, “what changed since last week?”, “which sources do the models trust in my category?”, “does anyone cite our pricing page?”. Four read-only tools cover search, aggregate metrics, single-prompt detail, and single-page detail.

​

search

Full-text search across your workspace — prompts, answers, pages, sources. Use it to locate something by wording when you do not have an id. Returns a list of matches, each with its type, id, and a snippet. Every snippet is capped at 400 characters, so a complete model answer can never come back through search. Once you have the id, call get_prompt or get_page for the full record.

​

get_analytics

The main measurement tool. One call returns an aggregated slice of your tracking data for a time window, ordered so the interesting rows come first. Each area answers a different question: Rates come back as {value, n} and deltas as {value, real}. A value of null means not measured; 0 with n > 0 is a measured zero. Per-model rows also carry {tracked, readable} — tracked: false means the model was never queried for this workspace, so treating it as 0% invents a failure that did not happen.

​

get_prompt

Everything recorded for one prompt: its topic, its per-model rates, and the answers collected in the window — full answer text, not a snippet. Passing exact text saves a search round-trip when you already know the wording. Inexact text will not match — fall back to search if it misses.

​

get_page

Everything recorded for one URL on your site: how often it was cited, in which answers, on which models, and its average position within the citation lists it appeared in. AvgPosition is the mean index of a URL inside the model’s citation list, computed per source domain. It is not a brand rank and says nothing about where you place against competitors.

​

Track

These tools change what gets measured. Reach for them when the answer is “we are not tracking the right things”: “start watching these five buying-intent prompts”, “stop wasting a slot on that one”, “add the competitor who keeps showing up in answers”.

​

add_prompts

Adds one or more prompts to the workspace. From the next daily run, each new prompt is read across every model your workspace tracks. Returns the created prompts with their ids, plus any that were rejected as duplicates. Your plan caps how many prompts you can hold at once: 50 on Starter, 150 on Growth, 350 on Business. A prompt added today produces its first data on the next workspace-local calendar day.

​

remove_prompt

Stops tracking a prompt and frees its slot. Returns a confirmation. No new readings are collected for that prompt afterwards, so any trend line for it ends on the day you remove it.

​

add_competitor

Registers a brand to detect alongside yours in answers already being collected. It does not create new readings, so it costs nothing. Competitor mention rates use the same denominator as your own — successful runs naming the brand over all successful runs — so adding a competitor never changes your numbers.

​

Automations

Automations are scheduled work: a weekly digest, a recurring audit, a check that runs after every deploy. Natural questions here sound like “email me a summary every Monday”, “what is already scheduled?”, “run last week’s report again now”.

​

list_automations

Lists every automation in the workspace with its id, name, schedule, and last run. Takes no required parameters.

​

get_automation

Full definition and run history for one automation.

​

create_automation

Defines a new scheduled automation. Returns the created automation with its id. Creation is free; every scheduled execution spends credits like a manual run.

​

run_automation

Executes an automation immediately, outside its schedule.

​

delete_automation

Removes an automation and cancels its schedule.

​

Agent

The agent tools run a chat inside your workspace, with your tracking data in reach. Use them for questions that need reasoning across several slices — “why did our mention rate drop on Perplexity last week?”, “draft a plan for the three prompts we lose most” — rather than for numbers you can pull directly with get_analytics.

​

ask

Sends a question to the agent. Returns the answer and a session_id. Long questions may return status: "running" with no answer yet — that is expected, not an error. Poll get_session with the returned id until the answer is there.

​

get_session

Retrieves a chat session: its messages, its status, and optionally the agent’s step-by-step trace. The events trace is the way to see which tools the agent called and with what arguments — useful when an answer looks wrong and you want to know which slice it read.

​

get_account

Returns the workspace behind your API key: plan, prompt slots used and available, tracked models, retention window, and credit balance. Takes no required parameters. Call it first from a fresh integration to confirm which workspace a key points at.

​

Reading what comes back

Every numeric field can be null, and null never means zero. A null rate means Attensira did not measure that thing in that window — the model was not tracked, or no run succeeded. A null delta with real: false means the change did not clear a two-proportion z-test at 95%, so there is no change you can prove, in either direction. New workspaces track two models by default: chatgpt and perplexity. Four models have API readers — chatgpt, perplexity, claude, gemini — and google_ai is read by consumer scraping only. Each prompt runs at most once per model per country per workspace-local calendar day, sampled once on Starter and three times on Growth and Business. For the full treatment of null against zero, small n, and when a delta is worth acting on, read Reading the numbers.