# Research Scan as an agent primitive

Infrastructure for agents rather than a chatbot. What it means to treat verified evidence as a component other systems build on.

Research Scan is not an application with an agent bolted on. It is a component
that agents call, and it was designed from the start to sit underneath something
else.

That is a claim about shape, not ambition. The shape is: a question goes in, an
agent supplies the judgement, a deterministic engine does the retrieval and the
checking, and verified evidence objects come out. Nothing in that chain assumes a
chat window, a particular model, or a human waiting for prose.

## The shape

```
question
   │
   ▼
agent            planning · screening · gap queries · reranking
   │             (your model, your rubrics, your harness)
   ▼
engine           retrieve · expand · dedupe · coverage · shortlist · verify · audit
   │             (deterministic, model-free, no LLM SDK)
   ▼
evidence objects EvidencePacket JSON + Markdown, every DOI checked
```

The middle two rows are replaceable independently. Swap the model and the engine
does not notice. Change how the engine ranks a shortlist and the model does not
notice. They meet only at the file boundary.

## Why a chatbot would be the wrong shape

A chat interface makes three assumptions that are wrong for this problem.

**That the answer is prose.** The useful output of a literature scan is
structured: papers with scores, arguments, limitations and verification records.
Rendering it as a paragraph throws away everything a downstream system could act
on.

**That one pass is enough.** A scan retrieves, judges, expands from what it kept,
counts coverage, refines where coverage is thin, then verifies. Those are distinct
decisions with distinct inputs. A conversation flattens them into one turn.

**That a human is in the loop.** Sometimes there is not. A scan can run unattended
and hand structured JSON to whatever comes next.

## Serving as an evidence primitive

Because the output is a schema-validated object rather than a rendering, Research
Scan can serve as an evidence primitive inside larger agent workflows — the step
that turns "what does the literature say" into something later steps can compute
on.

Some concrete shapes that follow:

**A novelty check before a project starts.** The agent runs a scan against the
project brief, and the top of the shortlist is the prior art. `relation:
contradicting` papers are the ones worth reading first.

**A gate in a longer pipeline.** A scan returns a `ScanSummary`; a downstream step
branches on its counts. If coverage on a criterion is thin, that is a signal about
the state of the field, not just about the search.

**A recurring watch.** The same brief, re-run on a schedule with a moving date
window, produces comparable run directories. Because clocks are injectable and
stages are deterministic, differences between two runs are differences in the
literature, not noise in the tool.

**A source of citations another agent must not invent.** The strongest property
for composition is negative: a downstream model handed `evidence.json` has real
DOIs, and any record that failed verification is already marked. It does not need
to be trusted about bibliography, because it was never asked to produce one.

## Running it unattended

The skill returns a `ScanSummary`, so a scan can run headless and hand structured
JSON to the next step:

```bash
claude -p "Use the research-scan skill to scan brief.md with --slug nightly --top 5. \
           When it finishes, return its ScanSummary as your final answer." \
  --plugin-dir /path/to/research-scan \
  --allowedTools "Bash(research-scan *),Read,Write,Edit,Glob,Grep" \
  --output-format json \
  --json-schema "$(research-scan schema --name ScanSummary)" \
  > scan.json

jq '.structured_output.counts' scan.json
```

Two details decide whether this works, both documented in the main repo:

**Ask for the skill in prose.** A bare `/research-scan …` slash command runs
entirely inside the skill's fork, so the session returns no top-level assistant
turn for `--json-schema` to bind to and `structured_output` comes back `null`. The
scan still succeeds and writes its run directory — you just do not get the
structured result. Phrasing it as an instruction makes the session invoke the
skill, receive the fork's report, and emit the `ScanSummary` itself.

**`--allowedTools` must carry `Glob`.** It is not optional: the skill globs
`screen-batches/` to find the batches to score.

## The property that makes it composable

Everything above rests on one thing: the layer that decides what counts as a
verified record contains no model.

Models improve, change price, get deprecated and get replaced. If the definition
of "this paper exists and its DOI resolves" lived inside a model, every one of
those events would be a change to your evidence. It does not, so they are not.

The agent changes. The evidence layer stays.

## Where to go next

- [Agent and tool separation](/concepts/agent-tool-separation/) — the boundary in
  detail.
- [Custom agents](/integrations/custom-agents/) — driving the pipeline from
  something other than Claude Code.
- [MCP tools](/reference/mcp-tools/) — the four decision points, as tools.