Skip to main content
Glama

run_discovery_programme

Read-only

Run a discovery program end to end under pre-registration: every hypothesis names its test (discover_site_avoidance: a site, optionally a record, and its null; discover_codon_outliers: a gene and its genetic code; validate_gene_trait: a human gene, the trait's own gene or tissues, and GWAS Catalog categories; discover_flag_rates: a cryptic-element flag, optionally a record, against k-let shuffles; discover_tree_incongruence: a locus of a multi-locus alignment, by the ILD test; discover_gene_tree_discordance: a gene alignment against a species tree, by the SH test; discover_reference_stability: a candidate reference gene against its GTEx abundance peers; discover_annotation_contradictions: a UniProt signal peptide or transmembrane segment against the experimentally confirmed ones; discover_reference_concordance: a Cq table whose conditions should rank its reference genes alike; differential_expression: a gene of a DESeq2 fit, up or down in the contrast; gene_set_overrepresentation: a gene set holding more of a gene list than chance; gene_set_enrichment: a gene set toward the top or bottom of a ranked list by GSEA) and direction, and all are registered in a hypothesis ledger before any test runs.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "run_discovery_programme"
  }
}

Input Schema

NameRequiredDescriptionDefault
runNoa run file from an earlier call, to continue it: its seal and its pinned inputs are checked, hypotheses whose test failed or was deferred are retried, new ones are added, and nothing answered is run again.
alphaNoe-BH level the verdicts are decided at, across every hypothesis in the ledger.
kappaNoκ of the p-to-e calibrator e = κ·p^(κ−1); fixed for a ledger once it holds evidence. Advanced.
_filesNoThe 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.
ledgerNoa ledger file from an earlier run, to continue: its hypotheses keep their evidence and new ones are added beside them.
_subjectNoThe 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.
organismNothe organism the corpus is from, for the literature query each supported hypothesis needs. Advanced.
sequencesNothe corpus every registered test runs over: library document or file names, or wired records.
hypothesesNoeach {statement, test, params, direction, prior_belief?}. test: discover_site_avoidance (params site, record?, null_model, shuffle_k/shuffles/seed under the shuffle null; direction less, greater or two-sided) or discover_codon_outliers (params gene as its library name, genetic_code, alt_init?, min_codons?; direction two-sided) or validate_gene_trait (params gene as its HGNC symbol, expression_test coexpression with trait_genes or tissue with tissues, categories as GWAS Catalog parent categories, alpha?; direction greater; needs no corpus) or discover_flag_rates (params flag as one of sigma70-strongest, splice-donor, splice-acceptor, homopolymer, tandem-repeat, long-repeat, inverted-repeat, record?, shuffle_k/shuffles/seed; direction greater, meaning beyond chance in the flag's own tail) or discover_tree_incongruence (params locus as its alignment file's name, permutations/seed; direction greater; the corpus is one aligned FASTA per locus) or discover_gene_tree_discordance (params gene as its alignment file's name, species_tree in Newick, replicates/sh_form/gamma_categories/seed; direction greater, meaning the gene fits another tree better; the corpus is one aligned FASTA per gene) or discover_reference_stability (params gene as its HGNC symbol, tissues?, neighbours?, pseudocount?; direction greater for more variable than its abundance peers, less for steadier, or two-sided; needs no corpus) or discover_annotation_contradictions (params annotation as a UniProt accession, or accession:start-end where the protein has several, feature signal or transmembrane, predictor for signal, decoding for transmembrane; direction less, meaning it scores below the experimentally confirmed features; needs no corpus) or discover_reference_concordance (params cq_table as the long-format Target,Sample,Group,Cq table itself, permutations/seed; direction greater, meaning the conditions rank the genes more alike than independent orders; needs no corpus) or differential_expression (params gene as its count-table ID, symbol? as papers name it for the literature query, counts and samples as the tables themselves, and design/reference/test/reduced/contrast/name/fitType/sfType/lfcThreshold/altHypothesis/cooksFilter/cooksCutoff/minReplicatesForReplace as the tool takes them; direction greater for higher in the contrast's numerator, less for lower, or two-sided; one-sided needs the Wald test at lfcThreshold 0; needs no corpus) or gene_set_overrepresentation (params set as its GMT ID, genes, geneSets as GMT text, universe?, forceUniverse?, minGSSize?, maxGSSize?; direction greater; needs no corpus) or gene_set_enrichment (params set as its GMT ID, ranked as 'gene statistic' lines, geneSets as GMT text, minGSSize/maxGSSize/exponent/scoreType/eps/sampleSize/nPermSimple/seed; direction greater for toward the top of the list, less for the bottom, or two-sided; needs no corpus). prior_belief: the proposer's belief before any result, one sample or a list of them (true, false, definitely true, maybe true, uncertain, maybe false, definitely false, cannot comment).
budget_secondsNoseconds this call may spend running tests: whole tests run until the budget is spent and the rest are deferred, so a long program returns before a client's timeout and resume_research_run continues it. A test is never cut short and at least one runs per call. Unset: every test runs in this call. In s. Advanced.
check_literatureNorun each supported hypothesis's literature query against Europe PMC and record what came back in the ledger: papers to read (candidates) or none (not found). Never records a hypothesis as known; confirm_literature_hit does that for a paper someone read.
posterior_beliefsNoeach {id, samples}: the proposer's belief in a hypothesis after reading its evidence. With prior beliefs these give the follow-up order by Bayesian surprise.

Output Schema

NameRequiredDescriptionDefault
runYesthe whole program as a sealed jane.research-run file: the ledger, every corpus input pinned by SHA-256, the last attempt at each hypothesis. Pass it back to continue
ledgerYesthe whole ledger as a jane.discovery-ledger file, every hypothesis and its evidence with traces
reportYesthe program as text lines: registrations, runs, refusals, verdicts, literature queries
resultYesthe full result
followUpYeshypotheses with prior and posterior beliefs, most surprising first: what to test next, never a verdict
decisionsYesevery hypothesis: verdict (supported, not-supported, no-evidence), product e-value and tests
supportedCountYeshow many hypotheses e-BH supports

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / check_literature
      Added value: +{
      +  "default": false,
      +  "description": "run each supported hypothesis's literature query against Europe PMC and record what came back in the ledger: papers to read (candidates) or none (not found). Never records a hypothesis as known; confirm_literature_hit does that for a paper someone read.",
      +  "type": "boolean"
      +}
  2. Changed1 schema field changed
    • changedInput schema / properties / hypotheses / description
      Previous value: -"each {statement, test, params, direction, prior_belief?}. test: discover_site_avoidance (params site, record?, null_model, shuffle_k/shuffles/seed under the shuffle null; direction less, greater or two-sided) or discover_codon_outliers (params gene as its library name, genetic_code, alt_init?, min_codons?; direction two-sided) or validate_gene_trait (params gene as its HGNC symbol, expression_test coexpression with trait_genes or tissue with tissues, categories as GWAS Catalog parent categories, alpha?; direction greater; needs no corpus) or discover_flag_rates (params flag as one of sigma70-strongest, splice-donor, splice-acceptor, homopolymer, tandem-repeat, long-repeat, inverted-repeat, record?, shuffle_k/shuffles/seed; direction greater, meaning beyond chance in the flag's own tail) or discover_tree_incongruence (params locus as its alignment file's name, permutations/seed; direction greater; the corpus is one aligned FASTA per locus) or discover_gene_tree_discordance (params gene as its alignment file's name, species_tree in Newick, replicates/sh_form/gamma_categories/seed; direction greater, meaning the gene fits another tree better; the corpus is one aligned FASTA per gene) or discover_reference_stability (params gene as its HGNC symbol, tissues?, neighbours?, pseudocount?; direction greater for more variable than its abundance peers, less for steadier, or two-sided; needs no corpus) or discover_annotation_contradictions (params annotation as a UniProt accession, or accession:start-end where the protein has several, feature signal or transmembrane, predictor for signal, decoding for transmembrane; direction less, meaning it scores below the experimentally confirmed features; needs no corpus) or discover_reference_concordance (params cq_table as the long-format Target,Sample,Group,Cq table itself, permutations/seed; direction greater, meaning the conditions rank the genes more alike than independent orders; needs no corpus). prior_belief: the proposer's belief before any result, one sample or a list of them (true, false, definitely true, maybe true, uncertain, maybe false, definitely false, cannot comment)."New value: +"each {statement, test, params, direction, prior_belief?}. test: discover_site_avoidance (params site, record?, null_model, shuffle_k/shuffles/seed under the shuffle null; direction less, greater or two-sided) or discover_codon_outliers (params gene as its library name, genetic_code, alt_init?, min_codons?; direction two-sided) or validate_gene_trait (params gene as its HGNC symbol, expression_test coexpression with trait_genes or tissue with tissues, categories as GWAS Catalog parent categories, alpha?; direction greater; needs no corpus) or discover_flag_rates (params flag as one of sigma70-strongest, splice-donor, splice-acceptor, homopolymer, tandem-repeat, long-repeat, inverted-repeat, record?, shuffle_k/shuffles/seed; direction greater, meaning beyond chance in the flag's own tail) or discover_tree_incongruence (params locus as its alignment file's name, permutations/seed; direction greater; the corpus is one aligned FASTA per locus) or discover_gene_tree_discordance (params gene as its alignment file's name, species_tree in Newick, replicates/sh_form/gamma_categories/seed; direction greater, meaning the gene fits another tree better; the corpus is one aligned FASTA per gene) or discover_reference_stability (params gene as its HGNC symbol, tissues?, neighbours?, pseudocount?; direction greater for more variable than its abundance peers, less for steadier, or two-sided; needs no corpus) or discover_annotation_contradictions (params annotation as a UniProt accession, or accession:start-end where the protein has several, feature signal or transmembrane, predictor for signal, decoding for transmembrane; direction less, meaning it scores below the experimentally confirmed features; needs no corpus) or discover_reference_concordance (params cq_table as the long-format Target,Sample,Group,Cq table itself, permutations/seed; direction greater, meaning the conditions rank the genes more alike than independent orders; needs no corpus) or differential_expression (params gene as its count-table ID, symbol? as papers name it for the literature query, counts and samples as the tables themselves, and design/reference/test/reduced/contrast/name/fitType/sfType/lfcThreshold/altHypothesis/cooksFilter/cooksCutoff/minReplicatesForReplace as the tool takes them; direction greater for higher in the contrast's numerator, less for lower, or two-sided; one-sided needs the Wald test at lfcThreshold 0; needs no corpus) or gene_set_overrepresentation (params set as its GMT ID, genes, geneSets as GMT text, universe?, forceUniverse?, minGSSize?, maxGSSize?; direction greater; needs no corpus) or gene_set_enrichment (params set as its GMT ID, ranked as 'gene statistic' lines, geneSets as GMT text, minGSSize/maxGSSize/exponent/scoreType/eps/sampleSize/nPermSimple/seed; direction greater for toward the top of the list, less for the bottom, or two-sided; needs no corpus). prior_belief: the proposer's belief before any result, one sample or a list of them (true, false, definitely true, maybe true, uncertain, maybe false, definitely false, cannot comment)."
  3. Changed3 schema fields changed
    • changedInput schema / properties / budget_seconds / description
      Previous value: -"seconds this call may spend running tests: whole tests run until the budget is spent and the rest are deferred, so a long programme returns before a client's timeout and resume_research_run continues it. A test is never cut short and at least one runs per call. Unset: every test runs in this call. In s. Advanced."New value: +"seconds this call may spend running tests: whole tests run until the budget is spent and the rest are deferred, so a long program returns before a client's timeout and resume_research_run continues it. A test is never cut short and at least one runs per call. Unset: every test runs in this call. In s. Advanced."
    • changedOutput schema / properties / report / description
      Previous value: -"the programme as text lines: registrations, runs, refusals, verdicts, literature queries"New value: +"the program as text lines: registrations, runs, refusals, verdicts, literature queries"
    • changedOutput schema / properties / run / description
      Previous value: -"the whole programme as a sealed jane.research-run file: the ledger, every corpus input pinned by SHA-256, the last attempt at each hypothesis. Pass it back to continue"New value: +"the whole program as a sealed jane.research-run file: the ledger, every corpus input pinned by SHA-256, the last attempt at each hypothesis. Pass it back to continue"
  4. First observed

TDQS

A3.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructive=false, so the description's added value is in process behavior: hypotheses and directions are registered in a ledger before any test executes, which tells the agent the ordering is fixed and pre-registered. It also notes that continuation of an earlier run retries only failed or deferred hypotheses and never re-runs answered ones, though that detail sits in the schema rather than the description.

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

Conciseness2/5

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

One enormous sentence whose body is a parenthetical catalogue of all thirteen tests with their parameters, duplicating the schema's hypotheses description almost verbatim. The one genuinely distinctive idea, pre-registration into a ledger before any test runs, is stranded at the very end.

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?

For a 12-parameter orchestration tool with an output schema and rich annotations, the description supplies the key conceptual frame (program-level, pre-registered, test-per-hypothesis) and the schema fills in all mechanics. What is missing is guidance on choosing among the many test types at the program level, though the schema enumerates them.

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%, including detailed per-parameter prose for run, ledger, alpha, kappa, budget_seconds, check_literature and posterior_beliefs, so the schema carries the load. The description's test/param mapping largely mirrors what the hypotheses schema property already says, adding little meaning beyond it.

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?

Opens with a specific verb and resource ("Run a discovery program end to end under pre-registration"), which distinguishes it from the individual discover_* siblings, since this one orchestrates the whole set. The purpose is clear but is then buried under a long test enumeration rather than restated crisply.

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?

Usage context is implied: this is the batch/program-level entry point ('end to end', everything registered in a ledger before any test runs), and the schema covers continuing an earlier run. It never states explicitly when to use this instead of a single-test sibling, nor any exclusion, so routing must be inferred.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources