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

Annotations only say readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description goes well beyond: results are saved in Puley history and consume a read allowance; unsupported sources and unknown/stale source times fail without spending allowance; max_age_s=0 forces a fresh capture; transcript_mode='listen' uses the account's audio allowance; generated timing is approximate and capture_id is not a freshness guarantee. This explains why the tool is not read-only and what it costs.

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 opening is well front-loaded with the source list, and most sentences carry real information. But it is a single dense block of roughly 250 words that drifts from purpose into caveats, evidence semantics, and parameter documentation mid-paragraph, forcing the agent to scan for max_age_s and transcript_mode rather than finding them where expected.

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 and 0% schema coverage, the description usefully sketches return shape (follower counts, views, likes, transcripts, price, ratings), the kind=google_maps_choices variant, and failure semantics. It is only slightly incomplete: it refers to 'coverage/read_info' without explaining how to obtain it (source_read_status exists), and never addresses the read_with_account alternative.

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 0%, so the description carries the full burden and largely meets it: it spells out accepted link forms including '@handle', 'instagram @handle' and 'x @handle', defines max_age_s as maximum source-capture age in seconds with zero meaning a new capture, and defines all three transcript_mode behaviours. It does not state whether transcript_mode has other valid values or what happens on an unrecognised one.

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 names a specific verb (read) and enumerates concrete resources: TikTok/Instagram/YouTube/X/Facebook posts, Meta Ad Library, Amazon products, Google Maps places, Hellopeter/App Store/Google Play pages, and generic web pages, plus '@handle' shorthands. That is far more specific than a tautology. It does not, however, differentiate itself from near-neighbours such as read_site, see_page, read_reviews, read_comments, or read_with_account, leaving the agent to infer boundaries.

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?

Usage is implied throughout — pass a supported link and the tool reads it — and it notes 'Some sources cannot be read' plus a Maps multi-match fallback. But there is no explicit when-to-use-this-vs-alternatives guidance despite many overlapping siblings, and no statement of what to do instead when a source is unsupported.

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