# Agent and tool separation

The engine is deterministic and model-free; the agent supplies judgement under written rubrics. Files are the boundary between them.

Most AI research tools fuse two things that fail in different ways: the machinery
that finds and checks records, and the judgement that decides what matters.
Research Scan keeps them apart, and the whole design follows from that one
decision.

import TwoLayerDiagram from '@components/TwoLayerDiagram.astro';

<TwoLayerDiagram />

## Two kinds of stage

The repo has a vocabulary for this, and it is worth adopting: a stage is either
`[A]` or `[C]`.

**`[A]` — the agent performs it, under a rubric.** `plan`, `screen` and `rerank`.
These are judgements: which queries to run, whether this paper bears on the
question, which of the shortlisted papers actually belongs in the top ten.

**`[C]` — the CLI performs it, deterministically.** Everything else. HTTP, dedup,
graph expansion, coverage counting, shortlist ordering, verification, the
selection rules, file I/O.

Notice what is missing from the CLI's command list: there is no `screen` command
and no `rerank` command. They are not unimplemented — they are not the CLI's to
perform.

## The rule that keeps it honest

The package declares no LLM SDK. Not as a stylistic preference — as a boundary
that is checked:

> **No LLM SDK in this package, ever.** No `anthropic`, no prompts, no model
> calls. Every judgment belongs to the hosting agent. This is the property that
> makes the tool harness-agnostic.

The consequence is that the engine cannot cheat. It cannot quietly "improve" a
title, infer a missing year, or decide a paper looks important. It has no
faculty for it.

## Files are the interface

The two layers communicate through a run directory of validated JSON. The
filesystem is the protocol boundary between reasoning and execution, not a storage
detail.

Ownership is strict and never crossed:

| Owner | Files |
|---|---|
| The CLI | `candidates.json`, `shortlist.json`, `manifest.json`, `evidence.*` |
| The agent | `queries.json`, `screen.json`, `ranked.json` |

Neither edits the other's files. The CLI never rewrites what the agent wrote — if
a query plan is bad, that is visible in the plan, not silently corrected on the
way through.

Every file is schema-validated on the way in. Unknown keys are rejected
everywhere, so a typo surfaces as an exit-2 error listing the offending paths
rather than being swallowed.

## What the separation buys

**The model can change without touching the evidence layer.** A better model, a
cheaper one, a local one, a different vendor entirely — the engine does not know
or care. It reads the same files.

**Any harness can drive it.** Claude Code, Codex, Cursor, or a plain Python loop
with its own model. This is why the same chain runs over the same artifacts
regardless of who is driving.

**The judgement is auditable.** The rubrics ship as plain Markdown in the skill.
You can read the screening scale, disagree with it, and edit it — and because
scores are written to a file, you can see what any given change did.

**Failures stay attributable.** When a scan misses a paper, the run directory
tells you whether retrieval never surfaced it, screening scored it low, or the
rerank dropped it. Fusing the layers would make that question unanswerable.

## The anti-patterns this rules out

The doctrine names them explicitly, and they are worth reading as a description of
what the boundary is *for*:

- Hand-tuned weight vectors. **The rubric scores; code selects.**
- Rewarding citation count or venue prestige — the screener is not shown them,
  deliberately.
- "Repairing" metadata from model memory.
- Rewriting the agent's queries in code.
- Exclusions smuggled into query text as NOT-terms, instead of enforced in code at
  word boundaries.
- Letting a fallback hide a broken primary path.

Each of those is a way of moving judgement into the deterministic layer, or
mechanism into the judgement layer. Both directions cost you the property that
makes the pipeline trustworthy.

## Where to go next

- [Research Scan as an agent primitive](/concepts/research-scan-as-agent-primitive/)
  — what this separation makes possible in larger systems.
- [Artifacts and schemas](/concepts/artifacts-and-schemas/) — the interface in
  detail.
- [The agent layer](/architecture/agent-layer/) — the rubrics themselves.