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

Annotations already indicate readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds meaningful behavioral context: it refuses overwriting existing work, preserves immutable history, requires approved source references, and clarifies that assistant submissions never claim human authorship. It also mentions revision protection and idempotency through the expectedRevision parameter. These go beyond the annotations and give the agent concrete expectations about mutation behavior.

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 six sentences, each carrying meaningful content: purpose, prefill behavior, authorship constraints, attachment requirements, dependency resolution, and immutability. It's front-loaded with the core purpose. The sentences are dense but not bloated. Could be slightly more concise, but every sentence adds value for correct usage.

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?

Given the tool's complexity (nested changes array, expectedRevision object, 4 params, 50% schema coverage, no output schema), the description covers the critical usage constraints: prefill vs replace, overwrite refusal, immutable history, source ID requirements, and dependency resolution. It doesn't explicitly state what the return value is, but since there's no output schema and the focus is on mutation behavior, this is acceptable. The description is sufficient for an agent to understand the mutation's semantics and constraints.

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 50%: projectId and idempotencyKey have descriptions in the schema, but expectedRevision and changes do not. The description adds value by explaining the overall semantics: prefill vs replace intent, revision protection, and immutable history, which clarifies the purpose of expectedRevision. However, it doesn't explicitly explain the structure of 'changes' array items beyond what's in the schema, but the description's context about provenance and source markers helps interpret evidenceRefs and intent. The description partially compensates for the missing schema descriptions.

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 clearly states the verb 'Save' with the resource 'field contributions' and elaborates on the mechanism: provenance, source markers, comment and revision protection. It also distinguishes this from generic save operations by mentioning prefill/overwrite refusal semantics. It clearly differentiates from siblings like helvabase_assemble_contributions or helvabase_confirm_contribution_review by focusing on saving field-level contributions with specific constraints.

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 clear context for when to use this tool: 'Use prefill for empty fields; it refuses overwriting existing work.' It also states that 'Assistant submissions never claim human authorship or approval' and 'Attachments must reference an approved source ID.' However, it doesn't explicitly name alternative tools or state when NOT to use this tool in favor of a sibling. It implies usage context (when contributing to a dossier) but lacks explicit exclusions or alternative references.

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