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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds material behavior: reposts and promoted posts are excluded, en_original also strips replies and non-English, the series ends at the last bucket settled at least five minutes ago, and repeat reads come from cache. It also discloses the x402 pay-per-call versus API-key auth path — exactly the kind of context annotations can't express.

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?

Purpose and scope are front-loaded in sentence one, and the subsequent sentences each add either filtering semantics, freshness, use cases, or payment requirements. The trailing bracketed access note is long but necessary for invocation; the only minor redundancy is restating en_original's meaning already present in the schema.

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 compensates by describing the series shape, its cutoff semantics, and caching, and annotations cover safety. It still does not describe the response fields (timestamps, count keys) an agent would need to parse results, leaving a modest gap for a data-returning read tool.

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 an increment by clarifying that the window 'ends now' but is actually truncated at the last settled bucket, which changes how days_back is interpreted, and by restating the practical effect of x_query on the returned counts.

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 first sentence names the exact resource (X post counts per cashtag), the aggregation unit (per hour or per day), and the time range (1-31 days). It also explicitly distinguishes itself from the sentiment-oriented siblings with 'Counts are post volume, not sentiment,' and ties itself to the x_attention signals that consume the series.

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 enumerates concrete use cases: showing attention trends, explaining why an X signal fired, and picking a z_threshold. It also implicitly routes away from social-sentiment tools via the 'not sentiment' caveat, but it never names those siblings or states when to prefer them.

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