# Your first scan

Connect an agent, then ask it for a scan. Research Scan is driven by a model, not by a single command.

Research Scan is driven by an agent. The CLI does retrieval, expansion,
shortlisting, verification and rendering; the model plans the queries, screens
each candidate and reranks the shortlist. So the first step is not running a
command — it is connecting an agent that can.

## 1. Connect an agent

### Claude Code — the plugin

The plugin installs the skill and configures the `uvx` MCP server in one step.

```
/plugin marketplace add Synectic-Research/research-scan
/plugin install research-scan@synectic
```

### Claude Desktop, Cursor, or any MCP client

`research-scan mcp` speaks MCP on stdin and stdout and nothing else. It reads no
token and needs none: the process is trusted because your client launched it.
Nothing extra to install — the server ships with the package.

```json
{
  "mcpServers": {
    "research-scan": {
      "command": "uvx",
      "args": ["research-scan", "mcp"]
    }
  }
}
```

| Client | Where that goes |
|---|---|
| Claude Code | `.mcp.json` in the project root |
| Claude Desktop | `claude_desktop_config.json` |
| Cursor | `.cursor/mcp.json` |

More detail, including the skill-only routes, is in
[Integrations](/integrations/claude-code/).

## 2. Ask for a scan

With the skill installed, ask for a scan in your agent:

```
/research-scan "what is the strongest recent evidence that default enrolment changes
                how much people save?" --profile quick
```

A one-line question works. A brief works better, because the planning step maps
each section of it onto a specific part of the search plan.

```
/research-scan research/my-brief.md --profile standard --top 10
```

The full argument list:

```
/research-scan <brief.md | "question"> [--profile quick|standard|deep] [--top N]
                                       [--foundational N] [--from YYYY-MM] [--to YYYY-MM]
                                       [--slug name] [--domain behavioral|cs|biomed|general]
                                       [--max-candidates N] [--per-query N]
```

Start with `--profile quick` for a first run. It caps the pool at 250 candidates
and skips the gap round, which keeps the first scan to roughly twenty minutes
rather than forty.

## 3. Write a brief, if you want a better result

Each section of the brief feeds a specific part of the plan.

| Brief section | What it feeds |
|---|---|
| **`Purpose:` line** | Which sub-criteria the plan derives and what `why_it_matters` must argue. `build`, `research` or `orient`; omit it and the agent infers one. |
| **What this is about** | The `brief_summary` and the domain routing. Say the setting, not just the topic. |
| **What we need to decide or answer** | The sub-criteria every paper is scored against. Name the actual open choices, or the actual questions. |
| **What we already believe (the premise)** | The `contradictory` query. A scan that only confirms the premise is not evidence. |
| **Exclusions** | `must_not`, enforced in code at word boundaries — never as NOT-terms in query text. |
| **Known papers or authors** | `anchors`: pinned into the pool, exempt from the filters and the cap, always used as expansion seeds. |

Worked templates ship with the skill:
`skills/research-scan/examples/brief.example.md` is a `build` brief, and
`brief.research-example.md` is the same template at `Purpose: research`.

## 4. What happens while it runs

The agent works through the pipeline, pausing at each point where a judgement is
needed. Roughly:

1. It reads the brief and writes a query plan — 6 to 8 queries across mandatory
   types (`direct`, `terminology`, `contradictory`, `review`).
2. The CLI retrieves across the routed sources, dedups, filters and caps, then
   writes screening batches.
3. The agent scores every candidate 0–3 against the brief's sub-criteria.
4. The CLI expands the citation graph from everything scoring 2 or 3; the agent
   screens what comes back.
5. The CLI counts coverage per sub-criterion. If coverage is uneven, the agent
   writes one or two gap queries and a second round adds what they find.
6. The CLI shortlists; the agent reranks under the rerank rubric.
7. The CLI verifies every ranked paper's DOI against the live record and emits.

Screening is the long pole — it is the agent reading the pool, and it dominates
both the wall clock and the token cost. See
[the pipeline](/architecture/overview/) for the stage-by-stage detail.

## 5. Collect the results

Everything lands in `research/scans/<YYYY-MM-DD>-<slug>/`. The deliverable is
`evidence.json` plus `evidence.md` — the same list rendered for a human.

[Understanding your results](/getting-started/understanding-results/) walks
through what is in them.