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

Annotations already establish the safety profile (readOnly, non-destructive, not idempotent), and the description adds real context beyond them: no automatic baseline or category labels, the shape of returned data (population status, counts, reusable IDs, one relevance source), per-page credit consumption, and a stopping rule for leading-N ranking. The ranking_bound passage is cryptic and references a parameter that does not appear in the schema, which slightly muddies rather than clarifies.

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?

Front-loading the 'Use when' clause is good, and most sentences carry information. However the ranking_bound sentence is a dense conditional that is hard to parse, and several phrases ('one relevance source per returned candidate', 'candidate population status') pack multiple concepts without unpacking them, so the paragraph reads as compressed rather than efficient.

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 does carry return-value information and explains credit consumption, which is appropriate coverage. But for a tool with three nested filter objects and no documented ordering/grouping semantics, key behaviors needed to call it correctly — what each order mode means, how group_by changes results — are missing from both structured data and prose.

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 only 29% across 7 params, so the description must compensate. It does add high-value semantics for the most confusing part — the separation of discovery-only text from current/baseline measurement filters for whole-project vs topic-scoped activity — plus cursor continuation guidance. But it leaves order, group_by, limit behavior, and most filter parameters unexplained in both schema and description.

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 opening sentence states a concrete verb-and-resource pair: find assets/authors matching a topic and compare discussion across current/baseline windows. It is clear what the tool produces, though it never names the obvious siblings it competes with (compare_activity, aggregate_posts, search_posts), so an agent must infer the boundary itself.

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 a genuine when ('finding projects or voices matching a topic and comparing their discussion'), an explicit when-not ('not an exhaustive thematic or narrative census'), and routes follow-up to a named sibling ('read missing decisive wording/relations with get_posts'). It does not, however, contrast against the sibling tools that overlap most (compare_activity, aggregate_posts), leaving the selection boundary partly to inference.

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