eutils-mcp-server

Search and Fetch

eutils_search_then_fetch

Read-onlyIdempotent

Search an Entrez database and download matching records in one call, skipping a separate fetch step.

Instructions

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

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "db": "<db>",
      "term": "<term>"
    },
    "name": "eutils_search_then_fetch"
  }
}

Input Schema

Name	Required	Description	Default
`db`	Yes	Entrez database to search, for example "pubmed".
`term`	Yes	Entrez query, for example "CRISPR AND 2024[pdat]".
`retmax`	No	Records to download (default 20, max 500).
`retmode`	No	Response encoding. Default "text".
`rettype`	No	Record format. Defaults to "abstract" for pubmed, "fasta" for sequences.
`response_format`	No	Output format: 'markdown' for human-readable text, or 'json' for machine-readable data. Default: 'markdown'.	markdown

Output Schema

Name	Required	Description	Default
`term`	Yes
`text`	Yes
`total`	Yes
`history`	Yes
`retmode`	No
`rettype`	No
`database`	Yes
`retrieved`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 11, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds value beyond that: it explains the ESearch History handle mechanism, the round-trip saving, the retmax>500 refusal, and the friendly-empty-result behavior with spelling advice.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose, then organizes Args, Returns, Examples, and Error Handling. Despite covering a lot, every section earns its place with no filler.

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 compound search+fetch tool, the description covers purpose, alternatives, parameters, return shape, examples, and error handling. With an output schema also present, nothing an agent needs to invoke it correctly is missing.

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 the baseline is 3. The description goes slightly beyond by noting db-specific rettype defaults ('abstract' for pubmed, 'fasta' for sequences) and restating the retmax cap, adding useful semantics not fully captured by the schema's brief descriptions.

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 compound verb+resource: 'Search a database and download the matching records in one call.' It explicitly frames itself as the shortcut vs the individual tools, so an agent can distinguish it from eutils_esearch and eutils_efetch without opening schemas.

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?

Provides explicit 'Use when' and 'Don't use when' examples naming the alternative tools (eutils_esearch then eutils_esummary), plus guidance to search with retmax=0 when the result set is huge. This is textbook when/when-not/alternatives coverage.

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

Deploy Server