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

Annotations only declare readOnlyHint and openWorldHint=false, but the description goes much further: counts are read once a day so comparisons appear only once history reaches back, historyFrom bounds the history, notes explain gaps, and collected: false with reason tells the agent Instagram-only coverage plus the posting-partner reconnect case. It also discloses staleness via lastSyncedAt, which is the key behavioral risk for a metrics tool.

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 paragraph, front-loaded with followers then posts then usage, with no filler sentences. It is however long and partly repeats itself ('Nothing is read from the platforms here' restated by the lastSyncedAt clause), which costs a perfect score.

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 shape alone and does so thoroughly: followers fields, historyFrom, notes, collected/reason, posts.top and posts.bottom with ranking order and non-overlap, and ranked counts. Nothing needed to call or interpret this tool 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; the description earns above that by explaining the range coupling in prose ('last 28 days by default, or from and to (dates in timeZone)') and that limit applies to top and bottom separately. It adds little on from/to format beyond what the schema already documents.

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 ('how each connected account is doing': followers at now/7/28 days plus top and bottom posts by engagement) and explicitly separates itself from get_post_metrics, which 'reads them live and lists every post'. An agent can pick between the two without opening either 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?

'Use it to say how the account itself is doing, and which posts worked and which didn't' gives the selection criterion, and get_post_metrics is named as the alternative with the condition that selects it (live platform reads, every post). The only missing element is an explicit negative case, which the alternative already covers.

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