Server Quality Checklist

Tool Scores

• eutils_espellA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: the error-handling note that changed=false is reported rather than an error when NCBI has no correction. It stops short of describing rate limits or response latency, but the error semantics are a real value-add.

  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?

  Well front-loaded with purpose first, then structured Args/Returns/Examples/Error Handling sections. Every section earns its place except the Args block, which duplicates the schema verbatim, making it slightly longer than necessary.

  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?

  Although an output schema exists (so return explanation is optional), the description still documents the return shape and even covers the no-correction edge case. For a 3-parameter, fully-annotated tool, an agent has everything needed to select and invoke it correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the Args section largely restates what the schema already documents for db, term, and response_format. The only marginal addition is the illustrative example term 'breast cancr', which does not deepen syntactic understanding. Baseline 3 applies when the schema does the heavy lifting.

  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?

  The description opens with a specific verb and resource: 'Get NCBI's spelling suggestion for a query in one database.' An agent can immediately distinguish this diagnostic spelling tool from search/fetch siblings like eutils_esearch or eutils_efetch.

  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 'Use when' bullets (no-results search, 'did you mean' scenario) and a 'Don't use when' exclusion for structured field searches. The alternative condition is stated precisely, so nothing is left to inference.

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

• eutils_ecitmatchA
  4.6/5.0
  Behavior4/5

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

  Annotations already cover readOnly/openWorld/idempotent/destructive=false, so safety is handled. The description adds real value beyond them: validation behavior (rejects strings with fewer than six fields) and per-citation matched=false semantics when NCBI finds no record. This is meaningful error/edge-case disclosure not present in the annotations.

  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 purpose sentence, then cleanly sectioned Args/Returns/Examples/Error Handling. Slightly verbose with both Returns and a detailed Examples block, but each section carries distinct information and 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?

  Even though an output schema exists, the description restates the return shape and adds the matched-flag semantics that help the agent interpret partial matches. Validation rules, format spec, alternatives, and examples are all present for a 2-param tool.

  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, but the description adds the pipe-delimited field semantics, the note that the trailing pipe is optional and auto-added, and a worked example mapping a human citation to the array form. That exceeds what the schema states.

  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 ('Resolve') and resource ('formatted citation strings to PubMed IDs'), and immediately frames the scope against free-text searching. An agent can distinguish this from eutils_esearch without opening either 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-to-use ('when you have a reference list but no PMIDs', converting a bibliography), explicit when-not ('searching by topic - use eutils_esearch'), and names the alternative sibling. Nothing is left to inference.

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

• eutils_einfoA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description goes further by disclosing error behavior (unknown db names are rejected with samples; parse errors if NCBI changes the response shape) and by enumerating exactly what data each mode returns, including last_update and record_count.

  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?

  The core behavior is front-loaded in the first paragraph, followed by clearly labeled Args, Returns, Examples, and Error Handling sections. The Returns block partly duplicates the output schema, but the Examples and Error Handling sections earn their space.

  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 two-parameter, zero-required tool with a full output schema and rich annotations, the description covers both modes, the argument semantics, worked examples, sibling routing, and failure modes. An agent has everything needed to select and invoke it correctly; return-value detail is a bonus given the output schema exists.

  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 description coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema by explaining the consequence of each choice: omitting db yields the full list, supplying db yields record count, last update, searchable fields, and outbound links. The response_format enum is already fully documented in the schema and is merely restated.

  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?

  The first sentence states a specific verb (List / describe) applied to a precise resource (Entrez databases and their searchable fields and links). It cleanly separates the two operating modes (no args = list, db = describe), which lets an agent pick the right call without opening the 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?

  It gives concrete when-to-use examples mapped to inputs ("what fields can I search in PubMed?" -> db="pubmed") and an explicit don't-use case that names the alternative sibling (eutils_egquery) for record counts on a query. The choice between this tool and its closest sibling is fully resolved.

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

• eutils_elinkA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnly/openWorld/non-idempotent/non-destructive, so the description's added value is the History-server persistence semantics of cmd="neighbor_history" (a real side effect explaining the non-idempotent hint), the uids-vs-history mutual exclusion rule, and error-handling behavior (rejecting a mismatched history db, empty-result hint). It stops short of covering operational concerns like rate limits or expired-history handling, but the additions are substantive rather than restated annotation content.

  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?

  Well front-loaded: purpose first, then the database-bridging framing, then a structured Args/Returns/Examples/Error Handling layout. It is slightly long because the Args section and Returns block duplicate the input and output schemas, but every non-duplicated sentence earns its place.

  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 7-parameter tool with nested objects and cross-database semantics, the definition covers selection, chaining, constraints, and failure modes; the returns description is redundant given an output schema exists but does no harm. An agent has everything needed to call it correctly.

  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 description coverage is already 100%, so the Args section largely restates the schema. However, it adds meaning the schema does not encode: "Supply either uids or history, never both" and the note that history.db must match dbfrom, plus the shorthand that omit-db means same-database links.

  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+resource (find records linked to a set of UIDs) and immediately scopes it as cross-database navigation with concrete examples (gene to protein, pubmed to pmc). It explicitly differentiates itself from siblings by naming eutils_link_then_fetch as the alternative when records are wanted rather than UID lists.

  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?

  Contains an explicit "Use when" list with three concrete scenarios and a "Don't use when" clause that routes to eutils_link_then_fetch. It also names eutils_einfo for discovering link names and describes the chaining path into eutils_efetch.

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

• eutils_esummaryA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful disclosure beyond that: internal batching above 500 UIDs, refusal to combine uids and history, and rejection of retmax >500 rather than silent truncation. It loses a point for paying output-format detail that the output schema already supplies.

  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 one-line purpose, then cleanly labelled Args/Returns/Examples/Error Handling sections that are easy to scan. The Returns block restates what the output schema already provides and the Args list largely mirrors the schema, so a small amount of redundancy keeps it just short of a 5.

  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 read-only summarizer with a full output schema and rich annotations, everything an agent needs is present: the either/or parameter rule, defaults, caps, batching behavior, and failure modes. Nothing about correct invocation is left to inference.

  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 description coverage is 100%, so the baseline is 3, but the description goes further by stating the cross-parameter constraint ("Supply either uids or history, never both") and the retmax default/max in prose form. That inter-parameter rule is the kind of semantics a schema rarely makes explicit.

  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 ("Fetch compact summaries (DocSums) for a set of UIDs") and immediately scopes it against the heavier alternative: "Don't use when: you need the full abstract or sequence (use eutils_efetch)". An agent can distinguish this from eutils_efetch and eutils_esearch 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?

  Provides explicit "Use when" scenarios (screening titles by PMID, screening a large result set via history) and a "Don't use when" routing to eutils_efetch. It also names the sibling tools that produce the history handle, closing the loop on the prescreen-then-fetch workflow.

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

• eutils_link_then_fetchA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real behavioral detail beyond that: mutual exclusivity of term/uids, retmax capped at 500 with default 20, and graceful empty-result hinting when no links exist. This is richer than typical but stops short of describing pagination or auth needs.

  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?

  It is well front-loaded (purpose, then uses, args, returns, examples, errors) and every section is scannable. The Args block largely restates the 100%-covered schema, which is mild redundancy, but the examples and error-handling sections earn their space.

  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 an 8-parameter cross-database tool, the description covers selection of source/target, the term-vs-uids rule, format control, and failure modes, and an output schema exists so return values need not be re-explained. Nothing material is missing for correct invocation.

  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 nevertheless adds meaning the schema does not encode, notably the 'Pass exactly one of term or uids' constraint and the retmax default/ceiling framing, which helps an agent construct a valid call rather than just read field docs.

  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?

  The description names a specific compound action (follow links across databases and download target records in one call) and gives concrete examples (gene IDs to protein sequences, PMIDs to PMC full text). It is clearly distinguishable from eutils_elink and eutils_search_then_fetch because the 'link then fetch' scope is stated explicitly.

  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?

  It provides explicit 'Use when' examples and a 'Don't use when: you only need the linked UIDs (use eutils_elink, which is cheaper)' exclusion naming the alternative tool. The agent can route between this tool and eutils_elink without inference.

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

• eutils_egqueryA
  4.7/5.0
  Behavior5/5

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

  Annotations already establish read-only, idempotent, open-world safety, and the description adds materially more: counts-only output, a degraded-mode fallback limited to 12 of 38 databases, the DNS/redirect cause, the exact fallback trigger condition (network failure, never validation error), and the blank-term error string. This is unusually rich disclosure for a read tool with full annotation coverage.

  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-loaded with the one-line purpose, then cleanly sectioned into Args, Returns, Examples, and Error Handling. Despite its length, every section carries non-redundant operational information, particularly the degraded-mode caveat.

  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?

  Even though an output schema exists, the description spells out the full return shape including the degraded field, sorting order, and empty_databases, plus failure modes. Nothing an agent needs to interpret a result or handle a fallback is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, so both parameters are already documented, and the description largely restates them. The example query 'CRISPR base editing' adds a small amount of concreteness about term format, but no syntax, limits, or field-qualifier guidance beyond the schema.

  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 every Entrez database at once') plus the exact output contract ('report how many records each one matches'). The 'Don't use when' line explicitly separates it from eutils_esearch, so an agent can route without opening either 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?

  Provides both a positive trigger ('find which database holds data for a topic before committing to a search') and an explicit exclusion with the named alternative ('you already know the database (use eutils_esearch instead)'). The worked example ('which database has information about BRCA1 variants?') makes the intent unambiguous.

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

• eutils_efetchA
  4.8/5.0
  Behavior5/5

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

  Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds genuinely new behavior: DB-specific defaults, external-data fencing, retmax>500 refusal with internal batching, error-text detection, and explicit rettype prompting. This goes well beyond the structured fields.

  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 purpose followed by cleanly labeled Args/Returns/Examples/Error Handling sections. The Args block partially duplicates schema descriptions, but for an 8-parameter tool with several behaviors the length is justified, not padded.

  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?

  Given an output schema exists and annotations carry the safety profile, the description still supplies everything an agent needs: format defaults, source selection rules, paging limits, and error behavior. No material gap remains for correct invocation.

  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?

  With 100% schema coverage the baseline is 3, but the description adds meaning the schema lacks: the mutual-exclusivity rule ('supply either uids or history, never both'), per-database rettype default semantics, and the purpose of retstart/retmax as history-only paging controls.

  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+resource ('Download full records') and immediately clarifies the format behavior. It differentiates itself from siblings, notably by naming eutils_esummary as the cheaper tool for titles/dates, so an agent can distinguish it within the E-utilities family 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' examples (abstract fetch, sequence fetch, large-set download) plus a 'Don't use when' exclusion routing to eutils_esummary. It also states the history-vs-uids selection rule and the paging strategy with retstart/retmax.

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

• eutils_epostA
  4.8/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint/destructiveHint/idempotentHint), it discloses capacity (many thousands of UIDs per call), the validation rule (UIDs with URL metacharacters are rejected), and failure mode (upstream error if NCBI returns no History handle). This explains why idempotentHint is false: each call yields a fresh handle.

  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?

  Well structured and front-loaded: purpose first, then Args/Returns/Examples/Error Handling. The Args section largely restates the schema descriptions, which is mild redundancy, but no sentence is wasted elsewhere.

  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 3-parameter tool with an output schema and full annotation coverage, the description supplies everything an agent needs: purpose, routing advice, parameter shapes, return shape, and error behavior.

  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, but the description adds worked examples with real values (db="gene", uids=["7173","22018","54314"]) and restates the array-or-comma-separated flexibility of uids, which helps an agent choose a form quickly.

  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+resource+outcome: upload UIDs to the NCBI History server and receive a reusable handle. It distinguishes itself from the search-oriented siblings by explaining that this is the entry point when UIDs come from somewhere other than ESearch.

  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?

  Explicitly names when to use it (UIDs from another source, combining sets), when not to use it (you are about to search; ESearch with usehistory already posts its own results), and gives concrete examples. The alternative is named and the selecting condition is stated.

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

• eutils_esearchA
  4.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.

• eutils_search_then_fetchA
  4.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.