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

Annotations only declare read-only and open-world; the description carries the rest: section key remapping (oa→sections.open_access), the fulltext.status/reason vocabulary with a named failure taxonomy, the transient-lookup caveat, per-mode latency for citation, and file-vs-inline output behavior. This is unusually rich disclosure of what happens on failure and why.

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

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

Purpose is front-loaded, but the remainder is a single undifferentiated block mixing parameter interactions, response shapes, and rare failure modes. Most sentences carry information, yet the transient OA-status-lookup detail and repeated restatement of fulltext/oa behavior add density that slows an agent trying to extract the call decision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter tool with no output schema, the description supplies the return structure (file_path plus outline, fulltext.sections array, status/reason fields, links) and the failure paths an agent must handle. Nothing material needed to call it correctly appears to be missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema lacks: the response key difference for oa/graph, that fulltext_max_chars is ignored in file mode, and that citation_direction is honored for preprint citations. It stops short of explaining limit's per-section scoping beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Get article by PMID/PMCID/DOI'), and the identifier set immediately separates it from query-based siblings like article_search and gene_articles. The subsequent text confirms this is the single-record fetch path, not a search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit conditional guidance: use fulltext_output="inline" only if you cannot read server-side files, request ["fulltext"] separately because "all" excludes it, and oa/fulltext do not apply to preprints. It does not, however, route the agent between article_get and article_search/gene_articles, so the alternative-selection guidance is incomplete.

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

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

Annotations only declare readOnly/openWorld, so the description carries the real load and adds substantial context: the response is an envelope with results/warnings/errors, per-source failures never appear as items in results, and specific degradation modes are named (PubMed dropping unrecognized query terms, LitSense relevance-floor drops). It also discloses that LitSense rows are enriched with PubMed metadata, which an agent could not infer from the schema.

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

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

Three sentences, front-loaded with the purpose before moving to response shape and then per-source failure semantics. The parentheticals are dense but each carries real information (specific degradation examples), with no filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly compensates by documenting the envelope and error/warning channels, which is the highest-value gap to fill for a federated search. Parameters are fully covered by the schema; the only shortfall is the missing routing guidance relative to sibling retrieval tools.

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

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

Schema description coverage is 100% and the per-parameter docs (limit applied post-dedup, journal-name rewriting, offset caps, dateRange support matrix) are already thorough. The description adds only the LitSense row-shape detail and does not restate or extend the parameter meanings, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (search literature) plus a distinctive mechanism (federated search with deduplication across multiple backends), which separates it from article_get and preprint_fulltext. It never names a sibling or explicitly contrasts with single-article or gene-scoped retrieval tools, so the differentiation is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is the broad multi-backend search entry point but never says when to prefer it over article_get, gene_articles, or preprint_fulltext, nor when to restrict to a single source. The source-selection guidance that does exist (preprint_only, arxiv behavior, default federated scope) lives entirely in the schema field descriptions, not the prose.

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

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

Beyond readOnlyHint, the description discloses the default return shape (metadata with inline abstract), the conditional behavior of sections:["fulltext"] per source (PMC returns a file handle with file_path + outline and never body text; non-PMC returns explicit unavailable plus a reason), and crucially the partial-failure contract — a bad PMID yields a per-item error while the batch continues. That error-isolation semantics is exactly the kind of behavior the annotation cannot convey.

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

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

The default behavior is front-loaded and every clause carries operational information with no filler. The middle sentence is a long run-on that packs three conditional branches together, which slightly hurts scannability, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a batched read tool with one nested parameter and no output schema, the description covers defaults, per-entity-type return differences, the fulltext escape hatch, and per-item error handling — enough for an agent to call it and interpret results without trial and error.

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

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

Schema coverage is 100% and the nested item shape is fully specified, so the baseline is 3. The description earns above that by giving the only non-obvious value: sections:["fulltext"], including what that value does and how results differ for PMC vs non-PMC items — information the open-ended string array in the schema cannot supply.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource (get multiple entities) plus the key differentiator 'in parallel', which separates it from the many singular *_get siblings. It further scopes behavior to article items, but never states the tool is *only* for articles — the entity enum in the schema carries that breadth, leaving the description's stated purpose narrower than the tool actually is.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives one explicit routing rule: for inline text use article_get with fulltext_output="inline", which directly resolves the most likely confusion. It does not, however, say when to prefer batch_get over the singular siblings (gene_get, drug_get, etc.) or whether there is any overhead tradeoff for small batches, so the general when-to-use guidance 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.

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

Annotations already flag destructive and non-read-only, and the description adds real beyond-schema behavior: writes are atomic, nothing is written if any key is invalid, null restores defaults, sensitive keys demand confirm_sensitive, env values are masked to presence+fingerprint, and the write is refused outside a project root. It doesn't state whether a reset of a feature section is recoverable, which is the one gap for a destructive tool.

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

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

Front-loaded with what it covers, then actions, hard rules and examples — a well-organized layout for a complex tool. The opening clause ('unified observability and restricted controllability') is jargon that carries no operational information, and the examples block is long relative to the rest.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by describing the status response contents (settable_keys, config file health, conflicts, pending-restart flags, prerequisites). Combined with the restart workflow and error-path behavior, an agent has enough to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so per-parameter meaning is already documented; the description still adds value through worked examples, the null-removes-key convention, and the cross-parameter rule that confirm_sensitive is required when values touch connection targets or mirrors. The interaction with dry_run on both set and reset is clarified beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair (inspect/configure) and the exact resource (biomcp: three file-backed feature groups plus env-only parameters). The scope enumeration lets an agent distinguish it immediately from every sibling, which are all bio-data retrieval tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names each action and its trigger (status default with {}, set for atomic batch writes, reset for removals), states when to use filter instead of status, and excludes env parameters from set/reset. It also gives the operational sequence: finish prerequisites, restart once, re-call with {} to verify.

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

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

readOnlyHint already covers safety, and the description adds real behavioral detail: exact-match preference, case-insensitivity, cross-entity-type ranking order, demotion of numbered susceptibility-locus labels, and matched_on values ('exact'/'first'). That is substantive beyond the annotation. It does not describe result ordering stability or limits, so not a 5.

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

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

A single tightly packed sentence that front-loads the core purpose before ranking nuance. No filler, and every clause carries behavioral information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description's explanation of the matched_on field is valuable and helps the agent interpret results. Remaining gaps (result volume, what entity fields are returned) are minor for a single-param read-only lookup.

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

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

One parameter with 100% schema coverage, including examples in the schema, so baseline is 3. The description restates the concept of a free-text query but adds no syntax or format guidance beyond what the schema supplies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: resolves a free-text query to matching entities. The phrase 'across entity types' signals it is a cross-type resolver rather than a type-specific search, which distinguishes it implicitly from gene_search/disease_search, but no sibling is named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'free-text concept resolution' and the multi-type ranking behavior, so an agent can infer it is for when the entity type is unknown. There is no explicit when-to-use or when-not clause, and no named alternative such as gene_search for type-specific lookups.

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

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

Goes well past the readOnly/openWorld annotations: it discloses the ranking order (max clinical phase, then trial-report count), that salt forms are collapsed, and the envelope shape with errors[] semantics including a retryable flag. That is exactly the kind of post-call behavior an agent cannot get from 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.

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

Dense and front-loaded: purpose first, then ranking, then response shape. Only the trailing '(issue #130)' tracker reference fails to earn its place as agent-facing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so — envelope structure, ranking, and error taxonomy are all covered. What it omits is the per-drug result fields and any hint about valid disease ID namespaces, which matters because that is the required parameter.

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

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

Schema coverage is 50% (limit has no description at all) and the description never mentions limit or the expected disease_id format. It does add real signal about disease_id behavior — unresolved diseases land in errors[] rather than failing — which partially compensates but leaves the undocumented limit parameter unaddressed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — retrieve drugs associated with a disease — plus the upstream source (OpenTargets). The disease-scoped framing implicitly separates it from gene_drugs and drug_trials, though neither sibling is named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the 'for a disease' scoping; there is no explicit when-to-use, when-not, or pointer to the adjacent gene_drugs / drug_trials / disease_get tools. An agent can guess the context but gets no routing help.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: no mention of which sections are returned by default, whether missing IDs error or return empty, or that the response is compiled from external sources (open-world).

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

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

A single front-loaded sentence with no filler. It is efficient, though the terseness borders on under-specification rather than tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must carry the burden of explaining what 'detailed disease information' contains, and it does not — sections like gene_associations, phenotypes, and pathways go unmentioned. For a 3-parameter aggregation tool, this leaves the agent guessing about response contents and default scope.

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

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

Schema coverage is 67%, so disease_id is well documented in the schema with ID-format examples. However, the description says nothing about the 'sections' selector or the 'limit' cap, which are the two parameters most likely to change call behavior — it only restates the ID lookup.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Get') and resource ('detailed disease information') and the retrieval key ('by ID'). The 'by ID' phrasing implicitly separates it from disease_search, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'by ID' hints that this is a lookup for a known identifier, but the description never says when to use this instead of disease_search or the related disease_drugs/disease_trials tools, nor what to do if only a name is known.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuine value beyond that by declaring the response envelope shape ({ results, warnings?, errors? }), which matters since there is no output schema. It stops short of describing ranking or result content.

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

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

Two short sentences front-loaded with the core purpose and then the response shape. The trailing '(issue #130)' is internal issue-tracker noise that doesn't earn its place, a minor blemish.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only three-parameter search tool, the description plus a fully documented schema plus the disclosed envelope shape covers what an agent needs to invoke it correctly. Lacking only routing guidance relative to the many sibling search/get tools.

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

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

Schema description coverage is 100%, so query, limit, and offset are already fully documented with defaults and bounds. The description adds nothing beyond the schema for parameters, which is the expected baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Search for diseases') and enumerates the searchable facets (name, phenotype, keyword). It distinguishes itself from disease_get by the 'search' verb, though it doesn't explicitly say so.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus disease_get, gene_diseases, or other discovery tools. Usage is only implied by the verb 'search' and the mention of search facets.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real value by disclosing the response envelope shape (results, warnings, errors), but says nothing about pagination, truncation at the 50 limit, or ordering. The '(issue #130)' reference is internal noise rather than behavioral context.

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

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

Two compact sentences with the purpose front-loaded. The trailing issue-reference adds no value to an agent and is the only wasted token, keeping it just below 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description rightly explains the envelope return shape, which is the most important missing piece for a simple two-parameter read tool. It remains incomplete on the limit parameter's behavior and result ordering/pagination, which an agent needs to call it well.

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

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

Schema coverage is only 50%: disease_id's schema description is the tautological 'Disease ID', and limit has no description at all. The description repeats the disease scoping but explains nothing about the limit parameter's default of 20 or its 50 maximum, so it fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get clinical trials') scoped to a disease, which naturally separates it from drug_trials and trial_search in the sibling list. It does not name those siblings explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the required disease_id parameter — an agent can infer 'use when you have a disease and want its trials.' There is no explicit statement of when to prefer trial_search or drug_trials instead, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds little beyond "detailed" — no mention of what sections or return shape to expect, and no pagination or open-world nuance of its own.

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

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

A single tight sentence with no filler, front-loading the verb and resource. It is efficient but arguably over-terse for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a get-by-name tool with no output schema, the description is thin and never mentions the selectable sections or return content, forcing the agent to read the schema. The schema's detailed sections field partly fills this, keeping it at minimal viable rather than inadequate.

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

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

Schema coverage is 67%: the schema richly documents name and sections, but limit is undocumented. The description adds no parameter meaning whatsoever, so it fails to compensate for the coverage gap and just leans on the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ("Get") and resource ("detailed drug information") with the input mode "by name," letting an agent distinguish it from drug_search at a high level. It does not explicitly name or contrast with any sibling, keeping it below the top mark.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this versus drug_search or drug_trials, nor any prerequisite or exclusion. "By name" implies an identifier lookup but leaves the choice of tool to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: mechanism-style queries return nothing because MyChem has no mechanism text, which prevents a common failure. It does not mention pagination behavior or result shape, so it falls short of a 5.

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

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

Three tight sentences: positive scope first, the negative constraint second, the alternative third. No filler, and the most important routing information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only open-world search with no output schema and fully documented params, the definition covers what an agent needs: correct input type, the failure mode to avoid, and the alternative tool. Nothing essential is missing.

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

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

Schema coverage is 100%, so query, limit, and offset are all documented in the schema itself, and the description's note about chemical identity largely restates the query field. No extra syntax or format guidance beyond what the schema provides, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (search drugs) plus the scope (chemical identity: names, synonyms, identifiers in ChEMBL/MyChem), and explicitly names the sibling gene_drugs as the different tool. An agent can distinguish it from gene_drugs and drug_get 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when not to use it ('NOT a mechanism or target search') and gives the concrete alternative (gene_drugs with the target gene symbol) with example queries that select each path. This is textbook when/when-not/alternative routing.

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

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

Annotations already declare readOnlyHint=true, so safety is covered and the bar is lower. Beyond that the description adds nothing: no indication of return shape, result volume, pagination, or what identifier namespaces the drug must come from (e.g., must it match drug_search output).

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

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

One short, front-loaded clause with zero waste. It is efficient but borders on under-specification for a tool that has several look-alike siblings, so not a full 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one required param, read-only, no output schema), so little is needed, and the annotation plus schema cover the mechanics. Still missing is any hint of what the returned trials contain or how results are bounded, which an agent would want before calling.

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

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

A single parameter with 100% schema description coverage, so the schema already carries the semantics; the description's 'for a drug' merely restates it. Baseline 3 applies since the schema does the heavy lifting and the description adds no format or naming guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (find) and resource (clinical trials) scoped to a drug, so the agent knows exactly what it retrieves. It does not differentiate from close siblings like gene_trials, disease_trials, variant_trials, or trial_search, leaving the agent to infer the distinction from parameter shape alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'for a drug' phrasing implies the use case (you have a drug identifier and want trials), but there are no explicit when-to-use rules, no named alternatives, and no exclusions against the four trial-adjacent siblings in the toolset.

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

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

Annotations already declare readOnly and open-world, so safety is covered; the description adds genuine behavioral detail beyond that — automatic retry against the bare RefSeq accession when a version is stale, with the reinterpretation flagged in warnings, and invalid input surfacing the upstream VEP error explaining what could not be mapped. It also discloses the return payload (most severe consequence, per-transcript impact/codon change, SIFT/PolyPhen, co-located ClinVar/COSMIC/gnomAD data) with no output schema to do that work. Slightly short of a 5 only because rate limits or latency for on-demand VEP computation are not mentioned.

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

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

Front-loaded with the capability that differentiates it, then organized into labeled input-forms / per-species / returns / alternative sections. Dense but every paragraph carries operational information; the parenthetical worked examples (mouse Trp53, human NM_ rejected by species 'mouse') are justified given how easy that misuse is.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A three-parameter tool with no output schema, yet the description covers input syntax, species validity constraints, failure behavior, and the shape of the returned consequence data. Nothing an agent needs to invoke it correctly or interpret the response is missing.

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

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 goes well beyond the schema for the two non-trivial parameters: it enumerates accepted variant syntaxes (c./p./g. HGVS with or without version, rsID), gives concrete examples, and states the per-species validity rule that NM_ accessions only work when the transcript belongs to that species. The 'limit' parameter is left entirely to the schema, which is the only reason this is not a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (predict functional consequence) and resource (variant), and immediately scopes it with two differentiators no sibling claims: works on novel variants absent from any database, and works for non-human species. An agent can distinguish it from variant_get and variant_search from the first sentence alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rules: prefer HGVS over rsIDs when both are available and explains why (dbSNP coordinate mapping yields less specific consequences); for known human variants prefer variant_get because it adds CADD/REVEL/AlphaMissense/ClinVar stars. Both the when-to-use and the when-to-use-something-else cases are named with reasons.

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

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

Annotations already declare readOnly and openWorld, so the description adds real value with return semantics: stable IDs, gene symbols when available, species, taxonomy level, percent identity, sorted by identity. It also notes the input form (HGNC symbol or Ensembl ID). No output schema exists, so this return-shape disclosure is the main behavioral signal, though pagination/truncation behavior at the limit cap isn't discussed.

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

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

Front-loads purpose and the key differentiator before the return-field list and usage examples. Each sentence carries content, though the example parentheticals (ARAF/RAF1 for BRAF) are slightly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, six-parameter lookup with no output schema, the description covers purpose, input forms, scoping, and return fields, which is enough to call it correctly. It does not mention what happens on empty results or invalid species names, a minor gap.

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

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

With 100% schema coverage the baseline is 3, and the description still adds meaning beyond the schema: it explains the gene parameter accepts symbols or Ensembl IDs, demonstrates target_species ('mouse') and target_taxon (10090), and notes results are sorted by identity — clarifying how limit interacts with ordering.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Find orthologues or paralogues of a gene across species') and grounds it in the Ensembl Compara source, which separates it from the sibling ensembl_lookup/consequence/region tools that operate on a single gene or region. An agent can tell immediately what this returns: cross-species mappings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete trigger questions ('is this gene conserved?', 'what is the mouse orthologue of BRAF?') and explains how to narrow scope via target_species or target_taxon with an example value. It implies positioning ('the cross-species gene mapping source') without explicitly naming a sibling to use instead for within-species lookups.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavior: 356 species, versioned IDs resolved to the current record, and expand returning all transcripts with translation/protein IDs. It does not describe error or ambiguity handling, so it falls short of the richest behavioral disclosure.

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

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

Three tightly written sentences, front-loaded with the core purpose, then input/species behavior, then the sibling-tool boundary. Parenthetical examples earn their place and no sentence is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still explains the key return content: stable ID, symbol↔ID mapping, canonical transcript, coordinates, and expanded transcripts with protein IDs. It is complete enough to call correctly, though it could say more about response shape or edge-case behavior.

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

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 schema already explains gene_or_id, species, and expand. The description still adds semantic value by clarifying that versioned and bare IDs are resolved to the current record and by giving species aliases across the 356-species scope.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Uses a specific verb and resource: 'Resolve a gene in Ensembl terms', then enumerates stable ID, symbol↔ID mapping, versioned identifiers, canonical transcript, and coordinates. It explicitly distinguishes itself from gene_get, so an agent can select it without opening sibling schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the exact use case (ANY Ensembl species), accepted inputs, species aliases, and the effect of expand=true. It also names the alternative gene_get for rich human annotation, making the boundary between the two tools explicit.

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

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

Annotations already declare readOnly/openWorld, and the description goes further: it discloses the 50 kb variation window cap centered on midpoint, the echo fields effective_variation_window and variation_truncated, upstream timeout risk, and an output limit with truncation marker. This is unusually rich disclosure of behavior beyond annotations.

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

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

Front-loaded with the core purpose, then a clear layered structure (use case, cap behavior, limits, alternatives). Dense but every sentence carries information; the parenthetical field names are somewhat packed but earn their place. Slightly long for the tool's size.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description explains the notable return fields (effective_variation_window, variation_truncated, truncated marker), so an agent understands what it gets back. Combined with the cap and limit behavior, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics — the 50 kb cap applies to variation over the region span, and limit caps returned features with a truncated marker. It clarifies the region/cap interaction not spelled out in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('query what lives in') and resource (genomic interval) and enumerates the entities returned (genes/transcripts with IDs, symbols, biotypes; variants with rsIDs, alleles, consequence, clinical significance). It is immediately distinguishable from entity-level siblings like gene_get and variant_get, which it names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit use case ('ideal for locus triage — what genes and known variants sit in this GWAS hit interval?'), explicit routing away to alternatives ('for sequence text use genbank_get; for entity-level annotation chain IDs into gene_get / variant_get'), and the alternative approach for large sweeps ('issue adjacent region calls').

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-network profile is covered. The description still adds substantive value beyond that: it identifies the return values as NCBI entrezgene IDs (not symbols) and warns that they cannot be fed directly into gene_get, which prevents a real downstream misuse. It does not cover failure/empty-result behavior or rate limits, so not a 5.

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

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

The core mapping statement is front-loaded and the crucial caveat (numeric id ≠ symbol) follows immediately. The id→symbol bridge sentence is somewhat repetitive of the preceding sentence and could be tightened, but every element carries useful routing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description correctly takes on the job of saying what comes back (a list of entrezgene IDs) and how to use it. What an agent still can't tell is cardinality or the behavior when an accession has no linked gene, which is a modest but real gap for a 1-param lookup.

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

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

Only one parameter and schema description coverage is 100%, with the pattern and versioned/bare examples (NG_017013.2, NC_000023.11) already documented in the schema. The description adds no further parameter guidance, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+mechanism: 'Map a GenBank/RefSeq nucleotide accession to its NCBI Gene IDs (elink nuccore→gene).' That distinguishes it from genbank_search/genbank_get (which retrieve records) and from gene_get/gene_search (which operate on symbols or gene queries), so an agent can route 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames the use case as a bridge from a sequence record to gene-level annotation, and names the downstream chain: gene_get takes a symbol not an entrez id, and gene_search rows carry both symbol and entrez_id, so the id→symbol bridge exists via gene_search. This is concrete when-to-use plus named alternatives rather than inference.

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

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

Goes well beyond the readOnly/openWorld annotations: discloses the 2 Mb whole-record cap, the 1,000-character inline threshold, file-mode caching with path/char counts, cache ephemerality (~7 days / 500 files), server-local path caveat, the 200,000-char inline cap, and that max_response_bytes errors rather than truncates.

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

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

Front-loaded with purpose and the size caps, and nearly every clause carries operational information. Some redundancy remains — the file/inline tradeoff is explained in the prose and again in the sequence_output schema description, which lengthens an already dense paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Seven parameters, two enums, and no output schema, so the description bears the full burden of describing returns — it does, enumerating sequence_text/char_count/truncated versus mode/file_path/char_count/total_char_count. An agent has everything needed to call and interpret results.

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

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

Schema coverage is already 100%, yet the description adds genuinely non-obvious semantics: the reverse-strand slice convention (strand=2 with seq_start > seq_stop), and the fact that the echoed region field preserves the request order while NCBI text renders complement(min..max). That resolves a real ambiguity the schema cannot express.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Fetch a GenBank/RefSeq nucleotide record as text', and names both output formats. The distinction from the sibling genbank_search (search vs. fetch by accession) is implied by the name and required accession parameter but never stated explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives conditional guidance for parameters — region required for records over 2 Mb, inline mode only if server-side files are unreadable — but never says when to choose this over genbank_search, sra_get, or ensembl_region. Usage must be inferred from the verb.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-corpus profile is covered. The description adds useful value by enumerating the returned fields (accession.version, definition, length_bp, organism, topology), but says nothing about result caps, pagination behavior, or rate limiting on an open-world NCBI endpoint.

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

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

Two sentences, front-loaded with the resource and scope, then the query modes, then the return fields and handoff. No filler; every clause carries information an agent would act on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by listing the fields returned, and it closes the loop on pagination-adjacent workflow by pointing to genbank_get/genbank_genes. It could be more complete by noting the default result limit of 10 or that offset pages through a possibly large hit count.

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

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

Schema coverage is 100%, so query, organism, limit, and offset are all documented in the schema itself, and the description's query-syntax examples largely duplicate the schema's own example. Baseline 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Search NCBI nucleotide records') and scopes the corpus explicitly (GenBank/RefSeq/INSDC). It also names the downstream siblings (genbank_get, genbank_genes), so an agent can distinguish this from gene_search, variant_search, and sra_search 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete query-form guidance (plain terms, accession, or field syntax with worked examples) plus a next-step routing hint to genbank_get/genbank_genes. It lacks explicit negative guidance — nothing says when to prefer sra_search or gene_search instead — so it falls short of a 5.

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

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

Annotations only declare readOnlyHint=true; the description adds real value beyond that by spelling out the response envelope and, critically, that per-backend failures arrive in `errors` and never as items inside `results`, plus degradation notes in `warnings`. This is exactly the kind of non-obvious contract an agent needs to avoid misreading partial failures as empty results. No pagination or result-count guidance, keeping it from a 5.

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

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

Two sentences, purpose front-loaded, then the response contract. Every clause carries information. The trailing '(issue #130)' is internal tracking noise that adds nothing for an agent, a minor blemish.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly shoulders the burden of explaining the return shape, including error and warning semantics. For a one-parameter read tool that is nearly complete; only result volume/pagination behavior is unaddressed.

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

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

Schema coverage is 100% and the single `symbol` parameter is documented there as an HGNC gene symbol, so the schema does the work. The description adds no format, casing, or multi-symbol guidance beyond it. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Find articles about a gene.' An agent can immediately tell this is a gene-scoped article lookup, distinct from a generic article search. It stops short of naming the sibling (article_search) it should be weighed against, so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The gene-scoped framing implies when to use it — when you have a gene symbol and want literature — but there is no explicit when-to-use rule and no mention of article_search as the alternative for free-text or topic queries. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely valuable behavioral context beyond that: a required DISGENET_API_KEY environment variable and a documented fallback to OpenTargets associations when it's absent, which tells the agent results may come from different sources.

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

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

Two sentences, purpose front-loaded, and the environment/fallback caveat follows immediately. Nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should hint at what is returned (disease names, association scores, sources), but it doesn't. The data-source fallback is well covered, but the undocumented 'limit' parameter and unstated return shape leave gaps.

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

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

Schema coverage is 50%: 'symbol' is documented as an HGNC gene symbol in the schema, but 'limit' (default 10, max 50) is undocumented anywhere. The description adds no parameter-level detail, so it neither compensates for the gap nor harms; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (get diseases associated with a gene), which is unambiguous and distinguishable from gene_get or disease_search by direction of the lookup. It doesn't explicitly name a sibling to contrast with, but the scope is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case (find diseases for a given gene) but gives no explicit when-to-use guidance, no exclusions, and doesn't point to alternatives like disease_search for the reverse lookup or gene_drugs for the drug angle. The API-key/fallback note is about data source, not tool selection.

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

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

Beyond the readOnlyHint annotation, the description discloses meaningful behavioral traits: ranking by max clinical phase then trial-report count, salt-form collapsing, and an envelope response with warnings and structured errors. It also explains how OpenTargets failures and unresolved genes appear in errors[] rather than inline results.

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

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

The purpose is front-loaded and the description is compact. However, the issue references "(#130, #179)" add internal noise that does not help an agent invoke the tool correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only tool with no output schema, the description covers the important behavioral context: ranking, salt-form collapsing, and the response envelope with error semantics. It does not describe the fields of individual drug result items, leaving a minor gap in return-value detail.

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

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

Schema description coverage is 100%, and the single symbol parameter is fully documented in the schema as an HGNC gene symbol. The description does not add meaning beyond that, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: "Find drugs targeting a gene." It is clear what the tool returns conceptually, but it does not explicitly differentiate this from sibling tools such as drug_search, gene_get, or gene_trials.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case of finding drugs for a gene, but it gives no explicit when-to-use guidance, exclusions, or alternatives. An agent must infer from the name and sibling list whether to call this versus gene_trials or drug_search.

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

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

Goes well beyond the readOnlyHint annotation: discloses deduplication behavior, how genes_overlap is resolved via a follow-up entity lookup and why it can exceed the submitted gene count, expected latency (15–45 s, worst case ~105 s with retries), external reachability of reactome.org, and a concrete client-timeout caveat. This is exactly the operational context annotations cannot convey.

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

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

Front-loaded with the purpose and hard requirement, then layers operational detail. It is long and somewhat run-on in the genes_overlap and timeout sentences, but nearly every clause carries useful information, so waste is minimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by explaining return semantics (genes_overlap count, total pathways found vs. returned page) and the two-step timing profile. An agent has enough to call it correctly and set expectations for latency and result interpretation.

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

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

Schema coverage is 100% and the schema already documents both parameters, including the min-3 rule, dedup behavior, and the 1–100 limit range. The description restates the gene-list constraints without adding new syntax or format guidance, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Perform pathway enrichment analysis for a gene list') and names the underlying method (Reactome over-representation), which distinguishes it from the many gene_* retrieval siblings like gene_diseases or gene_drugs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear preconditions for use — at least 3 genes, list deduplicated case-insensitively — and implies the scenario (you have a gene list and want pathways). It does not name an alternative tool or say when not to use it, so it stops short of the top score.

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

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

Annotations already cover the read-only/open-world safety profile, so the bar is lower, and the description clears it by disclosing real behavior: response section keys mirror requested section names and legacy storage keys (civic, hpa, clingen, disgenet) never appear. It omits other useful behavior — what happens for an unknown symbol, what limit constrains, and cost/latency of heavy sections like all.

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

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

Purpose is front-loaded in the first clause, and the second sentence carries the high-value key-mapping caveat. The mapping sentence is dense with repeated quoted examples and the "legacy storage keys never appear" clause is slightly verbose, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description sensibly explains the response envelope's key structure, which is the most important return detail. However, for a 4-parameter lookup with a 16-value section enum it should also cover failure modes (invalid/unknown symbol), what limit governs, and how expensive "all" is.

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

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

Schema coverage is 75% and symbol/smart are well documented there, but the sections param is described only as "Sections to include". The description adds the missing meaning by mapping section values to the exact response keys returned, which is information the schema does not provide. The limit parameter remains unexplained in both places.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Get detailed gene information by symbol") with the required key (symbol). It is clearly a single-entity lookup, but it never names the sibling it differs from (gene_search vs gene_get), so an agent must infer the distinction from naming convention alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: "by symbol" suggests you already have a valid HGNC symbol, and the note about legacy storage keys hints at the section-selection workflow. No explicit when-to-use/when-not-to-use guidance and no alternative tool (gene_search, gene_diseases, gene_drugs) is referenced, even though several siblings cover overlapping data.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and scope are covered externally. The description adds nothing beyond those hints — no note on matching behavior (fuzzy vs exact symbol match), result ordering, or how to page through large hit sets.

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

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

One compact sentence with the resource and match criteria front-loaded and no filler. It is appropriately sized, though its brevity edges into under-specification rather than pure efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only search with 100% schema coverage and no output schema, the definition is minimally sufficient to call the tool. It still omits result shape, whether paging is expected, and how matches are ranked, so an agent gets no help interpreting the response.

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

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

Schema description coverage is 100%, so all four parameters (query, chromosome, limit, offset) are already documented in the schema, and that sets the baseline at 3. The description only echoes the query parameter's three modes and ignores the chromosome filter, limit, and offset, adding no extra meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search) and resource (genes) plus the match fields (symbol, name, keyword), so the operation is unambiguous. It does not distinguish itself from siblings like gene_get or gene_diseases, leaving the search-vs-lookup split to inference from the names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says what can be searched but never when to pick this over gene_get (exact retrieval) or gene_enrich (set-based analysis). An agent must infer from the tool names that search is for discovery when no identifier is known.

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

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

The readOnlyHint annotation already establishes that this is a safe read-only lookup, and the description does not contradict that. It adds no behavioral context beyond the annotation, such as result limits, data source, or whether the gene-to-trial association is direct or inferred.

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

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

The description is a single front-loaded sentence with no wasted text. It is appropriately sized for a simple one-parameter lookup tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity, one-parameter read-only lookup, the description plus the fully documented schema and readOnlyHint are mostly sufficient. The main gap is that it does not clarify expected results or relationship to the broader trial_search family, but invocation is still clear.

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

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

Schema coverage is 100%, and the single parameter is documented as an HGNC gene symbol. The description's phrase 'for a gene' reinforces the parameter's purpose but adds no format or lookup details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Find clinical trials,' scoped explicitly to 'a gene.' This distinguishes it from sibling tools such as drug_trials, disease_trials, and variant_trials by the entity the search is based on.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The scope implies that the tool should be used when looking up clinical trials associated with a gene. However, the description does not explicitly say when to prefer this over trial_search, drug_trials, disease_trials, or variant_trials, so routing remains partly inferred.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true; the description explains why a 'get' is not read-only — download=true writes a supplementary file to a local temp path and returns path/size/source URL. It also discloses the non-obvious GDS behavior (structured guidance returned as a successful result, not an error) and that malformed accessions fail schema validation, which is exactly the context an agent needs to interpret results.

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

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

Front-loaded with the core purpose in the first sentence, then chaining, then edge cases in descending priority — good ordering. The download paragraph duplicates the schema's file-preference wording and could be trimmed to a pointer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must describe returns and does so for series (summary, organisms, platform_ids, sample preview, supplementary URLs, cross-references), for GDS, and for download. Return shapes for GSM sample and GPL platform records are left unspecified, a minor but real gap.

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

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

Schema description coverage is 100%, and the schema already documents the .gz/.csv/.txt preference and the max_bytes default, so the description largely restates structured data. It adds the 'subject to max_bytes' linkage between download and the size cap, but nothing beyond that; baseline 3 is appropriate when the schema carries the weight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get the full SOFT record details for a GEO entry') and immediately enumerates the three accession families (GSE/GSM/GPL), which cleanly separates it from the geo_search sibling. An agent knows this is the record-fetch step, not the discovery step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly maps returned cross-references to the follow-up tools (sra → sra_get, pubmed_ids → article_get, samples → geo_get(GSM...), platform_ids → geo_get(GPL...)), giving strong chaining context, and explains what happens with GDS accessions. It does not state the inverse condition (use geo_search first to obtain an accession), so the routing is clear but not fully bidirectional.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds valuable behavioral detail beyond that: every result carries accession, bioproject, and pubmed_ids, and sra_project appears only when NCBI has linked the SRA study. The caveat that geo_get is the reliable route to SRA accessions is especially useful and not conveyed by annotations.

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

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

The description is front-loaded with the primary purpose, then efficiently adds query syntax and downstream-routing details. Every sentence carries useful information, including the important conditional caveat about sra_project, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although there is no output schema, the description compensates by naming the key result fields and explaining the conditional sra_project behavior. It also routes agents to geo_get, article_get, and sra_get appropriately, making it complete enough to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds meaningful query semantics by showing both plain-term and NCBI field-syntax forms, which goes beyond the schema’s free-text examples, though it does not add per-parameter details for organism or entry_type beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: searching NCBI GEO for functional genomics studies, with concrete scope including expression microarrays, RNA-seq, and high-throughput sequencing series. It also implicitly differentiates from geo_get by explaining that search results carry accessions that can be passed to geo_get for full details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context by explaining that queries accept plain terms or NCBI field syntax and by naming downstream tools for accessions, PubMed IDs, and SRA projects. It does not explicitly state when to prefer geo_search over sibling searches such as sra_search or genbank_search, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds genuinely new behavioral context beyond that — results are pre-filtered to significant associations, sorted ascending by p-value, and empty results carry an explanatory note rather than signaling failure. It does not mention the limit's truncation effects or pagination, but the value added is substantial.

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

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

Three short, front-loaded blocks: what it returns and how it's sorted first, required-parameter format second, and the empty-result caveat last. Every sentence carries operational value, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so completely: named fields, sort order, and the meaning of an empty result plus its accompanying note. An agent has everything needed to call it and interpret the response.

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

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

Schema description coverage is 100%, so gene, tissue, and limit are already documented; the description only reinforces tissue examples and format. It adds marginal param meaning (significance filtering and ascending p-value ordering) rather than new per-parameter semantics, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get significant cis-eQTL associations for a gene in a specific GTEx tissue') and enumerates the returned fields with a defined sort order. It is clearly distinguishable from sibling gtex_expression (expression levels) and from variant-level tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete usage context: tissue is required and must be a GTEx tissueSiteDetailId, with examples. It anticipates the main misread (empty list = valid negative result) and explains the fallback note. It does not explicitly route to an alternative tool (e.g., gtex_expression) when the goal is expression rather than eQTLs.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds real context on top: dataset version (v10), 54 tissue sites, TPM normalization, and descending sort order. It stops short of noting that the default limit (20) truncates below the full 54 tissues or what occurs for an unknown gene/tissue.

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

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

Two tight sentences, zero filler, with the core operation and dataset scope front-loaded and the input/optional-filter details second. Every clause (v10, 54 tissues, TPM, sort order) carries information an agent can act on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully characterizes the return (median TPM per tissue, ordered highest first). It is nearly complete for a read-only lookup, but omits how limit interacts with the 54-tissue ceiling and what the response looks like when a gene or tissue matches nothing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, and the description largely restates them (gene formats, tissue example). It adds no semantics beyond the schema, such as case sensitivity for tissue IDs or how invalid tissue strings are handled, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get median gene expression across GTEx tissues') plus concrete dataset facts: GTEx Analysis v10, 54 tissue sites, TPM units, sorted highest first. That is enough to separate it from the only close sibling, gtex_eqtl, but the description never names that sibling or explicitly contrasts expression levels with eQTL associations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: accepts an HGNC symbol or Ensembl ID and optionally a tissueSiteDetailId filter. There is no statement about when to prefer this over gtex_eqtl, gene_get, or ensembl_lookup, and no guidance on behavior when a gene has no GTEx data.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds real behavioral context by enumerating the return payload (since there is no output schema) and noting that exact ISSN lookups collapse to a single result while name searches can return up to `limit`. It does not describe what happens on no-match or ambiguous name matches, which is the main remaining gap.

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

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

Two sentences, both front-loaded: the first delivers purpose plus return shape, the second delivers accepted inputs plus the chaining hint. The long metric enumeration earns its space because there is no output schema to carry it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of explaining returns and does so thoroughly, and both parameters are covered. It is not fully complete because match-ambiguity behavior and failure modes for an unrecognized journal are unstated, which matters for a read-only open-world lookup.

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

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 genuinely adds meaning beyond the schema by noting that ISSNs live on article records (a data-source hint absent from the property description) and by clarifying the accepted identifier classes. The `limit` semantics are restated rather than extended, so it is not a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb+resource framing ('Journal quality metrics') and immediately enumerates what is returned: OpenAlex 2-year mean citedness, h-index, i10-index, citation counts, is_oa, and quality-list tiers. It also positions the tool relative to the well-known Clarivate impact factor, so an agent knows exactly what this produces and how it differs from a familiar alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a concrete workflow hint that no sibling tool offers: ISSN input can be sourced from 'article records carry journal_issn', which tells an agent how to chain this from article_search/article_get. What it does not do is state when-not to use it or name any sibling alternative, so it falls short of the full when/when-not/alternatives bar.

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

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

Goes well beyond the readOnly/openWorld annotations: it enumerates available sections, names per-section data sources (USPTO PPUBS, EPO OPS, Google Patents), documents the claim-rendering fallback, explains _warnings flagging, and clarifies that section failures are reported inline rather than failing the whole call. This is exactly the behavioral context an agent needs.

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

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

Front-loads the core action and examples, then layers on source/fallback detail. Dense but purposeful; the parenthetical source note and warning behavior each earn their place. Slightly heavy with nested parentheticals.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden and does so: it covers what sections return, how failures degrade gracefully, and how provenance is surfaced. An agent can call this correctly and interpret results without further documentation.

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

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 meaning by explaining what each requested section yields and that source provenance varies per section. It doesn't detail the limit parameter's per-array semantics, keeping it just short of the top.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Get) + resource (patent details) + lookup key (publication number) with concrete format examples. Clearly distinguishes this single-record retrieval from the sibling patent_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'by publication number' framing implies this is the detail-fetch step after finding an ID, but it never explicitly says to use patent_search first nor states any when-not conditions. Usage is inferable rather than stated.

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

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

Consistent with readOnlyHint/openWorldHint and adds substantial context annotations cannot carry: per-backend auth requirements (EPO_OPS_CONSUMER_KEY, USPTO_API_KEY), the auto-mode concurrency and single-fallback-to-uspto_odp behavior, the fact that degradation surfaces in `errors`/`warnings` out of band, that every `patents` element is real and respects `limit`, and that seminal_prior_art is auto-mined from top-result co-citations. This is exactly the invisible behavior an agent needs.

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

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

The backend inventory is a single pipe-delimited run-on with stacked parentheticals that is hard to parse, and the quoting advice is duplicated verbatim from the `query` schema description. It is front-loaded correctly and most sentences carry information, but the density costs readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 11 parameters and no output schema, the description covers the response shape (patents, errors, warnings, seminal_prior_art), credential prerequisites, fallback behavior, and latency tradeoffs. An agent has everything needed to call this correctly and interpret partial results.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds real meaning beyond the schema by explaining what `source` selection implies (forced backend vs. auto) and that sort_by relevance ranking 'currently affects the ppubs backend only', which the enum alone does not convey. Filter parameters like cpc/assignee/date_range are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+scope: 'Search patents worldwide (US, EP, WO, JP, and 100+ authorities)', and it further carves out what kind of search it is (full-text conceptual, bibliographic, prior-art discovery). Against sibling patent_get the search-vs-fetch distinction is unambiguous, so an agent can route 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational guidance on backend choice: what each backend covers, what credentials it needs, what the default auto mode does, and 'Pass source to force a specific backend'. It also flags the seminal=true cost (~5-30s) and when to disable it. It stops short of naming an explicit alternative tool (e.g. patent_get for a known patent number), so it is not a full when/when-not treatment.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true; the description is consistent with this by noting that download writes a file to disk and returns the path. It also adds genuine non-schema behavior: per-record {_error} items and a top-level warnings array when section records partially fail. Missing only auth/rate-limit info, which would push it to a 5.

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

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

Front-loaded with the tool's purpose, then cleanly segmented into SEARCH/GET/DOWNLOAD labels. The warnings sentence is dense but carries unique behavior, and there is no filler; slightly tightening the section-records clause would make it a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 7 optional parameters, no output schema, and only minimal annotations, the description does the heavy lifting needed for correct invocation: mode selection, file-writing behavior, and error/warning handling. Return-value detail is only partially covered for search results, keeping it just shy of a 5.

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

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

Schema description coverage is 100%, so every parameter (query, pdb_id, format, sections, limit, offset, download) is already documented in the schema. The description reinforces mode combinations (query omits pdb_id; sections list per-entity records) but adds no syntax or format detail beyond what the schema provides, so baseline 3 fits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb/resource ('Access the Protein Data Bank for macromolecular structure data') and explicitly breaks the tool into three distinct operations (SEARCH, GET, DOWNLOAD). An agent can immediately tell what the tool does and which operation it needs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit mode-selection rules: use query to search, pdb_id to get metadata, pdb_id + download=true to save the file. The omission of a 'when not to use' or sibling comparison is minor since no other PDB tool exists in the sibling list, but the conditional guidance per mode is clear.

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

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

Annotations only declare readOnly/openWorld, but the description adds substantial operational context: per-(doi,version) caching, immutability of JATS per version, aggressive rate limiting with >=60s cooldown, 429/Cloudflare handling, retry_after_sec envelopes, and per-article license carriage. This is exactly the kind of behavior an agent needs and cannot get from annotations.

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

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

Dense but front-loaded: purpose, input, on-demand policy, rate-limit behavior, license, output modes in a logical order. It is longer than strictly necessary — the rate-limit and caching points are each stated with some redundancy — but nearly every sentence carries operational value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema, the description fully explains both return shapes (file_path + outline vs. capped inline sections) and the failure envelope. Combined with the four fully documented parameters, an agent has everything needed to invoke it correctly.

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

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 further by explaining why version is cacheable (immutable JATS per version), that fulltext_max_chars is inline-only and ignored in file mode, and that pinned versions serve with zero network. Sibling-tool rejection of journal DOIs is also reinforced.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("preprint full text" from bioRxiv/medRxiv, JATS XML parsed to sections) and names the DOI input format. It is clearly distinguishable from article_get, which the schema explicitly routes journal-article identifiers to.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says downloads are strictly on-demand and never run during search, and redirects corpus-scale text mining to the bioRxiv/medRxiv S3 buckets. It does not, however, directly name the sibling to use for journal articles or for metadata-only lookups within the description text itself.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses that coverage spans NCBI, ENA, and DDBJ submissions and specifies the payload shape per accession type. It stops short of noting error behavior for unknown accessions or any rate/latency considerations, keeping it at 4 rather than 5.

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

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

Two short paragraphs with no filler: the capability and prefix taxonomy lead, and the chaining guidance follows. Every clause adds either scope, coverage, or routing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With only one parameter, no output schema, and annotations covering safety, the description covers everything an agent needs: what accession to pass, where to obtain it, what each type returns, and cross-database prefix coverage. Nothing material is missing.

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

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

Schema coverage is 100% and includes a regex plus example, so the schema already carries the syntax burden. The description goes further by mapping each prefix family (SRR/ERR/DRR, SRX/ERX/DRX, etc.) to the entity and returned content, giving the agent semantic meaning beyond the pattern.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Get full details for an SRA accession") and immediately enumerates the four accession classes (run/experiment/study/sample) plus what each yields, so an agent knows exactly what comes back before calling. It is clearly distinguished from sra_search (search) and geo_get (upstream source) by name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: "Chain from geo_get (sra field) or sra_search (experiment_accession / first_run_accession)," naming the fields that supply the argument. It also preempts a likely failure mode by noting that ENA and DDBJ-prefixed accessions returned by sra_search resolve here, so the agent doesn't hesitate on non-SRR ids.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds real value by enumerating exactly what is returned (experiment/study/sample accessions, organism, library strategy, run count, first_run_accession) and noting cross-database accession prefixes (SRA/ENA/DDBJ) are all resolvable downstream. Pagination behavior and empty-result handling are left to the schema.

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

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

Two sentences, front-loaded with the core purpose, followed by supported query forms and the return/result-chaining contract. Slight redundancy with the schema's query description, but no padding or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing return content and does so concretely, including which fields enable chaining into sra_get. What remains unstated (pagination defaults, error/no-match behavior) is minor and largely covered by the schema parameters.

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

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

Schema description coverage is 100%, so the query, limit, and offset semantics are already documented in the schema. The description restates the query forms (free text, accession, field syntax), which adds only marginal meaning beyond the schema's own description of the same parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search) and resource (NCBI SRA for sequencing experiments and runs) and explicitly distinguishes itself from the sibling sra_get by noting results are 'all resolvable by sra_get' and that first_run_accession is 'for chaining into sra_get'. An agent can differentiate it from geo_search or genbank_search by the resource named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the accepted query forms (free text, accession, NCBI field syntax) and routes to sra_get for detail retrieval, which clarifies the search-then-fetch workflow. It stops short of explicit when-not-to-use guidance (e.g., preferring geo_search for GEO series or genbank_search for nucleotides), leaving that to inference from the resource name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. Beyond that the description adds nothing: it does not say what 'detailed' means, that results can be scoped by the sections array, or how the limit parameter affects the response.

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

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

A single front-loaded sentence with no waste, but the terseness comes at the cost of under-specification rather than efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must convey what a 'detailed' result contains and how sections/limit shape it; it does neither. For a 3-parameter retrieval tool this leaves the agent guessing about response scope.

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

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

Schema coverage is 67%; nct_id and sections have inline descriptions but limit has none. The description mentions only nct_id and ignores the sections parameter, which materially changes what comes back (core/eligibility/locations/outcomes/all) — the most important parameter to explain is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb (Get) and resource (detailed trial information) plus the lookup key (NCT ID). It does not distinguish itself from the sibling trial_search, which is presumably the search-based counterpart, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'by NCT ID' implies this is the keyed-lookup counterpart to trial_search, but the description never names the alternative or states when to prefer it. Usage is inferable rather than explicit, and no prerequisites are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond what the schema states—no mention of result ordering, pagination behavior via page_token, or the size/nature of the underlying registry.

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

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

A single efficient sentence with no waste, and the core action is front-loaded. It is arguably clipped to the point of under-specification, but as a conciseness measure it is tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter search tool in a crowded sibling set with no output schema, the description is too thin: it omits pagination behavior, relative positioning versus the other trial tools, and any sense of result shape or scale. An agent can invoke it but has little help invoking it correctly among alternatives.

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

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

Schema description coverage is 100%, so all six parameters including phase, status, intervention_type, and page_token are documented in the schema itself, some with verifiability notes. The description restates the query facets but adds no semantics beyond the schema, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Search clinical trials") plus the searchable facets, so the basic operation is clear. However, with six sibling trial-related tools (trial_get, drug_trials, gene_trials, disease_trials, variant_trials, discover), the description gives no clue how this differs from them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no exclusions, and no named alternatives. An agent cannot tell from the description whether to use trial_search, trial_get, or the entity-scoped *_trials siblings for a given request.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds real behavioral payload beyond them: the guaranteed top-level core fields, the key-mirroring rule for response sections, and the guarantee that the legacy 'alphagenome' key never surfaces. It omits the failure mode of the alphagenome_scores section and what limit actually constrains, but the response-shape disclosure is valuable.

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

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

Purpose is front-loaded in the first sentence, followed by return-shape facts in a logical order with no filler. The final sentence on the legacy key is slightly niche but earns its place as an anti-confusion rule for agents parsing responses.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the needed work of describing the return envelope (core fields at top level, section keys mirroring requests). Combined with the thorough id schema and the safety annotations, an agent has enough to call it; only the unexplained limit parameter and the unmentioned error stub keep it short of full completeness.

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

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

Schema coverage is 67%: id and sections are richly documented in the schema itself, so the description's main contribution is the section-name-to-response-key mapping, which is genuinely additive. The limit parameter has no description anywhere, and the description doesn't explain what it limits in a single-variant lookup, leaving a real semantic gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("Get detailed variant information") and clarifies that core fields are always returned while others are opt-in. It clearly reads as a detail-fetch counterpart to variant_search, though it never names that sibling explicitly to differentiate the two.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use sections to request additional data" gives guidance on how to widen the response, which implies the default lightweight path. However, there is no explicit when-to-use condition versus variant_search, no prerequisite notes, and no warning that one of the listed sections fails.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-call behavior are covered. The description adds a genuinely useful operational prerequisite not present in structured fields – the ONCOKB_TOKEN environment variable – but says nothing about behavior when the token is missing, rate limits, or partial/absent annotations for a variant.

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

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

Two short sentences, front-loaded with the purpose and followed by the prerequisite; nothing is padded. It is perhaps overly terse given the tool's domain complexity, but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Inputs are fully covered by the schema and there is no output schema to explain, but the description gives no hint of what OncoKB annotations contain (e.g., oncogenicity, evidence level, therapies), which matters for an agent deciding whether this tool answers its question. Adequate but with a clear gap given the specialized data source.

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

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

Schema description coverage is 100%, with both 'gene' and 'protein_change' documented with examples (BRAF, V600E), so the schema carries the load. The description only restates the entities at a high level and adds no format or validation semantics beyond it – baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource: 'Get OncoKB annotations for a variant in a cancer gene' clearly identifies the data source (OncoKB) and the input entity (variant), distinguishing it from generic siblings like variant_get or variant_search. It does not explicitly name the sibling it differs from, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to prefer this over variant_get, variant_search, or gene_get, nor any exclusion conditions. The only contextual hint is the phrase 'in a cancer gene', which implies oncology relevance but leaves the choice between siblings to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavior beyond invocation syntax: it says nothing about how many results are returned by default, whether zero filters means a broad scan, or how the score/frequency filters interact. With annotations carrying the read-only signal, a 3 is appropriate.

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

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

Front-loaded purpose sentence followed by a scannable four-bullet cheat sheet and a single prohibition. The bullets restate examples already present in the schema, which is mild redundancy, but every line is actionable and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Eleven parameters, all optional, no output schema, no required arguments. The description never says what happens when it is called with no filters at all, nor does it mention the limit cap of 50 that constrains result volume. For a wide, fully-optional search tool this leaves the agent guessing at default behavior.

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

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

Schema description coverage is 100% and every property already carries an example, so the schema does the heavy lifting and the baseline is 3. The description's examples duplicate rather than extend the schema (rs113488022, NM_004333.4:c.1799T>A, BRAF/V600E all appear verbatim in property descriptions), adding reinforcement but no new semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb+resource ("Search for variants"), which implicitly separates it from the sibling variant_get (fetch-one) and the annotation tools variant_oncokb/variant_trials. It stops short of explicitly naming those siblings or stating what a result row contains, so an agent must infer the search-vs-fetch boundary from the verb alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The bulleted examples give concrete, per-mode invocation patterns (rsid, HGVS, gene+hgvsp, significance) and the closing sentence is an explicit anti-pattern rule: do not use compound free-text, use gene + hgvsp instead. That is strong when-to-use guidance, but it never routes the agent to alternatives (e.g. use variant_get once you have an exact ID) or states preconditions.

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

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

Annotations only declare readOnlyHint=true, while the description adds meaningful behavior: the response envelope { results, warnings? }, warning propagation when MyVariant.info ID resolution fails, and retry guidance. It does not explain pagination or detailed result contents, but it substantially exceeds the 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.

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

The purpose is front-loaded in the first sentence, followed by a compact response and failure-mode note. The second sentence is dense with nested clauses, but every part contributes useful behavioral context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Because there is no output schema, the description must carry return-value context, and it does so with the envelope and warning explanation. For a simple one-parameter read tool this is nearly complete, though it still lacks explicit routing guidance among sibling trial tools.

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

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

Schema coverage is 100%, and the schema already documents the single 'variant' parameter as an rsID, HGVS, or variant ID. The description adds resolution-failure context and mentions BRAF V600E-style naming retry, but does not add new accepted formats beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Find clinical trials for a variant.' The variant scoping implicitly distinguishes it from gene_trials, disease_trials, and trial_search, but the description does not explicitly name those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus sibling trial tools such as gene_trials, disease_trials, drug_trials, or trial_search. The retry note addresses failed ID resolution, not tool selection.

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