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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds real behavior: a control step that runs first, a refusal with no charge on failure, provenance on every result (run id, date, citation line), and the full two-step payment flow via payment_url with MPP/x402 options at $3.00. The 'charges nothing' sentence reads oddly next to '$3.00 per run' until the validate-then-pay flow is parsed, which costs some clarity but not accuracy.

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 triggers are correctly front-loaded, but the payment mechanics are restated three times ('charges nothing', 'Price: $3.00 per run', then the MPP/x402 breakdown) and a sample URL is appended inline. The result is a bloated definition whose most decision-relevant sentence competes with billing boilerplate.

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 the work of explaining the return shape: per-brand share, point change versus prior year, growth, volume band, ranked, plus provenance fields. For a two-parameter read-only tool that is essentially complete; only routing among the 24 sibling analytics tools is unaddressed.

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, including the 2-6 rival constraint. The description adds only the loose notion of 'the brands named' and no format hints for the comma-separated rivals string, so the schema does the heavy lifting and baseline 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?

The description states a specific verb and resource: ranked share of US Google searches among named brands, with point change, growth and a volume band. It clearly separates itself from generic volume reporting by saying 'Shares and bands only, never monthly volumes.' It never names a sibling (e.g. run_ai_visibility or run_answer_share), so differentiation within the crowded run_* family is left to inference.

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?

Strong trigger language: 'Use when the user asks who they really compete with, whether a competitor is gaining on them, or how their brand interest compares with rivals.' It also scopes the output ('shares and bands only, never monthly volumes'), which implicitly tells the agent when not to use it. It stops short of naming an alternative tool for monthly volumes or AI-visibility questions.

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