Fetch a paper by DOI/arXiv ID and ingest it (one-shot).

Persist a JSON payload of per-paper summaries (when LLM was invoked out-of-band) to Obsidian + Zotero. The payload shape matches the summarize_cluster prompt's expected output: {summaries: [...]}.

Persist crystal answers to hub//crystals/.md.

Convert fit-check sidecar decisions into paper labels. Persists fit_check_apply decisions before pruning. When to use: after accepted and rejected sidecars are written. When NOT to use: to score candidates; use fit_check_apply instead. Args: cluster_slug: cluster whose sidecars and notes are used. Returns: keys tagged, already, missing, error. Example: >>> apply_fit_check_to_labels("my-topic") {"tagged": ["paper-1"]}

Write subtopics frontmatter to each paper note.

Answer a question about one cluster, dispatching to the source named by source / mode.

Single entrypoint for all cluster-question workflows. Replaces the deprecated aliases ask_cluster_notebooklm / read_briefing / brief_cluster (gated behind RESEARCH_HUB_MCP_INCLUDE_DEPRECATED=1, removed in v2.0.0). Routes the question through three internal paths: source='local' answers from cached crystals + memory only; source='notebooklm', mode='ask' opens NotebookLM via Playwright and asks live; source='notebooklm', mode='briefing' returns the last downloaded NotebookLM briefing markdown; source='notebooklm', mode='brief' runs the full bundle-upload-generate-download round-trip to refresh the briefing artifact.

When to use:

• User asks a natural-language question about one cluster and you want the cheapest, fastest answer first (source='local').

• User asks an ad-hoc question that requires fresh paper content retrieval (source='notebooklm', mode='ask').

• User wants to read the existing brief text (mode='briefing').

• User asks to regenerate the brief (mode='brief' with force_regenerate=True).

When NOT to use:

• You want one specific crystal answer by slug; use read_crystal instead — it skips dispatch overhead.

• You want to search across multiple clusters; use web_search or search_papers instead.

• You want to inspect cluster memory directly (entities / claims / methods); use read_cluster_memory.

Apply AI-authored autofill sections to paper notes. Consumes autofill_emit JSON and updates notes. When to use: after an AI returns summaries for an autofill prompt. When NOT to use: to generate prompts; use autofill_emit instead. Args: cluster_slug: cluster to update; scored: list or {"papers": [...]}. Returns: keys cluster_slug, candidate_count, filled, skipped, missing, error. Example: >>> autofill_apply("my-topic", {"papers": [{"slug": "paper-1"}]}) {"cluster_slug": "my-topic", "filled": []}

Build an autofill prompt for paper notes with TODO bodies. Emits the JSON prompt for autofill_apply. When to use: after ingest creates notes with abstracts but TODO content. When NOT to use: to write AI output; use autofill_apply instead. Args: cluster_slug: cluster whose notes are scanned for TODO placeholders. Returns: keys prompt, paper_count, error. Example: >>> autofill_emit("my-topic") {"paper_count": 3}

One-shot research pipeline: search + ingest + NotebookLM brief (+ optional crystals).

Slugifies topic into a cluster (or reuses cluster_slug), searches arXiv + Semantic Scholar, ingests papers into Zotero + Obsidian, then bundles + uploads + generates + downloads a NotebookLM brief. With do_crystals=True and a detected supported LLM CLI on PATH, also generates and applies the canonical Q&A crystals so the cluster is fully ready for read_crystal() queries.

Use when: user says "research X for me" or "find papers on X".

Returns {ok, cluster_slug, papers_ingested, notebook_url, brief_path, total_duration_sec, error}.

Return an inline citation string for a paper.

Generate topics/NN_.md files from paper frontmatter.

Persist a quote to /.research_hub/quotes/.md.

Check how many crystals are stale (>10% cluster paper delta since generation).

Garbage-collect accumulated research-hub files (v0.46+).

Pass everything=True for the common case (bundles + debug logs + artifacts). Default mode lists candidates without deleting; pass apply=True to actually remove.

Use when: user says "clean up", "free disk space", or "GC the vault".

Returns {ok, total_bytes, files_deleted, dirs_deleted, candidates}.

Run the cluster-rebind workflow specified by action.

Single entrypoint that consolidates four legacy rebind operations (propose / apply / list_orphans / status) into one tool with an action discriminator. Replaces the deprecated aliases propose_cluster_rebind / apply_cluster_rebind / list_orphan_papers / summarize_rebind_status, which are gated behind RESEARCH_HUB_MCP_INCLUDE_DEPRECATED=1 and slated for removal in v2.0.0.

When to use:

• After ingest leaves orphan paper notes that don't match any active cluster, and you want to plan moves before touching files.

• After a manual cluster rename, when existing paper notes still reference the old slug.

• Periodic vault hygiene: surface stuck or low-confidence orphans via action='status'.

When NOT to use:

• You want to delete clusters wholesale, not rebind their papers; use research-hub clusters delete (CLI) instead.

• You want to archive papers carrying a label; use prune_cluster instead.

Unified ingest. Auto-routes by source shape: DOI/arXiv -> add_paper, folder -> import_folder, URL -> .url file + import.

Assemble a markdown draft from cluster quotes + overview + crystal TLDRs.

Assemble captured quotes into a markdown draft.

Remove the discover stash directory for a cluster.

Apply fit-check scores from an AI judge and produce a papers_input.json ready for ingest.

Second half of the interactive discovery flow. The user runs discover_new first (which emits a search-results stash + a scoring prompt), pastes the prompt into an AI of choice, then feeds the AI's scored output back through this tool. The scored candidates are filtered by threshold and written to papers_input.json in the cluster's discover-stash directory, ready for the standard ingest pipeline (research-hub auto or research-hub clusters ingest).

When to use:

• You have a JSON list of fit-check scores from an AI judge and want to admit only the high-confidence candidates into the vault.

• You're running the two-phase discovery flow because the topic boundaries are fuzzy and you want a human / AI in the loop on which papers belong.

When NOT to use:

• You haven't run discover_new yet — there's no stash to apply scores against. Run discover_new first.

• You already have a fully-resolved list of DOIs to ingest; skip discovery and call add_paper per item, or auto_research_topic for the one-shot path.

• You want to re-score an EXISTING ingested cluster's papers; use fit_check_emit + fit_check_apply (the post-ingest re-scoring path).

Run search + emit fit-check prompt, stashing state for discover_continue.

Return current discover state for a cluster.

Emit a query-variation prompt for discovery search. Generates alternate discover_new queries. When to use: before discovery when the seed query is narrow. When NOT to use: to run search; use discover_new instead. Args: cluster_slug: context; query: seed query; count: variant target. Returns: keys prompt, target_count, error. Example: >>> discover_variants("my-topic", "LLM agents", count=4) {"target_count": 4, "prompt": "..."}

Download a generated NotebookLM briefing back to the vault.

Opens the cluster's NotebookLM notebook using the saved local session, extracts the latest briefing summary text, and saves it under <vault>/.research_hub/artifacts/<cluster_slug>/brief-<UTC>.txt. The cluster's nlm_cache.json entry is updated with the new path.

Build the topic-build Phase 2 (sub-topic assignment) LLM prompt.

Part of the multi-phase topic build flow: Phase 1 proposes sub-topics for a cluster; Phase 2 (this tool) emits the prompt that asks an LLM to assign each paper to one of those sub-topics.

Emit (or refresh) the .base dashboard file for a cluster.

Emit the markdown prompt the calling AI should answer to generate crystals.

Resolve candidate identifiers to full paper records.

Copy an example into the user's cluster registry.

List bundled example clusters.

Return one bundled example cluster definition. Inspects sample JSON before examples_copy. When to use: before copying an example such as cs_swe. When NOT to use: to list names; use examples_list instead. Args: name: bundled example id, such as cs_swe or bio_protein. Returns: keys name, slug, field, query, definition, year_from, year_to, min_citations, sample_dois, description, error. Example: >>> examples_show("cs_swe") {"slug": "llm-agents-software-engineering"}

Export citation in BibTeX, BibLaTeX, RIS, or CSL-JSON format.

Consume AI scores, filter candidates, write rejected sidecar.

Parse the latest NotebookLM briefing for off-topic flags. Audits briefing text before fit_check_drift. When to use: after NotebookLM flags papers. When NOT to use: to emit scoring prompts; use fit_check_emit instead. Args: cluster_slug: cluster whose briefing is audited. Returns: keys ok, cluster_slug, flagged, reason, error. Example: >>> fit_check_audit("my-topic") {"ok": True, "flagged": [...]}

Emit a drift-check prompt for the current cluster overview. Re-scores papers after fit_check_audit. When to use: when an overview changed and papers may not fit. When NOT to use: to apply scores; use fit_check_apply instead. Args: cluster_slug: cluster; threshold: accepted score cutoff, default 3. Returns: keys cluster_slug, paper_count, threshold, prompt, error. Example: >>> fit_check_drift("my-topic", threshold=3) {"cluster_slug": "my-topic", "prompt": "..."}

Build the Gate 1 fit-check prompt for an AI to score.

Generate a personal HTML dashboard for the vault.

Returns the path to the generated file. Open it in a browser to see cluster overview, paper counts, reading status breakdown, and NotebookLM links.

List papers that cite the given paper (forward citations).

Delegates to research_hub.citation_graph.CitationGraphClient (Semantic Scholar Graph API).

Show current configuration paths and settings.

List papers cited by the given paper (its bibliography).

Return every paper in a cluster plus a markdown digest for overview writing.

Walk a local folder and ingest non-DOI files as document notes.

Set, add, or remove labels on a paper note.

List all topic clusters with their bindings.

List all pre-computed crystal answers for a cluster.

Return paper states for the cluster, optionally filtered by label.

List captured quotes, optionally filtered by cluster.

List existing sub-topic notes for a cluster.

Update the reading status of a paper note.

Delegates to research_hub.operations.mark_paper.

Merge all papers from one cluster into another, then delete the source.

Delegates to research_hub.clusters.ClusterRegistry.merge.

Move a paper note from its current cluster to another.

Delegates to research_hub.operations.move_paper.

Build a NotebookLM upload bundle for a cluster.

Download the latest NotebookLM briefing artifact into the vault.

Trigger NotebookLM artifact generation for a cluster notebook.

Upload the latest cluster bundle to NotebookLM using the saved session.

Convert a freeform user intent into a structured research plan.

Call this BEFORE auto_research_topic when the user's request is vague, ambitious, or could collide with an existing cluster. Returns a suggested topic + search depth + NLM/crystals choices + clarifying questions for you to confirm with the user.

Use when the user says things like: "I want to learn about X" "research X for my dissertation" "find recent papers on X" "ingest X but skip NotebookLM"

The plan includes:

• intent_summary: rephrased one-line restatement (confirm with user)

• suggested_topic / cluster_slug

• suggested_max_papers (auto-tuned: 25 for thesis, 8 default, etc.)

• suggested_do_nlm / do_crystals (with detected CLI awareness)

• existing_cluster_match: warns if a similar cluster already exists

• clarifying_questions: ask these BEFORE calling auto_research_topic

• next_call: ready-to-execute auto_research_topic args after confirmation

• estimated_duration_sec: rough time estimate

After presenting the plan + getting user confirmation, call auto_research_topic with the plan's suggested args.

Propose names for a new research collection without creating anything.

Use this BEFORE creating clusters/collections/notebooks. Show the suggestions to the user and ask them to confirm or override each name. Only after the user agrees should you call the create tools.

Build the Phase 1 sub-topic proposal prompt for an AI to consume.

Archive or delete paper notes in a cluster whose frontmatter carries label.

Cluster cleanup operation that acts on the label sidecars written by apply_fit_check_to_labels (e.g. deprecated, off_topic, low_relevance). Moves matching paper notes to the cluster's _archive/ subfolder by default, or deletes them outright if delete=True. Pairs with apply_fit_check_to_labels as a two-step "decide → act" workflow: that tool labels papers based on fit-check sidecars; this tool acts on the labels.

When to use:

• After running apply_fit_check_to_labels (or manually labelling papers), you want to physically move the off-topic notes out of the active cluster folder.

• You want to keep an audit trail (default archive=True) so the moves are reversible.

When NOT to use:

• You want to ADD labels, not act on them; use apply_fit_check_to_labels instead.

• You want to delete the entire cluster (not just labelled papers); use research-hub clusters delete (CLI) instead.

• You want to rebind orphans to a different cluster, not archive them; use cluster_rebind instead.

Read cluster memory. kind may be entities, claims, methods, or all.

Read a specific crystal at the requested detail level.

Return the current topic overview markdown for a cluster, if present.

Remove a paper from the vault, optionally deleting its Zotero item too.

Run health checks on the research-hub installation.

Search for academic papers across multiple backends.

Search local vault notes by title or full text.

Show detailed info for a cluster including sync status.

Split a source cluster into a new cluster based on title keyword overlap.

Analyze a cluster's citation graph and suggest sub-topic splits.

Suggest which cluster a paper belongs to and find related papers.

Generate per-paper Key Findings + Methodology + Relevance via LLM CLI.

For each paper in cluster_slug, builds a prompt from the abstract and invokes the detected LLM CLI (claude, codex, or gemini — pass llm_cli to override). With apply=False (default), returns the parsed JSON without writing. With apply=True, writes back to BOTH the Obsidian markdown blocks and the Zotero child note for each paper.

Use when: user says "summarize this cluster's papers", "fill the TODO Findings", or after auto ingest before scanning the vault.

No LLM CLI on PATH: prompt is saved to artifacts//summarize-prompt.md; user can pipe it through their LLM and re-run with --apply (CLI) or pass the parsed payload to the apply_cluster_summaries MCP tool below.

Returns {cluster_slug, ok, error, cli_used, prompt_path, apply_result}.

Aggregate maintenance view: staleness + scope drift + vault health + recommendations.

One-shot vault maintenance: doctor autofix + dedup rebuild + bases refresh + cleanup preview.

Each sub-step is non-fatal — failures logged but don't abort the others.

Use when: user says "tidy", "maintenance", "vault health check".

Returns {ok, steps, total_duration_sec, cleanup_preview_bytes}.

Verify a paper exists via DOI, arXiv ID, or fuzzy title match.

General web search (blog posts / docs / news / GitHub READMEs).

Use alongside auto_research_topic when the user's need extends beyond peer-reviewed papers and into official docs, engineering blogs, or news.

Write a topic overview markdown file for a cluster.