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

The description adds substantial behavior beyond the annotations: a required `content:write` scope, a mandatory validation-then-confirm two-phase protocol, the fact that call one is a no-op, that unknown fields are refused by name, and that call one returns a summary plus confirm_token. These details are consistent with destructiveHint=true and idempotentHint=false, and no annotation is contradicted.

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?

Front-loaded with the action and the permission requirement, then the procedural rules in the order an agent needs them. Four short sentences with essentially no filler; the phrase "it checks the arguments as the change would" is slightly convoluted but still load-bearing.

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, non-idempotent mutation with no output schema, the description supplies the auth scope, the confirmation protocol, and the shape of the first call's response — the things an agent most needs to avoid an accidental write. The one real omission is that it never says which post fields may be supplied in the change payload, which is invisible in the schema because additionalProperties is open.

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 50%; the schema already documents confirm_token's two-call semantics, so the description's restatement of "call again with the same arguments plus confirm_token" adds only marginal value. Critically, the schema allows additionalProperties with only `id` required, so the actual set of post fields that can be changed is documented nowhere — a gap the description gestures at ("a field this tool does not take is refused") but does not close.

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 ("Change a post") that clearly distinguishes it from create_post, delete_post, pin_post, and restore_post in the sibling list. The added explanation of the confirm-token flow sharpens what kind of change operation this is (a staged mutation), though it never explicitly contrasts itself with other update tools like update_mix or edit_document.

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 two-call workflow is spelled out precisely: first call validates, second call applies with confirm_token, and the human must approve the summary in between. What is missing is routing guidance — no statement of when to reach for this versus another post-mutation or content-editing sibling, and no exclusions or prerequisites beyond the scope requirement.

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