Tools

List all registered lab instruments with run counts, watcher status, and file patterns. Optionally filter by status.

Get detailed information about a specific instrument, including watcher online/offline counts and file patterns.

Return the valid search_runs metadata filter values for one instrument (wavelengths, dye channels, etc.). Prefer the datahub://instruments/{id}/filter-options resource when the client supports resources.

Search instrument runs with filtering, pagination, and sorting. Supports run status filters and instrument-metadata filters (plate reader, gel-doc, qPCR, Hina microscope, Epson scanner, Aunty). Prefer global_search when the query may match filenames, instrument names, or attributor names rather than run IDs. Discover valid metadata filter values via get_instrument_filter_options or datahub://instruments/{id}/filter-options.

Get details for a specific instrument run by its natural key (instrument ID + run ID). Returns metadata, timestamps, instrument info, and attributions by default. Pass include to attach the first page of files, comments, and/or a failure_summary without extra tool calls. To show the interactive report (plate maps, spectra, images) or a bounded processed-CSV sample, call get_run_report for the same run.

Return an analysis-ready summary for a run: file counts, failure summary, image/report file refs, and a bounded processed-CSV sample (columns + first rows). Prefer this over downloading full CSVs when comparing or summarizing experimental results. Hosts that support MCP Apps render the interactive report View when this tool is called.

List files associated with a run (raw uploads and processed artifacts) with their status, category, and size. Paginated — runs can have thousands of files. Filter by status to gather fileIds for request_run_upload (e.g. status=['detected']). Use get_file for full per-file detail including metadata and S3 location.

Re-run Lambda processing for every uploaded, completed, failed, or stalled raw file on a run. Processed artifacts are skipped. The instrument must have a Lambda processor. Prefer this over looping reprocess_file for bulk retries after a parser fix, to kick stuck uploads, or to recover files that never reported back from processing.

Soft-delete a run (sets deleted_at). Does not remove files or S3 objects. Use restore_run to undo. Idempotent: deleting an already-deleted run succeeds as a no-op.

Restore a soft-deleted run by clearing deleted_at. Idempotent: restoring a run that is not deleted succeeds as a no-op.

Queue specific detected files for watcher upload (max 100). Requires an online watcher. Idempotent for files already in upload_requested.

Queue every detected file on a run for watcher upload. Requires an online watcher.

Return a paginated window of run report items (images, PDFs, spectra, or videos) with download URLs. Used by the Data Hub run report view. Call `get_run_report` instead.

Return a short-lived download URL for one file on a run, found by numeric id or by filename suffix. The view reads CSV and JSON bodies from that URL itself. Used by the Data Hub run report view. Call `get_run_report` instead.

Mark a run as performed by the authenticated user. Idempotent — claiming a run you already claimed is a no-op. Only self-attribution is supported; you cannot claim a run on behalf of another user. Prefer claim_runs when attributing multiple runs.

Mark multiple runs on one instrument as performed by the authenticated user (max 100). Idempotent per run. Returns claimed runs and any runIds that were not found; a missing ID does not fail the whole batch. Only self-attribution is supported.

Remove the authenticated user's attribution from a run. Idempotent — unclaiming a run you don't currently claim is a no-op. Only self-attribution is supported; you cannot remove another user's attribution.

List distinct users who have claimed at least one run on a given instrument. Use the returned userId with search_runs ranBy=<userId>.

List comments on a run (oldest first), including author display info.

Add a comment on a run as the authenticated user. Author is taken from the token — you cannot comment as another user.

Edit one of your own comments. Returns an error if the comment is missing or authored by someone else.

Soft-delete one of your own comments. Idempotent if already deleted.

Get detailed metadata for a single file by its numeric ID, including status, S3 location, size, extracted metadata, and any error message.

Get a short-lived pre-signed S3 URL to download the raw file contents. URL expires after 15 minutes.

Get a downloadable ZIP archive of every active, uploaded file in a run. If the archive is already cached, returns a short-lived (15 min) pre-signed S3 URL the caller can fetch directly without auth — paste it into a browser or share it as a download link. If the archive isn't cached, kicks off an async build and returns `{ status: 'building', jobId, retryAfterSeconds }`; call this tool again after the suggested wait to poll for completion. Most archives finish in a few seconds; large runs may take a minute or two. Mirrors the REST `download-archive` route, including its dedup-by-fingerprint cache, so concurrent callers share a single Lambda invocation.

Re-run the Lambda processing workflow for an uploaded, failed, completed, or stalled raw file on an instrument that has a Lambda processor. A file is stalled when it has been in 'processing' longer than the configured stall window (20 minutes by default, past the Lambda's 15-minute limit) or has no processing-started timestamp. Processed artifacts are rejected. Transitions the file back to 'processing'. Use this to retry after a parser fix, transient Lambda failure, a stuck upload that never entered processing, or a file that never reported back from processing.

Soft-delete a detected or upload_requested file (UI 'dismiss'). Uploaded files cannot be dismissed — delete the run instead. Idempotent: dismissing an already-dismissed file succeeds as a no-op.

List watcher agents with effective status, hostname, instrument assignment, and last heartbeat. Optionally include deregistered watchers or filter by effective status.

Get watcher detail including config YAML, OS info, effective status, and deregistration actor when applicable.

Paginated watcher event log (uploads, errors, config sync, update lifecycle). Useful after get_watcher_heartbeats when diagnosing failures.

Get recent heartbeat history for a watcher agent, useful for diagnosing connectivity gaps and error trends. Returns up to 100 most recent heartbeats within the lookback window.

Fuzzy search across runs, files, instruments, users, and comments (same backend as the UI ⌘K palette). Prefer this over search_runs when the query may match a filename, instrument display name, attributor name, user, or comment body. The users scope returns workspace member names/emails to any authenticated caller (no row-level member privacy). Use search_runs for date/status/metadata filters. Queries shorter than 2 characters are rejected.

Return the authenticated user's identity (id, name, email, image, isAdmin). Use the returned id with search_runs ranBy=, or pass ranBy="me" instead.

Get a dashboard-level overview: per-instrument run counts, watcher health (online/offline/no_watcher), and pending upload counts.

Report a bug or request about Data Hub itself (the web app, MCP tools, or the watcher). Show the user this draft and get their approval before calling. For a problem with a specific run's data, use add_run_comment instead. Any read token can call this.

List feedback reports. Workspace admins see every report; everyone else sees only their own. Descriptions longer than 280 characters are shortened. Use get_feedback for the full report.

Get one feedback report, including the full description. Workspace admins can read any report; everyone else can read only their own.

Set a feedback report's status to open, resolved, or declined, with an optional note shown to the reporter. Workspace admin only, and requires the write scope. Changing the status to resolved or declined notifies the reporter. Editing only the note does not.