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

Annotations declare a non-read-only, non-idempotent, open-world mutation, and the description adds genuinely new behavioral facts on top: the token requirement, the optimistic-concurrency 409 response, and the recommended re-read-and-retry reaction. It stops short of saying whether the proposal is published immediately or awaits review, which matters for a mutation named 'propose'.

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?

Three short sentences, zero filler, and the core action leads. The conflict-handling clause is dense with operational value rather than padding.

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 9-parameter, nested-object mutation with no output schema, the description covers auth and concurrency but omits the outcome of a successful call (is the revision live or pending?) and says nothing about the required kind/title/summary/body fields. Adequate but with clear gaps for this level of complexity.

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 44% across 9 parameters, so the description is expected to compensate. It does so well for the trickiest one, base_revision_id, spelling out the null case and conflict semantics, but the other eight (kind, title, summary, body_markdown, record_id, sources, conditions, tags) get no added meaning beyond the schema.

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 first sentence gives a specific verb and resource: 'Propose a new revision of an existing record.' That is enough to separate it from create_record (which makes a record) and get_revision (which reads one), though it never names those siblings explicitly. Purpose is unambiguous but sibling routing is left to inference.

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 explains the semantics of base_revision_id (null when the record has no published revision) and gives a concrete recovery path for the 409 conflict case, which is real usage guidance. However, it never states when to choose propose_revision over create_record or annotate, and no prerequisites other than the token are described.

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