ensembl_consequence

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description enriches this by explaining on-demand VEP behavior, that novel variants work, that non-human species are supported, and what results look like (most severe consequence, per-transcript effects, co-located variants). It also discloses the caveat that rsID resolution via dbSNP can yield less specific consequences. 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?

Four focused sentences, each earning its place: scope, input forms and preferences, return contents, sibling routing. The core purpose is front-loaded, and the alternative-tool guidance is saved for the end. No filler or redundant restatement of schema fields.

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 with no output schema, the description sufficiently explains return values, including impact, codon/amino-acid change, SIFT/PolyPhen, and co-located variant metadata. It also covers input formats, species support, novel-variant behavior, rsID caveats, and when to choose variant_get. Nothing critical for an agent to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents variant, species, and limit. The description adds meaningful value beyond this: concrete HGVS notation examples (NM_004333:c.1799T>A, ENST00000288602:c.1799T>A), the c./p./g. notation forms, and a clear preference rule for HGVS over rsIDs. This is more than the schema alone provides, though not every parameter nuance is expanded.

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?

Description states a specific verb ('Predict'), a clear resource ('functional consequence of a variant via Ensembl VEP'), and immediately distinguishes itself from variant_get by noting that variant_get is preferred for known human variants. It also highlights unique capabilities (novel variants, non-human species) that make it easy to differentiate from sibling 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?

Explicitly tells the agent when to use this tool: for novel variants, non-human species, and general VEP-based consequence prediction. It also provides concrete routing guidance: prefer variant_get for known human variants when deep pre-computed scores are needed, and prefer HGVS notation over rsIDs when both are available.

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