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

Goes well beyond the readOnly/idempotent annotations: it discloses that `priority` is always 0 on both stores, that no API key is needed with per-IP daily limits, and that throttling can yield Sonar's stored copy surfaced as `{ data, meta }` with `meta.stale`, `meta.stale_as_of`, and `meta.note`. This is genuinely useful operational context, though the free-tier limits are stated only qualitatively.

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-loads what the tool does, then layers the comparison, cost profile, and fallback behavior. Four sentences all carry information, though the throttling/meta explanation is dense and could be tightened.

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 explaining the returned ordering, the always-zero `priority` field, and the stale-fallback response shape including the note to relay to the user. An agent has what it needs to call and interpret the result.

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 each parameter (seed, store enum, country) is already documented in the schema, so the baseline is 3. The description adds no syntax or format meaning for any parameter; its field-level detail concerns output (`priority`), not inputs.

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?

States a specific verb (get) and resource (autocomplete suggestions) plus the source (App Store / Google Play) and ordering semantics. It explicitly contrasts with sonar_keyword_search, so an agent can distinguish it from the many keyword siblings without opening a schema.

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?

Names the alternative (sonar_keyword_search) and the selecting condition ('use when you only need term ideas without difficulty/popularity scoring'), and adds that it works without an API key under a free tier. The routing decision is fully determined.

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