This workflow requires the matching backend and MCP release (backend PR #794 and MCP PR #98). Documentation changes do not deploy the server or publish an npm release.
Use
inspect_research_session with view: "job", session_id, and the returned
job_id to poll chat, preparation, generation and edits. On success, read the
answer/references or the returned output_id. Use parent_job_id for a chat
follow-up. Preserve idempotency_key and the exact input on retries. A sync wait
expiring never cancels or duplicates the backend job. Native Tasks remain
available for the existing low-level queue_research_deliverable tool; the new
session tools use explicit durable job polling on both transports.
Read outputs before editing. Edits publish in place after success; default
reports are read-only. Highlights are generated once per default-report revision,
with learning-goal chapters and the report’s verified quotations. Original audio
is used when available; chat-only studies have no artificial narration.
Uploads accept file_name and data_base64, never server-local paths or arbitrary
URLs. The host must supply an attachment’s bytes. Downloads return structured
filename, mime_type, data_base64 and size_bytes (64 MB transfer maximum),
or a short-lived download_url for video. Decode file bytes to a local artifact;
do not display base64 to the human. Source access is rechecked on every read.
These tools are available on full, core and compact profiles; read-only includes
only the four inspectors/download tools. The eight-tool directory profile remains
unchanged. Legacy report-slide and run-based tools remain compatible. Integration
requires backend PR #794; no npm release is implied by this branch.
Example: research to Studio
action: "sync_study", or upload an external source. Save the
returned session ID and preparation job ID. Then queue a question:
inspect_research_session with view: "job" until it succeeds or fails.
Return the answer and its source references to the human. For another turn, use
parent_job_id to preserve the conversation context.
write-scoped key; inspection/download need read. A human’s
request to generate Highlights authorizes using the original participant audio
when available; no artificial narrator is introduced for chat studies.
See the REST API reference for exact schemas,
source IDs, pagination, templates and retry contracts.
Report templates accept Markdown, TXT, or DOCX with placeholders such as {{title}}
and {{findings}}. Presentation templates accept 16:9 PPTX files and reuse their
theme and layouts. Templates provide formatting, not research evidence.
Study questions and clickable evidence
For study findings, comparisons and quotations, resolve the intended studies, create a Hub session if needed, and attach only the requested missing studies. Retain the session for the conversation. Reuse unchanged sources; do not resync or run exhaustive analysis for every question. Follow-ups use the last completed chat job as
parent_job_id. Study-plan changes still use customize_study; status questions use their dedicated tools. Read-only and directory profiles cannot create chat turns.
The answer and its reference cards stay inside the MCP conversation. Always call view_research_answer after the chat job completes to display the full answer with clickable citations; do not replace it with a link to the Intelligence Hub dashboard. In clients that support MCP Apps, clicking a citation opens a card in the embedded answer, with original audio or video playback and transcript context. Clients without MCP Apps receive the readable answer and quotes, but cannot display interactive cards.
chat_research_session and queue_research_chat expose an MCP App that polls the same durable job. view_research_answer can reopen it using session_id and job_id. Clicking a citation fetches its exact quotation, nearby transcript context, study name and available original recording. Reference access is checked again on every read. Citation labels identify transcript turns, not distinct participants. Hub answer generation and verification group citations by source interview so multiple quotes from one interview are not described as different people. Chat interviews have no generated narration. External-document cards show their verified excerpt and page when available.
The App preserves the backend’s citation labels and displays no internal IDs or raw JSON. In clients without MCP Apps, the viewer returns readable text, quotation labels and an authenticated dashboard link. Interactive cards are supported inside the embedded App; the MCP server cannot control citation rendering in a host assistant’s prose.