Skip to main content
Glama

lookup_xref

Map a VFB ID to its external database accessions, or an external accession back to the VFB term that carries it. USE THIS INSTEAD OF search_terms FOR ANY EXTERNAL ACCESSION — a hemibrain/FAFB/MANC bodyId, a CATMAID skeleton id, a neuprint id. Free-text search on a bare number ranks a plausible near-miss first and gives you no way to tell a real match from a good guess; this tool confirms the accession against each candidate term's own cross-reference list and returns a row only if that term really carries it. Each row gives the VFB id, label, site (db, db_label, site_id), the accession and a resolved deep link into the external site. Pass exactly one of id or accession. THE TWO DIRECTIONS DIFFER WHEN EMPTY: an empty id->accession result is authoritative (the term has no cross-references); an empty accession->id result means the search index did not reach a term carrying that accession, NOT that no such term exists — report it as "could not confirm", never as "does not exist", and do not substitute a search_terms guess.

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

Input Schema

NameRequiredDescriptionDefault
dbNoOptional site filter. Matches a site symbol ("hb"), short_form ("neuprint_JRC_Hemibrain_1point2point1") or label, ignoring case, punctuation and spacing, and also accepts whole words from those names — "flywire", "hemibrain", "neuprint", "catmaid", "male-cns" all work. When set, the response carries db_matched and available_dbs; a filtered empty result means "none from this site", not "none at all".
idNoA VFB ID to list external accessions for (e.g. VFB_jrchjtdb). Mutually exclusive with accession.
accessionNoAn external accession to resolve back to a VFB term (e.g. 1734350908 for a hemibrain bodyId). Mutually exclusive with id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

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

No annotations are supplied, so the description carries the full burden and does: it discloses the verification behavior (returns a row only if the candidate term's own cross-reference list carries the accession), the row shape (VFB id, label, site/db/db_label/site_id, resolved deep link), and the asymmetry of empty results between directions with an instruction on how to report it. The 'could not confirm' vs 'does not exist' distinction is exactly the kind of behavioral context annotations could never encode.

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 the core mapping statement and the routing rule, then the failure-mode caveat, with zero filler sentences. It is dense and slightly long, and the mid-sentence explanation of why free-text ranking misleads is the one stretch that could be trimmed, but every clause carries operative guidance.

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?

For a three-param lookup with no annotations and no output schema, the description covers purpose, alternative, exclusivity constraint, result column set, and the interpretation of empty results per direction. An agent has everything needed to call it and to report its output correctly, including the non-obvious asymmetry.

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%, so the mutual exclusivity of id/accession and the db filter's matching rules are already fully documented in the schema. The description adds only the 'pass exactly one' constraint, which is valuable because required params = 0 leaves that unenforced, but otherwise it restates schema semantics. Baseline 3 is appropriate.

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 bidirectional verb+resource: map a VFB ID to external database accessions, or an external accession back to the VFB term. It immediately names the sibling it replaces (search_terms) and enumerates the accession types in scope (hemibrain/FAFB/MANC bodyId, CATMAID skeleton id, neuprint id), so an agent can distinguish it from search_terms without opening either schema.

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?

Explicit when-to-use in caps ('USE THIS INSTEAD OF search_terms FOR ANY EXTERNAL ACCESSION'), justified by why the alternative fails on bare numbers, plus an explicit when-not ('do not substitute a search_terms guess'). It even conditions on the outcome: pass exactly one of id or accession, and interpret empty results differently per direction.

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.