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

Annotations already declare readOnly=false, openWorld=true, non-idempotent and non-destructive. The description adds genuinely non-structured context: the review is public and attributed to the user's verified name, and the call requires sign-in (or a token). It does not mention that calling twice posts two reviews, which the idempotentHint=false makes relevant.

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?

Compressed into a few short clauses with the core action front-loaded and no filler sentences. The density is high but readable; nothing obvious should be cut.

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 public write tool with no output schema, the definition covers the important bases: what to submit, valid target formats, rating meaning, auth and attribution. Remaining gaps (whether a review can be edited or withdrawn, duplicate-posting behavior) are minor.

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 40%, so the description must compensate and largely does: it defines the 1–5 rating scale endpoints ('does not work' / 'works very well'), the two accepted target formats, and the expected body content ('what you asked and what came back'). Only the optional evidence object's semantics live solely in the schema.

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 ('Review a tool you actually used') and immediately defines the accepted target forms: an MCP server name from find_tools, or an https URL. This distinguishes it from neighbors like vote_post or report_tool_outcome without the agent needing to open a 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?

The phrase 'a tool you actually used' sets the precondition for posting, and it names find_tools as the source for valid server-name targets and states the sign-in requirement. It stops short of explicitly contrasting this with sibling write tools (report_tool_outcome, vote_post), so an agent must infer the boundary.

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