ensembl-mcp-server

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

Annotations already establish readOnly, openWorld, and idempotent behavior. The description adds valuable behavioral substance by specifying exactly what kinds of data are returned, including homology type, percent identity, percent positives, and taxonomy level. This goes beyond the annotation bar and gives an agent a clear mental model of the output.

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 information dense. Every sentence contributes something functional: the core purpose, return-value detail, motivation/examples, and input requirements. There is no filler or tautological phrasing.

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 tool of moderate complexity with five well-documented parameters, with annotations and an output schema already present, the description supplies all the missing operational context: when to use it, what kind of results to expect, and how to structure the query. Nothing essential for choosing or invoking it is left unexplained.

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 every parameter is already well documented. The description reinforces the id/symbol either-or constraint and the target-species filtering option, which adds a small amount of use-case framing but does not deepen the semantics of any parameter significantly. The schema remains the primary semantic source.

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

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

The description opens with a specific verb and resource: 'Find orthologs and/or paralogs of a gene across species.' It clearly distinguishes from sibling tools like ensembl_get_sequence, ensembl_get_xrefs, and ensembl_lookup_gene by focusing specifically on cross-species homology relationships rather than sequences, annotations, or identifiers.

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 with concrete examples ('what is the mouse equivalent of human TP53?') and states the two accepted input modes: symbol + species or stable gene ID. It also explains the target_species filtering behavior. However, it does not explicitly name sibling tools or say when not to use this tool, though schema-level guidance points to ensembl_lookup_gene for ID resolution.

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?

Read-only and idempotency are already covered by annotations, so the description adds useful behavior beyond those: it warns that large sequences are returned in full and that the character count is provided so callers can budget context. It also clarifies molecule-type restrictions, which is valuable operational context.

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 every sentence contributes practical guidance: return behavior, sequence-type semantics, region formats, and the protein workflow. Nothing is redundant or padded.

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 read-only sequence retrieval tool with five parameters, an output schema, and full schema coverage, the description covers the essential decisions an agent must make: which ID type to pass, which sequence type to request, how to specify regions, and where to get a transcript ID when needed.

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 schema already documents each parameter, but the description adds concrete region format examples and cross-parameter constraints, such as protein sequences requiring ENST/ENSP IDs and the expand parameters applying only to genomic/region queries. This goes beyond what the schema alone 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 states a specific verb ('Fetch') and resource ('DNA, cDNA, CDS, or protein sequence') and immediately clarifies the supported input identifiers and modes. Its scope is distinct from the sibling tools, which handle homology, xrefs, variants, and region metadata rather than sequence retrieval.

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 context on which sequence type to request and explains how to provide genomic regions. It also explicitly tells the caller to use ensembl_lookup_gene with expand_transcripts=true when a protein sequence is needed from a gene ID, though it does not directly contrast itself with all 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 already declare readOnlyHint, idempotentHint, and openWorldHint. The description goes beyond this by specifying the output shape (dbname, primary ID, display ID, description), explaining the default behavior when dbname is omitted, and describing how returned IDs chain to protein, literature, disease, and pathway resources. It does not cover error-case or rate-limit behavior, so the remaining edge-case transparency keeps it from a 5.

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 core purpose, followed by output format, filter behavior, chaining semantics, and prerequisite. The sentences are purposeful and efficient, though the 'Common dbname values' list partially duplicates the input schema and could be trimmed.

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 output schema, rich annotations, and schema descriptions, this tool definition is nearly complete. It covers the prerequisite (stable Ensembl ID), the default behavior (all xrefs), filtering semantics, and usage context. The main missing piece is a more explicit relationship to sibling tools, but that is not critical for basic 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 input schema already explains both parameters thoroughly, including Ensembl ID types and common dbname examples. The description largely repeats the same enumerated dbname values and 'Ensembl stable ID' prerequisite rather than adding significant new meaning beyond 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 verb and resource: 'Retrieve cross-database references for a gene or feature' and lists concrete databases (HGNC, UniProt, EntrezGene, OMIM, RefSeq, Reactome). This clearly distinguishes it from sibling tools that handle homology, sequence retrieval, variant prediction, or region queries.

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 provides clear context: the tool requires an Ensembl stable ID and instructs the agent to 'use ensembl_lookup_gene first.' It also explains the optional dbname filter. However, it does not explicitly state when not to use this tool compared with sibling tools, e.g., when to choose ensembl_get_sequence or ensembl_get_homology instead.

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 communicate read-only and idempotent behavior. The description adds genuinely useful behavioral details beyond that: the default division behavior when no division is passed, the division categories, and the fact that nameContains performs a local case-insensitive substring match. There is 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 dense but efficient: three sentences cover purpose, workflow role, and filtering behavior. The only slight redundancy is repeating the default-division behavior already stated in the schema, but the rest of the content earns its place.

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 low complexity (2 optional params, 100% schema coverage, output schema present, read-only annotations), the description covers all essential decision points: what the tool returns, why it must be called first, and how to limit results by division or partial name. No meaningful gap remains.

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 input schema already fully explains both division and nameContains with examples. The description adds workflow context—'input format every other Ensembl tool expects'—which helps an agent understand why the parameters matter, but it does not materially change the semantics 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 verb and resource: 'List species supported by Ensembl' and enumerates the returned fields (display name, common name, assembly, taxon ID, division). It also clearly separates this discovery/list tool from the sibling get/lookup/query/predict tools, which operate on specific species or regions.

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 strong contextual guidance, calling the tool a 'Required discovery step' and explaining that species names like homo_sapiens are the input format all other Ensembl tools expect. It also explains when to use division and nameContains. It does not explicitly name alternatives to avoid, but the discovery-step framing makes the place in the workflow 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?

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds batch behavior, a 20-item cap, the succeeded/failed batch split, and the fact that returned stable IDs and coordinates feed other tools. It does not contradict the annotations, though it could say more about single-lookup failure or ambiguity 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 front-loads the core purpose and outputs, then explains modes, defaults, and related tool usage. It is dense but every sentence contributes to correct tool selection or invocation, with no wasted words or tautological restating of the title.

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 read-only lookup tool with a rich input schema, an output schema, and strong annotations, the description covers the important gaps: entry-point role, species discovery, batch usage, exclusivity constraints, and linkage to downstream tools. Nothing critical is missing for an agent to successfully select and invoke 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 input schema already documents all six parameters, so the description does not need to re-explain them. It adds meaningful cross-parameter semantics: exactly one of symbol, id, ids, or symbols must be provided, and species handling changes depending on which mode is used. This goes beyond the schema's per-field descriptions, though the schema still carries most of the load.

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 states a specific verb and resource: 'Resolve a gene' to a concrete set of outputs (Ensembl ID, location, biotype, description, transcript list). It also distinguishes the tool from siblings by labeling it the 'entry point for most workflows' and explaining that the returned IDs and coordinates are inputs to 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 gives strong usage context: symbol vs stable ID lookup, batch mode, the one-of exclusion rule, species defaults, and a pointer to ensembl_list_species for valid species names. It does not fully state when to prefer sibling tools such as ensembl_query_region or ensembl_get_sequence instead, so it stops short of complete when/when-not 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?

The description adds meaningful behavioral context beyond the readOnly/openWorld/idempotent annotations: it reveals that responses are compacted by default, that transcript and PubMed lists are capped, that truthful pre-cap totals are always reported, and that setting a cap to 0 or include_all_colocated_pubmed=true retrieves the full set. 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 front-loaded with the primary purpose and input formats, and it maintains a logical progression from purpose to inputs to outputs to defaults. Some sentences duplicate details already present in the parameter schema (e.g. chr-prefix normalization, set to 0 to return every transcript consequence), which slightly inflates length, but the overall structure remains efficient for the 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?

Given the output schema and annotations are present, the description covers all necessary information: purpose, accepted formats, example inputs, default behaviors, and how to disable caps. An agent has enough information to select and invoke the tool correctly without inspecting external resources.

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 adds extra semantic value by explaining why the caps exist ('well-studied variants like rs334 otherwise carry 60+ consequences and 100+ citations') and clarifying how the caps interact with include_all_colocated_pubmed, going beyond the schema's functional definitions without being redundant.

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 goes on to enumerate exactly what is returned (consequence term, transcripts, genes, impact level, colocated variants), which clearly distinguishes it from sibling tools like ensembl_get_sequence, ensembl_lookup_gene, or ensembl_get_homology.

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 use context: 'Predict the functional consequences of a sequence variant' and lists the three accepted input formats. It does not explicitly say when not to use this tool or name alternative tools, but the domain is so specific and visually differentiated from the sibling names that an agent can confidently select it for variant effect prediction.

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?

It discloses highly relevant behavioral traits beyond the readOnlyHint annotation: Ensembl chromosome-name normalization, omission of the chr prefix in canonical output, the default feature broadening to gene to prevent overwhelming results, the scale of variation returns, and the rule that exon rows appear once per parent transcript. These are exactly the kind of behavioral details that affect invocation expectations.

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 verbose but each sentence earns its place by adding essential usage detail. It is front-loaded with the purpose and returns list, then addresses region format and parameter defaults. The text repeats some schema descriptions, which is a minor waste, but overall tightly 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 four parameters, strong annotations, output-schema presence, and the provided schema descriptions, the description covers everything an agent needs to call correctly: the region format, normalization, the default feature type, the risk of large returns, and the per-transcript exon disambiguation. No critical calling context 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 description coverage is 100%, so the input schema already documents all parameters comprehensively. The description adds some runtime behavior around the feature parameter (flooding risk, exon duplication semantics), but does not provide meaningful new meaning that is not already present in the schema. It hits the baseline for well-covered schemas.

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 phrase, "Find genomic features overlapping a chromosomal region," listing the resource types and clearly distinguishing it from sibling tools like gene-centric ensembl_lookup_gene or sequence-focused ensembl_get_sequence. The introductory purpose is concrete and 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 gives clear context for when to use this tool ("what's in this locus?") and for seeding follow-up lookups, and it warns about defaulting to gene-only to avoid huge returns. However, it does not explicitly list alternative tools for cases like single-gene lookup, leaving some usage routing to the agent's inference.

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