Skip to main content
Glama
plant-genomics-mcp

plant-genomics-mcp

by musharna

Synthesis: Homolog Search

find_homologs_synth
Read-onlyIdempotent

Run BLAST on a protein or nucleotide sequence, then return ranked homolog hits annotated with UniProt records by resolving subject accessions in one call.

Instructions

Synthesis: one-call equivalent of the find_homologs prompt. Runs BLAST then resolves UniProt-shaped subject accessions via the batch UniProt helper. Returns ranked hits each annotated with their UniProt record (or null if subject_id is not a UniProt accession).

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": {
      "sequence": "<sequence>"
    },
    "name": "find_homologs_synth"
  }
}

Input Schema

NameRequiredDescriptionDefault
top_nNo
programNoblastp
sequenceYesQuery sequence (protein or nucleotide)

Output Schema

NameRequiredDescriptionDefault
toolYesSynthesis tool name, e.g. analyze_locus_synth
inputYesEchoed input arguments
stepsYesPer-backend execution rows
resultNoComposed cross-source result; None if root step failed
elapsed_sYesTotal orchestrator wall time
started_atYesISO 8601 UTC timestamp
failed_stepsNoStep numbers whose status is "error". Non-empty means the result is partial: the call succeeded, so it is not an error result, but these backends failed and their sections are missing; each step's error says why.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.31.0
    • addedOutput schema / properties / failed_steps
      Added value: +{
      +  "description": "Step numbers whose status is \"error\". Non-empty means the result is partial: the call succeeded, so it is not an error result, but these backends failed and their sections are missing; each step's error says why.",
      +  "items": {
      +    "type": "integer"
      +  },
      +  "title": "Failed Steps",
      +  "type": "array"
      +}
  2. Changed2 schema fields changedv1.22.0
    • changedOutput schema / $defs / StepRow / description
      Previous value: -"One backend call inside a synthesis envelope.\n\n``status=\"ok\"`` populates ``result``; ``status=\"error\"`` populates ``error``\nwith the existing ``[ExceptionClass] message`` wire format from\n``errors.PlantGenomicsError.__str__``. ``status=\"skipped\"`` populates\n``error`` with a human-readable skip reason (e.g. phase 1 failed)."New value: +"One backend call inside a synthesis envelope.\n\n``status=\"ok\"`` populates ``result`` — unless the orchestrator carries the\npayload elsewhere in the envelope (``gene_report`` keeps it once, under\n``result.sections``), in which case the row is the audit trail alone and\n``result`` is None. ``status=\"error\"`` populates ``error`` with the\nexisting ``[ExceptionClass] message`` wire format from\n``errors.PlantGenomicsError.__str__``. ``status=\"skipped\"`` populates\n``error`` with a human-readable skip reason (e.g. phase 1 failed)."
    • changedOutput schema / $defs / StepRow / properties / elapsed_s / description
      Previous value: -"Per-step wall time when separately measurable, else None. Phase-2 gather rows and phase-0 pre-call validation failures return None because their wall time can't be honestly attributed per-step; SynthesisEnvelope.elapsed_s carries the authoritative total."New value: +"Per-step wall time: every awaited backend call is timed on its own, including inside a phase-2 gather. None only for rows that never ran (skipped, or a phase-0 pre-call validation failure); SynthesisEnvelope.elapsed_s carries the orchestrator total."
  3. First observedv1.8.0

TDQS

A3.5/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the two-stage execution (BLAST then batch UniProt resolution), ranked output, and the null-annotation edge case when subject_id is not a UniProt accession.

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?

Three tight sentences, front-loaded with what the tool is and followed by the execution flow and return shape. No filler, though the phrase 'one-call equivalent of the find_homologs prompt' is only meaningful to an agent that knows that prompt.

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?

An output schema exists and annotations are rich, so return values and safety need little prose. The description covers the pipeline and the null case, which is the non-obvious part; the remaining gap is the absence of any parameter-choice guidance for a composite search tool.

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

Parameters2/5

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

Schema description coverage is only 33% – only 'sequence' is documented in the schema. The description adds no guidance on 'program' (why pick blastn vs blastp vs blastx) or 'top_n' (result count tradeoffs), so the low-coverage gap is not compensated. The only added semantic is about subject accessions, which is output-side, not parameter-side.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the concrete pipeline: 'Runs BLAST then resolves UniProt-shaped subject accessions via the batch UniProt helper', which tells an agent exactly what the tool does and how it differs from a plain BLAST call. It is clear and specific, though it never names the sibling raw-BLAST tool it presumably wraps.

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?

Framing as 'one-call equivalent of the find_homologs prompt' implies the intended use (get homologs with UniProt annotations in a single call), but there is no explicit when-to-use versus when-to-use-a-sibling guidance and no stated prerequisites. Usage must be inferred.

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