Jean — Molecular Biology & Genomics

map_reads

Read-only

Map sequencing reads (FASTQ or FASTA) or assembled contigs onto a reference and return the alignment as SAM, the file a pileup viewer, a variant caller or samtools reads next.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "reads": "<reads>"
    },
    "name": "map_reads"
  }
}

Input Schema

Name	Required	Description	Default
`k`	No	k-mer size of the minimizer seeds (`-k`). Advanced.
`w`	No	minimizer window (`-w`): one seed kept per this many consecutive k-mers. Advanced.
`depth`	No	per-base read depth of the SAM written (`samtools depth`): off; every position inside some read's span (an intron or deletion inside a read prints 0); or every position of each reference a read landed on (`-a`). Reads that are unmapped, secondary, QC-failed or duplicate are not counted. Values: none (Off), covered (Covered positions), all (Every position (-a)).	none
`mates`	No	mate-2 reads, pairing record for record with `reads`. Empty maps the reads single-end.
`reads`	Yes	the reads: FASTQ (quality kept in the SAM) or FASTA (QUAL written as `*`).
`zdrop`	No	Z-drop (`-z`): stop extending when the score falls this far below its best, which clips a read at a junction instead of forcing it through. Advanced.
`_files`	No	The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name.
`md_tag`	No	write MD tags (`--MD`); the consensus uses them to trust reads with edits nearby less.
`preset`	No	what is being mapped (`-x`): it sets every option below to minimap2's values for that data. The defaults shown are the short-read preset's; an option left unset takes the chosen preset's own value. Values: sr (Short reads), splice:sr (Short RNA-seq reads), splice (Long RNA reads, cDNA), splice:hq (Accurate long RNA reads), map-ont (Nanopore), lr:hq (Accurate long reads), map-hifi (PacBio HiFi), map-pb (PacBio CLR), map-iclr (Illumina Complete Long Reads), lr:hqae (Assembly evaluation), asm5 (Assembly, ~0.1% divergent), asm10 (Assembly, ~1% divergent), ava-pb (PacBio all-vs-all overlaps), ava-ont (Nanopore all-vs-all overlaps), asm20 (Assembly, several % divergent).	sr
`max_gap`	No	a chain stops at a gap longer than this between seeds (`-g`). In bp. Advanced.
`_subject`	No	The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several.
`gap_open`	No	gap-open penalty of the short-gap cost (`-O`, first value). Advanced.
`variants`	No	call SNVs and indels from the SAM written (`bcftools mpileup \| bcftools call -mv`): genotype, quality, allelic depths and strand counts per site, as VCF.
`bandwidth`	No	band of the chaining and alignment dynamic programming (`-r`, first value): the most the two sequences may drift against each other inside one chain. In bp. Advanced.
`consensus`	No	the sample's sequence called from the reads over the reference (`samtools consensus`); N where no call is confident. Values: off (Off), fasta (FASTA), fastq (FASTQ (with quality)), pileup (Pileup (every column)).	off
`end_bonus`	No	bonus for reaching the read's end (`--end-bonus`); higher prefers end-to-end alignment over soft-clipping. Advanced.
`reference`	No	what to map against: bases, or a FASTA with one or more records. Unset, it is the record this step runs on.
`gap_extend`	No	per-base extension of the short-gap cost (`-E`, first value). Advanced.
`max_intron`	No	longest intron an alignment may span (`-G`); it also sets the reference gap and both chaining bands, as minimap2 does. In bp. Only applies when preset is splice or splice:hq or splice:sr. Advanced.
`markdup_tag`	No	tag each duplicate with the name of the read it copies (`do:Z`, `-t`). Only applies when mark_duplicates is true.
`match_score`	No	score per matching base (`-A`). Advanced.
`markdup_mode`	No	what makes two reads duplicates (`-m`): the template's two outer ends (samtools' default, as Picard), or each read's start by strand. Values: t (Template ends), s (Read starts). Only applies when mark_duplicates is true.	t
`min_dp_score`	No	lowest peak alignment score kept (`-s`).
`variants_baq`	No	recalibrate base qualities by their alignment uncertainty near indels (BAQ, bcftools' default; off is `-B`). Only applies when variants is true.
`gap_open_long`	No	gap-open penalty of the long-gap cost (`-O`, second value); a gap costs the cheaper of the two. Advanced.
`max_secondary`	No	most secondary placements kept per read (`-N`).
`output_format`	No	SAM (`-a`, every read with its alignment) or PAF (minimap2's default: one line per hit, no read sequence). Unset: PAF for the all-vs-all presets, SAM otherwise. Values: sam (SAM), paf (PAF).
`variants_args`	No	further `bcftools mpileup` options (`--max-BQ`, `--delta-BQ`, `--ff`, `-M`, `-E`). Only applies when variants is true.
`bandwidth_long`	No	wider band for the long join (`-r`, second value): when the best chain leaves much of a long read unexplained, its seeds are re-chained in this band. No effect under the short-read preset. In bp. Advanced.
`base_alignment`	No	in PAF, align base by base (`-c`): exact ends, CIGAR as `cg:Z`, NM. Off, a hit's coordinates are its chain's ends, which is much faster. SAM always aligns. Only applies when output_format is paf.
`consensus_args`	No	further `samtools consensus` options, applied last (e.g. `--min-MQ 20 -t :hiseq`); all but files and threads. Only applies when consensus is fasta or fastq or pileup.
`consensus_mode`	No	how a column is called (`-m`). Values: bayesian (Bayesian), bayesian_p (Bayesian, precise), bayesian_m (Bayesian, blended), bayesian_116 (Bayesian (samtools 1.16)), simple (Simple counting). Only applies when consensus is fasta or fastq or pileup.	bayesian
`markdup_remove`	No	remove the duplicates from the SAM instead of flagging them (`-r`). Only applies when mark_duplicates is true.
`min_minimizers`	No	fewest seeds a chain may have (`-n`). Advanced.
`variants_prior`	No	the mutation-rate prior (`call -P`): higher calls more sites. Only applies when variants is true.
`gap_extend_long`	No	per-base extension of the long-gap cost (`-E`, second value). Advanced.
`mark_duplicates`	No	mark PCR and optical duplicates (`samtools fixmate -m`, `sort`, `markdup`): reads whose 5′ ends, strands and mate position match are copies of one fragment; the best by base quality is kept and the rest flagged 0x400. The SAM comes back sorted by coordinate, and flagstat, coverage and depth then count the flags.
`min_chain_score`	No	lowest chaining score kept (`-m`), roughly the number of matching bases the seeds cover.
`secondary_ratio`	No	a secondary placement is kept when its score is at least this fraction of the primary's (`-p`).
`variants_indels`	No	call indels too, with bcftools' default indel model (off is `-I`, SNVs only). Only applies when variants is true.
`write_secondary`	No	also write secondary records to the SAM (`--secondary=yes`); off, they are counted but not written, as minimap2 does for short reads.
`zdrop_inversion`	No	Z-drop at which a stalled long alignment is tested for an inversion (`-z`, second value); an inverted segment found there is written as its own record. Advanced.
`consensus_region`	No	one region (`-r`): name or name:start-end, 1-based. Only applies when consensus is fasta or fastq or pileup.
`mismatch_penalty`	No	penalty per mismatch (`-B`). Advanced.
`consensus_profile`	No	a platform's quality calibration and tuned parameters (`-X`). Values: none (None), hiseq (Illumina HiSeq), hifi (PacBio HiFi), r10.4_sup (Nanopore R10.4 simplex (sup)), r10.4_dup (Nanopore R10.4 duplex), ultima (Ultima Genomics). Only applies when consensus is fasta or fastq or pileup.	none
`variants_full_baq`	No	run BAQ on every read at a column with an indel, not only the reads it is likely to change (`-D`; nothing with BAQ off). Only applies when variants is true.
`variants_gap_open`	No	phred-scaled probability that sequencing opens a gap (`-o`); lower calls more indels. Only applies when variants is true.
`transition_penalty`	No	penalty for a transition (A↔G, C↔T) mismatch (`-b`); 0 scores it as any mismatch. Illumina Complete Long Reads use 4. Advanced.
`variants_adjust_mq`	No	cap the mapping quality of reads with many high-quality mismatches (`-C`; 50 for BWA reads, 0 is off, values up to 10 do nothing). Only applies when variants is true.
`variants_max_depth`	No	most reads piled up per position (`-d`); at most 255, where bcftools starts downsampling at random. Only applies when variants is true.
`consensus_ambiguity`	No	a heterozygous call as its IUPAC code (`-A`). Only applies when consensus is fasta or fastq or pileup.
`consensus_min_depth`	No	fewer usable reads than this is N (`-d`). Only applies when consensus is fasta or fastq or pileup.
`consensus_positions`	No	which positions are written. Values: covered (Covered span), reference (Whole reference (-a)), all (Every reference (-aa)). Only applies when consensus is fasta or fastq or pileup.	covered
`max_fragment_length`	No	longest fragment (insert) two mates may span and still pair (`--frag`/`-I`). In bp. Only applies when mates is set.
`max_seed_occurrence`	No	seeds occurring more often than this in the reference are skipped (`-f`); the query length they cover is what `rep_len` reports, and it lowers MAPQ. Advanced.
`variants_gap_extend`	No	phred-scaled probability that sequencing extends a gap (`-e`). Only applies when variants is true.
`variants_indel_bias`	No	raise to favour indel recall over precision (`--indel-bias`). Only applies when variants is true.
`variants_indel_size`	No	approximate largest indel considered, in bases (`--indel-size`, at least 20). Only applies when variants is true.
`noncanonical_penalty`	No	cost of a splice site that is not GT..AG, GC..AG or AT..AC (`-C`). Only the splice presets align across introns. Only applies when preset is splice or splice:hq or splice:sr. Advanced.
`variants_homopolymer`	No	how strongly a homopolymer run lowers an indel's quality (`-h`); lower trusts indels in runs less. Only applies when variants is true.
`depth_count_deletions`	No	count a read's deletions toward the depth under them (`-J`); off, a deleted base is not covered by that read. Only applies when depth is covered or all.
`depth_min_read_length`	No	a read with fewer aligned bases than this (soft clips excluded) does not count (`-l`). In bp. Only applies when depth is covered or all.
`depth_remove_overlaps`	No	count the overlap of a read pair once (`-s`): the second mate starts counting where the first ended. Only applies when depth is covered or all.
`markdup_supplementary`	No	also flag the supplementary, secondary and unmapped records of a duplicate (`-S`). Only applies when mark_duplicates is true.
`depth_min_base_quality`	No	a base below this quality does not count (`-q`). Only applies when depth is covered or all.
`homopolymer_compressed`	No	seed on homopolymer-compressed sequence (`-H`), so runs of one base count once: the PacBio CLR preset's answer to its length errors in homopolymers. Advanced.
`variants_count_orphans`	No	keep reads paired but not properly paired (`-A`). Only applies when variants is true.
`variants_keep_reference`	No	also write the positions where the reads agree with the reference (`call -m` without `-v`): one record per covered position, variant or not. Only applies when variants is true.
`consensus_fill_reference`	No	the reference's base where no read gives one (`-T`), instead of N. Only applies when consensus is fasta or fastq or pileup.
`consensus_show_deletions`	No	write a deletion as `*` (`--show-del`). Only applies when consensus is fasta or fastq or pileup.
`markdup_optical_distance`	No	also call a duplicate optical when its Illumina tile x/y lies within this many pixels of the original's (`-d`); 0 is off. Illumina suggests 100 for unpatterned flow cells and 2,500 for patterned ones. In px. Only applies when mark_duplicates is true.
`variants_max_indel_depth`	No	positions this deep or deeper get no indel call (`-L`). Only applies when variants is true.
`variants_min_indel_reads`	No	fewest reads carrying an indel for it to be considered (`-m`). Only applies when variants is true.
`consensus_show_insertions`	No	write inserted bases (`--show-ins`). Only applies when consensus is fasta or fastq or pileup.
`depth_min_mapping_quality`	No	a read below this mapping quality does not count (`-Q`). Only applies when depth is covered or all.
`variants_min_base_quality`	No	skip bases below this quality (`-Q`). Only applies when variants is true.
`variants_min_indel_fraction`	No	smallest fraction of reads carrying an indel for it to be considered (`-F`). Only applies when variants is true.
`variants_overlap_adjustment`	No	where two mates overlap, count the shared bases once by zeroing one mate's qualities (off is `-x`). Only applies when variants is true.
`variants_min_mapping_quality`	No	skip reads below this mapping quality (`-q`). Only applies when variants is true.

Output Schema

Name	Required	Description
`paf`	Yes	the hits as PAF, as minimap2 writes it by default (empty when the output is SAM); for the all-vs-all presets, every overlap between two reads
`sam`	Yes	the alignment as SAM text (header + records), as `minimap2 -ax <preset>` writes it. Open it in the pileup, or hand it to a variant caller
`vcf`	Yes	SNVs called from the SAM written, as `bcftools call -mv` writes the VCF (GT, PL, AD; DP, DP4, MQ and the bias tests per site). Empty unless `variants` is on. Open it in the variant viewer
`calls`	Yes	each call: contig, position, reference and alternate alleles, QUAL, genotype, depth, DP4, allelic depths, PL and mean mapping quality. Empty unless `variants` is on
`depth`	Yes	`samtools depth` of the SAM written, as samtools prints it (reference, 1-based position, depth; one line per position). Empty unless `depth` asks for it
`mapq0`	Yes	mapped reads with MAPQ 0: placed, but with an equally good placement elsewhere
`stats`	Yes	every count: reads, fragments, mapped, unmapped, MAPQ bins, proper pairs, supplementary and secondary placements, reads spanning an intron, and per reference its reads and covered bases
`mapped`	Yes	reads with a primary placement
`markdup`	Yes	`samtools markdup`'s statistics when duplicates were marked: reads examined, pairs and singles, duplicate pairs and singles, optical duplicates, and the estimated library size. Empty otherwise
`options`	Yes	every minimap2 option the run used, with its flag, the preset value, and whether it was changed
`reading`	Yes	what the run found, generated from its counts: the conclusion, then each qualifier the run earned
`coverage`	Yes	`samtools coverage` of the SAM written: per reference its reads, covered bases, percent covered, mean depth, mean base quality and mean mapping quality (reads that are unmapped, secondary, QC-failed or duplicate excluded, as samtools does). Null for PAF output, which writes no SAM to summarize
`flagstat`	Yes	`samtools flagstat` of the SAM written, as samtools prints it (QC-passed + QC-failed: total, primary, secondary, supplementary, duplicates, mapped, paired, properly paired, singletons, mates on another reference). Empty for PAF. Null for PAF output, which writes no SAM to summarize
`unmapped`	Yes	reads with none
`consensus`	Yes	`samtools consensus` of the SAM written, as samtools prints it (FASTA, FASTQ or pileup). Empty unless `consensus` asks for it
`junctions`	Yes	splice junctions as `minimap2 --write-junc` writes them (BED-like: reference, start, end, read, motif score, strand; one line per intron per read, primary alignments of MAPQ 10 or more). Empty outside the splice presets
`meanIdentity`	Yes	mean identity of primary alignments, matching bases over aligned columns (0–1). Null when no read aligned, so there is nothing to measure: a 0 would read as every base mismatched
`junctionTable`	Yes	each distinct junction once: reference, start, end, strand, motif score (6 = GT..AG) and the number of reads that support it
`properlyPaired`	Yes	reads in a proper pair (0 when mapped single-end)
`variantSummary`	Yes	the calls counted: SNVs, indels, homozygous and heterozygous, transitions and transversions among the SNVs, covered positions, and the bcftools command used
`consensusSummary`	Yes	the consensus counted: sequences, bases, N (no call), IUPAC ambiguity codes, lower-case and deletion calls, mean quality, and the samtools arguments used

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 20, 2026

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the description's job is lighter. What it does add is genuinely useful: the return artifact and why it matters downstream. What it omits is substantial for a 79-parameter wrapper: that the same call can silently produce VCF variant calls, a consensus FASTA/FASTQ, or a depth track, and that mark_duplicates re-sorts the SAM.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that moves from inputs to output to downstream use with no filler. It is well built but thin for the surface area it fronts, which is penalised under contextual completeness rather than here.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 79-parameter tool that bundles minimap2 alignment, duplicate marking, depth, consensus calling and bcftools variant calling, one sentence is not enough. The presence of an output schema excuses it from describing return values, but nothing tells the agent that enabling variants or consensus changes the nature of the result entirely, which is the main way to misuse this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and every parameter including the 8 enums carries its own detailed prose, so the schema does all of the semantic work. The description adds no parameter-level meaning beyond paraphrasing the FASTQ/FASTA distinction that the reads field already states. Baseline 3 is correct here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource chain: map FASTQ/FASTA reads or contigs onto a reference and return SAM. That is far more concrete than the name alone, but it never distinguishes this from close siblings such as align_read, align_sequences or compare_reads_to_reference, and it understates the output by naming only SAM when output_format also allows PAF and the variants/consensus options emit VCF and FASTA.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names downstream consumers (pileup viewer, variant caller, samtools) but gives no when-to-use guidance, no exclusions, and no pointer to the sibling aligners an agent must choose between. The one implicit cue, that this is the tool to reach for when you need a SAM, is the only routing signal present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Jean — Molecular Biology & Genomics tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?