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

Annotations already declare readOnlyHint=false and destructiveHint=true, indicating a write operation. The description adds that it does not upload or certify, which clarifies scope but does not elaborate on side effects, idempotency behavior (though the schema's idempotencyKey description covers this), or what happens to existing data. It adds some value beyond annotations but is not rich.

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 description is two sentences: the first states the core action and the optional version, the second states a key exclusion. It is front-loaded with the most important information and contains no filler or redundancy.

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 creation tool with nested objects, no output schema, and only partial parameter descriptions, the description is insufficient. It does not explain the return value or what the agent should expect after registration, nor does it clarify what 'unreviewed version description' means in practice. It also fails to reference the sibling tool for adding versions to existing evidence, leaving the agent without full context.

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 only 50%: only the idempotencyKey parameter has a description, while the nested 'evidence' object (containing title, proofType, version, etc.) is undocumented. The description mentions 'optionally with an unreviewed version description' but does not explain the required fields or the structure of the version object. The agent must rely entirely on the schema, and the description fails to compensate for the missing parameter semantics.

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 clear verb ('Register') and resource ('evidence record'), and immediately distinguishes the tool from file upload or certification. It conveys that this creates a new evidence entry, differentiating it from sibling tools like helvabase_add_evidence_version which operate on existing records.

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 description provides exclusionary guidance ('Does not upload or certify a file') but no explicit when-to-use or when-not-to-use recommendations. It does not mention alternatives like helvabase_add_evidence_version for adding a version to existing evidence, nor does it explain conditions for using this tool over others. The guidance is limited to stating non-actions.

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