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

Annotations declare non-destructive, idempotent mutation; the description adds real context beyond that: it requires the organizer key, it never edits user-authored content ('Organizers never edit what people wrote'), and it discloses a specific failure mode with its error code (409 suggestions_closed). Return value shape is not described, but the critical guardrails are present.

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 content is dense and front-loaded, but the text is a run-on: the title phrase 'reply or pin' collides with 'Body (any of):' with no separator, and the mode/parameter mapping is buried in a comma-spliced list. It is information-rich but harder to parse than it needs to be.

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 7-parameter mutation tool with no output schema and near-zero schema coverage, the description covers modes, field semantics, auth, and a failure condition. The main remaining hole is what `id` identifies and what the tool returns after a successful moderation action.

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 14%, so the description has to carry the load, and it does for most fields: it glosses status values ('shown (approve or show again)', 'answered (Q&A)'), explains that '' clears stage, defines label as a category id, and notes reply is capped at 500 chars and '' removes it. The required `id` parameter is never explained, leaving one meaningful 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?

The description names the two resources this tool operates on (Boards/nominations vs Ideas) and the concrete actions in each mode (approve, hide, answer; set status, category, reply, pin), which is enough to distinguish it from list_posts and approve_all_posts. It stops short of a single crisp verb+resource summary because the opening merges the title with the body text.

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?

It clearly conditions which fields apply in which mode (status/hidden/answered for Boards, stage for Ideas) and states a hard precondition: on a nomination these actions only work while suggestions are open, returning 409 suggestions_closed afterwards. It does not route the agent to alternatives such as approve_all_posts, so there is a small gap.

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