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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds one extra behavioral fact — the recorded version is left "unreviewed" (matching the missing_review default) — which is useful context an agent would not get from annotations alone, but it says nothing about permission requirements or the effect on prior versions.

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 tight sentences, with the core action front-loaded and the exclusion trailing. Nothing is padded, though the second sentence could have been sharper by naming the transport tool.

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 mutation tool with no output schema and a partially documented nested payload, the description covers the most important trap (no file bytes here) but leaves the shape and constraints of the version metadata to the schema, which only partly documents itself.

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 33%: only idempotencyKey is documented in the schema, while the nested version object's seven fields (fileName, issuer, mimeType, validFrom, validUntil, jurisdiction, status) are undocumented anywhere. The description's note that hashes/storage references are handled elsewhere slightly clarifies the intent of the version object, but it adds no meaning to any individual parameter.

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 has a verb ("Record") and a resource ("unreviewed evidence version"), which distinguishes it from write-heavy siblings like upload_original. However, the phrase "evidence version description" is ambiguous — it is unclear whether an actual version is being recorded or merely a textual description of one, and the tool is never contrasted with the closely related helvabase_create_evidence.

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 an exclusion clearly: file uploads, hashes and storage references belong to "the dedicated upload transport", so an agent knows not to use this for binary content. It does not, however, name that alternative tool explicitly or state the prerequisites (existing evidenceId) for calling this one.

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