Research Scan
Type to search documentation.

Your first scan

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

View as MarkdownOpen in ChatGPTOpen in Claude

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"]
    }
  }
}
ClientWhere that goes
Claude Code.mcp.json in the project root
Claude Desktopclaude_desktop_config.json
Cursor.cursor/mcp.json

More detail, including the skill-only routes, is in Integrations.

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 sectionWhat it feeds
Purpose: lineWhich 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 aboutThe brief_summary and the domain routing. Say the setting, not just the topic.
What we need to decide or answerThe 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.
Exclusionsmust_not, enforced in code at word boundaries — never as NOT-terms in query text.
Known papers or authorsanchors: 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 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 walks through what is in them.

Last updated Aug 21, 2026