List Entrez databases, or describe one database's searchable fields and links.

Call with no arguments to list all Entrez databases. Call with db to get that database's record count, last update time, searchable field names, and the links available to other databases.

Args:

• db (string, optional): database to describe, for example "pubmed". Omit to list all.

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Returns: Without db: { count, databases: string[] } With db: { database, menu_name, description, record_count, last_update, build, field_count, fields: [{ name, fullname, description, termcount? }], link_count, links: [{ name, dbto, menu }] }

Examples:

• Use when: "what fields can I search in PubMed?" -> db="pubmed"

• Use when: "which Entrez databases exist?" -> no arguments

• Use when: "what databases link from a gene record?" -> db="gene"

• Don't use when: you want record counts for a query (use eutils_egquery instead)

Error Handling:

• Rejects a database name that is not one of the known Entrez databases, and lists samples

• Returns a parse error if NCBI changes the response shape

Search every Entrez database at once and report how many records each one matches.

Use this to find which database holds data for a topic before committing to a search. It returns counts only, never records.

Args:

• term (string): Entrez text query, for example "CRISPR base editing".

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Returns: { term, databases_searched, databases_with_hits, hits: [{ db, menu, count, status }] (sorted by count, descending), empty_databases: string[] }

Examples:

• Use when: "which database has information about BRCA1 variants?" -> term="BRCA1 variants"

• Don't use when: you already know the database (use eutils_esearch instead)

Error Handling:

• Returns "The search term was empty" when term is blank

• NCBI EGQuery redirects to an internal host that is not published in public DNS, for every client including ones with a valid API key. When the real EGQuery is unreachable this tool falls back to per-database ESearch counts over 12 commonly used databases, and says so in a "degraded" field. Counts are then a subset, not all 38.

• The fallback triggers only on a network failure, never on a validation error.

Get NCBI's spelling suggestion for a query in one database.

Args:

• db (string): database to check against, for example "pubmed".

• term (string): query to check, for example "breast cancr".

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Returns: { database, query, corrected_query, changed }

Examples:

• Use when: a search returned no results and you suspect a typo

• Use when: "did you mean" for a query -> term="diabetis"

• Don't use when: the query is a structured field search; ESpell works on plain terms

Error Handling:

• Reports changed=false when NCBI has no correction, rather than an error

Search an Entrez database and return matching UIDs.

This is the entry point for a retrieval pipeline. It returns UIDs, never records. By default it also stores the result set on the NCBI History server and returns a history handle, so later calls can page through the whole set without re-searching.

Entrez field tags go in square brackets: gene[tiab], 2008[pdat], mouse[orgn]. Boolean operators AND, OR, NOT must be uppercase.

Args:

• db (string): database to search, for example "pubmed".

• term (string): Entrez query, for example "breast cancer AND 2008[pdat]".

• retmax (number, optional): UIDs to return, 0-10000. Default 20. Use 0 for count only.

• retstart (number, optional): index of the first UID. Default 0.

• sort (string, optional): "pub_date", "relevance", "first_author", ...

• datetype ('pdat' | 'edat' | 'mdat', optional): date field for mindate/maxdate.

• mindate, maxdate (string, optional): YYYY, YYYY/MM, or YYYY/MM/DD.

• usehistory (boolean, optional): return a History handle. Default true.

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Returns: { database, term, total, count, offset, has_more, next_offset, uids: string[], query_translation, term_translations: [{ from, to }], history? }

Examples:

• Use when: "find papers about CRISPR in Nature" -> db="pubmed", term="CRISPR AND nature[journal]"

• Use when: "how many records mention this gene?" -> retmax=0

• Don't use when: you already have UIDs (use eutils_esummary or eutils_efetch)

• Don't use when: you don't know which database (use eutils_egquery first)

Error Handling:

• Rejects retmax above 10000 with advice to use the History server

• Rejects an unknown database and lists valid ones

• Returns an empty result with spelling advice rather than an error

Upload a list of UIDs to the NCBI History server and get a reusable handle.

Use this when you already have UIDs from somewhere other than an ESearch, or when you want to combine several sets. Many thousands of UIDs fit in one call.

Args:

• db (string): database the UIDs belong to, for example "gene".

• uids (string[] | string): UIDs or accessions, as an array or comma-separated string.

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Returns: { database, uploaded, history: { db, web_env, query_key } }

Examples:

• Use when: "fetch these five gene IDs" -> db="gene", uids=["7173","22018","54314"]

• Use when: combining UID lists from two sources before one download

• Don't use when: you are about to search; ESearch with usehistory already posts its own results

Error Handling:

• Rejects UIDs containing URL metacharacters

• Reports an upstream error if NCBI returns no History handle

Fetch compact summaries (DocSums) for a set of UIDs.

Use this to screen records by title, authors, journal, and date before paying the cost of downloading full records.

Args:

• db (string, optional): database, for example "pubmed". Required unless history is given.

• uids (string[] | string, optional): UIDs or accessions.

• history (object, optional): handle from eutils_esearch, eutils_epost, or eutils_elink.

• retstart (number, optional): first record index, for history sets. Default 0.

• retmax (number, optional): records to return for a history set. Default 20, max 500.

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Supply either uids or history, never both.

Returns: { database, total, count, offset, has_more, next_offset?, batches?, records: [{ uid, title, authors[], journal, source, pubdate, volume, issue, pages, doi?, pmcid?, pubtype[], lang[] }] }

Non-PubMed databases return whichever scalar fields the DocSum carries.

Examples:

• Use when: "show me the titles of these PMIDs" -> db="pubmed", uids=["31452104"]

• Use when: screening a large result set -> pass history from eutils_esearch

• Don't use when: you need the full abstract or sequence (use eutils_efetch)

Error Handling:

• Refuses more than 500 UIDs per call and batches larger lists internally

• Refuses to combine uids and history in one call

• Rejects retmax above 500 rather than silently truncating

Download full records in a chosen format.

Defaults are chosen for readability: PubMed returns plain-text abstracts, and sequence databases return FASTA. Returned record text is external data and is fenced with an explicit marker.

Args:

• db (string, optional): database, for example "pubmed". Required unless history is given.

• uids (string[] | string, optional): UIDs or accession.version identifiers.

• history (object, optional): handle from eutils_esearch, eutils_epost, or eutils_elink.

• rettype (string, optional): "abstract" (pubmed default), "fasta" (sequence default), "gb", "docsum", "medline", ...

• retmode ('text' | 'xml', optional): default "text".

• retstart (number, optional): first record index, for history sets.

• retmax (number, optional): records to return for a history set. Default 20, max 500.

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Supply either uids or history, never both.

Returns: { database, rettype, retmode, record_count?, batches?, text }

Examples:

• Use when: "give me the abstract for PMID 31452104" -> db="pubmed", uids=["31452104"]

• Use when: "fetch the protein sequence" -> db="protein", uids=["NP_005537.3"], rettype="fasta"

• Use when: downloading a large set -> pass history and page with retstart/retmax

• Don't use when: you only need titles and dates (use eutils_esummary, which is far cheaper)

Error Handling:

• Asks for an explicit rettype when the database has no default

• Detects an error message returned as record text and reports it as a tool error

• Refuses retmax above 500; larger sets are batched internally

Find records linked to a set of UIDs, either in another database or within the same one.

This is how you move between databases: gene to protein, pubmed to pmc, nucleotide to snp, and so on. With cmd="neighbor_history" the linked set is stored on the NCBI History server and returned as a handle you can feed straight into eutils_efetch.

Args:

• dbfrom (string): source database, for example "pubmed".

• db (string, optional): target database, for example "pmc". Omit for same-database links.

• uids (string[] | string, optional): source UIDs.

• history (object, optional): handle whose db matches dbfrom.

• cmd (string, optional): "neighbor" (default), "neighbor_score", "neighbor_history", "acheck", "ncheck", "lcheck", "llinks", "prlinks".

• linkname (string, optional): a specific link, for example "pubmed_pmc". Use eutils_einfo to list them.

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Supply either uids or history, never both.

Returns: { dbfrom, dbto?, command, groups_found, total_linked, groups: [{ dbto, linkname, count, ids[], query_key? }], histories? }

Examples:

• Use when: "which PMC articles correspond to these PMIDs?" -> dbfrom="pubmed", db="pmc"

• Use when: "find proteins for these gene IDs" -> dbfrom="gene", db="protein"

• Use when: chaining a download -> cmd="neighbor_history", then pass histories to eutils_efetch

• Don't use when: you want records, not UID lists (use eutils_link_then_fetch)

Error Handling:

• Rejects a history whose db does not match dbfrom

• Returns an empty result with a hint to list valid link names via eutils_einfo

Resolve formatted citation strings to PubMed IDs.

Use this when you have a reference list but no PMIDs. It is far more reliable than free-text searching for a specific article.

Args:

• citations (string[]): each string formatted as journal_title|year|volume|first_page|author_name|your_key| A trailing pipe is optional and is added for you.

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Returns: { submitted, matched, records: [{ input, journal, year, volume, first_page, author, key, pmid, matched }] }

Examples:

• Use when: "find the PMID for Mann BJ, Proc Natl Acad Sci USA 1991;88:3248" -> citations=["proc natl acad sci u s a|1991|88|3248|mann bj|Art1|"]

• Use when: converting a bibliography into PMIDs before fetching abstracts

• Don't use when: you are searching by topic (use eutils_esearch)

Error Handling:

• Rejects a citation string with fewer than six pipe-separated fields

• Reports matched=false per citation when NCBI finds no corresponding record

Search a database and download the matching records in one call.

This is the shortcut for the common "find me the papers about X" request. It runs ESearch with a History handle, then EFetch, saving a round trip. Use the individual tools when you want to screen titles before downloading.

Args:

• db (string): database to search, for example "pubmed".

• term (string): Entrez query.

• retmax (number, optional): records to download. Default 20, max 500.

• rettype (string, optional): "abstract" (pubmed default), "fasta" (sequence default), ...

• retmode ('text' | 'xml', optional): default "text".

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Returns: { database, term, total, retrieved, rettype, retmode, history, text }

Examples:

• Use when: "summarize recent papers on CRISPR delivery" -> db="pubmed", term="CRISPR delivery AND 2024[pdat]"

• Use when: "get the sequences for these gene records" -> db="nuccore", term="..."

• Don't use when: you want to inspect titles first (use eutils_esearch then eutils_esummary)

• Don't use when: the result set is huge; search with retmax=0 first to see the count

Error Handling:

• Returns a friendly empty result, with spelling advice, when nothing matches

• Refuses retmax above 500

• Reports the ESearch count so you can judge whether to page

Follow links from one database to another and download the target records in one call.

Typical uses: gene IDs to protein sequences, PMIDs to PMC full text, nucleotide records to SNPs. Give it either a query or a UID list in the source database, and it returns records from the target database.

Args:

• dbfrom (string): source database, for example "gene".

• db (string): target database to download from, for example "protein".

• term (string, optional): query in dbfrom. Pass exactly one of term or uids.

• uids (string[] | string, optional): source UIDs in dbfrom.

• linkname (string, optional): specific link to follow.

• retmax (number, optional): target records to download. Default 20, max 500.

• rettype (string, optional): record format for the target database.

• response_format ('markdown' | 'json'): output format. Default 'markdown'.

Returns: { dbfrom, dbto, source_total, retrieved, rettype, source_history, history, text }

Examples:

• Use when: "get the protein sequences for these gene IDs" -> dbfrom="gene", db="protein", uids=[...]

• Use when: "find PMC full text for papers about X" -> dbfrom="pubmed", db="pmc", term="..."

• Don't use when: you only need the linked UIDs (use eutils_elink, which is cheaper)

Error Handling:

• Rejects passing both term and uids, or neither

• Returns an empty result with a hint to list link names when no links exist

• Refuses retmax above 500