Reply to a customer review

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

Annotations only flag destructive/idempotent/openWorld; the description goes further, disclosing that replies are public, that the default is a non-applying dry run returning a plan, that a review holds at most one reply, that replace overwrites it, and that ASC_WRITE=1 is required. This is rich context an agent cannot get from the annotations.

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?

Front-loaded with the action, then the confirmation protocol, then the destructive/permission note — no filler. Minor overlap with the schema's own dry_run description keeps it from a full 5.

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 destructive mutation with no output schema, the description covers the safety protocol, the permission prerequisite, and the overwrite behavior. Nothing critical to calling it correctly is missing.

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 50% and the description compensates: it explains dry_run's default-and-confirm semantics and the meaning of replace (overwrites an existing reply), which the schema leaves as a bare boolean with only a default. It says nothing about the text length bound, which the schema does cover.

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 ('Publishes a developer reply to a customer review') and immediately scopes it with the one-reply-per-review rule and the replace flag, so an agent can separate this write path from read siblings like get_reviews.

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?

Gives an explicit two-step workflow (dry_run true -> show plan -> call again with false), tells when to pass replace:true, and names the required env gate ASC_WRITE=1. It stops short of naming a competing sibling tool for the same task, so it lands at 4 rather than 5.

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