Skip to main content
Glama

List Ensembl Species

ensembl_list_species
Read-onlyIdempotent

List species supported by Ensembl with display name, common name, assembly, taxon ID, and division. Required discovery step — species names like homo_sapiens are opaque to non-biologists and are the input format every other Ensembl tool expects. Use nameContains to find a species by partial name match; filter by division to select one. With no division, lists the endpoint default division — the vertebrates (~356 species on the default GRCh38 endpoint). Species are sorted by internal name and returned max_results at a time (default 25); totalCount reports every match, and when more follow, nextOffset is the offset for the next page.

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_list_species"
  }
}

Input Schema

NameRequiredDescriptionDefault
offsetNo0-based position in the name-sorted matches 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 species.
divisionNoFilter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return the endpoint default division (vertebrates).
max_resultsNoMaximum number of species to return, counted from offset. Default 25. Set to 0 to return every matching species from offset to the end, uncapped. totalCount always reports the full number of matches before this cap.
nameContainsNoCase-insensitive substring filter applied locally after fetching. Matches against species name, display name, and common name. Example: "sapiens" matches homo_sapiens; "mouse" matches mus_musculus.

Output Schema

NameRequiredDescriptionDefault
capNoThe max_results limit applied to this page.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of species returned on this page.
noticeNoGuidance when the filter matches no species, the offset is past the end, or more species follow this page.
speciesNoSpecies matching the filter criteria, sorted by internal name: at most max_results entries starting at offset.
truncatedNoTrue when more matching species follow this page; request nextOffset to continue.
nextOffsetNoOffset of the first species after this page — pass it as offset to fetch the next page. Present only when more species follow.
totalCountNoTotal number of matching species after local filtering, before offset and max_results. Exceeds the returned species count when the list was paged.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / max_results / default
      Previous value: -50New value: +25
    • changedInput schema / properties / max_results / description
      Previous value: -"Maximum number of species to return, counted from offset. Default 50. Set to 0 to return every matching species from offset to the end, uncapped. totalCount always reports the full number of matches before this cap."New value: +"Maximum number of species to return, counted from offset. Default 25. Set to 0 to return every matching species from offset to the end, uncapped. totalCount always reports the full number of matches before this cap."
  2. Changed9 schema fields changed
    • addedInput schema / properties / max_results
      Added value: +{
      +  "default": 50,
      +  "description": "Maximum number of species to return, counted from offset. Default 50. Set to 0 to return every matching species from offset to the end, uncapped. totalCount always reports the full number of matches before this cap.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "description": "0-based position in the name-sorted matches 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 species.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "The max_results limit applied to this page.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / nextOffset
      Added value: +{
      +  "description": "Offset of the first species after this page — pass it as offset to fetch the next page. Present only when more species follow.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when the filter matches no species."New value: +"Guidance when the filter matches no species, the offset is past the end, or more species follow this page."
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Number of species returned on this page.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / species / description
      Previous value: -"Species matching the filter criteria, sorted by internal name."New value: +"Species matching the filter criteria, sorted by internal name: at most max_results entries starting at offset."
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Total number of matching species after local filtering."New value: +"Total number of matching species after local filtering, before offset and max_results. Exceeds the returned species count when the list was paged."
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when more matching species follow this page; request nextOffset to continue.",
      +  "type": "boolean"
      +}
  3. 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": [
      +      "species",
      +      "totalCount"
      +    ]
      +  },
      +  {
      +    "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.",
      +          "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: -[
      -  "species",
      -  "totalCount"
      -]
  4. Changed1 schema field changed
    • changedInput schema / properties / division / description
      Previous value: -"Filter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return all divisions."New value: +"Filter to a specific Ensembl division. EnsemblVertebrates includes human, mouse, zebrafish, and other vertebrates. EnsemblPlants covers crop and model plant genomes. EnsemblFungi, EnsemblMetazoa, EnsemblProtists cover non-vertebrate model organisms. Omit to return the endpoint default division (vertebrates)."
  5. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only declare read-only, open-world, idempotent; the description adds real behavioral detail beyond that — the no-division default is the vertebrates endpoint (~356 species on GRCh38), results are sorted by internal name, pages cap at max_results (default 25), totalCount reports all matches, and nextOffset chains pages. That is exactly the pagination and default-scoping context an agent needs before calling.

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

Conciseness5/5

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

Front-loaded with purpose, then workflow role, then filtering, then pagination — a sensible order for an agent scanning top-down. No filler sentences; even the parenthetical species count carries decision-relevant information about the default scope.

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?

An output schema exists, so return values need not be documented, yet the description goes further and explains totalCount/nextOffset paging, which is the main failure mode for a list tool. Combined with defaults, sort order, and the discovery-step framing, nothing needed to invoke it correctly 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 description coverage is 100%, so the baseline is 3; the description earns above that by adding facts the schema does not carry, notably the concrete default-division size (~356 vertebrates) and the nameContains-to-species example mapping. It does not re-derive the enum meanings or offset semantics, leaving those to the schema, so it is additive rather than redundant.

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?

States a precise verb+resource ('List species supported by Ensembl') and immediately enumerates the payload fields (display name, common name, assembly, taxon ID, division). It also positions itself against siblings by naming itself the 'required discovery step' whose output is 'the input format every other Ensembl tool expects', so an agent can place it in a workflow without reading a schema.

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 clear when-to-use guidance: it is a prerequisite for other Ensembl tools because species names like homo_sapiens are opaque. It also routes within the tool ('Use nameContains to find a species by partial name match; filter by division to select one'), which is effectively alternative-selection guidance. It stops short of any explicit when-not-to-use or exclusion, which keeps it at 4 rather than 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.