⚠️ CALL THIS TOOL FIRST every turn, before any other TogoMCP tool.

Returns the v6 Usage Guide, which enforces the empirically-validated workflow:

GATE 0: classify the question (bounded → STEP −1 | open-ended → EXPLORATION).
STEP −1: analyze entities, databases, endpoints (no tools).
STEP  0: pick database(s) from the DATABASE CATALOG in this guide — no tool call.
STEP  1: specialized search or ncbi_esearch — ground in real IRIs.
STEP  2: get_MIE_file(database) — required before any run_sparql.
STEP  3: run_sparql() — pin every graph; LIMIT 10 first; max 2 consecutive.
STEP  4: synthesize — each fact once, no meta-commentary.

Why this matters (measured): questions with ≥3 consecutive run_sparql calls score ~1.1 points lower than compliant ones; jumping to text search before reading the MIE schema accounts for ~95% of silent SPARQL failures. The guide's DATABASE CATALOG lists all databases with what each is for (scan it to pick 1–3), plus the EXPLORATION habits (Seed Definition, concierge check, prioritized Next Steps) for open-ended deep dives.

Most RDF Portal endpoints host MANY databases (primary: 16, ebi: 5, ncbi: 5, sib: 4) and every endpoint hosts many GRAPHS. An unpinned query silently reads all of them, so a co-hosted graph can supply a predicate you believe is native and return a plausible, correctly-shaped, WRONG number — with no error. The guide's CO-TENANCY section is the one to read before writing SPARQL.

Re-run GATE 0 every turn — prior workflow does not carry forward.

Returns: str: The content of the TogoMCP usage guide.

Get the available SPARQL endpoints for RDF Portal.

RETURNS a dict with two keys: databases (maps each database -> {url, endpoint_name, keyword_search}) and endpoints (maps each endpoint_name -> {url, databases}).

Returns: Dict with two keys: - databases: Dict mapping database -> {url, endpoint_name, keyword_search} - endpoints: Dict mapping endpoint_name -> {url, databases}

Run a SPARQL query on an RDF database. ALWAYS pass database (required; valid values: uniprot, rhea, pubchem, pdb, chembl, chebi, reactome, ensembl, amrportal, mesh, go, taxonomy, mondo, nando, bacdive, mediadive, clinvar, pubmed, pubtator, ncbigene, medgen, ddbj, glycosmos, supercon, bgee, oma, brenda, hgnc, jpostdb, massbank, nbrc, mogplus, hco, mco, togovar, ontology) for single-database queries. For cross-database queries on a shared endpoint, still pass a member database AND add endpoint_name (valid values: sib, pubchem, pdb, ebi, primary, ncbi, ddbj, glycosmos, nims, togovar) or endpoint_url, which take priority over database. Invalid database/endpoint_name values fail immediately with a deterministic error — do not retry. RETURNS the query results as a CSV-formatted string (first row is the header of SELECT variable names).

Get a list of named graphs on a SPARQL endpoint. ALWAYS pass database (required). Virtuoso/OpenLink internal graphs are filtered out. Graph URIs containing the database substring (case-insensitive) are ranked first — useful when the endpoint hosts multiple databases (e.g. SIB hosts UniProt + Rhea + Bgee + OMA). For a database not yet in the registry, pass endpoint_url (or endpoint_name if its parent endpoint is registered) to bypass database validation; the required database value is then used only as a ranking hint. RETURNS a CSV-formatted list of named graphs (database-name matches first); on missing endpoint selection it returns a string beginning with 'Error:' — check for that prefix before use.

At the start of any task, identify ALL databases needed and call this tool for EACH of them before writing any SPARQL queries. Do not query a database until its MIE file has been read. Get the MIE (Metadata Interoperability Exchange) file containing the ShEx schema, RDF and SPARQL examples of a specific RDF database. RETURNS the MIE file as a YAML-formatted string; an unknown database returns a string beginning with 'Error:' that lists the valid database names.

Search for a UniProt entity ID by query.

⚠️ Only the search string and limit are accepted. Extra parameters like taxon, organism, reviewed, species, etc. are silently dropped and have no effect — express such filters inside the Solr query string instead (e.g., organism_id:9606 AND reviewed:true).

The search string can be passed as any of: query (canonical), search, term, keyword, keywords, search_term, or name.

RETURNS a TSV string with columns: accession, protein_name, organism_name. On upstream/HTTP failure this tool does NOT raise — it returns a plain string beginning with "Error:" (not TSV). CHECK FOR the "Error:" prefix BEFORE parsing rows.

Get a PubChem compound ID (CID) for a compound name.

RETURNS the PubChem Compound ID(s) as a JSON-formatted string. On upstream/HTTP failure this tool does NOT raise — it returns a plain string beginning with "Error:" (not JSON). CHECK FOR the "Error:" prefix BEFORE parsing.

Get compound attributes from PubChem RDF.

RETURNS the compound attributes as a JSON-formatted string. On upstream/HTTP failure this tool does NOT raise — it returns a plain string beginning with "Error:" (not JSON). CHECK FOR the "Error:" prefix BEFORE parsing.

Search PDBj for structures, chemical components, or BIRD molecules.

Returns rich, named fields per hit (not just the title) — for pdb, each result carries the experimental method, resolution, bound ligands, and citation; for cc, the formula, SMILES, and InChI.

RETURNS a JSON string {"total": int | null, "results": [ {…fields…} ]}. total is null when PDBj gives no count (typical for structured-filter searches) — that is NOT zero and does NOT mean "no results"; consult results directly. On upstream/HTTP failure returns a JSON object with an error key instead — CHECK FOR error BEFORE reading results.

Search for MeSH ID by query.

RETURNS a JSON-formatted string of the search results. On upstream/HTTP failure this tool does NOT raise — it returns a plain string beginning with "Error:" (not JSON). CHECK FOR the "Error:" prefix BEFORE parsing.

Search the Reactome pathway knowledgebase by keyword (name / fuzzy match).

Resolves a term (pathway / reaction / protein / complex / small-molecule name) to Reactome stable IDs. Matching is keyword/fuzzy — UNLIKE the exact-match ChEMBL search tools, so expect ranked, approximate hits.

RETURNS a dict {'total_count', 'has_more', 'results'} — NOT a bare list. total_count is the number of records RETURNED (capped by limit); has_more is true if more matched beyond the cap. Each result carries 'id' (stable Reactome stId, e.g. "R-HSA-109581"), 'name', 'type' (facet type), 'exactType' (specific BioPAX-ish class), 'species' (list), and — only when include_summation=True — 'summation' (≤240-char description). On upstream failure returns {'error': ...} instead — CHECK FOR 'error' BEFORE READING 'results'.

species and types are validated case-INSENSITIVELY against Reactome's controlled vocabularies and normalized to canonical casing before dispatch: the server-side filter is case-SENSITIVE and silently ignores a mis-cased value (returning UNFILTERED results), so a mis-cased species used to lose most hits. An unrecognized species/type now RAISES rather than silently returning the wrong rows.

Search the Rhea reaction database by keyword and return matching reactions.

Matching is KEYWORD/FUZZY over reaction participants, equations, EC numbers, and cross-references — NOT exact-ID lookup. A term like "glucose" matches any reaction mentioning glucose. Field-scoped terms and wildcards are supported (e.g. ec:1.1.1.1, chebi:17234, uniprot:*). A chebi:-scoped term takes a BARE ChEBI number, not the CHEBI: prefix; a redundant chebi:CHEBI:17234 is auto-corrected to chebi:17234 (the prefixed form otherwise 500s).

RETURNS a dict {'total_count', 'has_more', 'results'} — NOT a bare list. 'total_count' is the number of reactions RETURNED (capped by limit, max 500); 'has_more' is true if more matched beyond the cap. Each result carries the requested columns as snake_cased keys (e.g. 'rhea-id' → 'rhea_id', 'chebi-id' → 'chebi_id'). On upstream failure returns {'error': ...} instead — CHECK FOR 'error' BEFORE READING 'results'.

Valid columns (default rhea-id,equation): rhea-id, equation, chebi, chebi-id, ec, uniprot, go, pubmed, reaction-xref(EcoCyc|KEGG|MetaCyc| Reactome|M-CSA).

Resolve a name to ChEMBL IDs across several entity kinds in one call.

Cross-entity convenience wrapper over the ChEMBL RDF graph. Two matching regimes, because the entity kinds carry different searchable text:

• EXACT (case-insensitive) NAME match — COMPOUND (skos:altLabel: brands, generics, synonyms), TARGET (component skos:altLabel: gene symbols, protein names), CELL_LINE and TISSUE (rdfs:label, e.g. "Liver", "CCRF S-180"). Not fuzzy/substring — fix typos before calling. Prefer the entity-specific tools (search_chembl_molecule / search_chembl_target) when you know the kind; they carry extra fields (organism/type).

• KEYWORD-IN-DESCRIPTION — ASSAY. Assays have no name; their searchable text is a free-text dcterms:description, so ASSAY does a keyword (token) match on that description, NOT an exact match, e.g. entity_type="ASSAY", query="acetylcholinesterase" → every assay whose description mentions it. ASSAY results are relevance-ranked (best description match first).

Default (no entity_type) searches the four EXACT-name kinds and UNIONs them. ASSAY is opt-in via entity_type="ASSAY" — its keyword semantics and high hit counts would otherwise swamp a name lookup. (DOCUMENT is not supported; query SPARQL directly for it.)

The search string can be passed as any of: query (canonical), search, term, keyword, keywords, search_term, or name.

RETURNS a dict {'total_count', 'has_more', 'results'}. total_count is the number of rows RETURNED (capped by limit), NOT the full match count; check has_more (true = more results exist beyond this page — relevant mainly for ASSAY, whose keyword search can have many hits). Each result carries 'chembl_id', 'entity_type', and 'organism' (null for COMPOUND / where absent — use it to tell e.g. human from mouse targets). Name kinds also carry 'name' (rdfs:label); ASSAY rows instead carry 'description' (the free-text assay description, name=null) and a relevance 'score' (higher = better match). On endpoint failure this tool does NOT raise — it returns a dict with a single 'error' key instead; CHECK FOR 'error' BEFORE READING 'results'.

Resolve a biological TARGET (protein/receptor/enzyme) to a ChEMBL ID.

⚠️ DO NOT use this tool to look up drugs, compounds, or molecules by name. For drug/compound/molecule names (e.g., "sorafenib", "imatinib", "aspirin"), use search_chembl_molecule instead.

Resolution is deterministic SPARQL against the ChEMBL RDF graph, not a lexical search — there is no ranking to second-guess: • UNIPROT ACCESSION (e.g. "P00533") → the structured skos:exactMatch link. Returns every target containing that protein (the single protein plus any complex/family/chimera it participates in) — filter target_type to get just one. • GENE SYMBOL / PROTEIN NAME (e.g. "EGFR", "epidermal growth factor receptor") → EXACT (case-insensitive) match on the target component's skos:altLabel synonyms. Not fuzzy/substring — fix typos before calling.

Every result carries organism and type, so a symbol shared across species or complexes is disambiguated by inspecting those fields (or by passing the organism/target_type filters) — NOT by trusting order.

Target-type values (for type and the target_type filter): SINGLE PROTEIN, PROTEIN COMPLEX, PROTEIN FAMILY, PROTEIN-PROTEIN INTERACTION, CHIMERIC PROTEIN, NUCLEIC-ACID, CELL-LINE, TISSUE, ORGANISM, SELECTIVITY GROUP, SMALL MOLECULE, OLIGOSACCHARIDE, LIPID, METAL, and other rarer kinds. An unrecognized target_type raises rather than silently matching nothing.

The search string can be passed as any of: query (canonical), search, term, keyword, keywords, search_term, or name.

RETURNS a dict {'total_count', 'has_more', 'results'}. total_count is rows RETURNED (capped by limit), not the full match count; has_more is true if more exist beyond this page. Each result has 'chembl_id', 'name' (rdfs:label), 'organism', and 'type'. On endpoint failure this tool does NOT raise — it returns a dict with a single 'error' key instead; CHECK FOR 'error' BEFORE READING 'results'.

Resolve a DRUG / COMPOUND / MOLECULE (by name or structure) to a ChEMBL ID.

✅ Use this tool for drug, compound, or molecule names (e.g., "sorafenib", "imatinib", "aspirin", "Gleevec"). ⚠️ For biological targets (proteins, receptors, enzymes, genes such as EGFR, BRCA1, TP53), use search_chembl_target instead.

Resolution path is auto-selected from the query shape:

• NAME / BRAND / SYNONYM → deterministic SPARQL, EXACT (case-insensitive) match on the molecule's skos:altLabel synonyms (which include brand and trade names — "Gleevec" → CHEMBL941 IMATINIB). Not fuzzy/substring: fix typos before calling. No relevance ranking to second-guess.

• InChIKey / InChI → deterministic SPARQL, EXACT (case-SENSITIVE) match on the RDF-stored identifier. These are canonical (toolkit-independent), so exact match is correct, e.g. "BSYNRYMUTXBXSQ-UHFFFAOYSA-N" → CHEMBL25.

• SMILES → the ChEMBL REST chemistry engine (flexmatch), NOT exact match: a SMILES is written differently by each toolkit, so flexmatch normalizes the structure first, e.g. "CC(=O)Oc1ccccc1C(=O)O" → CHEMBL25.

Structure detection is conservative (multi-word input, or input without the "InChI=" prefix / InChIKey pattern / structural punctuation, is treated as a name), so a bare-chain SMILES like "CCO" is treated as a name.

The search string can be passed as any of: query (canonical), search, term, keyword, keywords, search_term, or name.

RETURNS a dict {'total_count', 'has_more', 'results'}. total_count is rows RETURNED (capped by limit), not the full match count; has_more is true if more exist beyond this page. Each result has 'chembl_id' (e.g. "CHEMBL25") and 'name' (rdfs:label, may be None for some structure hits). On endpoint/HTTP failure this tool does NOT raise — it returns a dict with a single 'error' key instead; CHECK FOR 'error' BEFORE READING 'results'.

Discover all available ID conversion routes between databases.

⚡ PLANNING TOOL — Call this EARLY when a question involves 2+ databases that are on DIFFERENT SPARQL endpoints and you need to map IDs between them.

Returns a map of all source→target database pairs that TogoID can convert. Use this to plan your cross-database strategy BEFORE attempting SPARQL joins or manual ID lookups.

Common conversion routes include: - ncbigene ↔ uniprot (Gene IDs to/from protein accessions) - uniprot ↔ pdb (Protein accessions to/from 3D structure IDs) - ncbigene ↔ ensembl_gene (NCBI Gene to/from Ensembl gene IDs) - chembl_target ↔ uniprot (Drug targets to/from protein accessions) - ncbigene ↔ hgnc (Gene IDs to/from HGNC symbols) - pubchem_compound ↔ chembl_compound (Compound IDs across databases)

When to use: - Question references 2+ databases on different SPARQL endpoints - You need to bridge identifiers (e.g., "find UniProt proteins for these NCBI Gene IDs") - Before writing complex multi-step SPARQL to join databases manually

When NOT to use: - Both databases share a SPARQL endpoint (use a single SPARQL query) - You only need data from one database - NCBI esearch can already cross-reference what you need

Returns: Dictionary mapping database pairs to their relationship metadata. Each entry shows source, target, and the nature of the link.

Check if a specific ID conversion route exists and get its details.

Use this to verify that a particular source→target conversion is available before calling convertId. Also reveals the nature of the relationship (e.g., "encoded by", "has structure", "is target of").

This is a single-hop, pairwise check: pass source and target as two separate args (unlike convertId, which takes one comma-joined route).

RETURNS a JSON string of a bare array of relationship objects, each with forward (label from source to target), reverse (label from target to source), and description (explanation of the link). An empty array means no direct route exists.

List all databases registered in TogoID with their ID formats.

Returns configuration for every dataset TogoID knows about, including:

• label: Human-readable database name

• regex: Pattern for validating IDs (helps you check if you have the right ID format before converting)

• prefix: URI prefix for linked data

• examples: Sample IDs you can use to test conversions

Useful for: - Discovering which databases are available for ID conversion - Checking the expected ID format (e.g., UniProt accession vs entry name) - Finding example IDs to test with countId before bulk conversion

Returns: Dictionary mapping dataset keys (e.g., 'uniprot', 'ncbigene', 'pdb') to their configuration objects.

Get configuration for a specific database in TogoID.

Retrieves detailed metadata about a single dataset, including its ID format, URI prefix, example IDs, and available annotations.

RETURNS a dict with label (human-readable name), regex (ID-validation pattern — use it to check your IDs are well-formed), prefix (URI prefixes for linking), examples (sample IDs — test with countId before bulk conversion), and annotations (available annotation types).

Get human-readable descriptions for all databases in TogoID.

Returns names, descriptions (in English and Japanese), and organization info for each registered database. Useful for understanding what each database contains when planning cross-database queries.

Returns: Dictionary keyed by dataset name with description metadata.

Convert identifiers from one database to another.

Maps IDs between biological databases — e.g., NCBI Gene IDs to UniProt accessions, or UniProt accessions to PDB structure IDs.

RETURNS a JSON string of a bare array of [source_id, target_id] pairs, e.g. '[["672", "P38398"], ["675", "O15129"]]'. An empty array means none of the input IDs converted along the route.

Check how many of your IDs can be converted before doing bulk conversion.

A lightweight pre-check: tells you how many source IDs have mappings in the target database WITHOUT actually returning the mapped IDs. Use this to: - Verify your IDs are in the correct format - Estimate result size before a large convertId call - Check if a conversion route works for your specific IDs

This is a single-hop, pairwise check: pass source and target as two separate args (unlike convertId, which takes one comma-joined route).

Search NCBI databases using E-utilities esearch API.

⚠️ CRITICAL FOR COMPREHENSIVE RESULTS ⚠️ ALWAYS use NCBI field tags for Gene, ClinVar, and similar databases! Without field tags, you may miss 70-80% of relevant results.

MANDATORY FIELD TAGS FOR GENE DATABASE: • [Organism] - Taxonomic filtering (e.g., "Homo sapiens[Organism]", "Archaea[Organism]") • [Gene Name] - Gene symbols (e.g., "TP53[Gene Name]", "nifH[Gene Name]") • [All Fields] - Broad keyword search (e.g., "nitrogenase[All Fields]")

IMPACT OF FIELD TAGS (Gene Database): • Without field tags: ~300 results (20-30% recall) ❌ • With field tags: ~1,300 results (100% recall) ✅ • Performance loss: Missing field tags = 70-80% data loss!

EXAMPLE (Gene): ✅ query="Archaea[Organism] AND (nifH[Gene Name] OR nitrogenase[All Fields])" ❌ query="archaea AND nifH" (missing [Organism]/[Gene Name] tags → ~23% recall)

RETURNS formatted text results carrying the database-specific IDs. On a missing/invalid database or query it returns a single text item whose message begins with "Error:" — check for that prefix before using the IDs.

List all supported NCBI databases with descriptions and example queries.

Returns: Formatted list of available databases

Fetch summary information for given IDs using esummary. Useful for getting detailed info after esearch.

RETURNS a text item holding the parsed JSON summary data. On a missing/invalid database or empty ids it returns a single text item whose message begins with "Error:" — check for that prefix before use.

Fetch full records using efetch. Returns actual data (sequences, records, etc.)

Resolve a human gene symbol/alias to its HGNC ID for variant search.

This is the FIRST step of the two-step variant workflow: the hgnc_id returned here is what search_variant takes as gene_hgnc_id.

The TogoVar endpoint does loose token matching with no relevance order (it returns the same set for "ALDH2" and the non-existent "ALDH2A1"), so this tool RE-RANKS client-side: exact symbol match first, then prefix, then other matches. Each result carries match_type ("exact"|"prefix"|"word"|"fuzzy") against your query — CHECK IT: if the top hit is not exact, the exact symbol you asked for does not exist and the rows are loose false positives, so do not blindly feed the first hgnc_id downstream. (The endpoint echoes the matched token as symbol and the HGNC approved gene name as name; it does not expose approved-vs-alias status, so use name to sanity-check.)

Resolve a disease term to MONDO / MedGen IDs for variant search.

The returned mondo_id (or MedGen CUI) is what search_variant takes as disease_id. Both land directly on TogoMCP's existing mondo/medgen RDF databases and TogoID nodes.

The TogoVar endpoint does loose token matching with no relevance order (a query like "cystic fibrosis" also returns unrelated "Hepatic fibrosis…" rows), so this tool RE-RANKS client-side: exact label match first, then prefix, then whole-word, then loose token matches last. Each result carries match_type ("exact"|"prefix"|"word"|"fuzzy") — a top hit that is not exact means no exact label matched.

COVERAGE LIMIT: TogoVar only indexes diseases that have ClinVar/MGeND variant associations, so some canonical/parent MONDO terms are simply absent here (e.g. MONDO_0007254 "breast cancer" does NOT appear in these results). But a broad/parent MONDO ID still WORKS as a disease_id in search_variant even when unlisted here — the variant search resolves it via MONDO descendant expansion (MONDO_0007254 -> ~24,550 variants). So if you know or can resolve the canonical MONDO ID (e.g. via OLS4 or the mondo RDF database), pass it straight to search_variant; do not assume this resolver is exhaustive.

Search TogoVar for human genome variants with population frequencies.

TogoVar integrates allele frequencies from gnomAD, ToMMo (Japanese), NCBN, GEM-J, JGA, and BioBank Japan, plus ClinVar + MGeND clinical significance and SIFT/PolyPhen/AlphaMissense predictions — data with no SPARQL counterpart elsewhere in TogoMCP.

All filters are optional and combined with AND. Supply zero filters to browse; but scope tightly — the database holds ~1 billion variants.

COUNTS: total is the size of the whole REST backend (1,097,708,150) and is constant across queries; filtered is the count matching your filters. Note the REST backend is LARGER than TogoMCP's togovar SPARQL graph (~2.8x: the SPARQL side is the annotated subset, 390,725,782), so REST counts will not match SPARQL COUNT(*) — they measure different sets.

PAGING CAP: the API allows offset + limit <= 10,000 and returns HTTP 400 beyond it, so a result set larger than 10,000 cannot be fully paged. Narrow the filters until filtered <= 10,000 to enumerate one exhaustively.

STATISTICS SCOPE (stat=True): all facets are scoped to the filtered set, but they count at different granularities. type counts per variant (sums to filtered); dataset per variant-cohort; consequence per variant-TRANSCRIPT (VEP fan-out, so its sum is filtered x transcripts per variant — ~5-6 for a typical gene, 400+ in transcript-dense loci like BRCA1); significance per variant-condition record. So consequence/ significance sums exceed filtered and must NOT be summed against it (they are not per-variant counts). See statistics_caveats for the per-facet rule.

ROUND-TRIP TO SPARQL: gate on tgv_id. It is NULL for variants that exist in the REST backend but NOT in the (smaller) SPARQL subset — including some ClinVar-Pathogenic ones. variant_iri is emitted ONLY when tgv_id is non-null, so a non-null variant_iri is safe to query in the togovar SPARQL graph; a row with tgv_id: null has no SPARQL record at all, and REST is the only source for it.

TWO-STEP WORKFLOW for gene/disease filters: 1. search_gene("ALDH2") -> hgnc_id -> pass as gene_hgnc_id. 2. search_disease("breast cancer") -> mondo_id -> pass as disease_id.