biomedmcp

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real value with the ten-call cap and the atomic quota reservation, but leaves the most consequential behavior unstated: what happens if one entry fails, whether partial results are returned, and whether quota is consumed for failed entries.

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 fragments with the purpose front-loaded before the example. The concrete JSON example earns its space by fixing the nesting convention, though the trailing 'biomedmcp://guide' pointer is cryptic without explanation.

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?

An output schema exists, so return values need no prose, and annotations cover safety. But for a multiplexing tool spanning nine operation types with zero schema description coverage, the description omits per-operation argument requirements, idempotency_key semantics, and error/partial-failure 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 0%, so the description carries the full burden. The inline example usefully shows the {operation, arguments} nesting and that arguments mirror the sibling tools' parameters, but only 'get' is illustrated out of nine allowed operations, and the idempotency_key parameter is never explained at all.

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: "Execute up to ten independent read operations" in one call, plus the distinguishing benefit of "one atomic quota reservation." That separates it from the single-operation siblings (get, search, literature_search), though it never names an alternative 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 word "independent" is the only usage constraint and implies operations cannot depend on each other's results, which is useful guidance. There is no explicit statement of when to prefer this over looping the sibling tools, no exclusion of write operations beyond the word "read," and no advice on how many calls make batching worthwhile.

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, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds that an empty call returns an overview and that a guide URI exists, but says nothing about what 'diagnose' does or what changes when source/entity are supplied.

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?

It is short and front-loaded, but written as cryptic fragments ('e.g. {}; biomedmcp://guide') rather than complete sentences, so brevity comes at the cost of comprehension.

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?

An output schema exists so return values need not be explained, but for a three-parameter introspection tool with an undocumented enum and an unexplained boolean flag, the description leaves the agent without enough information to invoke it intentionally.

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 0% across three parameters, including a 17-value entity enum with no descriptions. The description never maps 'source', 'entity', or 'diagnose' to behavior ('diagnose' is not mentioned at all), so it fails to compensate for the documentation 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 verb 'Inspect' and objects 'enabled sources, workflows, sections' give a rough sense of a discovery/introspection tool, but 'sections' and 'an advanced operation's exact schema' are undefined and nothing distinguishes it from siblings like query_source or get. An agent can guess it is the introspective entry point but not precisely what it returns.

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 only usage hint is 'e.g. {}', implying a no-argument call yields an overview, plus a pointer to 'biomedmcp://guide'. There is no statement of when to prefer this over query_source, get, or search, and no conditions under which it should not be called.

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 establish readOnlyHint, idempotentHint, and destructiveHint=false, so safety behavior is covered. The description adds little beyond that: it does not explain section-selection behavior, pagination, freshness semantics, or what the guide reference contains, and the sentence about sources is not actionable on 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?

The description is short and front-loads the reader/router distinction, which is good. But the middle sentence is cryptic and the guide pointer is not self-explanatory, so the compactness comes partly at the cost of clarity.

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?

This is a complex tool with nested objects, enums, conditional section schemas, and 0% parameter description coverage; the description is far too thin to be complete. The output schema existing means return values need not be described, but the input behavior and section semantics still need much more explanation.

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 0%, so the description must carry parameter meaning. It gives a useful example covering entity, id, and species, but leaves sections, section_parameters, freshness, source_versions, and their nested objects entirely unexplained for an 8-parameter tool.

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 says it reads records/evidence sections and gives one example, which is more specific than the bare name 'get'. However, 'ordinary records/evidence sections' is vague and only distinguishes this tool from one sibling (variant_evidence); it does not clarify how it differs from search, resolve, or literature_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 only explicit routing guidance is 'variants use variant_evidence', which is useful but narrow. There is no guidance on when to use this generic get versus search, resolve, or other siblings, and 'Sources constrain all lookups and identity dependencies' is too cryptic to function as usage 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 readOnly=true, idempotent=true, openWorld=true, and non-destructive, so safety is covered and the description's job is to add behavior. It does add real facts beyond annotations: results are deduplicated, source outcomes are retained, and continuation is via an opaque cursor. However, these are compressed into a cryptic clause with no clarification of provider coverage, result-set semantics, or what "source outcomes" means.

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 dense sentences with the purpose front-loaded, followed by an inline example and a documentation pointer; there is no padding. The middle clause ("deduplicate evidence and retain source outcomes and opaque continuation") is over-compressed to the point of ambiguity, which costs it a point.

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?

An output schema exists so return-value description is not required, but for a 6-parameter tool with a nested 13-field filter set and 17% schema coverage, the definition leaves major calling decisions (freshness, ranking_mode, limit ceiling, most filters) undocumented. An agent could call it, but not confidently configure it.

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 only 17% across 6 parameters and a 13-field nested filter object, so the description carries a heavy compensation burden. It mentions "publication/topic/source filters" generically and gestures at "opaque continuation" for cursor, but says nothing about freshness, ranking_mode, limit bounds, sort, or most filter fields (gene, drug, disease, open_access, no_preprints).

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?

"Find papers with publication/topic/source filters" gives a specific verb (find) plus resource (papers) and names the filter axes, so it is clearly a literature retrieval tool rather than a trial or variant lookup. It stops short of explicitly differentiating itself from siblings like trial_search, search, or variant_evidence, so it is clear but not sibling-routed.

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 explicit when-to-use or when-not-to-use statement, and no alternative tool is named; the agent must infer that this is the papers route from the word "papers." The example query and the guide URI imply usage but do not state conditions 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?

The annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a useful precondition to check capabilities/schema and shows an example, but it does not disclose rate limits, auth requirements, pagination, error behavior, or freshness implications beyond 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?

The description is concise and front-loads the main instruction before the example and guide URI. The embedded JSON example is useful but makes the sentence structure less clean; overall there is little wasted wording.

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 complex multi-source dispatcher with four parameters and 0% schema description coverage, the description is very thin and relies heavily on external capabilities/schema and a guide URI. The output schema removes the need to explain return values, but input semantics are not sufficiently covered.

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 0%, so the description must carry parameter meaning. It provides one example using source, operation, and params, but does not explain the 24 enum values for source, the operation string format, the params object contents, or the freshness enum, leaving most parameter semantics undocumented.

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 identifies a generic dispatcher for 'advanced source operations,' but it does not specify what those operations concretely do or what resource scope they cover. It distinguishes itself from dedicated tools for common tasks, but the core purpose remains broad and escape-hatch-like.

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 explicitly says to check capabilities/schema first and directs common tasks to dedicated tools, giving clear context for when this tool is appropriate. It stops short of naming specific sibling alternatives or source-specific exclusions, but the usage boundary is reasonably 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 already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds the useful detail that reset times are reported and that unauthenticated callers see lower limits, but says nothing about response shape beyond that.

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 clauses follow the purpose immediately, and the example call plus guide URI are appended without bloating the text. The trailing 'e.g. {}; biomedmcp://guide' is slightly cryptic but costs little.

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 an output schema present, return values need no explanation, and for a zero-parameter read-only tool the description covers purpose, auth caveat and an example invocation. Only the exact meaning of the rate/allowance units is left implicit.

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?

The tool takes no parameters, so the baseline applies; the 'e.g. {}' snippet usefully confirms it is callable with an empty argument object.

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 concrete verb and resource ('Inspect current research allowance and reset times'), so an agent can tell this returns quota state rather than performing a search or retrieval. No sibling tool covers quotas, so 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 clause 'sign in for higher limits' hints at when the result may be limited and what to do about it, but there is no explicit guidance on when to call this versus other introspection tools such as capabilities.

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/idempotentHint/openWorldHint annotations already establish the safety and side-effect profile, so the description's room to add value is narrower. It adds the traversal vocabulary and a worked example, but says nothing about result volume, the meaning of limit, or what an empty/unknown relation returns.

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?

Very compact and front-loaded: the core action comes first, then the relation inventory, then a concrete call example. The semicolon-chained relation list is dense but scannable; the trailing bare URI is the only piece that reads as unexplained noise.

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?

An output schema and full annotations are present, so return shape and safety need not be restated. Against that, four of six parameters are undocumented in both schema and description, and the guidance for species/assembly (only relevant to some entity types) is absent, which is a real gap for a 17-entity graph tool.

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 0%, so the description must compensate, and it does well for `relation` by enumerating the valid relation names per entity type — meaningful given `relation` is an unconstrained string. However, `id`, `limit`, `species`, and `assembly` receive no explanation at all beyond the single article-ID example, leaving half the surface undocumented.

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 ("Traverse an evidence relationship") and immediately enumerates which relations are valid for which entity, so an agent knows exactly what class of operation this is. It does not explicitly distinguish itself from siblings like get, search, or literature_search, which keeps it below 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: the relation table tells you what you *can* request, so an agent can infer this is the tool for expanding from a known ID to linked evidence. There is no statement of when to prefer this over get/search/resolve, and no exclusions or prerequisites beyond a pointer to "biomedmcp://guide".

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, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds only the vague claim that dossiers 'retain citations/outcomes' plus a pointer to an external guide URI, which is not actionable behavior disclosure. It says nothing about the size or cost of dossier retrieval across seven workflows and twelve nested section types.

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?

It is short, and the inline example earns its place, but the lead sentence about citations/outcomes is cryptic and front-loads the least useful information. The trailing 'biomedmcp://guide' URI is unexplained context that reads as an afterthought.

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?

This is one of the most complex schemas in the sibling set — seven workflow enums, twelve optional section blocks, pagination and threshold sub-parameters — with zero schema description coverage. The description supplies an example and a guide link but leaves an agent unable to choose a workflow or populate section_parameters correctly. An output schema exists, but that only excuses return-value documentation, not the input guidance 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 0% schema description coverage across six parameters (two required, plus a deeply nested DossierParameters object with twelve sub-parameter types), the description must compensate. The single JSON example clarifies 'workflow', 'focus', and 'species' shape, but 'sections', 'section_parameters', 'assembly', and the nested QTL/Civic/Fulltext parameter objects are entirely unexplained.

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?

"Dossiers retain citations/outcomes" and "get further sections" gesture at retrieving dossier content, but the tool is named 'research' and the description never states plainly what operation it performs or what resource it returns. An agent cannot distinguish it confidently from siblings like 'get', 'search', or 'variant_evidence'.

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?

"Inspect capabilities and get further sections for completeness" implies a sequence (call capabilities first, then this tool to fill gaps), but it is framed as an aside rather than explicit when-to-use guidance. No exclusions, prerequisites, or comparison to alternative sibling tools 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 cover safety (readOnly, idempotent, openWorld, non-destructive), and the description adds genuinely non-obvious semantics: a single resolution requires an exact species-qualified symbol/ID, and provider match score alone never establishes identity. That is real policy information the agent could not get from the schema or annotations. What it omits is what comes back on ambiguity (multiple candidates vs. failure), though the output schema likely covers return shape.

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 definition is short, front-loaded with the core action, and the example earns its space by demonstrating three parameters at once. The telegraphic phrasing ("before evidence joins", "provider score alone never establishes identity") is compressed to the edge of readability, costing some clarity for the brevity gained.

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?

Annotations plus an output schema relieve the description of safety and return-value duties, and it does explain the resolution policy. Against a 4-parameter tool with a 17-value entity enum and zero schema descriptions, it is still incomplete: the assembly parameter and the behavior on unresolvable/ambiguous input are unaddressed, leaving the agent to consult the linked biomedmcp://guide.

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 0% schema description coverage, the description must carry parameter meaning, and it partially does: the example shows `query` as a free-text symbol and `entity` as a lowercase type token, while "species-qualified" implies the species role and default. However, `assembly` (grch37/grch38) is never mentioned, and the interaction between `assembly` and genome-related entities is left entirely unexplained.

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 verb+resource is concrete: it resolves aliases/ambiguity for entities into canonical identifiers, and the example ({"entity":"gene","query":"HER2","species":9606}) makes the operation tangible. It does not name a sibling tool to contrast with, so the boundary against `search` or `get` is only implied by "Retrieve known unambiguous identifiers directly".

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?

"Resolve aliases/ambiguity before evidence joins" gives the trigger condition, and "Retrieve known unambiguous identifiers directly" gives the when-not case, effectively telling the agent to skip this tool when it already holds a canonical ID. The alternative is described by behavior rather than by tool name, so the routing requires a small 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 readOnly, idempotent, openWorld, and non-destructive, so safety needs little restating, but the description adds no behavior beyond them. It says nothing about pagination via cursor, the cached_if_fresh vs fresh tradeoff, the summary/full response-size behavior, or any quota/rate constraint despite a quota sibling existing. The only addition is a guide URI, which defers rather than discloses.

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 compact fragments, with the core purpose front-loaded and the sibling routing immediately after the example. Nothing is padded, though the guide URI is a weak use of the final slot and "ordinary records" spends words without adding precision.

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?

This is a broad, high-complexity search surface — 7 parameters, 14 entity types, 20 filter fields gated per entity, plus an output schema — and the description covers only the query/entity/filters triad. For a tool with an output schema the return shape need not be explained, but the entity vocabulary, pagination, and freshness/output semantics are left entirely to the schema.

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 only 14%, so the description carries real burden, yet it explains a single invocation shape: {"entity":"gene","query":"BRCA1","filters":{"species":9606}}. It never touches limit, cursor, output, or freshness, and does not mention that valid filter keys are constrained per entity by the schema's conditional blocks — a non-obvious rule the one example only hints at.

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?

"Find ordinary records with entity filters" gives a verb and a resource, and the two exclusion sentences distinguish it from literature_search and trial_search. However, "ordinary records" is vague: the entity enum contains 14 domains (gene, variant, drug, gwas, patent...), and the description never characterizes the record corpus it actually searches.

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 explicitly routes two adjacent needs away — papers to literature_search, trials to trial_search — which is exactly the sibling differentiation an agent needs. It stops short of positive guidance (when to choose this over get, query_source, relate, or research), so it is clear context without full alternative coverage.

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 read-only, idempotent, non-destructive, open-world behavior. The description adds meaningful non-annotation context: the demo-data caveat, separate clinical/assayed reporting, unique mutant samples, events/exclusions, hash and denominator preservation, and a private-compute platform note. It does not contradict the annotations.

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

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

The description is compact and front-loads purpose, discovery, and reporting constraints with no filler. However, several distinct instructions are packed into a few run-on sentences, making the structure less scannable than it could be.

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 complex seven-mode analysis tool, the definition covers discovery, the demo caveat, reporting semantics, and provenance preservation, and an output schema exists. It still leaves the agent to infer which analysis mode to choose from the schema's const values alone, a significant gap for this complexity.

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 reported at 100%, so the oneOf variants and their constraints already document valid inputs. The description adds only a single gene_profile example and generic reporting expectations; it does not explain what mutation_cohort, filter_cohort, compare, survival, co_occurrence, or top_mutated each mean beyond their const names.

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 specific verb and resource, 'Analyze an installed verified public study,' and names the bundled demo study plus the capabilities(source=study) discovery path. It does not explicitly distinguish this multi-mode analysis tool from siblings such as research or query_source, so it stops short of full sibling differentiation.

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 prerequisites, namely an installed verified public study, and a discovery step via capabilities(source=study), plus the caveat that ubi_synthetic is an invented demo. It does not name an alternative analysis tool or state when not to use this one, but the context is sufficiently 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 already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds two useful behavioral facts beyond that: the corpus is limited to public trials, and results do not establish individual eligibility. It says nothing about pagination behavior (cursor/limit exist in the schema), caching/freshness semantics, or rate limits.

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 compact segments: purpose, boundary, and a concrete call example, with the purpose front-loaded. The trailing 'biomedmcp://guide' reference is terse and unexplained, spending a few characters without telling the agent what the guide contains.

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?

An output schema exists, so return values need not be described, and the safety profile is carried by annotations. However, for a paginated, filter-heavy search tool with 17% schema coverage, the description omits pagination guidance and the meaning of the freshness modes, leaving real gaps an agent would hit on a second call.

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 only 17% across six parameters, so the description must carry the load, and it largely does not. It gives meaning for 'query' and hints at the filter categories ('disease/intervention', 'status' in the example), but leaves limit, cursor, freshness, and most of the six filter keys (drug, gene, phase, source) unexplained in either place.

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 specific verb and resource ('Find public clinical trials') and scopes the search to disease/intervention plus trial-specific filters, which distinguishes it from literature_search and other siblings. It stops short of naming a sibling it should be preferred over, 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?

It supplies a clear usage boundary ('Does not determine individual clinical eligibility'), which tells the agent this is a discovery/search tool and not an eligibility adjudicator. It offers no explicit alternative tool for eligibility questions and no when-to-use conditions relative to siblings such as study_analysis.

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, idempotent, openWorld, non-destructive, so the safety bar is low. The description adds genuinely useful behavior context: ambiguity is preserved rather than collapsed, predictions carry source and uncertainty, and EVE is license-gated. It omits caching/freshness behavior despite a freshness parameter, and says nothing about response size or pagination.

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?

Roughly four compact sentences front-loaded with the purpose, then defaults, then optional sections, then an id example. Dense but nearly every clause carries information; the linked guide reference is a small dangling fragment.

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?

An output schema exists so return values need not be described, and the annotations cover the safety profile. Still, for a six-parameter tool with nested section sub-parameters and zero schema descriptions, an agent lacks enough to fill in freshness, assembly, or the civic/gwas/cbioportal sub-objects 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 0%, so the description must carry parameter meaning, and it only partially does. It gives an id format example and implies sources/sections via the defaults and predictions/eve mention, but leaves assembly, sections as a list, freshness, and the nested section_parameters (civic, gwas, cbioportal) entirely unexplained.

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 clause names a specific verb and resource ("Retrieve variant evidence") and adds a distinguishing scope qualifier ("assembly/transcript ambiguity preserved"). It is clearly a variant-evidence lookup rather than a generic fetch, though it never explicitly contrasts itself with siblings like get or query_source.

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 states which sources are included by default (ClinVar, population, CIViC) and how to opt into predictions (AlphaMissense) or EVE scores, which is real usage guidance. However, there is no when-not-to-use guidance and no routing advice against sibling tools such as get, query_source, or search.

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