ask_cluster
Answers natural-language questions about a research cluster using cached data or live NotebookLM queries. Also retrieves or regenerates briefings.
Instructions
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'withforce_regenerate=True).
When NOT to use:
You want one specific crystal answer by slug; use
read_crystalinstead — it skips dispatch overhead.You want to search across multiple clusters; use
web_searchorsearch_papersinstead.You want to inspect cluster memory directly (entities / claims / methods); use
read_cluster_memory.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cluster | No | Cluster slug to ask. One of ``cluster`` or ``cluster_slug`` must be set; ``cluster_slug`` is a backwards-compat alias accepted for legacy clients. | |
| question | No | Natural-language question. May be ``None`` only when ``mode='briefing'`` or ``mode='brief'`` (where the action is read/regenerate, not Q&A). | |
| source | No | ``'local'`` (default) for cached crystals + memory, or ``'notebooklm'`` for the Playwright-driven NotebookLM backend. NotebookLM paths require a logged-in browser session — run ``research-hub notebooklm login`` once. | local |
| detail | No | Response verbosity. One of ``'gist'`` (default, ~100 words) / ``'standard'`` / ``'detailed'``. Only honoured by local + briefing modes. | gist |
| headless | No | For ``source='notebooklm'``, whether to run the browser headless. Default ``True``; set ``False`` if you need to debug a Google auth challenge. | |
| timeout_sec | No | Max seconds to wait for NotebookLM. Default 120. Increase to 240+ for large clusters. | |
| max_chars | No | For ``mode='briefing'``, truncate the briefing text after this many chars. Default value comes from the module-level ``_BRIEFING_MAX_CHARS``. | |
| force_regenerate | No | For ``mode='brief'``, force the full round trip even if a recent briefing exists. Default ``False`` (use cached briefing when available). | |
| mode | No | NotebookLM sub-action. One of ``'ask'`` (default; live Q&A), ``'briefing'`` (return existing brief markdown), or ``'brief'`` (full bundle → upload → generate → download). Ignored when ``source='local'``. | ask |
| cluster_slug | No | Backwards-compat alias for ``cluster``. Prefer ``cluster``; ``cluster_slug`` exists for parity with the deprecated ``ask_cluster_notebooklm`` signature. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||