Skip to main content
Glama
plant-genomics-mcp

plant-genomics-mcp

by musharna

Gramene Homologs

gramene_homologs
Read-onlyIdempotent

Fetch orthologs and paralogs for a plant locus from Gramene to compare genes across species and find in-species duplicates.

Instructions

Fetch orthologs and paralogs for a plant locus from Gramene compara (data.gramene.org v69). Default homology_type='ortholog'; pass 'paralog' for in-species duplicates or 'all' for everything. 'ortholog' includes syntenic_ortholog_* rows; homoeologs (polyploid subgenome copies) come back only under 'all', and excluded_categories counts every category the filter left out. Returns target_locus + homology category (type) + shared gene_tree_id per hit (Gramene's tree id; for the tree's members pass the locus to gene_tree_members). Rows carry no taxon unless with_organism=true (adds 'organism' per row) or target_organism is given, which filters to one organism before the cap and adds 'organism' per row. Paralogs here are within_species_paralog only: Gramene drops Compara's other_paralog ('ancient paralogues'); ensembl_plants_paralogs lists both. Pair with resolve_locus_to_uniprot for protein-level enrichment and with blast_sequence for sequence similarity discovery.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "locus": "<locus>"
    },
    "name": "gramene_homologs"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax homolog rows to return. 'total' always reports the true pre-cap count and 'truncated' says whether the cap bit.
locusYese.g. AT1G01010 (Arabidopsis), Os01g0100100 (rice)
cursorNonext_cursor from the previous page; omit for the first (#123)
homology_typeNoFilter on homology kindortholog
with_organismNoAdd 'organism' (Gramene species slug, null when unknown) to every row without filtering; one extra call per 100 rows (#130)
target_organismNoKeep only homologs in this organism (slug, scientific/common name, or NCBI taxid), filtered BEFORE the cap so a hub gene's rice or wheat orthologs cannot be pushed past 'limit' by other species. Adds 'organism' to every row and 'total_all_organisms'.

Output Schema

NameRequiredDescriptionDefault
locusYes
totalYesHow many homologs (after any target_organism filter) exist upstream for this query, all pages (pre-cap) (#123)
releaseYesGramene release identifier, e.g. v69
homologsYes
returnedYesRows in this payload (#123)
truncatedNoTrue when the row list was capped (< total); pass limit= to change the cap
next_cursorNoPass back as cursor= to get the rows after this page; null on the last page. Opaque, and bound to this tool and query (#123)
target_organismNoCanonical organism the rows were filtered to, when target_organism was passed
upstream_versionNoGramene release that produced THIS response, as stated by the release pinned in the request path (e.g. 'v69'); same value as release. null means Gramene did not state one — never that no release exists, and never inferred from a separate metadata call, which can describe a different release than the one that answered.
excluded_categoriesYesHomologs Gramene returned that homology_type left out, counted per category (e.g. {'within_species_paralog': 3, 'homoeolog_one2one': 2} under 'ortholog'); empty under 'all'. Counted over every organism, before any target_organism filter
total_all_organismsNoHomolog total before the organism filter; present only when filtered

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.29.3
    • changedOutput schema / $defs / GrameneHomolog / properties / gene_tree_id / description
      Previous value: -"Gramene gene-tree ID (shared across all homologs in the record)"New value: +"Gramene gene-tree ID (shared across all homologs in the record). Gramene's release, not rest.ensembl.org's: a tree rebuilt since has another id there, so gene_tree_members takes locus= instead"
  2. Changed3 schema fields changedv1.24.0
    • changedOutput schema / $defs / GrameneHomolog / properties / type / description
      Previous value: -"Homology category: ortholog_one2one | ortholog_one2many | ortholog_many2many | within_species_paralog | between_species_paralog"New value: +"Gramene homology category, as upstream names it, e.g. ortholog_one2one, ortholog_many2many, syntenic_ortholog_one2one, within_species_paralog, homoeolog_one2one (wheat). homology_type='ortholog' keeps the categories whose name contains 'ortholog', 'paralog' those containing 'paralog'"
    • addedOutput schema / properties / excluded_categories
      Added value: +{
      +  "additionalProperties": {
      +    "type": "integer"
      +  },
      +  "description": "Homologs Gramene returned that homology_type left out, counted per category (e.g. {'within_species_paralog': 3, 'homoeolog_one2one': 2} under 'ortholog'); empty under 'all'. Counted over every organism, before any target_organism filter",
      +  "title": "Excluded Categories",
      +  "type": "object"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "returned",
      -  "locus",
      -  "release",
      -  "total",
      -  "homologs"
      -]New value: +[
      +  "returned",
      +  "locus",
      +  "release",
      +  "total",
      +  "homologs",
      +  "excluded_categories"
      +]
  3. Changed11 schema fields changedv1.22.0
    • addedInput schema / properties / cursor
      Added value: +{
      +  "description": "next_cursor from the previous page; omit for the first (#123)",
      +  "type": "string"
      +}
    • addedInput schema / properties / target_organism
      Added value: +{
      +  "description": "Keep only homologs in this organism (slug, scientific/common name, or NCBI taxid), filtered BEFORE the cap so a hub gene's rice or wheat orthologs cannot be pushed past 'limit' by other species. Adds 'organism' to every row and 'total_all_organisms'.",
      +  "type": [
      +    "string",
      +    "integer"
      +  ]
      +}
    • addedInput schema / properties / with_organism
      Added value: +{
      +  "default": false,
      +  "description": "Add 'organism' (Gramene species slug, null when unknown) to every row without filtering; one extra call per 100 rows (#130)",
      +  "type": "boolean"
      +}
    • addedOutput schema / $defs / GrameneHomolog / properties / organism
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Gramene species slug of target_locus; present with with_organism or target_organism, null when Gramene has no record for the locus",
      +  "title": "Organism"
      +}
    • addedOutput schema / properties / next_cursor
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Pass back as cursor= to get the rows after this page; null on the last page. Opaque, and bound to this tool and query (#123)",
      +  "title": "Next Cursor"
      +}
    • addedOutput schema / properties / returned
      Added value: +{
      +  "description": "Rows in this payload (#123)",
      +  "title": "Returned",
      +  "type": "integer"
      +}
    • addedOutput schema / properties / target_organism
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Canonical organism the rows were filtered to, when target_organism was passed",
      +  "title": "Target Organism"
      +}
    • changedOutput schema / properties / total / description
      Previous value: -"Number of homologs after filtering, BEFORE the row cap"New value: +"How many homologs (after any target_organism filter) exist upstream for this query, all pages (pre-cap) (#123)"
    • addedOutput schema / properties / total_all_organisms
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Homolog total before the organism filter; present only when filtered",
      +  "title": "Total All Organisms"
      +}
    • addedOutput schema / properties / upstream_version
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Gramene release that produced THIS response, as stated by the release pinned in the request path (e.g. 'v69'); same value as release. null means Gramene did not state one — never that no release exists, and never inferred from a separate metadata call, which can describe a different release than the one that answered.",
      +  "title": "Upstream Version"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "locus",
      -  "release",
      -  "total",
      -  "homologs"
      -]New value: +[
      +  "returned",
      +  "locus",
      +  "release",
      +  "total",
      +  "homologs"
      +]
  4. Changed3 schema fields changedv1.20.0
    • addedInput schema / properties / limit
      Added value: +{
      +  "default": 100,
      +  "description": "Max homolog rows to return. 'total' always reports the true pre-cap count and 'truncated' says whether the cap bit.",
      +  "maximum": 100,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / total / description
      Previous value: -"Number of homologs after filtering"New value: +"Number of homologs after filtering, BEFORE the row cap"
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "default": false,
      +  "description": "True when the row list was capped (< total); pass limit= to change the cap",
      +  "title": "Truncated",
      +  "type": "boolean"
      +}
  5. First observedv1.8.0

TDQS

A4.6/5.0
Behavior5/5

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

Provides rich behavioral context beyond annotations: explains that ortholog includes syntenic_ortholog_* rows, that homoeologs come only under 'all', that excluded_categories counts filtered categories, that rows lack taxon unless with_organism=true or target_organism is set, and that target_organism filters before the cap. Also notes with_organism triggers one extra API call per 100 rows, which is critical for performance awareness.

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 dense with information but well-structured, front-loading the main purpose and then detailing key behavioral nuances. It could be slightly more concise, but every sentence adds value and there is no redundant information.

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 (6 parameters, specific data source, filtering behaviors) and the presence of an output schema, the description is complete. It covers return row structure, filtering effects, performance implications, and related tools, leaving no critical gaps for correct invocation.

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% (all parameters have descriptions in the schema), so the schema already documents parameters well. The description adds some high-level context about homology_type and with_organism, but does not delve into detailed syntax or format beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 specific verb+resource: 'Fetch orthologs and paralogs for a plant locus from Gramene compara (data.gramene.org v69).' It names the data source and version, and distinguishes itself from sibling tools like ensembl_plants_paralogs and orthodb_orthologs by describing scope and data provenance.

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

Usage Guidelines5/5

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

Explicitly specifies when to use each homology_type value ('ortholog' default, 'paralog' for in-species duplicates, 'all' for everything) and names alternatives like ensembl_plants_paralogs for broader paralog coverage and gene_tree_members for tree members. It also pairs with resolve_locus_to_uniprot and blast_sequence for enrichment, providing clear usage guidance.

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