eutils-mcp-server

Overview Schema Source Related Servers Score Discussions Admin

Entrez Text Search

eutils_esearch

Read-only

Search any Entrez database and return matching UIDs for retrieval pipelines, with optional history handle for paging through results.

Instructions

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

Input Schema

TableJSON Schema

Name	Required	Description	Default
`db`	Yes	Entrez database to search, for example "pubmed" or "protein".
`sort`	No	Sort order, for example "pub_date", "relevance", or "first_author". Valid values vary by database.
`term`	Yes	Entrez query. Field tags go in square brackets, for example "breast cancer AND 2008[pdat]" or "mouse[orgn]".
`retmax`	No	Maximum UIDs to return (default 20). Use 0 to fetch only the count.
`maxdate`	No	End date, as YYYY, YYYY/MM, or YYYY/MM/DD. Requires datetype.
`mindate`	No	Start date, as YYYY, YYYY/MM, or YYYY/MM/DD. Requires datetype.
`datetype`	No	Which date field mindate/maxdate apply to: pdat (publication), edat (Entrez), mdat (modification).
`retstart`	No	Index of the first UID to return. Use for paging.
`usehistory`	No	Store the result set on the NCBI History server and return a history handle (default true). Set false to skip it.
`response_format`	No	Output format: 'markdown' for human-readable text, or 'json' for machine-readable data. Default: 'markdown'.	markdown

Output Schema

TableJSON Schema

Name	Required	Description
`term`	Yes
`uids`	Yes
`count`	Yes	Records returned on this page.
`total`	Yes	Records matching the whole query, not just this page.
`offset`	Yes
`history`	No	Present when usehistory is true.
`database`	Yes
`has_more`	Yes
`next_offset`	No
`query_translation`	Yes	How Entrez rewrote the query.
`term_translations`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses a real server-side side effect: the result set is stored on the NCBI History server and a handle returned. It also documents failure modes (retmax>10000 rejection with advice, unknown-database rejection listing valid ones, empty results returned with spelling advice rather than as errors), which an agent cannot infer from annotations alone.

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 purpose and scoping in the first paragraph, then Args/Returns/Examples/Error Handling sections that are easy to scan. It is somewhat long and the Args block restates fields already 100% covered by the schema, so it loses a point for redundancy rather than for verbosity.

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 10-parameter, open-world search tool with an output schema, the description covers the return shape, the history-handle mechanism, syntax rules, and error behavior. Nothing an agent needs to call it correctly is missing, and the output schema carries the response detail.

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

Parameters4/5

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

Schema coverage is 100%, so a 3 is the floor. The description adds value the schema does not: the uppercase-only rule for AND/OR/NOT and the YYYY / YYYY/MM / YYYY/MM/DD date formats, plus a consolidated default listing. Much of the Args block duplicates the schema, which caps it below 5.

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 verb and resource ("Search an Entrez database and return matching UIDs") and immediately frames it as "the entry point for a retrieval pipeline" that "returns UIDs, never records." The Don't-use-when clauses name eutils_esummary, eutils_efetch, and eutils_egquery, so an agent can distinguish it from siblings without opening any 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/when-not routing with concrete conditionals: don't use it when you already have UIDs (use esummary/efetch), and don't use it when the database is unknown (use egquery first). The Examples block reinforces this with realistic query-to-parameter mappings, including the count-only pattern via retmax=0.

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

Install Server