Skip to main content
Glama
plant-genomics-mcp

plant-genomics-mcp

by musharna

GO Annotations

locus_go_annotations
Read-onlyIdempotent

Fetch Gene Ontology annotations for a plant locus from QuickGO by resolving it to a UniProt accession and returning GO terms grouped by aspect for functional analysis.

Instructions

Fetch Gene Ontology annotations for a plant locus from QuickGO (EBI). Free, no API key. The locus is first resolved to a UniProt accession via the same logic as resolve_locus_to_uniprot, then QuickGO is queried by geneProductId. Returns annotations[] with goId/goName/goAspect/qualifier/evidence + a by_aspect rollup ({molecular_function: [{goId, goName}, ...], biological_process: [...], cellular_component: [...]}) deduped on goId so the high-level term set is one read away; by_aspect_deduped_on names that key in the payload. truncated is true when numberOfHits exceeds returned — raise limit (max 100). taxon_name_included is false when QuickGO could not supply taxonName for this answer (taxonId is still given).

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

Input Schema

NameRequiredDescriptionDefault
limitNoMax annotations from QuickGO (1–100, default 50)
locusYese.g. AT1G01010 (Arabidopsis), Os01g0100100 (rice)
cursorNonext_cursor from the previous page; omit for the first (#123)
organismNoPlant organism — accepts canonical slug (arabidopsis_thaliana), scientific or common name, or NCBI taxidarabidopsis_thaliana

Output Schema

NameRequiredDescriptionDefault
locusYes
totalYesHow many GO annotations (QuickGO numberOfHits) exist upstream for this query, all pages (pre-cap) (#123)
returnedYesRows in this payload (#123)
by_aspectYesaspect → [{goId, goName}, ...], deduped on goId, over annotations[] only
truncatedYesTrue when numberOfHits exceeds returned (raise `limit`)
annotationsYes
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)
numberOfHitsYesTotal annotations available upstream
upstream_versionNoQuickGO release that produced THIS response, — always null today: this backend states no release on its responses; upstream_release(backend='quickgo') reports the release its own endpoint calls current at query time, or why there is none. null means QuickGO 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.
uniprot_accessionYesUniProt accession used to query QuickGO
with_from_includedNoFalse when withFrom was not asked for (gene_report's GO section), in which case every withFrom is null because it was left out — not because the annotation has no partner or source cross-ref.
taxon_name_includedNoFalse when QuickGO failed the search that asks for taxonName and answered the same search without it: every taxonName is then null because it could not be had, not because the annotation has no taxon. taxonId is still given.
by_aspect_deduped_onYesThe key by_aspect collapses annotations[] on: a dedup, not a truncation
taxon_name_missing_becauseNoQuickGO's failure, quoted, when taxon_name_included is false; else null

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.32.1
    • addedOutput schema / properties / taxon_name_included
      Added value: +{
      +  "default": true,
      +  "description": "False when QuickGO failed the search that asks for taxonName and answered the same search without it: every taxonName is then null because it could not be had, not because the annotation has no taxon. taxonId is still given.",
      +  "title": "Taxon Name Included",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / taxon_name_missing_because
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "QuickGO's failure, quoted, when taxon_name_included is false; else null",
      +  "title": "Taxon Name Missing Because"
      +}
  2. Changed1 schema field changedv1.28.0
    • addedOutput schema / properties / with_from_included
      Added value: +{
      +  "default": true,
      +  "description": "False when withFrom was not asked for (gene_report's GO section), in which case every withFrom is null because it was left out — not because the annotation has no partner or source cross-ref.",
      +  "title": "With From Included",
      +  "type": "boolean"
      +}
  3. Changed1 schema field changedv1.27.0
    • changedOutput schema / properties / upstream_version / description
      Previous value: -"QuickGO release that produced THIS response, — always null today: this backend states no release on its responses. null means QuickGO 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."New value: +"QuickGO release that produced THIS response, — always null today: this backend states no release on its responses; upstream_release(backend='quickgo') reports the release its own endpoint calls current at query time, or why there is none. null means QuickGO 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."
  4. Changed9 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"
      +}
    • changedOutput schema / properties / by_aspect / description
      Previous value: -"aspect → [{goId, goName}, ...], deduped on goId"New value: +"aspect → [{goId, goName}, ...], deduped on goId, over annotations[] only"
    • addedOutput schema / properties / by_aspect_deduped_on
      Added value: +{
      +  "const": "goId",
      +  "description": "The key by_aspect collapses annotations[] on: a dedup, not a truncation",
      +  "title": "By Aspect Deduped On",
      +  "type": "string"
      +}
    • 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"
      +}
    • changedOutput schema / properties / returned / description
      Previous value: -"Number of annotations in annotations[]"New value: +"Rows in this payload (#123)"
    • addedOutput schema / properties / total
      Added value: +{
      +  "description": "How many GO annotations (QuickGO numberOfHits) exist upstream for this query, all pages (pre-cap) (#123)",
      +  "title": "Total",
      +  "type": "integer"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when numberOfHits exceeds returned (raise `limit`)",
      +  "title": "Truncated",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / upstream_version
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "QuickGO release that produced THIS response, — always null today: this backend states no release on its responses. null means QuickGO 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",
      -  "uniprot_accession",
      -  "numberOfHits",
      -  "returned",
      -  "annotations",
      -  "by_aspect"
      -]New value: +[
      +  "total",
      +  "locus",
      +  "uniprot_accession",
      +  "numberOfHits",
      +  "returned",
      +  "truncated",
      +  "annotations",
      +  "by_aspect",
      +  "by_aspect_deduped_on"
      +]
  5. First observedv1.8.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already cover readOnly, idempotent, openWorld and non-destructive, so the bar is lower; the description still adds real behavior: no API key required, an internal UniProt resolution step borrowed from resolve_locus_to_uniprot, the truncation/false-taxonName fallbacks, and the dedup convention. It stops just short of stating error behavior or rate limits.

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?

Front-loaded with purpose and cost (free, no key) before mechanics, and every clause carries information. It is somewhat over-packed for a single paragraph and spends several clauses describing the response payload, which is partly redundant given an output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a paginated, externally-sourced annotation lookup with full annotation coverage, the description supplies the resolution chain, pagination, truncation and known fallback cases. Since an output schema exists, the lengthy payload narration is not strictly needed, and no cross-tool routing guidance is offered — both keep it from a 5.

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 baseline is 3; the description earns a bump by linking `limit` to the `truncated` flag (raise limit when truncated, max 100) and naming which key the deduped rollup uses, giving operational meaning beyond the field docstrings. The `organism` and `cursor` semantics are already fully covered by the schema, so nothing further is added there.

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 and resource — 'Fetch Gene Ontology annotations for a plant locus' — plus the upstream source (QuickGO/EBI) and the resolution path. An agent can tell it apart from batch_locus_go_annotations (batch) and go_enrichment (enrichment) without inspecting schemas.

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

Usage Guidelines3/5

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

Usage is implied by 'for a plant locus' (single-locus scope) and the pagination note 'next_cursor from the previous page; raise limit (max 100)'. But there is no explicit when-to-use / when-not guidance pointing at the batch sibling or an enrichment alternative, so routing remains an inference.

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