analytical-grounding

name	analytical-grounding
description	Retrieve canonical pathway members, cell-type marker records, and genomic interval feature overlaps from declared analytical sources.
tools	["pathway.retrieve_members","cell_type.retrieve_markers","region.retrieve_features"]
mutating	false

Analytical Grounding

Use this skill for source-declared records that ground an analytical statement, without asking Genomi to choose the interpretation.

Use When

• The input is a controlled pathway or gene-set name/id and the agent needs its canonical member genes.
• The input is a controlled cell type and the agent needs marker-gene records.
• The input is a genomic interval and the agent needs overlaps against declared GENCODE or ENCODE annotation files.

Operations

• pathway.retrieve_members: retrieve Reactome, KEGG human pathway, or supplied or installed MSigDB Hallmark GMT member genes. Use a source for free-text pathway names unless the identifier prefix makes the source clear.
• cell_type.retrieve_markers: retrieve HPA single-cell marker records, installed CellMarker/PanglaoDB tables, or supplied marker tables.
• region.retrieve_features: retrieve interval overlaps from supplied or installed GENCODE GTF and/or ENCODE cCRE BED files for GRCh37/GRCh38. Supply assembly; without it the tool reports unsupported assembly instead of guessing a genome build.

Boundaries

• These are retrieval verbs over declared source coverage.
• Do not use them as experimental protocol recommendations, workflow templates, or free-text biological interpretation.
• Treat coverage_status literally:
  • data_returned: declared source records were returned.
  • in_scope_empty: the input was in declared scope, and no records matched.
  • out_of_scope_for_input: the source, assembly, identifier, or required source file is outside declared coverage.
• Preserve source priors. A pathway member, marker gene, interval overlap, or druggable-target membership row is evidence context, not a selected answer.

Examples

• pathway.retrieve_members with {"pathway_id_or_name":"R-HSA-70635"}
• pathway.retrieve_members with {"pathway_id_or_name":"hsa00010"}
• cell_type.retrieve_markers with {"cell_type_id_or_name":"hepatocytes","source":"hpa"}
• cell_type.retrieve_markers with {"cell_type_id_or_name":"Hepatocyte","source":"cellmarker"}
• region.retrieve_features with {"region":"1:1000-1250","assembly":"GRCh38"}

The installer can cache gencode-grch38, gencode-grch37, encode-ccre-grch38, panglaodb-markers, and cellmarker-human under GENOMI_HOME. MSigDB Hallmark requires a user-supplied official GMT export.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

cell_type.retrieve_markers

Retrieve canonical marker genes for a controlled cell-type source entity.

Use when: Returns source-declared marker genes for HPA single-cell records or supplied CellMarker, PanglaoDB, or ENCODE marker tables.

Why necessary: Cell-type identity questions need marker records, not disease genetics or GWAS evidence.

Result semantics: Returns marker records only; it does not annotate clusters, assign cell identities, rank cell types, or interpret cell states. Free-text cluster IDs and hypothetical cell-state labels are out of scope.

pathway.retrieve_members

Retrieve canonical member genes for a controlled pathway or gene-set source entity.

Use when: Returns source-declared member genes for Reactome pathways, KEGG human pathways, or supplied MSigDB Hallmark GMT gene sets.

Why necessary: Pathway membership is a grounding fact and should be retrieved separately from disease or variant claims.

Result semantics: Returns pathway membership records only; it does not infer pathway activity, choose genes, or summarize pathway biology. Free-text pathway names should include source unless the identifier prefix implies a declared source.

region.retrieve_features

Retrieve genomic-region feature annotations from supplied or installed GENCODE and ENCODE annotation files.

Use when: The user or an upstream tool supplies a genomic interval and the agent needs transcript or regulatory-feature overlaps for an explicit GRCh37 or GRCh38 assembly.

Why necessary: Genomic coordinates need gene and regulatory feature context before they can be biologically discussed.

Result semantics: Returns source-declared interval overlaps for the assembly shown in query. Empty results mean no overlap in declared files, not biological absence outside declared coverage.