Skip to main content
Glama

Get Gene Homologs

ensembl_get_homology
Read-onlyIdempotent

Find orthologs and/or paralogs of a gene across species. Returns each homolog's stable ID, species, homology type (ortholog_one2one, ortholog_one2many, paralog_many2many, etc.), percId and percPos (percent identical and positive positions, over the target protein's length), and taxonomy level. Essential for cross-species research — for example, "what is the mouse equivalent of human TP53?" or "how conserved is BRCA2 across mammals?". Provide either symbol + species or a stable gene ID. Target species can be filtered to a single species or left open to return all available homologs. Homologs keep Ensembl's own order, which starts with the closest relatives, and are returned max_results at a time (default 25); totalCount reports every homolog, and when more follow, nextOffset is the offset for the next page. A target_species outside the comparison Ensembl runs for the source species is answered from Ensembl's pan-taxonomic comparison when that comparison holds both species. Includes targetProteinId when available for ensembl_get_sequence with type="protein". targetSymbol is best-effort: a secondary gene lookup shares ten seconds across the returned rows and the remaining call deadline; missing names never remove homologs.

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": "ensembl_get_homology"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoEnsembl stable gene ID (e.g. ENSG00000139618). A version suffix (ENSG00000139618.17) is accepted and dropped before the query. Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol.
typeNoType of homologs to return. orthologues: genes related by speciation (cross-species equivalents). paralogues: genes related by duplication (within or across species). all: both orthologs and paralogs.orthologues
offsetNo0-based position in Ensembl's homolog order where the returned page starts. Default 0. Pass nextOffset from a previous response to fetch the following page; an offset at or past totalCount returns no homologs.
symbolNoGene symbol in the source species (e.g. BRCA2, TP53). Species defaults to homo_sapiens; set species for other organisms. Cannot be combined with id.
speciesNoSource species (the species the query gene belongs to) in Ensembl internal format. Default is homo_sapiens. Use ensembl_list_species with nameContains (a genus or common name, e.g. mouse) to find valid values.homo_sapiens
max_resultsNoMaximum number of homologs to return, counted from offset. Default 25. Broad orthology queries (e.g. BRCA2 across all species) can return 150+ homologs. Set to 0 to return every homolog from offset to the end, uncapped. totalCount always reports the full number available before offset and this cap.
target_speciesNoFilter to homologs in a single target species (e.g. mus_musculus for mouse). Omit to return homologs across all available species. Use ensembl_list_species with nameContains (a genus or common name) to find valid values.

Output Schema

NameRequiredDescriptionDefault
capNoThe max_results limit applied to this page.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of homologs returned on this page.
noticeNoGuidance when the homologs come from Ensembl's pan-taxonomic comparison, no homologs are found, the offset is past the end, more homologs follow this page, or symbol enrichment is incomplete.
queryIdNoThe resolved Ensembl gene ID used for the homology query.
homologsNoHomologous genes for the query gene, in Ensembl's order: at most max_results entries starting at offset.
queryTypeNoThe homology type queried (orthologues, paralogues, or all).
truncatedNoTrue when more homologs follow this page; request nextOffset to continue.
nextOffsetNoOffset of the first homolog after this page — pass it as offset to fetch the next page. Present only when more homologs follow.
totalCountNoTotal number of homologs available before offset and the max_results cap. Exceeds the returned homologs count when the list was paged.
querySpeciesNoThe source species used for the query.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • changedInput schema / properties / max_results / description
      Previous value: -"Maximum number of homologs to return. Broad orthology queries (e.g. BRCA2 across all species) can return 150+ homologs; the default keeps responses focused. Set to 0 to return every homolog uncapped. totalCount always reports the true number available before this cap."New value: +"Maximum number of homologs to return, counted from offset. Default 25. Broad orthology queries (e.g. BRCA2 across all species) can return 150+ homologs. Set to 0 to return every homolog from offset to the end, uncapped. totalCount always reports the full number available before offset and this cap."
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "description": "0-based position in Ensembl's homolog order where the returned page starts. Default 0. Pass nextOffset from a previous response to fetch the following page; an offset at or past totalCount returns no homologs.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / cap / description
      Previous value: -"The max_results limit applied to the homolog list."New value: +"The max_results limit applied to this page."
    • changedOutput schema / properties / homologs / description
      Previous value: -"Homologous genes found for the query gene, capped to max_results. totalCount reports the full count available before the cap."New value: +"Homologous genes for the query gene, in Ensembl's order: at most max_results entries starting at offset."
    • addedOutput schema / properties / nextOffset
      Added value: +{
      +  "description": "Offset of the first homolog after this page — pass it as offset to fetch the next page. Present only when more homologs follow.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when the homologs come from Ensembl's pan-taxonomic comparison, no homologs are found, the list was capped, or symbol enrichment is incomplete."New value: +"Guidance when the homologs come from Ensembl's pan-taxonomic comparison, no homologs are found, the offset is past the end, more homologs follow this page, or symbol enrichment is incomplete."
    • changedOutput schema / properties / shown / description
      Previous value: -"Number of homologs returned after the max_results cap."New value: +"Number of homologs returned on this page."
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Total number of homologs available before the max_results cap. Exceeds the returned homologs count when the list was capped."New value: +"Total number of homologs available before offset and the max_results cap. Exceeds the returned homologs count when the list was paged."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the homolog list was capped at max_results."New value: +"True when more homologs follow this page; request nextOffset to continue."
  2. Changed5 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The gene symbol or stable ID was not found in Ensembl for the source species. `invalid_species`: The species or target_species string was not recognized by Ensembl. `no_input`: Neither symbol nor id was provided. `conflicting_input`: Both symbol and id were provided. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The gene symbol or stable ID was not found in Ensembl for the source species. `invalid_species`: The species or target_species string was not recognized by Ensembl. `target_not_compared`: Both species are valid, but target_species is outside the comparison Ensembl runs for the source species, and Ensembl's pan-taxonomic comparison does not hold both species or its species list could not be read. `no_input`: Neither symbol nor id was provided. `conflicting_input`: Both symbol and id were provided. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "not_found",
      -  "invalid_species",
      -  "no_input",
      -  "conflicting_input"
      -]New value: +[
      +  "not_found",
      +  "invalid_species",
      +  "target_not_compared",
      +  "no_input",
      +  "conflicting_input"
      +]
    • changedOutput schema / properties / homologs / items / properties / percId / description
      Previous value: -"Percent identity between the query and target gene sequences (0-100). Higher values indicate more conserved sequences."New value: +"Percent identity over the target protein's length (0-100): identical positions divided by the target protein's length. The query-side value differs when the two proteins differ in length."
    • changedOutput schema / properties / homologs / items / properties / percPos / description
      Previous value: -"Percent positive (similar) positions in the alignment (0-100). Includes conservative substitutions as well as identical residues."New value: +"Percent positive positions over the target protein's length (0-100): identical residues plus conservative substitutions, divided by the target protein's length."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no homologs are found, the list was capped, or symbol enrichment is incomplete."New value: +"Guidance when the homologs come from Ensembl's pan-taxonomic comparison, no homologs are found, the list was capped, or symbol enrichment is incomplete."
  3. Changed3 schema fields changed
    • addedOutput schema / properties / homologs / items / properties / targetProteinId
      Added value: +{
      +  "description": "Target translation stable ID. Pass to ensembl_get_sequence with type=\"protein\".",
      +  "type": "string"
      +}
    • addedOutput schema / properties / homologs / items / properties / targetSymbol
      Added value: +{
      +  "description": "Target gene display name, when a bounded secondary lookup resolves it.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no homologs are found or the list was capped."New value: +"Guidance when no homologs are found, the list was capped, or symbol enrichment is incomplete."
  4. Changed5 schema fields changed
    • changedInput schema / properties / id / description
      Previous value: -"Ensembl stable gene ID (e.g. ENSG00000139618). Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol."New value: +"Ensembl stable gene ID (e.g. ENSG00000139618). A version suffix (ENSG00000139618.17) is accepted and dropped before the query. Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol."
    • changedInput schema / properties / species / description
      Previous value: -"Source species (the species the query gene belongs to) in Ensembl internal format. Default is homo_sapiens. Use ensembl_list_species to discover valid values."New value: +"Source species (the species the query gene belongs to) in Ensembl internal format. Default is homo_sapiens. Use ensembl_list_species with nameContains (a genus or common name, e.g. mouse) to find valid values."
    • changedInput schema / properties / target_species / description
      Previous value: -"Filter to homologs in a single target species (e.g. mus_musculus for mouse). Omit to return homologs across all available species. Use ensembl_list_species to discover valid values."New value: +"Filter to homologs in a single target species (e.g. mus_musculus for mouse). Omit to return homologs across all available species. Use ensembl_list_species with nameContains (a genus or common name) to find valid values."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The gene symbol or stable ID was not found in Ensembl. `no_input`: Neither symbol nor id was provided. `conflicting_input`: Both symbol and id were provided. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The gene symbol or stable ID was not found in Ensembl for the source species. `invalid_species`: The species or target_species string was not recognized by Ensembl. `no_input`: Neither symbol nor id was provided. `conflicting_input`: Both symbol and id were provided. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "not_found",
      -  "no_input",
      -  "conflicting_input"
      -]New value: +[
      +  "not_found",
      +  "invalid_species",
      +  "no_input",
      +  "conflicting_input"
      +]
  5. Changed1 schema field changed
    • addedInput schema / properties / species / minLength
      Added value: +1
  6. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "homologs",
      +      "totalCount",
      +      "queryId",
      +      "querySpecies",
      +      "queryType"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `not_found`: The gene symbol or stable ID was not found in Ensembl. `no_input`: Neither symbol nor id was provided. `conflicting_input`: Both symbol and id were provided. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "not_found",
      +            "no_input",
      +            "conflicting_input"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "homologs",
      -  "totalCount",
      -  "queryId",
      -  "querySpecies",
      -  "queryType"
      -]
  7. Changed7 schema fields changed
    • addedInput schema / properties / max_results
      Added value: +{
      +  "default": 25,
      +  "description": "Maximum number of homologs to return. Broad orthology queries (e.g. BRCA2 across all species) can return 150+ homologs; the default keeps responses focused. Set to 0 to return every homolog uncapped. totalCount always reports the true number available before this cap.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "The max_results limit applied to the homolog list.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / homologs / description
      Previous value: -"Homologous genes found for the query gene."New value: +"Homologous genes found for the query gene, capped to max_results. totalCount reports the full count available before the cap."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no homologs are found."New value: +"Guidance when no homologs are found or the list was capped."
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Number of homologs returned after the max_results cap.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Total number of homologs returned."New value: +"Total number of homologs available before the max_results cap. Exceeds the returned homologs count when the list was capped."
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when the homolog list was capped at max_results.",
      +  "type": "boolean"
      +}
  8. Changed2 schema fields changed
    • changedInput schema / properties / id / description
      Previous value: -"Ensembl stable gene ID (e.g. ENSG00000139618). Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be used together with symbol."New value: +"Ensembl stable gene ID (e.g. ENSG00000139618). Use ensembl_lookup_gene to get the stable ID from a symbol. Cannot be combined with symbol."
    • changedInput schema / properties / symbol / description
      Previous value: -"Gene symbol in the source species (e.g. BRCA2, TP53). Requires species to be set. Cannot be used together with id."New value: +"Gene symbol in the source species (e.g. BRCA2, TP53). Species defaults to homo_sapiens; set species for other organisms. Cannot be combined with id."
  9. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare read-only/idempotent/open-world, yet the description adds substantial behavior: Ensembl's own ordering (closest relatives first), page size default 25, totalCount/nextOffset pagination contract, the pan-taxonomic comparison fallback for out-of-comparison target_species, and the best-effort targetSymbol budget shared across a ten-second lookup. These are non-obvious traits the annotations cannot convey.

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?

Purpose and input contract are front-loaded, followed by return shape, then pagination, then the targetProteinId/targetSymbol caveats — a sensible order with no filler sentences. Some sentences (the pan-taxonomic and targetSymbol ones) are dense and run long, which slightly hurts scannability.

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?

Even though an output schema exists, the description covers ordering, pagination, identifier semantics, cross-comparison fallback, and the downstream link to ensembl_get_sequence. Nothing an agent needs to call this correctly or interpret the result is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning: percId/percPos are measured over the target protein's length, page counts are relative to offset and max_results, and target_species can fall back to pan-taxonomic comparison. That goes beyond restating schema text.

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?

Opens with a specific verb+resource ('Find orthologs and/or paralogs of a gene across species') and immediately enumerates the returned fields, so an agent knows exactly what it gets. It also routes the reader toward ensembl_lookup_gene and ensembl_get_sequence, distinguishing it from siblings.

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?

Gives concrete usage examples ('mouse equivalent of human TP53', 'how conserved is BRCA2 across mammals') and states the input contract: either symbol + species or a stable gene ID. It points to ensembl_lookup_gene for symbol→ID conversion but never states an explicit when-not-to-use case, keeping it short of a 5.

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.