> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costory.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Scouts

> A Scout is an agent you assign to reports and alerts. Each time one is delivered, it investigates what moved and adds the cause, the owner and the next step, in Slack, Teams or email. It remembers what it found.

> [!NOTE]
>
> Scouts are in Beta and free during the Beta.

A Scout is an agent you assign to your reports and alerts. Each time one of them is delivered, the Scout reads it, works out what moved and why, and adds its answer to the delivery. It keeps a memory between runs, so each investigation starts from what the last one learned instead of starting cold.

The Scout reads the same cost model you query through the [Costory MCP](https://docs.costory.io/features/mcp.md): allocated cost, usage metrics, events and deploys. There's nothing to wire up per Scout.

## How a Scout works

| | What it is |
| - | - |
| **What it reads** | The reports and alerts you assign to it, including every graph, breakdown and text block in them. |
| **What it uses to investigate** | Your allocated cost, usage metrics, events and deploys, plus its own memory of past runs. |
| **What it produces** | Follow-up answers added to the delivery (in Slack, Teams or email), entries in its memory, and events on the cost timeline. |

## Create a Scout

* **In the app:** open **Scouts** in the left sidebar and click **New scout**. Costory asks a few questions, then writes the Scout's instructions and assigns its reports or alerts.

![Costory chat prefilled with a request to create a new Scout](https://mintcdn.com/costory/y-rYlb9_PtjXh7ZB/images/scouts/scouts-new-scout-chat.png?fit=max\&auto=format\&n=y-rYlb9_PtjXh7ZB\&q=85\&s=3432c543efd78a6774ec20758c57d930)

New scout opens a chat with Costory, prefilled to define the Scout

![Costory Scouts page showing the FinOps Advisor Scout with its instructions](https://mintcdn.com/costory/y-rYlb9_PtjXh7ZB/images/scouts/scouts-page-finops-advisor.png?fit=max\&auto=format\&n=y-rYlb9_PtjXh7ZB\&q=85\&s=7be5ad6e03f0832fe1bff214d9aabbbb)

The Scouts page, with a Scout's assigned reports, alerts and instructions

### Assign a Scout to a report or an alert

* **From a report or an alert:** in the report or alert editor, the right panel has a **Scout** field ("Scout reads your reports and enriches its delivery with follow-up answers"). Pick a Scout from the list. It then runs every time that report or alert is delivered.

![Report editor with the Scout field open and a Scout selected from the list](https://mintcdn.com/costory/y-rYlb9_PtjXh7ZB/images/scouts/scouts-assign-to-report.png?fit=max\&auto=format\&n=y-rYlb9_PtjXh7ZB\&q=85\&s=9739dac1573b80643acbc18ce3e43f9d)

The Scout field in the report editor

* **From Claude, Cursor or any MCP client:** ask your assistant to create a Scout. The [Costory MCP](https://docs.costory.io/features/mcp.md) exposes `create_scout`, `update_scout` and `list_scouts`.

Example prompt:

```text theme={null}
Create a Scout called "LLM cost watcher". Assign it to the "Support agent LLM cost" alert and the weekly LLM cost report. Write for the Support AI team: say what changed, the likely cause and the owner, and only recommend an action when the increase is above €500 a week.
```

## Scout settings

Open a Scout from the **Scouts** page. Click **Edit** to change it.

| Setting | What it does |
| - | - |
| **Name and description** | How the Scout appears in the list and in the report or alert editor. |
| **Instructions** | Plain text, like a prompt: who the Scout writes for, the structure of each finding, and the rules it follows. See [Write good instructions](#write-good-instructions) below. |
| **Assigned reports** | Reports the Scout reads each time they're delivered. |
| **Assigned alerts** | Alerts the Scout reads each time they fire. |
| **Open memory** | Opens the Scout's memory, which is a Costory dashboard. You can read it and edit it like any other dashboard. |
| **Backfill** | Runs the Scout again on the last 2 reports that were sent, so you can see its output right after you create or edit it. |

## Write good instructions

The instructions decide whether a Scout is useful or noisy. The ones that work best:

1. **Name the reader.** For example: "engineering managers and the CTO" or "the Support AI team".
2. **Give each finding a fixed structure.** For example: What, Why it matters, Action, Owner, Estimated impact, Effort.
3. **Rank and cap.** For example: rank by estimated monthly impact and keep at most 5 findings, then list what to watch.
4. **Say how to treat data artefacts.** Spend moving between accounts with no net change, or a one-off commitment purchase, is a "check data" note, not a saving.
5. **Forbid invented numbers.** Every amount has to come from the data.
6. **End with a question to ask next**, in the Costory chat or in Claude with the Costory MCP.

Write your own, or start from a template. Templates are available in the app when you create a Scout. They're starting points: nothing is created until you pick one.

## Ask a Scout and steer it

* **In the thread:** reply in Slack and mention `@costory` to ask a follow-up, add context it couldn't know ("we shipped a new checkout on Tuesday") or correct it.
* **In the chat or through the MCP:** ask it to change its tone or what it shows you.
* Reinstall the [Slack app](https://docs.costory.io/setup/collaboration/slack.md) if `@costory` doesn't respond.

## Memory

A Scout remembers in two ways:

* **Events.** When it finishes an investigation, it can record what it found as an event. Events show on the cost timeline next to deploys, in the **Events** page, and through `list_events` in the Costory MCP. Anyone looking at a chart later sees what the Scout found and when. See [Events](https://docs.costory.io/features/events.md).
* **Its instructions.** A correction like "don't comment on staging, focus on production" can update the Scout's instructions, so it applies to every later run.

The Scout's memory is a dashboard (**Open memory**). You can edit it by hand, but it's better to steer the Scout through the thread or its instructions and let it keep the dashboard itself.

## What a Scout can and can't change

* It reads your cost data. It never gets write access to your cloud accounts or your code.
* Inside Costory, it can create or update alerts, reports and dashboards, and it always asks you before it does.
* It recommends. Your team, or your coding agent, applies the change.

## Next step

> [card] [Alerts](https://docs.costory.io/features/alerts.md)
>
> What a Scout reads: alerts that fire on a condition

> [card] [Cost Reports](https://docs.costory.io/features/digest.md)
>
> What a Scout reads: scheduled reports and digests

> [card] [Costory MCP](https://docs.costory.io/features/mcp.md)
>
> Create and edit Scouts from Claude or Cursor


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.