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

Annotations already declare destructiveHint=true and idempotentHint=true, so the write/idempotency profile is covered structurally. The description adds two useful facts annotations cannot convey: edits are confined to the offer copy, and expected_draft_revision is mandatory (implying optimistic concurrency control). It still doesn't say that content_ast replaces the existing document content, which matters for a destructive edit.

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, scope statement front-loaded, no filler. The third sentence restates what the schema's required list already enforces, so it earns slightly less than it could, but the prose is tight and skimmable.

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 destructive, idempotent mutation taking a nested content_ast payload, the description omits how the content is supplied or what the AST should contain, what happens to prior content, and any failure mode for a stale revision. With no output schema and 0% parameter coverage, the definition is under-specified for a tool this consequential.

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% across 6 parameters, so the description carries the full burden and only addresses one parameter (expected_draft_revision), which the schema's required array already states. content_ast (a free-form nested object), document_id, idempotency_key, offer_id and request_id get no meaning from the description at all.

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?

States a specific verb and resource ('Edit one document for this offer') and immediately scopes it against the library document, which is exactly the distinction needed against siblings like yardstick_offers_library_documents_update_draft. An agent can tell the offer-scoped edit apart from the library edit without opening either schema.

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 scope statement ('for this offer only... the library document does not change') implies when this tool applies rather than an alternative, but it never names the sibling to use when the library draft should change. No prerequisites or preconditions beyond the revision requirement are given.

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