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

Annotations already declare this a safe, idempotent read, so the description correctly spends its budget on content instead: it enumerates the returned contract (required vs optional fields, where each lives on the page, example payload, delivery instructions). It also discloses a real constraint the agent would otherwise trip on — everything required is visible on the review card — plus the sort-by-newest and 500-most-recent rules.

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 directive "Read this BEFORE scraping" is front-loaded where the agent will see it, and every clause carries distinct information. The middle section is a long comma-chained list that is dense but not padded; it could be broken into shorter sentences for scanning.

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?

No output schema exists, so the description carries the return-value burden itself and does so by enumerating the fields, rules, examples, and delivery format it provides. For a one-optional-param discovery tool, nothing an agent needs in order to call 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 100% and the enum already constrains the value, so the baseline is 3. The description adds meaning beyond it by explaining what omitting the parameter does (lists supported platforms) and that only Google Maps currently exists, which prevents the agent from assuming multi-platform coverage.

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 uses a specific verb-plus-resource framing — it returns, per platform, the exact submission format including identity fields, per-review fields, source locations, and an example payload. An agent immediately knows this is a schema/spec-discovery tool rather than a data-fetching or submission tool, which distinguishes it from siblings like submit_reviews and begin_submission.

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?

"Read this BEFORE scraping" gives an explicit ordering constraint, and the no-platform branch is described as a listing mode. What is missing is naming the actual workflow alternatives (submit_reviews, begin_submission) and stating that this tool must be called instead of guessing a payload. Clear context, but no explicit exclusions.

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