Reply to (or remove a reply from) a Google review

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

The description explicitly discloses the upsert behavior ('THIS IS AN UPSERT: a listing has exactly one reply per review, so replying to a review that already has an answer REPLACES it rather than adding a second'), the verified-listing requirement ('Google only accepts replies on a VERIFIED listing'), and the confirm-gating for destructive deletes ('Deleting is public and immediate, so it is confirm-gated'). These go beyond the annotations (which only indicate destructiveHint and idempotentHint) and provide critical operational details.

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 moderately sized but every sentence carries operational value: purpose, upsert semantics, verification requirement, confirmation for deletion, content quality guidance, and prerequisites. It is front-loaded with the core purpose and scoping. While it could be slightly condensed without losing meaning, the density is high and it avoids redundancy with the annotations, making it effectively concise.

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?

Given the tool's complexity (dual action, upsert behavior, deletion gate), the description covers all necessary aspects: the upsert replacement rule, the requirement of a verified listing, the confirm-gated destructive delete, content quality advice, and the integration prerequisites. The absence of an output schema means the description doesn't need to explain return values, and none are critical. An agent has everything needed to invoke this tool correctly.

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?

The schema already documents all five parameters with clear descriptions (e.g., 'delete: true removes the existing reply instead of writing one', 'comment: the public reply text — required unless you are deleting', 'confirm: required for delete:true', 'reviewId: from list_google_business_reviews', 'locationId: which listing — omit when only one is shared'). The description's mention of confirm-gating reinforces the confirm parameter, but it does not add substantial new meaning beyond what the schema provides. With 100% schema coverage, the baseline of 3 is appropriate.

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 explicitly states the primary function (publicly answering a customer review) and the secondary function (deleting an existing reply), with the specific resource (Google Business Profile listing) and context (brand's listing). It clearly distinguishes this tool from siblings like answer_google_business_question (which handles questions, not reviews) and post_to_google_business (which creates new posts). The verb 'answer' and the dual nature are unambiguous.

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 provides clear context for when to use the tool—when responding to or removing a reply to a review on a verified Google Business Profile. It states the prerequisite ('Needs Google Business Profile connected and the project approved') and gives qualitative guidance on reply content ('Write the reply in the brand's voice and answer the specific complaint'). However, it does not explicitly name alternative tools (like answer_google_business_question) or state when not to use this tool, but the purpose is clear enough for an agent to route correctly.

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