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

Goes well beyond the readOnlyHint annotations: it discloses that numbers are cached and refreshed roughly every 10 minutes, that `refreshing` is true while data loads, that a first report for many accounts can return zero posts before filling in about a minute later, and that metrics are null when a platform does not report them. Those are exactly the behaviors an agent needs to avoid misinterpreting an empty or partial response.

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 purpose and time windows are front-loaded, and nearly every sentence adds new information. It is a single dense paragraph, and the `refreshing` behavior is explained twice (once as the cache flag, once as the slow-first-report case), which is mild redundancy rather than filler.

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?

An output schema exists, so return values do not need full exposition, yet the description still explains the non-obvious `views_vs_account_median` scaling and the `refreshing` flag. Combined with the caching, latency and null-metric caveats, an agent has enough to call this tool correctly and interpret its output.

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 description coverage is 0%, so the description carries the burden, and it does most of the work: it names the supported windows (7, 30, 90 days) and explains that account_id and external_user_id scope partner-account results to one end user versus the caller's own accounts. It stops short of stating whether `days` accepts only those three values or an arbitrary integer, and does not say how the two account parameters interact when both are supplied.

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 opens with a specific verb-and-resource statement: it returns views, likes, comments, shares and saves per post across four named platforms over a stated time window. That is far more than a restatement of the name. The one gap is that it never distinguishes itself from the sibling get_post_analytics, so an agent must guess which analytics tool to pick.

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?

It gives real usage context: use the median-relative field to find above- and below-average posts, and use account_id or external_user_id for partner accounts. However, it never says when to prefer this over get_post_analytics or list_posts, and gives no explicit exclusions, so the routing guidance is only implied.

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