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

Annotations already declare readOnly, non-destructive, closed-world, non-idempotent, but the description adds genuinely non-derivable traits: results are capped at the leading 30 groups, counts cover only adjacent stored windows, pending/unavailable is distinct from zero, and no full coverage or streaming is implied. These are the kind of limits an agent cannot infer from structured fields.

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?

Four tight sentences, front-loaded with the use case, then the result shape, then the semantic caveat, then the scope boundary. Each sentence contributes distinct information with no 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?

With no output schema, the description usefully sketches the return (counts for adjacent windows, top 30 groups) and rules out coverage assumptions. It is nearly complete for the calling decision, with the only real gap being the unexplained expected_input_stamp parameter.

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% for both parameters, so the description carries the full burden, yet neither view_id nor expected_input_stamp is mentioned. The role of expected_input_stamp in particular is entirely opaque. The description contextualizes the Live view domain but adds no parameter-level meaning.

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 states a specific capability: returning counts of leading assets/voices for a configured Live view, limited to the leading 30 groups. It also differentiates from siblings by naming aggregate_posts and source posts as alternatives for larger rankings or narrative. It stops short of a crisp verb+resource opener, but the scope is unambiguous.

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?

Opens with an explicit 'Use when' condition and routes the agent to alternatives with their selecting conditions ('use aggregate_posts for a larger ranking and source posts for narrative'). It also warns that pending/unavailable is not zero activity, which prevents a common misinterpretation of the result.

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