add_dna_match

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

Annotations already declare the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower, and the description still adds real context: a validation gate ('Nothing is written unless the segments parse'), the storage format guarantee that get_dna_matches reads back, and the atomicity implied by refusing unparseable data. It does not state what the call returns or whether auth/permissions are required.

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?

Three short paragraphs, front-loaded with the verb and resource before the mechanics and the caveat. Each paragraph carries information (validation, storage, relationship caveat), though the middle paragraph's format-compatibility explanation is slightly more than an agent needs to invoke the call.

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 non-idempotent write tool with no output schema, the description covers the essentials: what is recorded, that validation gates the write, that a new citation is minted, and how the result is read back via get_dna_matches. The main gap is the return value (e.g. the new match handle or transaction id), which nothing else documents.

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 all four parameters in detail, including the CitationInput precedence rules. The description reinforces the citation parameter's meaning ('the test the match came from') and the segment-row format, but adds little 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 opening sentence gives a specific verb and resource ('Record a DNA match') plus the scoping constraint that it is cited to the test that found it. It implicitly distinguishes itself from the read-side sibling get_dna_matches, which it names as the reader. It does not, however, distinguish itself from closely related siblings like parse_dna_segments or add_citation, which an agent might also consider.

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?

The final paragraph gives explicit when-not guidance: 'A match proves the two share DNA, not how they are related. Record any relationship separately, with its own evidence.' That steers an agent away from a plausible misuse. It stops short of naming a concrete alternative tool (e.g. a relationship/event add) or noting that segments can be checked with parse_dna_segments first.

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