Jean — Molecular Biology & Genomics

read_variant_calls

Read-only

Read a variant call set (VCF, bgzipped VCF or BCF) in this project and return the records matching a query: a locus, a variant class, a QUAL floor, PASS-only, a sample that is not hom-ref, or an INFO key.

Input Schema

Name	Required	Description
`end`	No	last base of the region, 1-based and inclusive. Needs `contig`. Unset is the contig's last record.
`file`	No	which call set in this project, by name. Unset, it is the project's only one, and it refuses rather than guessing when there is more than one.
`limit`	No	how many matching records to return. The COUNT is always the full number of matches: this caps the rows, never the accounting.
`start`	No	first base of the region, 1-based and inclusive, as VCF itself counts. Needs `contig`. Unset is the contig's first record.
`types`	No	keep only these variant classes. The classes are htslib's own, assigned by the ported `setVariantType` and identical to the ones the panel's type filter offers. Unset keeps every class.
`_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.
`contig`	No	restrict to one contig, named as the FILE names it: `20` and `chr20` are different names and neither is normalized into the other. With `start`/`end` this is a locus read; alone it is the whole contig.
`sample`	No	keep only records where this sample's genotype is neither hom-ref nor missing, which is that sample's own variants out of a cohort. Named as the file's header names it.
`_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.
`info_key`	No	keep only records carrying this INFO key; with `info_value`, only those where it equals that value.
`min_qual`	No	keep only records whose QUAL is at least this. A record stating no QUAL (`.`) is DROPPED unless `include_missing_qual` is on, because a missing score is not a passing one.
`pass_only`	No	keep only records whose FILTER is PASS or unset (`.`): the usual first question of a call set, and the one filter that changes what most downstream steps should see.
`info_value`	No	with `info_key`, the value that key must equal.
`include_missing_qual`	No	keep records that state no QUAL when `min_qual` is set. Off by default: a caller asking for a quality floor is asking about scores, and a record with none has not met it.

Output Schema

Name	Required	Description
`read`	Yes	how many records were read before filtering. For a locus read this is the records in that window, NOT the file (`scope` says which)
`scope`	Yes	whether the numbers describe the whole file or one region, and (when the file was too large to read whole) that its header alone was opened. A count read from a window must never be readable as the file's
`matched`	Yes	how many records matched: the full count, not the number of rows returned
`samples`	Yes	the call set's sample names in header order, empty for a sites-only VCF, which is a fact about the file rather than a failure
`summary`	Yes	what was read and what matched, in one sentence generated from this run
`variants`	Yes	the matching records, up to `limit`: chrom, pos (1-based), ids, ref, alts, qual, filters, end and the record's own htslib class label. Genotypes are not included: `sample` filters on them and `variant_call_summary` counts them, and a cohort record would otherwise carry thousands of columns per row
`filters_applied`	Yes	every filter this run actually applied, with its value. A caller comparing two runs needs to know which asked the narrower question

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 20, 2026

TDQS

A3.5/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 elsewhere. The description adds that the read is project-scoped and returns matching records, but says nothing about result size, ordering, pagination, or what happens when no filter is supplied — all left to the schema.

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 with the resource and formats first, then the filter axes. Dense but every clause maps to a real capability; the parenthetical format list and trailing filter enumeration are the only mildly heavy elements.

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

Completeness4/5

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

With 14 parameters, nested _subject/_files objects, a 100%-covered schema and an output schema, the description's job is mainly to orient. It does that well by naming formats and query axes; the only shortfall is not signaling the default-capped row limit or the file-selection refusal, both of which the schema covers.

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%, so the schema already carries detailed parameter meaning (QUAL dropping behavior, contig naming, limit vs. COUNT). The description's enumeration of query axes is a useful conceptual index but adds no semantics beyond the documented fields, so the baseline of 3 applies.

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 opens with a specific verb and resource ('Read a variant call set') and enumerates the supported formats (VCF, bgzipped VCF, BCF) plus the query axes. It is clearly distinct from aggregate siblings such as variant_call_summary or variant_consequences, though it never names an alternative to route against.

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

Usage Guidelines3/5

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

The listing of query dimensions ('a locus, a variant class, a QUAL floor, PASS-only, a sample...') implicitly tells an agent what this tool is for. However, there is no explicit when-to-use or when-not guidance, and no pointer to alternatives like variant_call_summary for aggregates or variant_consequences for annotation.

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?