dna_match

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

Beyond the readOnly/openWorld annotations, the description discloses an important behavioral fact: results are non-unique ('Several always fit'), so the output is a candidate set rather than a verdict. It also credits the underlying methodology (Shared cM Project 4.0 ranges). It doesn't say how many candidates come back, but the output schema presumably covers that.

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 sentences, zero filler. The core purpose is front-loaded and the disambiguation caveat follows immediately after.

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-parameter, single-required-input tool with an output schema present, the description supplies everything the agent needs: what the result means, its ordering, and that the result is inherently ambiguous. Return-value details are correctly left to the output schema.

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 50%: shared_cm is fully documented in the schema, while lang has only an enum and default with no prose. The description adds no parameter-level detail (no unit hints, no format/locale behavior), so it neither compensates for the gap nor goes beyond the schema. Baseline 3 is appropriate.

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 concrete transformation (shared DNA in cM → candidate relationships) and names the source of the ranges (Shared cM Project 4.0), plus the output ordering ('closest first'). It also distinguishes itself from a sibling by explicitly naming the 'kinship tool' as the complementary step rather than a substitute.

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 real routing guidance: when several relationships fit, use documents and the kinship tool to disambiguate. What's missing is a positive trigger for when to reach for dna_match in the first place (e.g., vs. the kinship or check_match tools) — the agent must infer that this is the cM-interpretation step.

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