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

Annotations already convey readOnlyHint=false and destructiveHint=true; the description goes beyond by disclosing 'Any text change clears the old score' and the credit costs for revise/fix/humanize/review, plus that editing text is free. It clarifies that staging marks ready-to-publish but publishing happens elsewhere. No contradiction. Could be a 5, but some details like idempotency or failure effects are absent.

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 description is dense but every sentence earns its place: action semantics, cost, side effects, user-decision boundary, and sibling routing. It is somewhat long and list-heavy, but appropriately so given seven actions. Front-loads the core purpose and defers the sibling comparison to the end.

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?

Given the high complexity (7 actions, 6 params, no output schema), the description covers what each action does, cost/credits, side effects on scores, user decision boundary, and when to use the sibling tool. The input schema adds parameter types/enums, and the description fills the behavioral gaps. Complete enough for an agent to invoke correctly.

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 covers 67% of parameter descriptions; the description enriches the action enum with plain-language meanings (e.g., 'revise rewrites it in the brand voice per a one-click preset', 'fix makes the surgical change the reviewer's notes asked for'). It also adds which parameters apply to which actions, bridging the 33% gap. Slightly more param-level detail would push to 5.

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 ('Act on one draft') and resource ('draft in the user's queue'). Distinguishes seven sub-actions, and explicitly points to sibling tool teach_content_voice for global reactions. Title adds context. Clear and specific.

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?

Provides explicit when-to-use guidance: 'Stage and discard are the USER's decisions — act on their say-so, never on your own judgment.' Also explicitly names the alternative tool (teach_content_voice) and the condition for using it. This is model-tier usage guidance.

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