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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is known. The description adds meaningful behavioral guarantees: only failed channels are retried, and already-published channels are never re-posted, which prevents duplicate posts. It does not mention side effects like rate limits or partial failure behavior, but the non-repost guarantee is strong context.

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?

Two sentences, front-loaded with the core action, and no filler. Every phrase adds useful information: the action, the channel scope, the optional filtering behavior, and the anti-duplicate guarantee.

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 only two parameters and no output schema, the description covers the critical invocation details: which post, which channels, and the safety guarantee about not re-posting published channels. It could be slightly stronger by explaining what happens if there are no failed channels or what the response contains, but it is sufficient for correct use.

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 description coverage is only 50%: channel_ids is described in the schema, and the description reinforces it by explaining it can target specific channels. However, post_id has no description in either the schema or the tool description, so the agent must infer its meaning from the parameter name alone.

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 names a specific action ('Retry publishing'), a specific resource (a post), and a precise scope ('failed Facebook/Instagram channels'). It also states a key exclusion ('published channels are never re-posted'), which distinguishes it from broader tools like publish_post_now or publish_to_channels.

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 description gives clear context: use this when a post had failed channels and you want to retry them now. It also clarifies the optional channel_ids behavior, but it does not explicitly name alternatives or state when not to use the tool.

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