pharmacogenomics-guidelines-mcp-server

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

Adds substantial behavior beyond the readOnly/openWorld/idempotent annotations: pagination via nextOffset, a 24,000-byte soft budget that cuts only between complete rows, and oversizedRow as the indivisible exception. It also discloses that missing coverage returns found=false and advises consulting linked guidelines before clinical use.

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 and selectors are front-loaded, and subsequent sentences cover view modes, pagination, size limits, missing results, and a clinical-use caution without filler. The density is appropriate for a parameterized read tool with nuanced pagination behavior.

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 and complete parameter descriptions available, the description still covers the essential operational details an agent needs: selector modes, view constraints, pagination behavior, oversized-row handling, missing-coverage semantics, and a clinical-use warning. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description still adds useful semantics about the by selector modes, view behavior, and ambiguous drug-name paging with drugId retry, though it does not add much for limit, offset, or guidelineId 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 retrieval action and resource: guideline coverage by source ID, exact gene symbol, or exact drug name/ID. The scope is clear, but the description does not explicitly differentiate this tool from siblings such as pgx_get_recommendations or pgx_search_pairs.

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 when to use summary versus drugs/pairs views, including the requirement that view=drugs or pairs needs by=id. It also tells the agent how to recover from ambiguous drug names by retrying with drugId, though it does not explicitly compare this tool against sibling tools.

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 read-only/idempotent/open-world, but the description adds real behavioral rules: omitted genes are never treated as normal/negative/No Result, every prerequisite must be explicit, source text/populations/classifications are preserved, and recommendation vs incomplete-diagnostic paging advance independently. It also warns to consult source guidelines before clinical use. Minor deduction because some added clauses ('without joins', 'retain ordered alerttext, No CDS and n/a') are cryptic rather than clarifying.

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 correctly: drug mode first, then the matching modes, then the view toggle, then invariants, paging, and the clinical caveat. Dense but nearly every sentence carries operational content for a 14-parameter, three-mode tool. A few compressed phrases cost clarity without saving much space.

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 not be explained, yet the description still points to page.nextOffset and incompletePage.nextOffset, showing awareness of the result shape. Given three modes, nested objects, and 14 parameters, it covers selection, invariants, and paging well; it says nothing about failure modes when a selector is ambiguous or unmatched, which is the remaining 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%, so the schema already documents every parameter including the mode/view enums and nested genotype/geneResults shapes. The description reinforces the mode-to-selector coupling and the 'uniquely resolved' genotype constraint but introduces almost no syntax or format detail beyond what is already structured. 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 ('Browse CPIC recommendations') and then partitions it into three named modes with the exact selector each requires. It also names sibling tools (pgx_search_pairs for drug identifiers, pgx_list_reference for phenotypes), so an agent can locate this tool in the family without opening schemas.

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

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

Gives explicit selection logic per mode and for the view toggle ('view=test_alerts selects complete example CDS alerts instead of recommendations'). It routes the agent to pgx_list_reference for valid phenotype values. It stops short of stating when to prefer pgx_get_guideline or pgx_lookup_diplotype instead, so exclusions are 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 already declare readOnly, idempotent and openWorld, so the safety profile is covered; the description adds real value beyond that by disclosing paging behaviour (live genes/phenotypes) versus complete-vocabulary static topics, and by describing that phenotypes preserves distinct activity-score rows, frequencies and consultation text. Return shape detail is somewhat redundant with the existing output 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 dense sentences, each carrying distinct information (coverage, phenotypes nuance, paging/static split, downstream use). The opening sentence is a long enumeration but is front-loaded with the tool's scope, and nothing is padding.

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 annotations, a full output schema and 100% schema coverage, the description supplies the remaining context an agent needs: static vs live behaviour, the geneSymbol dependency for phenotypes, and the intended downstream chaining. Complete enough to call correctly without opening 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 100% and the schema already documents limit clamping, zero-based offset with nextOffset, and geneSymbol's per-topic requirement. The description only reinforces the phenotypes/geneSymbol dependency and mentions paging generically, adding little syntax or semantics beyond the schema. 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?

The description names the resource concretely, enumerating the six reference vocabularies (gene symbols, CPIC levels, ClinPGx testing labels, classifications, input formats, phenotypes) that the tool exposes. It also distinguishes itself from siblings by framing the output as input to later 'discovery, diplotype and recommendation calls'. It stops short of naming a specific sibling it replaces, but the verb+resource is unambiguous.

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: use the results to feed subsequent discovery, diplotype and recommendation calls, and notes that static topics need no upstream request while genes/phenotypes are live. The phenotype prerequisite (geneSymbol) is stated. What's missing is an explicit statement of when to pick this over a specific sibling such as pgx_search_alleles.

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 read-only, idempotent, and open-world behavior, so the description adds value by disclosing edge-case semantics: multiple source rows stay ambiguous and no activity score or missing-gene result is inferred. These are concrete behavioral traits an agent could not derive from the annotations, though the return shape itself is not described.

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 and no sentence is filler, but the phrasing is densely compressed ('bounded reverse-order or status aliases', 'exact lookup precedes') in a way that takes parsing effort for a call-time 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 two-parameter read-only lookup with an output schema and full annotation coverage, the description supplies what structured fields cannot: input-notation breadth, ambiguity behavior, and non-inference guarantees. Little an agent needs 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: the diplotype must be *exact* source notation, covering star alleles, named HLA positive/negative statuses, and non-star sequences. That broadens the agent's understanding beyond the single schema example '*1/*2 or *15:02 positive'.

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 ('Translate a CPIC-supported diplotype or allele-status result for one gene'), scoping it to a single gene and a CPIC-supported input. What the diplotype is translated *into* (phenotype, activity, recommendation) is left implicit, relying on the output schema, which keeps it just 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?

Explicitly routes inspection of valid inputs to pgx_search_alleles and pgx_list_reference with topic phenotypes, and states that exact lookup takes precedence over reverse-order or status aliases. It gives clear context and named alternatives but does not spell out a condition under which a sibling should be chosen over this tool.

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?

Adds substantial behavior beyond the readOnly/idempotent/openWorld annotations: name-matching precedence (literal first, then gene-prefix stripping), case-insensitive clinicalFunctionalStatus matching, a 24,000-byte soft budget with an oversizedRow exception, and nextOffset continuation. It also discloses interpretive caveats (definitions are metadata, inferred frequencies do not establish individual risk).

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, followed by matching rules, interpretive caveats, and pagination guidance in a logical order. Dense but nearly every sentence carries operational or safety value; the prose is slightly telegraphic which costs some 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?

An output schema exists, so return-shape explanation is not needed, and pagination plus the oversizedRow edge case are covered. Filters, matching semantics, and interpretive caveats are all addressed for a fairly complex pharmacogenomic search.

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 exceeds that by explaining the cross-parameter matching precedence for name and the case-insensitive literal semantics for clinicalFunctionalStatus. It adds no detail on limit clamping or offset beyond what the schema already states.

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 and resource: it states it inspects CPIC allele function, evidence, definition metadata and population frequencies for a geneSymbol. It differentiates from pgx_list_reference for gene discovery, though it does not distinguish itself from pgx_lookup_diplotype or pgx_search_pairs.

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 gene discovery to pgx_list_reference, giving clear context for when this tool is not the right one. It stops short of stating when to prefer pgx_lookup_diplotype or pgx_search_pairs, so alternatives are only partially covered.

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, so the description correctly focuses on non-obvious behavior: AND semantics, the no-fallback rule for identifier filters, pagination via nextOffset, and the interpretive caveat that an evaluation is not a prescribing recommendation. That caveat is genuinely valuable context an annotation cannot express.

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?

Six short clauses, front-loaded with the resource and filter modes, then the AND/fallback rules, then return contents and pagination. No sentence is redundant with the schema or with another sentence.

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 12-parameter, all-optional search with full schema coverage, annotations, and an output schema, the description covers everything left unsaid: parameter interaction, return contents useful for chaining, pagination, and the interpretation warning. Nothing an agent needs in order to call it correctly 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 would be 3, but the description adds cross-parameter rules the schema cannot encode: filters are ANDed and identifier filters do not fall back to name-only matching. Those interaction semantics materially change how an agent composes a query, so it earns above 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?

States a specific verb (Search) and resource (evaluated gene–drug pairs) and enumerates the filter dimensions an agent can use, which makes it clearly distinct from pgx_search_alleles and the other siblings. It stops short of explicitly naming the sibling it is not, so it lands just below the top band.

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 operating context: filters combine with AND, identifier searches never degrade to name matching, and results carry guideline links for pgx_get_guideline, which routes the agent to the correct next tool. It offers no explicit when-not or alternative-tool exclusion, so a 4 rather than a 5.

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