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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description corroborates the write behavior by stating the report is saved to history — a useful, non-obvious side effect. It also adds a genuine behavioral guarantee ('Unavailable source data is not inferred') that cannot be derived from annotations, though it omits latency, cost, and failure behavior for private/missing accounts.

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?

One dense sentence plus two short ones, with the core purpose front-loaded and the 'median of newest posts' parenthetical clarifying the baseline metric. Slightly overloaded with clauses, but each adds information rather than restating the title.

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, the description appropriately describes the report's contents (followers, typical views/likes, cadence, standout posts) and its persistence side effect, which is what an agent needs to decide and act. Remaining gaps — auth/account-linking requirements and behavior on private or missing accounts — are minor for a two-parameter read-style tool.

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% and neither parameter has a description, so the description carries the burden — and it does partially by enumerating the valid platform set (TikTok, Instagram, YouTube, X) in prose, effectively acting as the missing enum. It also implies username must refer to a public account, but gives no format examples (handles with or without @, URLs) for the username parameter.

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 concrete artifact (a report) and enumerates its contents — followers, median views/likes of newest posts, posting frequency, standout posts — for a specific resource class (public social accounts). It clearly separates itself from siblings like read_with_account or creator_check by promising a composite report plus history persistence, though it never names a sibling explicitly.

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 only implied: 'public ... account' suggests when it applies, and 'Saves the report in Puley history' hints at a persistence side effect, but there is no explicit when-to-use guidance, no mention of alternatives such as creator_check or read_with_account, and no stated preconditions (e.g., private accounts, rate limits, cost).

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