> ## Documentation Index
> Fetch the complete documentation index at: https://docs.attensira.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP tool reference
> All 15 Attensira MCP tools — parameters, return shapes, and which ones spend credits or delete things.
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.
| Tool | Effect | Why |
| ------------------- | ------------- | --------------------------------------------------------------------------- |
| `add_prompts` | Costs credits | Each new prompt is read across your tracked models from the next run onward |
| `run_automation` | Costs credits | Triggers an automation immediately instead of waiting for its schedule |
| `ask` | Costs credits | Runs an agent chat on an agent model |
| `remove_prompt` | Destructive | Stops tracking a prompt; its history is no longer collected |
| `delete_automation` | Destructive | Removes the automation and its schedule |
`run_automation` accepts an `idempotency_key`. Pass one on every call. It maps to the `Idempotency-Key` header upstream, so a retried or duplicated call does not produce a second billed run.
The `get_analytics` `area` enum still uses the original wire words `group` and `engine` for what these docs call **topic** and **model**. The enum values are a stable contract, so they have not been renamed. Pass `group` when you mean topic and `engine` when you mean model.
## 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
Read-only. No credits.
Full-text search across your workspace — prompts, answers, pages, sources. Use it to locate something by wording when you do not have an id.
| Parameter | Type | Default | Notes |
| --------- | ------- | ------- | -------------------------- |
| `query` | string | — | Required |
| `limit` | integer | 20 | Maximum 50 |
| `offset` | integer | 0 | For paging through results |
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
Read-only. No credits.
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.
| Parameter | Type | Default | Notes |
| --------- | ------- | ------------- | ------------------------------------------------------------------------------------------------- |
| `area` | enum | — | Required. One of `visibility`, `prompt`, `page`, `source`, `competitor`, `group`, `engine`, `bot` |
| `days` | integer | 30 | 1–365 |
| `order` | enum | `worst_first` | Or `best_first` |
| `limit` | integer | 20 | Maximum 100 |
| `filter` | string | — | Narrows the slice, for example to one model or one topic |
Each area answers a different question:
| `area` | Answers |
| ------------ | ------------------------------------------------------ |
| `visibility` | Workspace-level mention and citation rates with deltas |
| `prompt` | Per-prompt rates — which prompts you win and lose |
| `page` | Which of your pages get cited |
| `source` | Which domains the models cite in your category |
| `competitor` | Rates for the competitors you track |
| `group` | Per-topic rollup (topic = `group` on the wire) |
| `engine` | Per-model rollup (model = `engine` on the wire) |
| `bot` | AI crawler activity on your site |
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.
`ShareOfVoice`, where it appears in a response, is the brand's own mention rate. It is not a share of a category that sums to 100%. Competitor rates use the same denominator as yours, so they do not sum to 1 either.
### get\_prompt
Read-only. No credits.
Everything recorded for one prompt: its topic, its per-model rates, and the answers collected in the window — full answer text, not a snippet.
| Parameter | Type | Default | Notes |
| --------- | ------- | ------- | --------------------------------------------------------- |
| `prompt` | string | — | Accepts either a prompt id **or** the prompt's exact text |
| `days` | integer | 30 | Window for the returned rates and answers |
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
Read-only. No credits.
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.
| Parameter | Type | Default | Notes |
| --------- | ------- | ------- | --------------------------------------- |
| `url` | string | — | Required. A page on your tracked domain |
| `days` | integer | 30 | Window |
`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
Costs credits. Not read-only.
Adds one or more prompts to the workspace. From the next daily run, each new prompt is read across every model your workspace tracks.
| Parameter | Type | Default | Notes |
| --------- | --------- | ------- | ---------------------------------- |
| `prompts` | string\[] | — | Required. One or more prompt texts |
| `group` | string | — | Optional topic to file them under |
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
Destructive. Not read-only.
Stops tracking a prompt and frees its slot.
| Parameter | Type | Default | Notes |
| --------- | ------ | ------- | ------------------- |
| `prompt` | string | — | Required. Prompt id |
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
Not read-only, but does not spend credits.
Registers a brand to detect alongside yours in answers already being collected. It does not create new readings, so it costs nothing.
| Parameter | Type | Default | Notes |
| --------- | ------ | ------- | --------------------------------------------- |
| `name` | string | — | Required. Brand name as it appears in answers |
| `domain` | string | — | Optional, for attributing citations |
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
Read-only. No credits.
Lists every automation in the workspace with its id, name, schedule, and last run. Takes no required parameters.
### get\_automation
Read-only. No credits.
Full definition and run history for one automation.
| Parameter | Type | Default | Notes |
| --------------- | ------ | ------- | -------- |
| `automation_id` | string | — | Required |
### create\_automation
Not read-only. Creating costs nothing; each run it triggers does.
Defines a new scheduled automation.
| Parameter | Type | Default | Notes |
| -------------- | ------ | ------- | ------------------------------------------------ |
| `name` | string | — | Required |
| `instructions` | string | — | Required. What the automation should do each run |
| `schedule` | string | — | How often it runs |
Returns the created automation with its id. Creation is free; every scheduled execution spends credits like a manual run.
### run\_automation
Costs credits. Not read-only.
Executes an automation immediately, outside its schedule.
| Parameter | Type | Default | Notes |
| ----------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------- |
| `automation_id` | string | — | Required |
| `idempotency_key` | string | — | Strongly recommended. Sent as `Idempotency-Key`; a repeat call with the same key does not bill twice |
### delete\_automation
Destructive. Not read-only.
Removes an automation and cancels its schedule.
| Parameter | Type | Default | Notes |
| --------------- | ------ | ------- | -------- |
| `automation_id` | string | — | Required |
## 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
Costs credits. Not read-only.
Sends a question to the agent.
| Parameter | Type | Default | Notes |
| ------------ | ------ | ------- | --------------------------------------------------- |
| `message` | string | — | Required |
| `session_id` | string | — | Continue an existing thread instead of starting one |
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.
The agent runs on an **agent model** — the LLM powering the chat. That is a different thing from a tracked **model**, which is the answer surface Attensira reads on your behalf. Changing your agent model does not change what is measured.
### get\_session
Read-only. No credits.
Retrieves a chat session: its messages, its status, and optionally the agent's step-by-step trace.
| Parameter | Type | Default | Notes |
| ------------ | --------- | ------- | ------------------------------------------------------------------ |
| `session_id` | string | — | Required |
| `include` | string\[] | — | Pass `["events"]` for the step-by-step trace of what the agent did |
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
Read-only. No credits.
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.
Credits and the response budget are currently inconsistent in the product. Treat the credit balance from `get_account` as directional, and do not build hard billing logic on it yet.
## 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](/measure/reading-the-numbers).