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

Annotations declare destructiveHint and non-idempotency, but the description adds what they cannot: the operation is atomic ('all or nothing'), delete is permanent ('for good'), each call counts as an edit, and the caller must be Editor or above. It also discloses a non-obvious side effect — a published post changing language moves to the new language's address. No contradiction with readOnlyHint=false or destructiveHint=true.

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?

Dense and front-loaded — scope first, then the change vocabulary, then permissions and alternatives. Nearly every clause carries information. The telegraphic, fragment-heavy style ('One change to many posts or pages, all or nothing') costs some readability, and the trailing apostrophe construction around update_post_settings is slightly awkward.

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 an 8-parameter destructive mutation with no output schema, the definition covers permissions, atomicity, per-change parameter applicability, and where to go for single-post edits. What it omits is what a caller gets back (counts of edited posts?) and how tag creation interacts with add_tag when the tag does not exist.

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 75%, so most parameters are already documented; the description still adds real meaning by explaining that parameters are conditionally applicable per change type, that authors accepts 'replace' or 'add after the ones there' in byline order, and that language changes relocate a published post. It does not explain post_ids cardinality limits or ordering, and author_mode is only glossed inline.

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?

Opens with a specific verb+resource+scope: one change applied to many posts or pages on a single named site, and then enumerates the eight exact change types (authors, add_tag, remove_tag, visibility, language, feature, unfeature, delete). An agent can distinguish this bulk-mutation tool from single-post siblings like update_post_settings or edit_post 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?

Explicitly routes the agent: use list_posts to obtain the ids, and use update_post_settings for one post's other settings. That is clear when-to-use context with named alternatives. It stops short of a full exclusion set — edit_post and delete_post exist as siblings and are never mentioned, so the boundary between bulk and single-post mutation is only partly drawn.

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