> ## 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 recipes

> Six task-shaped recipes for the Attensira MCP server — the call to make, the chain behind it, how to read the result, and what it cannot tell you.

Each recipe below is a real question someone asks on a Monday morning. Every one gives you the single call that mostly answers it, the longer chain when the single call is not enough, a table mapping what you see to what it means, and — the part that matters — what the numbers genuinely cannot tell you.

All calls assume you are connected to `https://mcp.attensira.com/mcp` with a workspace API key. See [the tool reference](/mcp/tools) for parameters.

## Find out where you lost ground this week

Start with workspace-level rates over a short window, then drill into the prompts that moved.

```json theme={null}
{ "tool": "get_analytics", "arguments": { "area": "visibility", "days": 7 } }
```

**The chain**

<Steps>
  <Step title="get_analytics area=visibility days=7">
    Establishes whether anything moved at all at the workspace level. If every delta comes back `real: false`, stop — there is nothing to explain.
  </Step>

  <Step title="get_analytics area=prompt days=7 order=worst_first limit=20">
    Ranks prompts by how badly you are doing on them, so the losses surface first rather than being averaged away.
  </Step>

  <Step title="get_analytics area=engine days=7">
    Splits the same window by model. A drop concentrated on one model is a different problem from a drop across all of them.
  </Step>

  <Step title="get_prompt on the two or three worst movers">
    Returns the actual answer text, which is the only place you find out *why* the model stopped naming you.
  </Step>
</Steps>

**How to read it**

| What you see                                       | What it means                                                         |
| -------------------------------------------------- | --------------------------------------------------------------------- |
| Delta `{real: false, value: null}`                 | No change you can prove. Not a decline. Do not report it as one.      |
| Your mention rate flat, a competitor's rising      | You did not lose ground — someone else gained. Different response.    |
| Drop on one model, others flat                     | Likely an answer-surface change on that model, not a content problem. |
| `value: null` on a model row with `tracked: false` | That model was never queried. It is not a 0%.                         |
| Rate down but `n` is 7 or fewer                    | One or two bad readings can move this. Widen `days` before acting.    |

**What this cannot tell you.** A seven-day window on Starter sampling gives you very few readings per prompt, and a rate built on single-digit `n` swings hard for reasons that have nothing to do with you. Nothing here tells you *why* a model changed its answer: model providers swap the underlying models behind a surface without notice, and a rewritten system prompt on their side looks identical to a content problem on yours. You are seeing what changed, not who changed it.

## See which sources the models trust in your category

Source share tells you which domains the models actually pull from when answering your prompts.

```json theme={null}
{ "tool": "get_analytics", "arguments": { "area": "source", "days": 90, "order": "best_first", "limit": 50 } }
```

**The chain**

<Steps>
  <Step title="get_analytics area=source days=90 best_first">
    A long window, because source share is a distribution and short windows make it lumpy. `best_first` puts the most-cited domains at the top.
  </Step>

  <Step title="get_analytics area=source days=90 filter=<one model>">
    Repeat per model. Perplexity and ChatGPT lean on visibly different domain mixes, and a category-wide average hides that.
  </Step>

  <Step title="get_analytics area=page days=90">
    Shows where your own domain lands in the same window, so you can see whether you are in the mix at all.
  </Step>
</Steps>

**How to read it**

| What you see                                      | What it means                                                                       |
| ------------------------------------------------- | ----------------------------------------------------------------------------------- |
| One domain above roughly a fifth of all citations | Models treat it as the reference for your category. Being absent from it costs you. |
| A long flat tail of many small domains            | No consensus source. Coverage breadth matters more than any single placement.       |
| High source share, low `AvgPosition` index        | Cited often and cited early in the list. The strongest signal available here.       |
| Your domain absent entirely                       | You were not cited in this window. Not proof you are uncitable.                     |

**What this cannot tell you.** Source share is citations to a domain over all citations in the window — it is not traffic, authority, or influence on the answer text. A model can name your brand in prose while citing a competitor's blog, and a model can cite a page it disagreed with. The list also reflects your prompts, not the category: if your tracked prompts skew to one topic, the source mix skews with them. Widen the prompt set before calling it a picture of the category.

## Check whether a competitor is gaining

```json theme={null}
{ "tool": "get_analytics", "arguments": { "area": "competitor", "days": 30 } }
```

**The chain**

<Steps>
  <Step title="get_analytics area=competitor days=30">
    Gives each tracked competitor's mention rate on the same denominator as yours.
  </Step>

  <Step title="get_analytics area=visibility days=30">
    Your own rate over the same window, so you can compare movement rather than levels.
  </Step>

  <Step title="get_analytics area=prompt days=30 order=worst_first">
    Finds the specific prompts where the gap lives. Competitors rarely gain evenly.
  </Step>

  <Step title="get_prompt on those prompts">
    Read the answers. What the model says about them is the actual competitive intelligence.
  </Step>
</Steps>

**How to read it**

| What you see                                        | What it means                                                              |
| --------------------------------------------------- | -------------------------------------------------------------------------- |
| Their rate up, yours flat, both deltas `real: true` | They gained. You did not lose. The market grew around you.                 |
| Both rates up                                       | The models are naming more brands per answer, not reshuffling ranks.       |
| Their rate up, yours down                           | The closest thing to genuine displacement — and worth reading answers for. |
| Rates summing well past 100% across brands          | Expected. Answers name several brands, so these never sum to 1.            |

**What this cannot tell you.** These are not shares of a fixed pie. Competitor mention rate uses the same denominator as yours, so it measures how often a brand appears in *your* prompts' answers — nothing about their overall market presence, spend, or growth. A competitor you have not registered with `add_competitor` is invisible here and will read as absent, which is not the same as not appearing. There is no sentiment measurement, so a mention that trashes them counts exactly like a recommendation.

## Turn a losing prompt into a plan

The one prompt you keep losing is the most actionable object in the product.

```json theme={null}
{ "tool": "get_prompt", "arguments": { "prompt": "best project management tool for agencies", "days": 90 } }
```

**The chain**

<Steps>
  <Step title="get_prompt with the exact text or id, days=90">
    Returns full answer text — not the 400-character snippets `search` returns — plus per-model rates.
  </Step>

  <Step title="get_analytics area=source filter=<this prompt or its topic>">
    Shows which domains the models leaned on when answering it. That is your target list.
  </Step>

  <Step title="get_page on any of your URLs that did get cited">
    Tells you what already works, which is a better template than guessing.
  </Step>

  <Step title="ask, passing what you found">
    Costs credits, and earns them here: the agent reasons across the slices you just pulled and drafts a plan. Poll `get_session` if it returns `status: "running"`.
  </Step>
</Steps>

**How to read it**

| What you see                                                  | What it means                                                                    |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Competitors named, you absent, citations to third-party lists | A placement problem. You need to be on those lists.                              |
| You named but never cited                                     | The model knows you and does not reach for your pages. A content problem.        |
| Cited but with a high `AvgPosition` index                     | You appear late in citation lists. Depth of coverage, not existence, is the gap. |
| Mention rate 0 with `n` above 20                              | A real, measured absence worth working on.                                       |

**What this cannot tell you.** Nothing here predicts that a change will work. There is no attribution path from a page edit to a later mention — you can only change something and re-measure after enough calendar days have passed to build a new `n`. Sampling is at most once per prompt per model per day, so a plan executed today shows its earliest possible signal tomorrow and a trustworthy one much later. Answers also vary run to run at the model's discretion; a single collected answer is an anecdote.

## Set up a weekly report

```json theme={null}
{ "tool": "create_automation", "arguments": {
  "name": "Monday visibility digest",
  "instructions": "Summarise the last 7 days: workspace mention and citation rates with deltas, the five worst prompts, per-model split, and any competitor whose rate moved with real:true. Ignore deltas where real is false.",
  "schedule": "weekly on Monday"
} }
```

**The chain**

<Steps>
  <Step title="list_automations">
    Check what already exists. Two automations doing the same job bill twice.
  </Step>

  <Step title="create_automation">
    Free to create. Write the instructions to name the exact areas and windows you want, and to say explicitly that unproven deltas should be ignored.
  </Step>

  <Step title="run_automation with an idempotency_key">
    Test it once now rather than waiting a week. The key prevents a retry from producing a second billed run.
  </Step>

  <Step title="get_automation">
    Read the run history to confirm it produced what you expected before trusting it unattended.
  </Step>
</Steps>

**How to read it**

| What you see                           | What it means                                                                      |
| -------------------------------------- | ---------------------------------------------------------------------------------- |
| Digest reports every delta as a change | Your instructions did not exclude `real: false`. Rewrite them.                     |
| A week with no findings                | Normal. Most weeks contain no statistically real movement.                         |
| Numbers differing from the dashboard   | Check the window: 7 days against a 30-day default is a different slice, not a bug. |
| A run missing from the history         | The scheduled run did not execute. Re-run manually with a fresh key.               |

**What this cannot tell you.** A weekly cadence over a daily sampling floor means each report rests on at most seven readings per prompt per model — three times that on Growth and Business, since sampling depth is three there. That is thin for week-over-week comparison, and a digest that dutifully reports movement every week is reporting noise. Credits and the response budget are currently inconsistent in the product, so do not assume a schedule that fits this month's balance fits next month's.

## Audit which pages actually get cited

```json theme={null}
{ "tool": "get_analytics", "arguments": { "area": "page", "days": 90, "order": "best_first", "limit": 100 } }
```

**The chain**

<Steps>
  <Step title="get_analytics area=page days=90 best_first limit=100">
    Ranks your own URLs by citation activity. Long window, because page-level citations are sparse.
  </Step>

  <Step title="get_page on the top few">
    Shows which prompts and which models each page earns citations from.
  </Step>

  <Step title="get_analytics area=bot days=90">
    Shows AI crawler activity against your site — which pages were fetched at all.
  </Step>
</Steps>

**How to read it**

| What you see                         | What it means                                                          |
| ------------------------------------ | ---------------------------------------------------------------------- |
| Page cited often across many prompts | A hub. Keep it current; it carries disproportionate weight.            |
| Page crawled but never cited         | Reachable and not chosen. A content problem, not an access one.        |
| Page never crawled and never cited   | Start with access — nothing can cite a page it has not fetched.        |
| Citations concentrated on one model  | That surface favours your format. Others may need different structure. |

**What this cannot tell you.** Crawlers are not models: a crawler fetches pages, a model answers prompts, and a fetch is not a citation or a plan to make one. Crawler data also has a hard technical limit — AI crawlers do not execute JavaScript, so a client-side beacon, however written, has never seen one and never will; by the time the script runs, the only visitors left are humans with browsers. Use the install instructions the product generates at Settings for server-side collection. Finally, `AvgPosition` is a mean index within a citation list per source domain — it is not a rank against competitors and cannot be read as one.

## Where to go next

Before acting on any of these numbers, read [Reading the numbers](/measure/reading-the-numbers) for how `null`, zero, small `n`, and unproven deltas differ. Full parameter detail for every tool is in [the tool reference](/mcp/tools).