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. Each registered test then runs once over the corpus, every answering result is attached as a κ-calibrated e-value (evidence from another test, a changed parameter or the same data twice is refused and reported), and e-BH decides over all hypotheses, those without evidence included. Returns the verdicts, the whole ledger as a file that imports into Discovery Expert, every run's input, the refusals, and the literature query each supported hypothesis needs before it may be called new. Pass a previous ledger with posterior beliefs to get the follow-up order by Bayesian surprise, which ranks what to test next and never changes a verdict. Also returns the whole program as a sealed run file (every corpus input pinned by SHA-256, the last attempt at each hypothesis); pass it back as run to add hypotheses and retry the ones whose test failed, or to research_run_status and resume_research_run. Evidence that read one source (one table, or one sequence under two names) is averaged, not multiplied, and each verdict names the rule.

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.
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
    • 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)."
  2. 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"
  3. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the read-only and non-destructive annotations, the description discloses substantial behavior: hypotheses are registered before tests run, each registered test runs once, duplicate or changed-evidence attempts are refused, e-values are κ-calibrated, e-BH decides over all hypotheses, and supported hypotheses require a literature query before being called new. It also explains run-file sealing with SHA-256-pinned inputs, retry behavior, and how evidence from the same source is averaged rather than multiplied.

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?

The description is long but front-loaded with the core purpose, and its length is justified by the many supported test types and continuation modes. The structure is dense and relies on long parenthetical enumeration, but it remains logically ordered from purpose to execution, returns, continuation, and evidence rules. Some tightening and clearer paragraph structure would improve readability.

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

Completeness5/5

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

Given the tool's complexity, 11 parameters, nested schemas, annotations, and an output schema, the description is complete enough for correct invocation. It covers the programme semantics, test-specific hypothesis requirements, continuation behavior, budget/deferral behavior, and the nature of returned artifacts. Nothing critical an agent needs to call this correctly appears missing.

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

Parameters5/5

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

Although schema coverage is already 100%, the description adds meaningful semantics beyond the schema by explaining the hypothesis object structure and test-specific parameters for each discover_* and analysis type. It also clarifies how `run`, `ledger`, `posterior_beliefs`, `budget_seconds`, `sequences`, and `organism` affect orchestration and continuation. This materially helps an agent construct valid nested hypotheses rather than relying on the schema alone.

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

Purpose5/5

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

The description opens with a clear verb and resource: run a discovery programme end to end under pre-registration. It specifically distinguishes this orchestrator from sibling single-test tools by explaining that hypotheses name their tests, are registered in a ledger, and are judged together by e-BH. An agent can tell this is the multi-hypothesis programme runner, not one of the individual discover_* tools.

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

Usage Guidelines4/5

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

Usage context is clear: this tool is for running a pre-registered discovery programme over a corpus, with ledger and optional run-file continuation. It explicitly names alternatives for continuation, research_run_status and resume_research_run, and explains when to pass a previous ledger for Bayesian-surprise follow-up ordering. It does not explicitly state when not to use this versus calling individual test tools, but the multi-hypothesis/e-BH framing implies that distinction well.

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