NotchBio MCP tool reference
This reference describes the 26 tools in the current read-only preview. Connect using the URL in lab settings. Agents should call nb_list_documentation, read start-here and this tool-reference guide completely using next_offset, and check nb_get_capabilities before suggesting actions. The same guides are MCP resources at notchbio://docs/{slug}; notchbio://docs is their manifest. Tool schemas exposed by the server are authoritative.
Every call requires lab:read and current customer access. File tools also require lab:files; exports require both lab:files and lab:export; logs require lab:logs. A scope challenge can require reconnection. Project IDs and analysis IDs are UUIDs returned by discovery tools; artifact IDs are opaque handles, not filesystem paths. Never guess identifiers or expose private download links.
Results normally contain schema_version, data, warnings and next_actions; errors contain an error code, message and retryability. List tools use offset (default 0) and limit (default 50, range 1–200); follow next_offset until null. Document and text reads use offset and limit (default 12000, maximum 20000); follow the returned continuation. Preserve exact analysis lineage, units, comparison numerator and baseline when interpreting results. Unknown data is not evidence of failure.
Available tools
Section titled “Available tools”nb_get_profile
Section titled “nb_get_profile”Inputs: none. Scopes: lab:read.
Identify the connected customer, scopes and selected-project restrictions. Never returns tokens.
nb_get_capabilities
Section titled “nb_get_capabilities”Inputs: none. Scopes: lab:read.
Read implemented capabilities and limitations before offering a workflow or action.
nb_list_documentation
Section titled “nb_list_documentation”Inputs: none. Scopes: lab:read.
Discover the complete agent handbook: document IDs, headings, versions and content hashes.
nb_read_documentation
Section titled “nb_read_documentation”Inputs: slug: str, offset: integer (minimum 0)=0, limit: integer (1–20000)=12000. Scopes: lab:read.
Read a handbook document; follow next_offset to the end for complete instructions.
nb_search_documentation
Section titled “nb_search_documentation”Inputs: query: string (1–500 characters). Scopes: lab:read.
Find relevant handbook sections. Read the complete matching document before using that workflow.
nb_get_guidance
Section titled “nb_get_guidance”Inputs: topic: str='start-here'. Scopes: lab:read.
Read complete workflow guidance using a document ID from nb_list_documentation.
nb_get_defaults
Section titled “nb_get_defaults”Inputs: none. Scopes: lab:read.
Read current backend pipeline defaults; distinguish supplied flags from effective tool behavior.
nb_list_projects
Section titled “nb_list_projects”Inputs: offset: integer (minimum 0)=0, limit: integer (1–200)=50. Scopes: lab:read.
List accessible customer lab projects, excluding facility staging; follow next_offset.
nb_get_project
Section titled “nb_get_project”Inputs: project_id: UUID. Scopes: lab:read.
Read project organism, role, metadata and analysis/sample counts.
nb_list_samples
Section titled “nb_list_samples”Inputs: project_id: UUID or null=None, offset: integer (minimum 0)=0, limit: integer (1–200)=50. Scopes: lab:read.
Read the project sample sheet or owned global datasets. Includes raw-file handles when permitted.
nb_list_analyses
Section titled “nb_list_analyses”Inputs: project_id: UUID, offset: integer (minimum 0)=0, limit: integer (1–200)=50. Scopes: lab:read.
List recorded quick/advanced analyses in a project, with explicit pagination.
nb_get_analysis
Section titled “nb_get_analysis”Inputs: project_id: UUID, analysis_run_id: UUID. Scopes: lab:read.
Read exact recorded stages, parameters and input snapshot without advancing or retrying work.
nb_list_jobs
Section titled “nb_list_jobs”Inputs: project_id: UUID or null=None, analysis_run_id: UUID or null=None, offset: integer (minimum 0)=0, limit: integer (1–200)=50. Scopes: lab:read.
List only authorized NotchBio pipeline/import jobs; never enumerates the Modal account.
nb_get_job
Section titled “nb_get_job”Inputs: job_id: str, fresh: bool=False. Scopes: lab:read.
Observe a known job. fresh adds bounded Modal state; not_ready/unknown is not proof of failure.
nb_get_job_logs
Section titled “nb_get_job_logs”Inputs: job_id: str, limit: integer (1–200)=100. Scopes: lab:read + lab:logs.
Read a redacted recorded error plus bounded call-scoped logs when the deployed Modal SDK supports them.
nb_list_artifacts
Section titled “nb_list_artifacts”Inputs: project_id: UUID, analysis_run_id: UUID or null=None, offset: integer (minimum 0)=0, limit: integer (1–200)=50. Scopes: lab:read + lab:files.
Enumerate all committed version outputs, including trimmed FASTQs, CSVs, matrices and report/plot data.
nb_read_artifact
Section titled “nb_read_artifact”Inputs: artifact_id: str, offset: integer (minimum 0)=0, limit: integer (1–20000)=12000. Scopes: lab:read + lab:files.
Read a bounded text/CSV/TSV/JSON preview. Use downloads for complete files; binary/FASTQ require download.
nb_get_download
Section titled “nb_get_download”Inputs: artifact_id: str. Scopes: lab:read + lab:files + lab:export.
Issue an expiring, file-scoped complete download for the user’s host/browser or device.
nb_preview_artifact
Section titled “nb_preview_artifact”Inputs: artifact_id: str. Scopes: lab:read + lab:files.
Return a supported small raster image as MCP image content for inline display where supported.
nb_render_figure
Section titled “nb_render_figure”Inputs: artifact_id: str, kind: Literal['volcano', 'ma', 'pca', 'heatmap'], output_format: Literal['png', 'svg', 'pdf']='png'. Scopes: lab:read + lab:files + lab:export.
Render recorded scientific figure JSON; return an inline PNG plus a complete PNG/SVG/PDF download.
nb_get_qc
Section titled “nb_get_qc”Inputs: project_id: UUID, analysis_run_id: UUID. Scopes: lab:read.
Read recorded per-sample QC metrics for this exact analysis.
nb_get_preprocessing
Section titled “nb_get_preprocessing”Inputs: project_id: UUID, analysis_run_id: UUID. Scopes: lab:read.
Read trimming metrics/settings from the fastp lineage that actually fed the selected DESeq2 result.
nb_get_quantification
Section titled “nb_get_quantification”Inputs: project_id: UUID, analysis_run_id: UUID. Scopes: lab:read.
Read recorded salmon or STAR/featureCounts settings, per-sample metrics and reference provenance.
nb_list_comparisons
Section titled “nb_list_comparisons”Inputs: project_id: UUID, analysis_run_id: UUID. Scopes: lab:read + lab:files.
List exact persisted DE comparison IDs and numerator/denominator orientation.
nb_resolve_archive
Section titled “nb_resolve_archive”Inputs: accession: string (1–50 characters), offset: integer (minimum 0)=0, limit: integer (1–200)=50. Scopes: lab:read.
Resolve public accession metadata through the existing NotchBio archive service; does not import files.
nb_assess_archive
Section titled “nb_assess_archive”Inputs: accession: string (1–50 characters), offset: integer (minimum 0)=0, limit: integer (1–200)=50. Scopes: lab:read.
Assess per-run species and bulk RNA-seq evidence conservatively; unknown metadata remains uncertain.
Files, images and scientific context
Section titled “Files, images and scientific context”nb_read_artifact is a bounded preview, not a complete file. Use nb_get_download for a complete file. Download links are short-lived bearer credentials and should be treated as private. The host or browser controls saving to the device. nb_preview_artifact accepts PNG, JPEG or WebP images up to 4 MiB and 16 megapixels. nb_render_figure accepts supported recorded figure JSON and returns inline PNG plus a link in the selected format. Display and download behavior depend on the host.
For an analysis, list projects, select a project, list analyses, and inspect the selected analysis. Read QC, preprocessing, quantification and comparisons for that exact run. Distinguish defaults from parameters recorded for the run. Download a complete result before claiming it was fully analyzed. Archive tools resolve and assess public metadata; they do not import files, and ambiguous metadata remains uncertain.
The current preview cannot start, change, retry or cancel analyses, import archive data, upload local files, execute arbitrary code, or create a complete dashboard bundle. Use the lab application for these actions. Never report a proposed action as completed.