convert_variant

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the score is judged on added context; the description adds that output is normalized to hg38 and that no classification is performed. It does not state behavior on unparseable or ambiguous input (parse failures, multiple mappings), which is the main residual unknown.

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?

Two short sentences, front-loaded with the verb and output, followed by usage scoping. Every clause carries information and nothing is repeated from structured fields verbatim.

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?

Output schema exists so return values need not be explained, annotations carry the safety profile, and both parameters are documented in the schema. The only material omission is guidance versus liftover_coordinate, which matters because both touch hg19/hg38 conversion.

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 variant formats and the input_genome enum plus its hg19-to-hg38 lifting note are already documented in the schema. The description's phrase 'written in any notation' echoes the schema's format list rather than adding new semantics, so baseline 3 applies.

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?

States a specific verb+resource ('Convert a variant ... into normalized hg38 genomic coordinates') and immediately sets itself apart from annotate_variant by clarifying it returns chr/pos/ref/alt without annotation.

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?

Gives an explicit when-to-use ('when you only need the chr/pos/ref/alt') and an explicit when-not with a named alternative ('use annotate_variant for that'). It does not address the nearby sibling liftover_coordinate, which overlaps conceptually since hg19 input is lifted to hg38, leaving one confusable pair unresolved.

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