plant-genomics-mcp

Overview Schema Source Related Servers Discussions Admin

Gramene Homologs

gramene_homologs

Read-onlyIdempotent

Retrieve orthologs and paralogs for a plant locus from Gramene compara. Filter by homology type or target organism to identify evolutionary counterparts and gene tree relationships.

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. 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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Max homolog rows to return. 'total' always reports the true pre-cap count and 'truncated' says whether the cap bit.
`locus`	Yes	e.g. AT1G01010 (Arabidopsis), Os01g0100100 (rice)
`cursor`	No	next_cursor from the previous page; omit for the first (#123)
`homology_type`	No	Filter on homology kind	ortholog
`with_organism`	No	Add 'organism' (Gramene species slug, null when unknown) to every row without filtering; one extra call per 100 rows (#130)
`target_organism`	No	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'.

Output Schema

TableJSON Schema

Name	Required	Description
`locus`	Yes
`total`	Yes	How many homologs (after any target_organism filter) exist upstream for this query, all pages (pre-cap) (#123)
`release`	Yes	Gramene release identifier, e.g. v69
`homologs`	Yes
`returned`	Yes	Rows in this payload (#123)
`truncated`	No	True when the row list was capped (< total); pass limit= to change the cap
`next_cursor`	No	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)
`target_organism`	No	Canonical organism the rows were filtered to, when target_organism was passed
`upstream_version`	No	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.
`excluded_categories`	Yes	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
`total_all_organisms`	No	Homolog total before the organism filter; present only when filtered

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.24.0Sep 26, 2026

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"
+]

Changed11 schema fields changedv1.22.0Sep 24, 2026

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"
+]

Changed3 schema fields changedv1.20.0Jul 28, 2026

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

First observedv1.8.0May 30, 2026

TDQS

A5/5.0

Behavior5/5

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive hints; the description adds substantial behavior beyond that: homoeologs only under 'all', excluded_categories counts omitted categories, rows carry no taxon unless with_organism/target_organism is set, target_organism filters before the cap, and paralogs are within_species_paralog only. No contradiction with annotations.

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?

The description is dense but every sentence earns its place: purpose, default behavior, edge cases, output shape, taxon behavior, tool differentiation, and integration. It is front-loaded with the core purpose and does not waffle or restate schema fields.

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, the description is complete: it names the source version, output fields (target_locus + type + gene_tree_id), filter semantics, organism handling, cap ordering, and the key sibling alternative. The presence of an output schema reduces the need to document return details, but the description still gives a clear mental model.

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?

Schema coverage is 100%, so the baseline is 3, but the description goes well beyond the schema by explaining non-obvious semantics: the default ortholog meaning, homoeolog behavior under 'all', target_organism's pre-cap filtering and organism-adding effect, and with_organism's per-row behavior. This materially improves parameter understanding.

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 'Fetch orthologs and paralogs for a plant locus from Gramene compara (data.gramene.org v69)', which names a specific verb, resource, and data source. The scope is further distinguished from sibling ensembl_plants_paralogs by stating that paralogs here are within_species_paralog only.

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?

Specifies the default homology_type='ortholog' and exactly when to pass 'paralog' or 'all'. It also names the alternative tool for the excluded case ('ensembl_plants_paralogs lists both') and recommends pairing with resolve_locus_to_uniprot and blast_sequence.

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

Deploy Server