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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description earns its keep by explaining exactly what gets destroyed (the whole account list is replaced, [] empties it) and what survives (posts already made keep their accounts). It also adds a validation constraint (channel_ids must belong to this workspace) that appears nowhere in structured data.

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?

Four short sentences, front-loaded with the primary operation before the destructive detail and the set_audience pointer. Every sentence carries information; the market sentence is the only mildly tangential one, though it does prevent a plausible misuse.

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 mutation with no output schema, the description covers the two things an agent most needs: what is overwritten and what is preserved. It omits permission requirements and error behavior when channel_ids is invalid or oversized (maxItems 2000), which would round it out.

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 only 50%, so the description must compensate, and it does so for the highest-risk parameter by spelling out replace-vs-append semantics for channel_ids and the rename behavior for name. It leaves group_id and the workspace scoping implicit, so it does not fully close the coverage gap.

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 pair ('Renames a group and/or replaces its accounts'), and the conjunction makes the two independent operations explicit. This separates it cleanly from create_group, delete_group, and list_groups in the sibling set.

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?

Gives the decisive usage rule for the risky parameter ('channel_ids becomes the whole list; [] empties it') and routes market changes to set_audience, an explicit alternative. It stops short of stating when to prefer update_group versus create_group/delete_group for restructuring, but the context is otherwise unambiguous.

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