Tool reference
Genie declares 23 distinct tools to the agent: 14 in Genome mode, 6 in Analysis mode and 8 in Asset import mode. Each tool has a JSON schema that the backend registers with the runtime as a dynamic tool when a chat starts. The backend executes every call. Parameters and defaults below are taken from the schemas and from the backend handlers.
Summary matrix
| Tool | What it does | Genome (14) | Analysis (6) | Asset import (8) | Citation token |
|---|---|---|---|---|---|
| Genome view and tracks | |||||
genome_get_current_region | Report the current region with numeric start and end | yes | yes (region) | ||
genome_navigate | Move the view to a region given as chr:start-end | yes | yes (region) | ||
genome_list_assemblies | List assemblies and the project's fixed genome | yes | |||
genome_list_tracks | List loaded tracks and catalog tracks that can be added | yes | |||
genome_add_track | Add a catalog track, or a remote file by URL and type | yes | |||
Measurement (5 Mb scope limit per call, except genome_describe_viewport) | |||||
genome_describe_viewport | Per-track minimum, maximum and mean signal, or feature counts, in view | yes | yes (region only) | ||
genome_signal_stats | Minimum, maximum, mean, sum and covered fraction over a scope or regions | yes | yes (computation) | ||
genome_call_peaks | Keep intervals at or above mean + 2 SD (default), merge overlapping or touching ones, write a BED track | yes | yes (computation) | ||
genome_quantify_at_features | Summarize signal over feature intervals, rank them, write a TSV | yes | yes (computation) | ||
genome_correlate_tracks | Binned Pearson correlation between two signal tracks | yes | yes (computation) | ||
| Public data | |||||
public_data_search | Structured search of the ENCODE portal; returns ranked files with accessions | yes | yes (search and one per file) | ||
| Project assets and plans | |||||
project_list_assets | List the project's imported assets | yes | yes | yes | yes (catalog and one per asset) |
project_read_asset | Read one asset's metadata and previewable text | yes | yes | yes (asset) | |
project_update_asset_source | Edit an asset's kind, title, description or source | yes | yes | ||
project_inspect_local_folder | List files in a local folder with inferred asset kinds | yes | |||
project_import_local_folder | Import a local folder's files as assets | yes | |||
project_inspect_local_path | Inspect a local file or folder before import | yes | |||
project_import_local_path | Import a local file or folder | yes | |||
project_inspect_remote_source | Fetch a preview of a URL and find linked files | yes | |||
project_import_remote_source | Import a URL, and optionally its linked files | yes | |||
project_write_asset_artifact | Write a text note inside an imported asset's folder | yes | |||
project_read_analysis_plan | Read the latest output saved from Analysis mode | yes | yes (Studio output) | ||
| Outputs | |||||
create_html_artifact | Genome mode: an HTML page opened from the chat. Analysis mode: a saved Studio output | yes | yes |
"Citation token" means the result carries a [[cite:...]] token the agent can place after a claim. The viewport-summary token cites the region only, not the numbers. See Citations and evidence.
A computation tool that refuses a request (for example a scope over 5 Mb, or a viewport that is not a resolved numeric locus) returns success: false with an error string instead of failing outright. Such a result still appears as a finished tool card and, for the computation tools, still gets a citation whose excerpt is the failure. Read the result before relying on a number.
Genome view and tracks
genome_get_current_region
Reports the stored view region of the project's browser.
Parameters: none.
Returns: genomeId, viewRegion (locus, numeric start and end), updatedAt.
Citation: a genome-region record holding the locus.
Notes: reads the stored browser state, which is what the browser panel draws. If the view was set by an unresolved locus string, start and end are null.
genome_navigate
Moves the browser to a region by writing a new view region to the stored browser state. The browser panel reloads after the call.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
locus | string | no | chr:start-end; commas allowed (chr8:127,700,000-127,760,000) | |
chr | string | no | Use with start and end | |
start | number | no | 0-based start when using chr/start/end | |
end | number | no | Must be greater than start |
Give either locus or all of chr, start and end; otherwise the call fails with "Provide locus or chr/start/end."
Returns: success, genomeId, viewRegion, updatedAt.
Citation: a genome-region record holding the locus.
Limits: only coordinates resolve. The schema's description mentions gene symbols, but a string that is not chr:start-end is stored without numeric bounds, so the view does not go to the requested gene (the browser falls back to the genome's default region); the measurement tools then report that the viewport is not a resolved numeric locus. The agent has no gene lookup tool.
genome_list_assemblies
Parameters: none.
Returns: defaultGenomeId (hg38), selectedGenomeId (the project's genome) and genomes, a summary of every assembly in the raw catalog: 60 assemblies, including the 3 that the eg3 engine cannot render and the genome picker does not offer.
Citation: none.
Notes: each project has one immutable genome. The tool is for inspection only; to use another genome, create a new project.
genome_list_tracks
Parameters: none.
Returns: genomeId, tracks (id, name, type, visible, options, config, height and legacy code-location fields), plugins and availableCatalogTracks (id, type and name of each default catalog track for the genome, for use with genome_add_track).
Citation: none.
Notes: the agent can read whether a track is hidden but has no tool to hide, reorder or resize tracks. Use the Track Manager for that.
genome_add_track
Adds a track to the stored browser state. The browser panel reloads after the call.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
catalogId | string | no | A default catalog track id from availableCatalogTracks | |
sourceUrl | string | no | Remote data file URL (bigWig, bigBed, BED, bedGraph, tabix-indexed) | |
type | string | with sourceUrl | Track type, for example bigwig, bigbed, bed, bedgraph; lower-cased, not validated | |
indexUrl | string | no | Index file for tabix-indexed sources | |
name | string | no | file name from the URL | Display name |
hubUrl | string | no | Not supported: "hubUrl is not yet supported. Add a specific sourceUrl or catalogId." |
Returns: addedTrack (id, type, name, url, catalogId), trackCount, a summary of all tracks, updatedAt.
Citation: none. When the agent loads an ENCODE file, cite the search candidate's token for claims about the file.
Limits: the type is not checked against the engine's supported types; a wrong type shows up only when the browser fails to draw the track. A track added by URL keeps only its id, type, name, URL and the source "remote"; the assay and ENCODE output type are not stored with it unless the agent puts them in the name.
Measurement
These five tools read the track files themselves (bigWig, bigBed, BED, bedGraph) through the backend, not the rendered picture. The algorithms are described in Measurements.
Scopes. scope is "viewport" (the stored view region; default), "chromosome" (the whole chromosome the view is on) or "all" (every chromosome of the genome). genome_signal_stats also accepts explicit regions.
5 Mb limit. genome_signal_stats, genome_call_peaks, genome_quantify_at_features and genome_correlate_tracks refuse scopes whose total length exceeds 5,000,000 bp. On hg38 that rules out "chromosome" and "all" for every chromosome except chrM. genome_describe_viewport has no such check; above 5 Mb its per-track signal fetches fail.
Track kinds. Signal tracks are bigwig, bw, bedgraph and dbedgraph. Interval tracks are bigbed, bb, bed, categorical, qbed, refbed, repeatmasker and rmskv2. Everything else (gene annotation, VCF, BAM, Hi-C and other types) has no numeric summary.
genome_describe_viewport
Summarizes each track in the current view.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
trackIds | string[] | no | all tracks | Subset of track ids |
Returns: region (chr, start, end, locus) and one entry per track:
- signal tracks:
statswithmin,max,mean(length-weighted over covered bases),sum,nIntervals,coveredBases,coveredFraction(capped at 1); - interval tracks:
statswithfeatureCount,minScore,maxScore; - other tracks:
note: "no numeric summary"; - a track that could not be read:
error.
If the stored view is not a resolved chr:start-end region, the call returns no tracks and the warning "The current viewport is not a resolved numeric chr:start-end region."
Citation: a genome-region record that holds only the locus. It does not hold the statistics. In both demonstration answers the chip placed after the viewport statistics opened this region record.
Limits: no 5 Mb check; above 5 Mb each signal track returns an error while the call itself reports success. refbed tracks are classed as interval tracks but cannot be read and return an error.
genome_signal_stats
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
trackIds | string[] | no | all signal tracks | Non-signal ids are ignored |
scope | "viewport" | "chromosome" | "all" | no | "viewport" | |
regions | string[] | no | chr:start-end strings; when given, they override scope. Unparseable entries are dropped; if none parse: "No parseable regions were provided." |
Returns: scopeApplied, loci and, per signal track, the same stats as the viewport summary, computed over all loci together.
Citation: a genome-computation record holding the result JSON (up to 1,800 characters).
Limits: 5 Mb total across all loci.
genome_call_peaks
Calls exploratory threshold peaks on one signal track, writes them as a BED file and adds that file as a track.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
trackId | string | yes | Must be a signal track | |
scope | "viewport" | "chromosome" | "all" | no | "viewport" | |
method | "zscore" | "threshold" | no | "zscore" | |
threshold | number | no | 2 (zscore) or the mean (threshold) | For zscore, the number of standard deviations k; for threshold, an absolute signal value |
minWidth | number | no | 1 | Minimum merged interval width in bp; rounded, at least 1 |
Returns: method, threshold (the absolute cutoff actually used), minWidth, methodNote ("Simple z-score threshold caller over fetched intervals; not a model-based peak caller." or the absolute-threshold equivalent), peakCount, trackId of the new BED track, resultUrl, resultFileName, scopeApplied.
Output file: genome/results/peaks-<trackId>-<8 characters>.bed with columns chr, start, end, peak_<i>, score (maximum merged score, 4 decimals). The new track is named "<source track name> peaks".
Citation: a genome-computation record with the result JSON; its Open source link opens the BED file.
Limits: no control track, p-value, FDR or blacklist filtering. Only overlapping or touching intervals merge, so one enriched region is usually reported as several intervals: peak counts are fragment counts. The added BED track does not currently render in the browser (a known defect); the file itself is complete and can be used as a feature track by genome_quantify_at_features. 5 Mb limit.
genome_quantify_at_features
Summarizes a signal track over each feature of an interval track, ranks the features and writes a TSV.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
signalTrackId | string | yes | Must be a signal track | |
featureTrackId | string | yes | Must be an interval track, for example a peak BED from genome_call_peaks | |
scope | "viewport" | "chromosome" | "all" | no | "viewport" | |
metric | "mean" | "sum" | "max" | no | "mean" | Mean and sum are overlap-weighted |
topN | number | no | 20 | Rows returned inline; clamped to 1–100 |
Returns: metric, rowCount, resultUrl, resultFileName, topRows (rank, chr, start, end, name, feature score, value).
Output file: genome/results/quantify-<signal>-at-<feature>-<8 characters>.tsv with header rank chr start end name featureScore <metric>, all features ranked. The TSV is not added as a track.
Citation: a genome-computation record; Open source opens the TSV.
Limits: built-in gene annotation tracks (refGene, GENCODE, MANE) are not interval tracks and are rejected. 5 Mb limit.
genome_correlate_tracks
Computes a binned Pearson correlation between two signal tracks.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
trackIdA | string | yes | Signal track | |
trackIdB | string | yes | Signal track | |
scope | "viewport" | "chromosome" | "all" | no | "viewport" | |
binSize | number | no | max(100, ceil(scope length / 500)) | Bin width in bp; rounded, at least 1 |
Returns: trackIdA, trackIdB, r (null if either track has no variance across bins), nBins, binSize, scopeApplied.
Citation: a genome-computation record with the result JSON.
Limits: no check of assay type or normalization, no significance test, and r depends on the bin size. See Measurements. 5 Mb limit.
Public data
public_data_search
Searches the ENCODE portal for released files and returns ranked candidates that can be loaded with genome_add_track.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
assay | string | no | ENCODE assay title, for example "Histone ChIP-seq", "ATAC-seq", "DNase-seq" | |
target | string | no | Target label, for example "H3K27ac", "CTCF" | |
biosample | string | no | Biosample term, for example "K562"; relaxations may match organ or cell slims | |
organism | string | no | Homo sapiens | Scientific name |
assembly | string | no | from the project genome | hg38 maps to GRCh38 and hg19 to hg19 regardless of this field |
fileType | string | no | bigWig | File format |
freeText | string | no | Passed to the portal as a free-text search term | |
limit | number | no | 10 | Candidates returned; clamped to 1–25 |
Returns: source ("ENCODE"), the normalized query, total (number of candidates returned), relaxations, attempts (every portal query with its URL and counts), and candidates, each with rank, title, sourceUrl, track type, portalUrl, file accession, experiment accession, assay, target, biosample, assembly, file type, output type, biological replicates, match mode and its own citationToken.
Citation: one public-data-search record for the search (query, total, relaxations) and one public-data-file record per candidate (accession, experiment, assay, target, biosample, assembly, output type; Open source opens the ENCODE file page).
Limits: ENCODE only; 12-second timeout per portal request; results depend on the live portal. See Public data search for the two-stage query, the relaxations and the scoring.
Project assets and plans
project_list_assets
Parameters: none.
Returns: the project's asset catalog: each asset's id, kind, title, description, file path or URL, browser URL and its own citationToken, plus a top-level citationToken for claims about the catalog as a whole.
Citation: one asset-catalog record (the asset count and up to 20 title and location lines) and one asset or remote-source record per asset.
project_read_asset
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
assetId | string | yes | Imported asset id |
Returns: the asset's metadata and, for uploaded text files (for example BED, CSV, TSV, JSON, Markdown, VCF), a preview of the first 40 lines of the first 48 KiB.
Citation: an asset record (uploaded file) or remote-source record (URL asset). For a text preview, the excerpt is the preview and the record carries the line range; otherwise the excerpt is the asset's description or location.
project_update_asset_source
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
assetId | string | yes | Existing asset id | |
kind | string | no | One of the seven asset kinds | |
title | string | no | ||
description | string | no | ||
location | string | no | Display location or remote URL | |
sourcePath | string | no | Local path for an uploaded asset | |
replaceFromSourcePath | boolean | no | When true, replace the stored file from sourcePath |
Citation: none.
project_inspect_local_folder
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
folderPath | string | yes | Absolute or relative folder path | |
recursive | boolean | no | true | Include nested folders |
maxEntries | number | no | 400 | Clamped to 1–1000 |
Returns: files and subfolders with inferred asset kinds. Citation: none.
project_import_local_folder
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
folderPath | string | yes | Absolute or relative folder path | |
recursive | boolean | no | true | |
maxFiles | number | no | 200 | Clamped to 1–500; files beyond the cap are reported as skipped |
Returns: imported and skipped assets. Files already in the catalog are skipped. Citation: none.
project_inspect_local_path
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
path | string | yes | File or folder | |
recursive | boolean | no | true | For folders |
maxEntries | number | no | 400 | Clamped to 1–1000 |
Returns: inferred asset metadata for a file, or contained files and kinds for a folder. Citation: none.
project_import_local_path
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
path | string | yes | File or folder | |
recursive | boolean | no | true | For folders |
maxEntries | number | no | Cap on inspected entries | |
maxFiles | number | no | 200 | Cap on imported files from a folder |
skipExisting | boolean | no | true | Skip sources already in the catalog |
Returns: imported and skipped assets. Citation: none.
project_inspect_remote_source
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
url | string | yes | Absolute http(s) URL | |
maxBytes | number | no | 512 KiB | Preview bytes; clamped to 8 KiB–2 MiB |
maxLinks | number | no | 40 | Links discovered on an HTML page; clamped to 1–200 |
timeoutMs | number | no | 15,000 | Clamped to 1,000–60,000 ms |
Returns: final URL, content type and length, inferred kind, title, a text preview (first 40 lines) and discovered links. Citation: none.
project_import_remote_source
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
url | string | yes | Absolute http(s) URL | |
importDiscoveredLinks | boolean | no | true | Also import files linked from an HTML page |
maxDiscoveredLinks | number | no | 40 | Cap on discovered links |
Returns: imported and skipped assets; URLs already in the catalog are skipped. Citation: none.
project_write_asset_artifact
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
assetId | string | yes | Imported asset id | |
relativePath | string | yes | Path inside the asset's folder, for example notes/import-summary.md; must stay inside it | |
content | string | yes | UTF-8 text |
Returns: the written path and size. Citation: none.
project_read_analysis_plan
Parameters: none.
Returns: the latest Studio output saved from Analysis mode: its metadata, rendered HTML and extracted plain text. If none exists: planAvailable: false and "No Studio output has been created for this project yet."
Citation: a studio-output record holding the plan text (up to 1,800 characters).
Notes: this is the bridge from an Analysis-mode plan to Genome-mode work. It reads the most recent output of any kind. See Plans and Studio outputs.
Outputs
create_html_artifact
| Parameter | Type | Required | Default | Modes | Notes |
|---|---|---|---|---|---|
title | string | yes | both | Short title | |
html | string | yes | both | Complete HTML document; at most 750,000 bytes | |
artifactId | string | no | generated | both | Reuse to replace an earlier artifact or output |
kind | string | no | report | Analysis | report, data-table, mind-map, genome-plan, track-recommendation, infographic, slide-deck, figure-draft, hypothesis-cards, saved-view; unknown values become report |
description | string | no | Analysis | Summary shown in the Studio library | |
sourceAssetIds | string[] | no | Analysis | Assets used | |
sourceTrackIds | string[] | no | Analysis | Tracks used | |
genomeRegion | string | no | Analysis | Locus the output focuses on | |
metadata | object | no | Analysis | Extra JSON stored with the output |
Returns: the artifact's id, title and URL; in Analysis mode also the saved Studio output.
Citation: none. Tokens the agent writes into the HTML are not turned into chips there.
Notes: in Genome mode the page is stored in the chat's folder and the chat shows its title with an Open button; in Analysis mode it becomes a saved Studio output. See Plans and Studio outputs.
Unavailable custom-track tools
genome_create_custom_track, genome_update_custom_track and genome_update_builtin_track exist in the backend from the time when Genie rendered tracks with its own engine. They are not in any mode's declared tool list, so the model is not offered them, and the Genome-mode instructions say custom track authoring is unavailable. If one is called anyway, it fails with: "Custom track plugins are temporarily unavailable: the genome browser now renders with the eg3 engine, which does not yet support runtime-compiled track plugins. Use genome_add_track with a supported track type and a data file URL instead." The agent cannot author custom tracks, and no tool changes track order, height or visibility.
Runtime built-in tools (not declared by Genie)
The OpenAI Codex CLI app-server has its own built-in tools, and Genie does not disable them. Besides the declared Genie tools, the agent can therefore:
- run shell commands in the chat's working directory, with network access (shown in the chat as
$cards); - edit files (shown as file-change cards);
- use the runtime's web search (not shown as a card; recorded in the chat's runtime log);
- call MCP tools from servers in your own runtime configuration (shown as cards).
None of these produce Genie citation tokens. In the logged test sessions, the agent used built-in web search in 2 of 4 sessions and a shell curl command in one; the MYC and ALB demonstration sessions used only declared tools. The declared tool list is therefore not an enforced boundary. See Runtime, approvals and safety.