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

Goes well beyond the annotations by disclosing the public visibility of the post, that the mod's maintainer is notified, and that retrying the same draftId never posts twice (consistent with idempotentHint). The approval requirement and draft expiry behavior are real operational context. It does not explicitly state that a published post is publicly permanent or how to retract it, which matters given destructiveHint=true and openWorldHint=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?

The action and destination lead, followed by prerequisites and failure modes; every sentence supplies a constraint the agent could otherwise get wrong (approval gate, digest immutability, idempotency, expiry, GitHub exclusion). No filler or restatement of the tool name.

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?

Covers the prerequisites, side effects, idempotency and failure path for a destructive, open-world mutation, which is more than adequate. With no output schema, it could still say what a successful call returns (e.g., a post link or id) so the agent can report the result.

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 0%, so the description carries the burden and does so well: draftId comes from prepare_feedback, digest must be the draft's 'unchanged digest' (implying an integrity check that rejects modified previews), and approved may only be true after real approval rather than OAuth consent. consentVersion is repeated from the schema const rather than explained, which is the main unused opportunity.

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 ('Post the saved feedback preview') plus the destination ('connected user's public co.build account'), which clearly separates it from prepare_feedback (preview) and from publish_installation_report / submit_review siblings. An agent can distinguish the action 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?

Explicit gating conditions: use only after explicit approval of the exact action and public text, pass draftId from prepare_feedback, and 'OAuth consent is not approval'. It also gives an exclusion ('Never open GitHub issues or pull requests for feedback') and the recovery path for an expired draft, so when-to-use and when-not-to-use are both covered.

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