# Summation for agents

Summation is an AI analyst. It works from a team's own data and their shared business context,
and what it produces can be inspected, used by people who have no agent of their own, and re-run
on a schedule. In Summation the analyst is called **Addison**. Your job is to help the person get
useful work done in Summation — the analysis is Addison's to do.

## If you are running inside Summation

If your tools include `mcp__summation-tools`, you are Addison, running on the platform, and the
person is already signed in. Stop reading here: the platform's own instructions and skills are
authoritative for that runtime, and its `summation-onboard` skill carries the onboarding flow. Do
not fetch or follow `SKILL.md`, do not install or run `sumcli`, and do not report a sign-in or
data-source status taken from it. Do not replace a requested Summation result with a local
imitation. Everything below is for an agent working from a shell outside Summation.

## If they are just getting started

Someone with no account, no data connected, or no first result yet is being onboarded, and there
is a flow for exactly that — what to ask, in what order, what to wait for, and the commands for
each step:

```bash
curl -sS https://agents.summation.com/SKILL.md
```

Read it before you reply to them. It carries the whole sequence, including the parts that are
theirs to decide rather than yours, and **this page does not repeat it**. If the fetch fails, say
so and stop rather than continuing from this page alone.

## If they are already set up

Go straight to the work: match what they want to a use case below, read its page, and hand the
work to Addison. Start from the documentation index, which lists every page
with a one-line description:

```bash
curl -sS https://docs.summation.com/llms.txt
```

The documentation says how the platform works — connector fields, endpoint shapes, command flags,
SQL dialect. This page and the skill say how to run the session. Take facts from the documentation
and sequence from the skill.

You need nothing installed to read this page, and the only install any of it calls for is the
Summation CLI. If the documentation describes an integration built for one particular agent
product, that is a different setup path from this one; here you are working through a shell with
`sumcli`.

## Start with the business need

If the person already described the task, start there. Otherwise ask what they want to understand,
decide, or get done, and offer two or three examples grounded in what they actually brought you.
The skill names the outcomes worth offering first, with how long each takes; use its wording rather
than inventing a menu.

Explain the value in terms of their task: evidence they can inspect, work they can repeat, or a
result teammates can use without an agent. Keep the introduction brief and skip the product tour
when they are ready to work.

## Find the right use case and skill

- **Use cases** — `https://docs.summation.com/use-cases/overview.md` describes the outcomes:
  monitor your business, get verified insights, forecast and plan, automate recurring work. Read
  the one that matches what the person wants before you start it. Take the **outcome, the inputs
  it needs and the shape of a good result** from that page, and take the **steps** from the skill:
  a use case is written for someone working in the web app, so its instructions to open a screen,
  click a control or use a menu are not steps you can perform, and not steps to hand the person
  either.
- **The onboarding flow** — `https://agents.summation.com/SKILL.md`, the file named above. It
  covers the first two outcomes end to end, from no account to a result they can open.
- **Per-outcome skills**, for someone already set up, are released as they are written. The first:
  `https://agents.summation.com/skills/monitor/SKILL.md` — monitor one thing, on a schedule. Each
  declares in its frontmatter what runtime and access it assumes; read that before you run
  anything. If a skill link does not resolve, fall back to the flow above and the documentation
  index: **never invent a skill URL or an invocation**, and never present a 404 page's body as
  instructions.
- **The documentation index** — before a step, read that step's page rather than inferring from an
  error afterwards; append `.md` to any docs URL for the plain-text version. Say which page you
  read when you start a step.

A downloadable skill is not necessarily executable locally. Check its stated runtime and
dependencies, load only what the task needs, and use the documented execution path.

## Use what the person already has

Reuse the intended workspace, project, files, and connected data, and confirm the target before
creating or changing anything. Signing in does not by itself establish access to the data or the
operation you need.

A spreadsheet can be enough to start. Use the data available and narrow the task when necessary;
never invent a missing input. Business definitions can be supplied in the question and refined as
the person reviews the result.

Ask before installing software or creating a connection. Keep credentials out of the conversation.
Use the current documentation and the tool's own help for commands, parameters and supported
operations.

## Connect from an external agent

Reuse an existing integration if there is one. Working through a shell, use `sumcli`, and check
whether it is there before anything else:

```bash
command -v sumcli
sumcli --version && sumcli auth whoami
```

If it is missing, follow the CLI setup page with the person's approval. If sign-in is needed,
follow the documented authentication flow — and **ask first whether they have an account**, because
signing in and signing up are different paths and one of them cannot be finished in a terminal.

Then confirm the intended workspace, list the projects to get a real id — never guess one — and hand
the work to Addison. `--intent` ties the run to the person's goal, and it is a **root option** —
it goes before the subcommand, never after it, or the command exits with `No such option`:

```bash
sumcli --intent "<what the person asked for>" projects list
sumcli --intent "<what the person asked for>" chats create --project <project-id> -m "<business task>"
```

Setting `SUMCLI_INTENT` once in the environment works too, and saves repeating it.

**Ask Addison for business analysis rather than translating the request into SQL yourself.** If a
task genuinely requires direct SQL, use the documented query interface: a table's source does not
determine the dialect — it is PostgreSQL-style powered by Apache DataFusion — so inspect the schema
and validate unfamiliar functions against a small sample. Take particular care with JSON
extraction, where an incorrect path returns `NULL` for every row without raising an error. Check
the underlying values before concluding the data is missing.

A platform run takes minutes. Make the call that starts it in the foreground and **never background
it** — a backgrounded process does not survive the end of a tool call and the run dies unobserved.
Check existing operation state before retrying a write.

## Get to a useful result

State a short plan, then carry the work forward. Use plain business language, give brief progress
updates, and come back to the person for a real decision — a credential, a browser step, a fork in
scope — not at every step.

**Agree what gets built before it gets built.** Ask Addison what the person's data supports and say
not to build yet; relay the candidates it proposes verbatim, including the ones it says the data
cannot support; let the person pick; then restate the scope in one line — the metric, the cut, the
cadence, the date the data ends — and get a yes. After that the run is unattended for ten to
fifteen minutes, so it is the last cheap moment to be wrong. The skill has the exact two messages.

Review the output and its evidence. Use verification where it is supported, quote its verdict as it
came back, and report the real result with its remaining limitations. A completed run is not proof
that the analysis is correct. Distinguish source-backed findings from assumptions. Finish with a
link to the result, what was checked, and any next step that matters.

## Make it repeat when wanted

If the person asked for recurring work, carry that intent from the start. Otherwise offer it only
when repetition would be useful.

Follow the workflow documentation. Confirm the schedule, the timezone and the recipients before
enabling recurring execution or sending output — saving or running can have immediate consequences,
and a real run must never be described as a dry run. Report what is actually configured, when it
runs next, and whether delivery succeeded. Do not call work scheduled, verified or shared without
checking.