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

Beyond the sparse annotations (readOnlyHint: false, openWorldHint: true), the description discloses immutability, conflict on a second call, forbidden/not_yet error states, tier weighting rules, and the shape of the reply including weight and weight_explained. It even flags that the user's note is the only free text and is listed under _untrusted, which is valuable operational 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?

The description is reasonably long but front-loaded with the core purpose, followed by constraints, tier semantics, and reply details. There is minor redundancy in the same_human tier being explained twice, but each sentence otherwise carries meaningful operational guidance.

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?

With no output schema, the description fully covers the reply structure (weight, tier, weight_explained) and the important error/state outcomes (conflict, not_yet, forbidden). It also explains the tier/weighting model, which an agent needs to correctly interpret results and decide whether a call is appropriate.

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 75%, and the description adds meaning for purchase_id by tying it to a purchase the caller was part of and to verified status. It reinforces the constraints on stars and note already present in the schema. idempotency_key is left to the schema, but the schema's own description is thorough, so the overall parameter guidance is strong.

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 opens with 'Review the other side of a purchase you were part of', a specific verb and resource, and clarifies the two directions: the buyer rates the seller and the seller rates the buyer. This distinguishes it from sibling tools like replyToReview, which addresses responding to reviews rather than creating an initial review.

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 usage conditions: an API key is required, the caller must be part of the purchase, the purchase must be verified, and only one review per side is allowed. However, it does not explicitly name sibling alternatives such as replyToReview or getReviews or state when to prefer them, so it stops short of full alternative-routing guidance.

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