Gtdb Tools#

Configuration File: gtdb_tools.json Tool Type: Local Tools Count: 5

This page contains all tools defined in the gtdb_tools.json configuration file.

Available Tools#

GTDB_get_genome (Type: GTDBTool)#

Get comprehensive metadata for a specific genome by NCBI accession from GTDB. Returns nucleotide …

GTDB_get_genome tool specification

Tool Information:

  • Name: GTDB_get_genome

  • Type: GTDBTool

  • Description: Get comprehensive metadata for a specific genome by NCBI accession from GTDB. Returns nucleotide statistics (genome size, GC%, contig count, N50), gene-level metrics (completeness via CheckM/CheckM2, contamination, SSU/LSU counts, protein count, coding density), NCBI metadata (assembly level, BioProject, BioSample, isolation source, geographic coordinates), and taxonomic history across GTDB releases. Useful for evaluating genome quality, finding genome properties, and tracking taxonomic changes across GTDB versions.

Parameters:

  • operation (string) (optional) Operation type (fixed: get_genome)

  • accession (string) (required) NCBI genome accession (e.g., ‘GCF_000005845.2’ for E. coli K-12, ‘GCF_000009045.1’ for B. subtilis)

Example Usage:

query = {
    "name": "GTDB_get_genome",
    "arguments": {
        "accession": "example_value"
    }
}
result = tu.run(query)

GTDB_get_species (Type: GTDBTool)#

Get a recoverable page of genomes in a GTDB species cluster. total_genomes is exact because GTDB …

GTDB_get_species tool specification

Tool Information:

  • Name: GTDB_get_species

  • Type: GTDBTool

  • Description: Get a recoverable page of genomes in a GTDB species cluster. total_genomes is exact because GTDB returns the complete cluster; continue with next_offset while has_more is true.

Parameters:

  • operation (string) (optional) Operation type (fixed: get_species)

  • species (string) (required) Species name WITHOUT the s__ prefix (e.g., ‘Escherichia coli’, ‘Hydrogenothermus marinus’, ‘Bacillus subtilis’)

  • max_genomes (integer) (optional) Maximum number of genomes to return (default: 20). Species clusters can have thousands of genomes.

  • offset (integer) (optional) Zero-based genome offset. Continue with next_offset.

Example Usage:

query = {
    "name": "GTDB_get_species",
    "arguments": {
        "species": "example_value"
    }
}
result = tu.run(query)

GTDB_get_taxon_info (Type: GTDBTool)#

Get information about a GTDB taxon including its rank, total genome count, higher-rank lineage, a…

GTDB_get_taxon_info tool specification

Tool Information:

  • Name: GTDB_get_taxon_info

  • Type: GTDBTool

  • Description: Get information about a GTDB taxon including its rank, total genome count, higher-rank lineage, and release history. GTDB uses rank prefixes: d__ (domain), p__ (phylum), c__ (class), o__ (order), f__ (family), g__ (genus), s__ (species). For example, f__Lachnospiraceae returns its rank (Family), genome count, and lineage (Bacteria > Bacillota > Clostridia > Lachnospirales). Also returns the full lineage breakdown from domain to species. Useful for understanding where a taxon fits in the GTDB tree and how many genomes support it.

Parameters:

  • operation (string) (optional) Operation type (fixed: get_taxon_info)

  • taxon (string) (required) GTDB taxon name with rank prefix (e.g., ‘f__Lachnospiraceae’, ‘d__Bacteria’, ‘g__Escherichia’, ‘s__Escherichia coli’). Use GTDB_search_taxon to find valid names.

Example Usage:

query = {
    "name": "GTDB_get_taxon_info",
    "arguments": {
        "taxon": "example_value"
    }
}
result = tu.run(query)

GTDB_search_genomes (Type: GTDBTool)#

Search for prokaryotic genomes in GTDB by organism name. A multi-word query (e.g. a binomial like…

GTDB_search_genomes tool specification

Tool Information:

  • Name: GTDB_search_genomes

  • Type: GTDBTool

  • Description: Search for prokaryotic genomes in GTDB by organism name. A multi-word query (e.g. a binomial like ‘Mycobacterium tuberculosis’) is first matched precisely, requiring EVERY term of the query to appear in the genome’s name or taxonomy; ‘match_type’ is then ‘exact’. If nothing matches the whole query, the tool falls back to GTDB’s loose search, which matches ANY term of the query and therefore returns a broader taxon (often just the genus) or a different species; that case is reported as ‘match_type’: ‘broad’ with a top-level ‘note’, and ‘total_results’ then counts the broader match rather than the queried organism – always read ‘match_type’ and ‘total_results_scope’ before quoting a count or trusting a result. Results also match against the whole taxonomic clade rather than organism-name text alone, so exact/prefix name matches are ranked first within a page. Returns genome accessions with both NCBI and GTDB taxonomy classifications, allowing comparison between the two taxonomic systems. Each result shows the genome accession (GCA/GCF), NCBI organism name, NCBI taxonomy, GTDB taxonomy, and whether the genome is a GTDB species representative. Pagination is strictly one-based (page 0 is rejected because the live API treats it anomalously and can return the entire result set) with pages up to 1000 records; the response reports total_results, total_pages, has_more, and next_page. Useful for finding genome accessions, exploring taxonomic reclassifications, and linking genomes to the GTDB taxonomy.

Parameters:

  • operation (string) (optional) Operation type (fixed: search_genomes)

  • query (string) (required) Search query for organism name (e.g., ‘Escherichia’, ‘Staphylococcus aureus’, ‘Lactobacillus’)

  • page (integer) (optional) One-based page number (default 1). Never use 0; continue with metadata.next_page.

  • items_per_page (integer) (optional) Number of results per page (default 10, max 1000).

Example Usage:

query = {
    "name": "GTDB_search_genomes",
    "arguments": {
        "query": "example_value"
    }
}
result = tu.run(query)

GTDB_search_taxon (Type: GTDBTool)#

Search GTDB taxa by partial name, returning rank-prefixed names (d__, p__, c__, o__, f__, g__, s_…

GTDB_search_taxon tool specification

Tool Information:

  • Name: GTDB_search_taxon

  • Type: GTDBTool

  • Description: Search GTDB taxa by partial name, returning rank-prefixed names (d__, p__, c__, o__, f__, g__, s__). The upstream endpoint accepts at most 100 matches and has no offset. When data.possible_more is true, the result may be incomplete and the query must be narrowed; data.complete_known is true only when fewer than limit matches are returned.

Parameters:

  • operation (string) (optional) Operation type (fixed: search_taxon)

  • query (string) (required) Partial taxon name to search for (e.g., ‘Lachnospiraceae’, ‘Escherichia’, ‘Bacillota’). Case-insensitive.

  • limit (integer) (optional) Maximum number of results per rank (default: 20, max: 100)

Example Usage:

query = {
    "name": "GTDB_search_taxon",
    "arguments": {
        "query": "example_value"
    }
}
result = tu.run(query)