Retry Failed Platforms

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

The description fully discloses the tool's behavior: it resets failed rows to PENDING, moves the post to PUBLISHING, performs retries asynchronously, and does not allow content changes. This aligns with the annotations (readOnlyHint=false, destructiveHint=false) and gives the agent a complete mental model of side effects.

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 well-structured and front-loads the primary purpose, but it includes some redundancy (e.g., mentioning asynchronous behavior twice, restating the condition about failed rows). It is slightly longer than necessary but remains efficient and clear.

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?

The description provides sufficient context for an agent to decide when and how to use the tool: it references the prerequisite list_post_results call, explains the asynchronous nature, and gives practical guidance on retry conditions. Since an output schema exists, not describing return values is acceptable. No missing information prevents correct usage.

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?

Although the schema already covers both parameters (id and platformIds) with descriptions, the tool description adds significant semantic value: it specifies that platformIds come from list_post_results, that they are row IDs rather than platform names, that at least one is required, and that only FAILED rows are processed. This enriches the schema information.

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 clearly states the tool's function: re-queueing publishing for failed platforms. It specifies the action (reset to PENDING, retry) and the target (a post's failed platforms), making its purpose unmistakable and distinguishable from sibling tools like list_post_results or update_post.

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 provides explicit usage directions: call it after retrieving platformIds and errorMessages from list_post_results, retry only after the cause is fixed, and avoid retrying when the failure is a platform-side restriction. It also clarifies that only rows with status FAILED and IDs in platformIds are affected, and that other IDs are ignored.

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