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

Despite annotations already flagging mutation and safety, the description adds substantial behavioral detail: omitted items remain unchanged, accepted/rejected items are immutable, content replaces only that item, edits apply against the latest proposed text, and no intermediate content history is kept. It also discloses the conflict semantics and forbids blind retry, which is exactly the kind of context an agent needs for a versioned mutation.

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?

Sentences are dense but almost every clause carries necessary information, and the ownership constraint is front-loaded. The telegraphic style ('edits match the latest proposed text; content replaces only that item') reads as clipped fragments rather than structured guidance, which slightly hurts scanability for a nine-parameter 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 complex, non-idempotent-annotated mutation with nine parameters and no output schema, the description covers the domain semantics well but leaves several required inputs (base_revision, idempotency_key, evidence, rationale) unexplained. Nothing indicates what a successful call returns or how result_offset behaves, so an agent is only partially equipped.

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 0%, so the description carries the burden, and it does explain the core payload semantics (items, edits, content, and the two version parameters). However, it says nothing about required parameters base_revision, idempotency_key, project_id, change_id, or about evidence, rationale, and result_offset — base_revision in particular is central to the conflict behavior described but never tied to it.

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 makes clear this modifies an *existing pending proposal* belonging to the caller ('Maintain YOUR existing pending proposal; never another author's') and that the review stays pending, which separates it from submit_changes. It never states the resource name explicitly ('change proposal') nor a clean verb+object phrase, so an agent must infer from the name, but the operative intent is unambiguous.

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 gives a concrete prerequisite chain: read read_change(view=proposed, document_id) first, then pass its proposal_version plus the current contract_version. It also states a negative rule (not another author's proposal) and a recovery path for conflicts ('rereading, never blind retry'). What's missing is an explicit statement of when to prefer amend_changes over submit_changes; the 'same review stays pending' clause only implies it.

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