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

Annotations already cover readOnly/openWorld/non-destructive, and the description adds genuinely new behavioral facts: billing at $0.01 per page, a hard cap of 10 reviews per page, and the non-obvious behavior that each sort_by order surfaces a different set of reviews. That last point is exactly the kind of trait an agent could not infer from structured fields.

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-loads purpose, then layers in return fields, filtering behavior, pagination, and cost with no filler. Every sentence carries actionable information for an agent deciding whether and how to call it.

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?

Despite no output schema, the description enumerates the review fields returned (rating, text, author, timestamps, photos, owner response), and covers pagination, cost, filtering, and sorting. Nothing an agent needs to invoke 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%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that each sort_by order yields a different review set (schema only says 'Sort order') and clarifies the language filter behavior. The billing/pagination notes for pages also add value the schema only partially covers.

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 ('Get reviews of a Google Maps place by place_id') and distinguishes itself from siblings like place_details and place_photos by naming the exact resource returned. It also routes the agent to the source of the required id ('from search_places'), so the tool is identifiable without opening any 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?

Gives a clear entry condition (place_id comes from search_places) and practical usage tips (combine sort_by orders for more coverage, use language to restrict). It stops short of explicit when-not-to-use guidance or naming a specific alternative review tool, but the context is clear.

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