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

Annotations already cover safety (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial context beyond them: controls are validated first, the tool refuses and does not charge if a control fails, it self-states limits, and each result carries a run id, date, and citation line. It also discloses the two-step payment flow (payment_url, MPP/HTTP 402, x402 USDC alternative) and the $3.00 charge condition. That is exactly the behavioral context an agent needs before committing a paid call.

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?

The usage trigger is correctly front-loaded, but the payment material is repetitive: the price appears twice, 'Stripe shared payment token' is spelled out twice, and 'this tool charges nothing' immediately precedes a $3.00 price statement, which reads as contradictory on first pass. The 'Safe to cite' sentence is promotional framing that partially duplicates the controls and citation claims made elsewhere.

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 carries the burden of describing returns, and it does: a retention ratio against the best 12 months, months since peak, control checks, and a five-value verdict, plus a free sample URL for exact shape. The refusal path and payment path are both covered. Only the concrete response field names and the failure-response shape are left to the sample link.

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% and both parameters carry their own descriptions with examples, so the baseline is 3. The description adds only indirect meaning, clarifying that interest is measured on US Google Trends for the term and English Wikipedia for the article, which implies the two inputs must refer to the same subject. It adds no syntax, matching, or ambiguity guidance beyond that.

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 verb and resource: it measures how much of a subject's best 12 months of US Google Trends and English Wikipedia interest it retains today, and returns one of five named verdicts. The measurement basis and output labels are unusually concrete. It does not contrast itself with near siblings such as run_demand_check, run_share_of_search, or run_regulatory_trend, so the agent must infer the boundary.

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?

The opening clause gives a clear trigger: creative or campaign brief writing, or trend weighing, where the user asks whether something is a lasting shift or a fad that has peaked. That is a genuine when-to-use condition, not a restatement of the name. It gives no when-not-to-use conditions and names no alternative tool to prefer in adjacent cases.

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