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

Annotations declare write, idempotent, non-destructive, closed-world; the description independently adds the required scope ('Requires tickets:write') and retry semantics (retain request ID after an uncertain reply), which is meaningful operational context beyond the hints. It does not explain what the envelope contains or how it can later be inspected.

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?

Four short, front-loaded sentences with no filler; the freeze semantics come first, then constraints, then the operational caveat. Dense rather than bloated, though the telegraphic style costs some clarity.

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-destructive, idempotent write with no output schema, the description covers auth and retry behavior, but it leaves the core semantics of the envelope's fields (hash and schema version) undocumented, so an agent cannot verify it is passing the right values.

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 coverage is 0% for four required parameters. Only request_id gets any narrative treatment (via the retry guidance); snapshot_id, expected_source_hash, and especially the 1-4 expected_source_schema enum are left entirely unexplained, and the enum's meaning is exactly the thing an agent cannot guess.

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 verb is 'Freeze' and the object is 'verified saved values with the definitions and disclosures shown now', which hints at a snapshot-with-provenance operation but never plainly says it creates a durable 'report review envelope'. A reader can infer the general shape but not cleanly distinguish it from create_portfolio_snapshot or create_scope_baseline at a glance.

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?

Gives a clear usage constraint ('Original-capture definitions are unavailable') and an explicit exclusion scope ('this does not approve, share or hold data'), plus a recovery rule ('keep the exact request ID and fields after an uncertain reply'). It stops short of naming alternative tools, but the when/when-not framing is solid.

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