Agent and tool separation

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.

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 — what this separation makes possible in larger systems.
• Artifacts and schemas — the interface in detail.
• The agent layer — the rubrics themselves.