compare_variants

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

With no annotations, the description carries the full burden and largely does: it discloses that this performs live inference via score_variant with the SDK's recommended scorers, that results carry `source: live`, and that outputs are model predictions for research prioritization with no pathogenic/benign call. That is meaningful behavioral context beyond a bare 'compare' statement, though it doesn't quantify latency/cost of live inference.

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 core comparison semantics are front-loaded in the first sentence, followed by execution model, applicability, provenance, and a caveat. The 'comparison of predicted effect sizes, not of severity' idea is restated near the end, which is mildly redundant but not wasteful enough to hurt much.

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 two-nested-object tool with no output schema and no annotations, the description covers execution model, accepted variant types, provenance flag, and interpretive limits. It could say more about what the returned per-scorer structure looks like, but the essentials an agent needs to invoke it correctly are present.

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 description adds no field-level meaning for variant1/variant2 beyond noting the accepted variant classes (SNV, indel, MNV) and an example using rsIDs. The nested schema properties do carry descriptions, so variant structure is largely covered there, making 3 the appropriate baseline.

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 names a concrete operation on a specific resource: pairwise comparison of two variants, reporting per-modality predicted effects and which has the larger absolute quantile per scorer. It even disambiguates the semantics ('comparison of predicted effect sizes, not of severity'). It stops short of explicitly routing against near-name siblings like compare_variants_same_gene or compare_alleles.

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 states the operating context (runs live inference, works for SNVs/indels/MNVs) and gives a worked example, which implies when it applies. However, there is no explicit when-not guidance or pointer to alternatives such as batch_score_variants for many variants or compare_variants_same_gene for the same-gene case, leaving sibling selection to inference.

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