ensembl_lookup

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

The annotations already signal readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context: expand=true returns all transcripts with translation/protein IDs, versioned IDs are resolved to the current record, and species aliases are accepted. 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 core purpose and output, followed by input formats and then a clear alternative routing. Each sentence earns its place and the examples make the syntax immediately usable 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?

With no output schema, the description correctly takes responsibility for explaining return values: stable ID, symbol↔ID mapping, versioned identifier, canonical transcript, coordinates, and expanded transcript details. It does not cover edge-case behavior such as not-found handling or exact default output, but for a read-only lookup tool this is largely sufficient.

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 explaining that versioned IDs are resolved to the current record, that species accepts scientific names or aliases like 'homo_sapiens'/'human', and what expand=true changes about the response.

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 clear verb-resource pair: 'Resolve a gene in Ensembl terms' and enumerates the exact outputs (stable ID, symbol↔ID mapping, versioned identifier, canonical transcript, coordinates). It also distinguishes itself from gene_get by declaring that it is the identifier/structure authority.

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 explicitly tells the agent when to use a different tool: 'For rich human gene annotation (summary, pathways, drugs, diseases) use gene_get instead.' It also defines its own role as the identifier/structure authority, giving clear selection guidance among siblings.

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