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 declare readOnlyHint, openWorldHint, and idempotentHint, so the description doesn't need to repeat safety. It adds behavioral details like echoing the effective dataset and build and returning both tracks by default, which are not in annotations and provide useful operational context. No contradiction with 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 three sentences, front-loaded with the core function, followed by a practical use case and a parameter constraint. Each sentence adds value with no filler, and the structure flows logically from what to why to how.

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 moderate complexity (6 params), full schema coverage, and an output schema, the description covers the primary use case, key constraints, and return behavior without needing to describe return types. It is complete for the agent to understand when and how to invoke it, though it could explicitly mention that the result contains per-track data, which is implied but not stated outright.

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?

While the schema has 100% description coverage, the description adds the crucial constraint that exactly one of gene, transcript_id, or region must be supplied, which is not fully explicit in the schema (region is specified as mutually exclusive, but the mutual exclusivity among all three is not enforced in the schema). This extra guidance makes parameter semantics clearer than schema alone.

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 fetches gnomAD sequencing-coverage summaries for a gene, transcript, or region, listing the specific metrics (mean/median depth, fraction covered by thresholds) and the track separation. This distinguishes it from sibling tools that handle variants, constraints, or dataframes, making the purpose 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 provides an explicit use case: disambiguating true absent variants from uncallable positions, explaining why a well-covered region is informative. It also states the hard constraint of supplying exactly one of gene, transcript_id, or region, and mentions the optional coverage_source narrowing. This is strong grounding for when to use the 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?

Annotations include readOnlyHint, openWorldHint, and idempotentHint, but the description goes beyond by disclosing that null fields are reported as such (never fabricated), the v4 constraint is flagged beta, and constraint_flags surfaces caveats. It also states the tool echoes the effective dataset and build, which is important for understanding output. No contradiction with 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 information-dense but not overly long. It front-loads the primary purpose and then provides necessary interpretive context. A few minor redundancies with schema (echoes dataset/build) exist but are not wasteful. It is well-structured with clear sentences, earning a 4 rather than 5 due to slight redundancy.

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 and the rich output schema, the description covers all critical aspects: acceptance criteria for gene IDs, dataset options, interpretation thresholds, data quality caveats (null fields, beta flag, constraint_flags), and alignment with the reference genome. It is complete for an agent to decide and invoke 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 each parameter's description is detailed (e.g., gene accepts HGNC or Ensembl ID, dataset enum values, reference_genome derivation from dataset). The description adds value by explaining the relationship between dataset and reference build and emphasizing that reference_genome must match dataset or the call is rejected, which is not explicit in the schema. However, it does not add further parameter-level semantics beyond what schema provides, hence 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?

The description clearly states the tool fetches gnomAD loss-of-function constraint for a gene, listing specific metrics (pLI, LOEUF, Z-scores). It distinguishes itself from sibling tools by emphasizing the constraint/orthogonal axis to allele frequency, and it accepts HGNC symbol or Ensembl ID, which is unique among the listed siblings.

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 explicitly explains when to use this tool: for assessing gene constraint, the orthogonal axis to allele frequency, which complements variant-level tools like gnomad_get_variant. It also provides concrete thresholds for interpreting pLI and LOEUF, guiding the agent on how to interpret results, and advises obtaining stable IDs from ensembl_lookup_gene. It does not explicitly name alternatives but clearly contrasts with allele frequency 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?

Discloses per-item partial success (malformed/absent IDs land in failed[]), and explains that an empty found[] for a well-formed ID means absence from the dataset. This adds concrete behavioral details beyond the readOnly/idempotent annotations, with no contradictions.

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 thorough but well-structured, with a clear progression from purpose to batch behavior to pairing advice. While long, each sentence contributes useful detail without redundancy.

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 complexity (batch processing, open-world hint, output schema), the description covers critical operational aspects: partial success handling, empty results interpretation, and caution about callability. It is complete for the tool's 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?

While schema coverage is 100% with detailed descriptions, the description adds practical context on obtaining variant IDs (e.g., from VCF or ensembl_predict_variant) and clarifies the 1-based chrom-pos-ref-alt format, slightly enhancing parameter understanding 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?

Clearly states the tool fetches gnomAD population records for variants, lists included data types (allele counts, frequencies, quality flags, etc.), and distinguishes from siblings by focusing on the 'how common, is it benign' answer.

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?

Provides usage guidance by mentioning pairing with gnomad_get_coverage to confirm callability and implying this tool for frequency/clinical significance, though it could more explicitly state when to prefer related tools like gnomad_get_gene_constraint or gnomad_list_gene_variants.

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 mark readOnly, idempotent, and openWorld; the description goes far beyond by detailing the canvas staging behavior (table name, preview, canvas_id), the spill condition when canvas is disabled, the exact overwrite semantics for canvas_id reuse, and the echo of effective dataset/build. This is rich behavioral disclosure not present in annotations, and it doesn't contradict 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 compact but dense with information, using parallel structure and clear clauses. It front-loads the primary action and scoping, then adds necessary caveats (canvas behavior, exclusivity). Every sentence carries meaningful value; there is no repetitive or filler text.

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 params, canvas interaction, conditional behaviors) and the presence of a full schema and output schema, the description is remarkably complete. It covers all operational behaviors, follow-up steps, and edge cases (e.g., null AF handling, canvas disabled). The description fully compensates for any gaps the annotations or schema do not address.

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 each parameter has detailed descriptions, but the tool-level description adds crucial cross-parameter semantics: the mutual exclusivity of gene/transcript_id/region, the relationship between dataset and reference_genome, and the effect of max_af on null AF variants. These relationships are not fully captured in schema field descriptions and are essential for correct invocation.

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 specifies the action (list every gnomAD variant) with clear scoping (in a gene, transcript, or region) and key outputs (allele frequencies, predicted consequences). It distinguishes from siblings like gnomad_get_variant (which fetches a single variant) and gnomad_get_coverage, and even names the alternative gnomad_dataframe_query for post-querying.

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 explicitly states when to use this tool and when not: it lists the required exclusivity condition (exactly one of gene, transcript_id, or region), the optional filters (consequence_class, max_af), and the follow-up path via gnomad_dataframe_query. It also warns about canvas behavior when disabled, giving clear usage context without needing to infer from siblings.

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.