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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavioral context: the queueing semantics that 'idle' means every prior edit drained, not just the latest, and that a short note of the draft agent's last action is returned. That is non-obvious operational behavior beyond structured fields.

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 critical polling instruction is front-loaded and the negative scoping lands last, which is well ordered. It is slightly longer than needed because 'running means at least one edit is still queued or in progress' largely restates the idle definition from the opposite direction.

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?

With an output schema present, return values need not be re-explained, and the description covers the missing semantic layer (running vs idle meaning, queueing). Nothing an agent needs to poll correctly is absent.

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 100% and the single parameter is fully described there as the documentId returned by edit_document or create_document. The description only restates 'Pass documentId' without adding format, sourcing, or edge-case detail, so the baseline 3 applies when the schema does the heavy lifting.

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 states a specific verb and resource (check whether a document is still being edited) and explicitly scopes it to the post-edit/create lifecycle. It distinguishes itself from siblings by stating what it is not ('not the chat transcript, and not a way to edit'). An agent can identify this as a status/polling tool without opening the 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?

It names the exact triggering conditions (after edit_document or create_document), the polling loop (call until status is idle, then fetch), and the alternative to use for mutation (edit_document). This is explicit when-to-use, when-to-stop, and what-not-to-use guidance.

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