ensembl-mcp-server

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds value beyond annotations by detailing returned fields (stable ID, species, homology type, perc_id, perc_pos, taxonomy level), explaining the max_results cap behavior and totalCount reporting, and noting that target species can be filtered or left open. This is rich behavioral context without contradicting 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 slightly longer than strictly necessary but remains well-structured: purpose first, then return fields, use-case examples, and input requirements. Each sentence contributes useful guidance, and the front-loaded opening makes it easy to scan.

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 6 parameters, an output schema, and strong annotations, the description still manages to add key contextual details: use cases, input alternatives, target species filtering, and the max_results/totalCount behavior. It is fully complete for an agent to select and invoke this tool effectively without additional documentation.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters in detail. The description reinforces the id/symbol mutual exclusivity and gives examples, but it does not add substantial new meaning beyond what the schema already provides. 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 opens with 'Find orthologs and/or paralogs of a gene across species', a specific verb+resource statement that clearly identifies the tool's function. It also distinguishes this from sibling tools like ensembl_lookup_gene (gene lookup) and ensembl_get_sequence (sequence retrieval) by emphasizing cross-species homology relationships.

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 clear usage context with concrete examples (e.g., 'what is the mouse equivalent of human TP53?') and explains how to structure queries ('Provide either symbol + species or a stable gene ID'). It does not explicitly name alternative tools or state when not to use it, but the use case is implied strongly enough.

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?

With annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds valuable behavioral context: large sequences are returned in full but the length is included so callers can budget context, and the type parameter's default behavior (genomic includes introns) is clarified. No contradictions 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 a single dense paragraph of about 180 words that front-loads the core function and then layers caveats. Every sentence adds value, though the density of region-format details could have been easier to parse with sentence breaks or bullets. Still, it is appropriately sized for the tool's complexity.

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

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

This tool has 5 parameters, an output schema, and multiple modes (stable ID vs region, four sequence types). The description covers all critical behavioral nuances: return contents, large-sequence handling, type-specific requirements, region syntax, species resolution, and a pointer to a related tool for prerequisite lookup. The output schema covers exact return fields, so the description doesn't need to repeat them. This is a complete and well-rounded description.

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?

Although the schema already documents all five parameters at 100% coverage, the description enriches meaning by explaining the type enum in practical terms (e.g., cdna is 'spliced transcript', cds is 'coding sequence only, no UTRs'). It also gives concrete region format examples and clarifies when species is required, going beyond the schema's property descriptions.

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 starts with a specific verb and resource: 'Fetch the DNA, cDNA, CDS, or protein sequence for a gene, transcript, protein, or genomic region.' It enumerates the exact sequence types and supported identifiers, making it unmistakable what this tool does. It also distinguishes itself from sibling tools by focusing on sequence retrieval rather than homology, xrefs, or variant prediction.

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 clear when-to-use context, especially for region mode versus stable ID mode, and explicitly states that protein sequences require a transcript or protein ID, directing the caller to ensembl_lookup_gene when they only have a gene ID. It does not explicitly name alternative tools for other cases, but the guidance for the most common edge case is actionable and sufficient.

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 mark the tool as readOnly, openWorld, and idempotent. The description adds valuable behavioral context beyond that, such as 'IDs returned here chain to protein (pubchem via UniProt), literature (pubmed via PubMed IDs), disease (OMIM via MIM_GENE), and pathway (Reactome) resources.' This enriches the agent's understanding of the output semantics.

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 four sentences, front-loaded with the main action, and each sentence contributes essential information: what it does, output structure, filter behavior, chaining relationships, and prerequisite. No redundancy or filler.

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

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

With an output schema present, the description doesn't need to detail return fields, but it still covers the key contextual aspects: input requirements, filter usage, common dbname values, and how returned IDs link to other resources. The tool is simple (2 parameters, no nested objects), and the description fully supports 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?

The input schema already provides 100% coverage with detailed descriptions for both id and dbname, including examples. The description adds a consolidated list of common dbname values (e.g., HGNC, Uniprot_gn, EntrezGene) and clarifies the omission behavior, but these largely duplicate schema content. Baseline 3 is appropriate given the schema's thoroughness; the description only marginally adds meaning.

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

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

The description clearly states the tool retrieves cross-database references for a gene or feature, listing specific databases (HGNC, UniProt, EntrezGene, etc.). This specific verb+resource construction distinguishes it from sibling tools like ensembl_lookup_gene or ensembl_get_sequence.

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 a prerequisite: 'Requires an Ensembl stable ID — use ensembl_lookup_gene to get the ENSG… ID first.' It also explains the dbname filter behavior. However, it does not explicitly contrast with other sibling tools (e.g., homology, sequence), so it stops short of full when-to-use vs alternatives 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 provide readOnlyHint and idempotentHint. The description adds valuable behavioral context beyond annotations: the default division when omitted, the approximate species count (~356), and the note that nameContains is 'applied locally after fetching.' This helps the agent anticipate endpoint behavior.

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

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

The description is front-loaded with the primary purpose, then explains the discovery role, filtering options, and default behavior. Each sentence earns its place, though it could be tightened slightly. Overall it is well-structured and not overly verbose.

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

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

Given an output schema exists and the annotations cover safety, the description is complete enough: it covers default behavior, filtering examples, and the tool's role within the Ensembl tool family. It doesn't mention pagination or rate limits, but those are less critical for a discovery 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?

The input schema has 100% coverage with detailed descriptions for both parameters, including enums and examples. The description adds minimal extra meaning—it reinforces filtering behavior but mostly restates what the schema already documents. Baseline 3 is appropriate given 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's function: 'List species supported by Ensembl with display name, common name, assembly, taxon ID, and division.' It also differentiates it from sibling tools by labeling it a 'Required discovery step' whose output feeds every other Ensembl tool.

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

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

Explicitly says when to use this tool: 'Required discovery step — species names like homo_sapiens are opaque to non-biologists and are the input format every other Ensembl tool expects.' It also gives actionable filtering guidance for division and nameContains, making the usage context 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?

Despite annotations already providing readOnly, openWorld, and idempotent hints, the description adds substantial behavioral detail: the required mutual exclusivity of symbol/id/ids/symbols, the made-up of up to 20 items with a succeeded/failed split, the species default for symbol lookups, and the expand_transcripts flag with its default and effect on response size. These details go well beyond what annotations offer.

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

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

The description is front-loaded with the primary purpose and immediately establishes the tool's role. It is relatively long but every sentence carries useful information (modes, batch constraints, defaults, pointer to list_species). Slight density prevents a perfect score, but it is 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?

The description is complete for a lookup tool given that an output schema exists (so return format doesn't need to be spelled out), annotations cover safety semantics, and the description covers all relevant usage modes, constraints, defaults, and batch behavior. It also links to a sibling tool for species discovery, providing adequate context for the agent to choose 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?

The schema already provides 100% parameter descriptions, so the baseline is 3. The description adds extra semantics: 'Provide exactly one of symbol, id, ids, or symbols' clarifies a cross-parameter constraint not visible in the schema, and it reiterates the species default and batch limits, reinforcing the meaning beyond the schema fields.

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 uses a specific verb phrase ('Resolve a gene by symbol + species (or by stable ID)') and lists exact outputs (Ensembl ID, genomic location, biotype, description, transcript list). It also distinguishes itself from sibling tools by calling itself the 'entry point for most workflows' and noting that its outputs feed other tools.

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

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

The description clearly states when to use this tool ('entry point for most workflows') and provides contextual usage rules (when to use symbol vs ID lookup, batch vs single, species default). It also points to the sibling tool ensembl_list_species for discovering valid species names. However, it does not explicitly contrast with other sibling tools like get_sequence or get_homology, so the 'alternatives' guidance is partial.

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 goes beyond the readOnly and idempotent annotations by disclosing substantive behaviors: chromosome name normalization, default caps on transcript consequences and PubMed IDs, how to bypass caps, and that truthful totals are always reported. This gives the agent an accurate mental model of response truncation and how to retrieve full data.

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 moderately long (six sentences) but every sentence adds crucial information: purpose, three input formats, output summary, normalization, and cap behaviors. It is well-structured and avoids redundancy, making it appropriately concise for the tool's complexity.

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

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

With 5 parameters, 3 input formats, and an output schema, the description covers all key aspects: how to specify variants, what results are returned, and how to control response size. It integrates annotations and provides enough operational detail for an agent to invoke the tool correctly.

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

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

Because the schema already provides detailed descriptions for all 5 parameters (100% coverage), the description's extra examples and rationale (e.g., 'well-studied variants like rs334 otherwise carry 60+ consequences and 100+ citations') add useful context beyond the schema, such as guidance to include transcript version for best HGVS results. This enriches parameter understanding.

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: 'Predict the functional consequences of a sequence variant using the Ensembl Variant Effect Predictor (VEP).' It clearly differentiates from sibling tools (e.g., ensembl_get_sequence, ensembl_lookup_gene) by specifying the variant-effect prediction use case and lists input formats and output types.

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 clear context for when to use this tool (when you need functional consequence prediction for a sequence variant), and gives practical guidance on selecting among input formats (HGVS, region+allele, or rsID). It does not explicitly name alternatives or exclusions, but the niche is well-defined relative to 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?

Given the read-only, idempotent annotations, the description adds valuable behavioral context: Ensembl normalizes chromosome names, canonical output drops the 'chr' prefix, and exon rows carry parent transcript IDs causing duplicates. It also discloses the risk of huge outputs for variation queries. This goes well beyond 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 a single, well-organized paragraph that leads with the main purpose, then covers format, normalization, defaults, and pitfalls. Every sentence adds useful information without redundancy, making it appropriately sized for the tool's complexity.

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

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

With an output schema present and annotations covering safety, the description still adds necessary context: return fields, normalization, exon duplication, and output-volume warnings. It is complete for a region-query tool, covering both what it returns and how to use it safely.

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 repeats some schema content (e.g., region format, default feature type) and adds a concrete example, but does not significantly extend parameter meaning beyond what the schema already provides.

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

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

The description immediately states the tool's core action: 'Find genomic features overlapping a chromosomal region' and lists supported feature types (genes, transcripts, variants, regulatory elements, exons). The scope is specific and distinct from sibling tools like ensembl_lookup_gene, and the example with BRCA2 reinforces the purpose.

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 says when to use it ('what's in this locus?') and warns against retrieving variation in large regions due to output size. It also tells users to explicitly include feature types only when needed. However, it does not name sibling alternatives for different use cases (e.g., ensembl_lookup_gene for gene-by-name queries), so it lacks full when-not/alternative guidance.

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