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

Annotations already signal a non-read-only, idempotent, destructive mutation, and the description adds substantial behavior beyond that: zero-based character spans, persistence semantics, the irreversible adoption of prior fields and section targets, the need for a fresh clear report on draft changes, and the explicit statement that checks remain bounded and never confer human approval. No contradiction with the annotations.

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 five dense sentences with no filler, and it is front-loaded: purpose first, then critical semantics, then lifecycle constraints and boundary conditions. Every sentence carries load-bearing information.

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?

This is a complex five-parameter mutation with nested objects and no output schema, so the description carries a heavy burden. It covers purpose, location semantics, and lifecycle well, but it never states the response/return shape or how to populate `revision` beyond referring to the 'exact current draft'. It is adequate for tool selection but not fully self-sufficient for a correct first invocation.

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?

With schema description coverage around 40%, the description compensates for some gaps by explaining expectedReportRevision ('Echo ... null initially') and locations ('zero-based character spans of persisted text'). However, the `revision` object, `fields[].source`/`marker`, and the mapping between the `field` enum values and the mentioned check categories remain undocumented, so compensation is only partial.

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 opens with a specific verb and resource: 'Persist checks against the exact current draft and explicit text spans' for support gaps, repeated commercial values, and validity dates. It also references helvabase_draft_checks as the source of expectedReportRevision, helping distinguish this write-side operation from the related read-side sibling.

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 gives clear situational context: expectedReportRevision must be echoed from helvabase_draft_checks, and lifecycle constraints are explicit ('Once adopted... cannot be omitted', 'a changed draft needs a fresh clear report'). It stops short of a full 5 because it does not enumerate alternative tools or explicit when-not-to-use cases.

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