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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds real context: the call hits external networks live and writes back to the stored analytics history that get_analytics_summary reads, and the response includes per-item fetch timestamps. Worth noting there is a mild tension between 'this refresh updates' the stored history and readOnlyHint=true; the effect is confined to local cache rather than remote data, so this is not a hard contradiction, but the description could have made that boundary explicit.

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?

Two tight sentences: the first defines the action and return shape, the second routes to or away from the sibling. Nothing redundant, and the core behavior is front-loaded.

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 only two optional parameters, no output schema, and full annotation coverage, the description is nearly complete, and it usefully describes the return shape ('with when each was fetched'). It doesn't say what happens when a network is not connected or a refresh fails, which matters given the multi-network scope, so it stops short of 5.

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 100% and both parameters are already documented, including the 7/30/90 day options and the enumerated network examples. The description adds no syntax, default, or interaction guidance for 'days' or 'network' beyond what the schema provides, so the baseline of 3 applies.

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 ('pulls fresh followers and engagement from the connected networks') plus scope ('returns them with when each was fetched'), and explicitly distinguishes itself from get_analytics_summary as the write-through refresh versus the stored-history read. An agent can differentiate it from all 35 siblings without opening the 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?

Names the relevant alternative (get_analytics_summary) and the condition that separates them: this one fetches live data and updates stored history, the sibling reads that history. It gives no explicit when-not guidance (e.g. cost/rate implications of refreshing repeatedly) and doesn't mention the related list_connected_accounts dependency, so it falls short of a full 5.

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