gnomad-genetics-mcp-server

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

Annotations already declare readOnlyHint and idempotentHint, indicating a safe, non-mutating operation. The description adds behavioral context about what is returned (row count and column schema per table) and the staging concept, which complements the annotations without contradicting them. It does not mention error cases or side effects, but given the strong annotation coverage, this is sufficient.

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, two sentences total, with the primary purpose and usage in the first sentence and return details in the second. It is front-loaded, avoids redundancy, and every sentence adds essential information without fluff.

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 tool with only one parameter and a rich output schema (present though not shown), the description provides complete context: it explains the staging workflow, the source of the canvas_id, the purpose of writing correct SQL, and what the output will contain (row counts and column schema). This is adequate for an agent to know when and how to use 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?

The single parameter canvas_id is already well-described in the schema: 'Canvas ID returned by a prior staging call (gnomad_list_gene_variants or gnomad_search_clinvar).' The main description repeats this guidance but adds no new semantic details, so it adds minimal value beyond the schema's 100% coverage. This aligns with the baseline for high schema coverage.

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 clearly states the tool lists tables staged on a canvas with their columns, explicitly tying its purpose to enabling correct SQL for gnomad_dataframe_query. It also distinguishes itself from related tools by referencing the staging tools (gnomad_list_gene_variants, gnomad_search_clinvar) and the downstream query tool, making its role in the workflow 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?

The description specifies when to use it: after a staging call, and why: to inspect tables before writing SQL for gnomad_dataframe_query. It provides explicit source of the canvas_id. However, it does not explicitly state when not to use it or mention alternative inspection methods, though the context strongly implies this is the standard inspection step.

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 include readOnlyHint=true and idempotentHint=true, but the description adds specific constraints beyond those: 'SELECT statements only — writes, DDL, and file/HTTP table functions are rejected by the canvas gate.' It also mentions the workflow dependency on staging tools, which is valuable behavioral context not captured by annotations. The description does not contradict any annotation.

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 (about 4 sentences), front-loaded with the core purpose, and every sentence adds value: purpose, usage, example use cases, constraints, and prerequisite call. There is no fluff or repetition, making it efficient and well-structured.

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?

Given the tool is a SQL query against staged tables, the description covers all essential context: the staging mechanism (other tools), the required inputs (canvas_id and table_name), the workflow (call describe first), constraints (read-only, rejected functions), and example use cases. The presence of an output schema means detailed return values are not needed. This is complete for a tool of 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 description coverage is 100%, so both parameters (sql and canvas_id) are fully documented in the schema. The description reinforces their use but does not add new syntactic or semantic details beyond what the schema already provides (e.g., the schema already says 'Read-only SQL SELECT' and 'Canvas ID returned by gnomad_list_gene_variants or gnomad_search_clinvar'). Since the description adds no new parameter-level information, the 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?

The description clearly states what the tool does: 'Run a read-only SQL SELECT against a canvas table staged by gnomad_list_gene_variants (table gene_variants) or gnomad_search_clinvar (table clinvar_variants).' It specifies the verb (run), the resource (canvas table), and the scope (read-only SQL SELECT), and differentiates from siblings by naming the staging tools and the specific use cases (ranking, grouping, filtering).

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 provides explicit when-to-use guidance: 'Use the canvas_id and table_name those tools returned...' and 'Call gnomad_dataframe_describe first to discover staged table and column names.' It also gives explicit exclusions: 'writes, DDL, and file/HTTP table functions are rejected by the canvas gate.' This gives clear alternatives and context without ambiguity.

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 read-only, idempotent behavior; the description adds materially useful behavioral detail beyond that: the output shape (depth stats, threshold fractions, exome/genome separation), the default to return all available tracks, and the behavior of echoing the effective dataset and build. It does not cover failure modes or edge-case behavior, but 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 dense but efficient, front-loading the output content and purpose in the first sentence, then giving the use case, cardinality rule, and default behavior. The brief data-source attribution is earned for provenance. Every sentence contributes to correct selection or invocation.

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?

Given a rich 100%-covered input schema, an output schema, and read-only/idempotent annotations, the description covers the essential non-schema guidance: what the output means, why an agent would call this tool, the selector cardinality, and the default track behavior. Nothing critical 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 description coverage is 100%, so the baseline is 3. The description adds real value by clarifying the exact-one-of constraint across gene/transcript_id/region, which the schema only expresses through mutual-exclusion pair notes. It also reinforces the coverage_source default behavior. It does not add deep syntax guidance for each parameter, but the schema already handles that.

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 anchors on a specific, unambiguous operation: fetching gnomAD sequencing-coverage summaries. It enumerates the resource types (gene, transcript, region) and specifies exactly what the result contains (mean/median depth, fraction at 1×–100× thresholds, exome/genome tracks). This clearly separates it from sibling variant and dataframe tools even without naming 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?

It gives an explicit, actionable use case: disambiguating true absent variants from uncallable positions, with a clear explanation of why well-covered versus poorly-covered regions matter. It also instructs the caller to supply exactly one of gene, transcript_id, or region. It stops short of explicitly naming sibling alternatives or stating when not to use this tool, so it misses 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 already provide readOnlyHint, openWorldHint, and idempotentHint, so the bar is lower. The description adds substantial behavioral context: it discloses that null constraint fields are reported as such and never fabricated, that v4 constraint is flagged beta, that constraint_flags surfaces caveats, and that the effective dataset and reference build are echoed. These details address output edge cases and data-source caveats beyond what annotations convey, without contradicting them.

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 information-dense and front-loaded with the core purpose, then systematically elaborates on metrics, version differences, null behavior, and data source. Every sentence serves a purpose, with no filler. It is somewhat long but justified by the tool's complexity. A 4 reflects strong structure with minor verbosity, not a flaw.

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 output schema exists, so return-value explanation is not required. The description covers the core metrics, version-specific thresholds (pLI >0.9, LOEUF <0.6 v4 / <0.35 v2), null-field handling, beta status, covariance with reference genome, and the data source attribution. There are no obvious gaps that would prevent an agent from correctly invoking and interpreting the 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 100%, so the baseline is 3. The description reiterates the accepted gene identifier types (HGNC symbol or Ensembl ID) and mentions echoing dataset/reference build, but it does not add new meaning beyond the schema for parameters. The threshold values (LOEUF <0.6 in v4) are interpretation aids, not parameter semantics. Credit is given for reinforcing schema details, but no substantive additions.

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: 'Fetch gnomAD loss-of-function constraint for a gene' and enumerates the exact metrics returned (pLI, LOEUF, observed/expected ratios, Z-scores). It explicitly differentiates itself from the allele-frequency axis, making clear it is the orthogonal tool for gene tolerance. This distinguishes it from sibling tools like gnomad_get_variant and gnomad_list_gene_variants without ambiguity.

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 provides strong contextual guidance on when this tool is relevant ('a loss-of-function variant matters far more in a gene intolerant to being broken') and notes the beta flag for v4 constraint. However, it does not explicitly name alternative tools or state when NOT to use this tool. The schema also covers required input types. This is clear context but lacks explicit exclusions or sibling routing, so a 4 is appropriate.

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, openWorldHint, and idempotentHint. The description adds valuable behavioral context beyond these: per-item partial success (malformed/absent IDs land in failed[] without failing others), empty found[] semantics indicating absence in the dataset, and the recommendation to pair with coverage tool. It also mentions the data source. No contradiction with annotations; in fact, it reinforces the read-only nature by explaining non-destructive error handling.

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 comprehensive but not overly verbose. The first sentence front-loads the core purpose. It then covers batch behavior, absence semantics, and pairing guidance in clear, structured sentences. It includes a data source line at the end, which is useful but could be considered optional. Slightly longer than strictly necessary, but every sentence adds value; a strong structure 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?

Given the tool's complexity (batch, multiple datasets, reference genomes, partial success), the description covers all necessary operational details: accepted ID formats, dataset-to-genome mapping, error handling, and absence interpretation. Since there is an output schema (presumably documenting return fields), the description doesn't need to explain return values. The inclusion of the data source and the pairing suggestion for coverage completes the picture 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%, with each parameter described. The description adds substantial enrichment: it clarifies the meaning of dataset values (e.g., gnomad_r4 is GRCh38 default), provides concrete variant ID examples (1-55051215-G-GA, rs11591147), explains how reference_genome is derived from dataset and the requirement of coordinate alignment. These details go beyond the schema and help the agent construct correct calls.

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 clearly states the verb 'Fetch' and the resource 'full gnomAD population record for one or more variants', enumerating the specific data fields (allele counts, homozygote/hemizygote counts, quality flags, transcript consequence, in-silico scores, ClinVar significance). It distinguishes itself from siblings by framing the answer as 'how common, is it benign' and explicitly referencing gnomad_get_coverage for absence confirmation, which sets it apart clearly.

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 provides explicit usage context: 'The ''how common, is it benign'' answer in one call.' It also gives a clear pairing instruction with gnomad_get_coverage for confirming absence, and explains the batch behavior with per-item partial success and failure handling. This effectively tells the agent when to use this tool versus alternatives, including a direct reference to a sibling 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?

The description is transparent about staging results and about the destructive replacement behavior: 'Reusing it REPLACES (overwrites) the gene_variants table... it does not append.' However, this directly contradicts the annotation readOnlyHint=true, which indicates the tool does not modify its environment. Because the description contradicts structured annotations, the score must be 1 and this is an Annotation Contradiction.

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 long but every sentence earns its place: core behavior, optional filters, staging flow, disabled-canvas fallback, selector exclusivity, dataset/build echo, and data source. The main purpose is front-loaded, and the canvas details are logically sequenced without 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?

Given the tool's complexity — 8 parameters, canvas staging, and a disabled-canvas fallback — the description is complete. It covers result staging, inline preview, canvas_id semantics, capped preview behavior when canvas is disabled, selector exclusivity, and dataset/build behavior. Since an output schema exists, not detailing return fields is acceptable.

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 baseline is 3. The description adds value beyond the schema by stating the cross-parameter constraint 'Supply exactly one of gene, transcript_id, or region,' explaining what canvas_id reuse does, and noting the effective dataset/build echo. This is meaningful context that the individual property descriptions do not fully convey.

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: 'List every gnomAD variant in a gene, transcript, or region with allele frequencies and predicted consequences.' This clearly distinguishes it from siblings like gnomad_get_variant (single variant) and gnomad_get_coverage or gnomad_get_gene_constraint. An agent can tell what this tool does 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?

The description gives clear usage context: filter by consequence class and max AF, supply exactly one of gene/transcript/region, and use gnomad_dataframe_query to operate on the full staged result. It does not explicitly contrast this tool with alternatives such as when to prefer gnomad_get_variant or search_clinvar, so it stops 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?

Annotation Contradiction: readOnlyHint is true, but the description says the full set is staged on a DataCanvas table and the schema notes that reusing a canvas_id REPLACES the table. This describes a write/side-effect behavior that conflicts with the read-only annotation.

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 purpose, then covers filters, DataCanvas staging, query alternative, API-key behavior, and fallback behavior. It is somewhat dense and includes minor extras like 'Credit: ClinVar, NCBI', but every major sentence adds 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?

The description covers the external source, rate-limit behavior, DataCanvas staging, disabled-canvas fallback, filtering options, and the recommended way to query the complete result set. The output schema handles return-value expectations. The readOnlyHint contradiction leaves the overall behavioral context slightly incoherent, preventing a perfect score.

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 four parameters thoroughly. The description adds only light extra meaning, such as examples for clinical_significance ('pathogenic') and the 0–4 star rating concept; it does not materially compensate 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 opens with a specific action and resource: 'Search ClinVar (NCBI E-utilities) for a gene and return its classified variants.' It clearly differentiates this tool from gnomAD-native siblings by emphasizing an external ClinVar source, gene-level classification, and a 'gene-panel curation view.'

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 supplies clear context: you use this tool when you need ClinVar variant classifications for a gene, with optional filters and a staged DataCanvas table for further querying via gnomad_dataframe_query. It does not explicitly state when not to use it or name alternative tools beyond the dataframe query direction.

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