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

The readOnlyHint annotation already indicates the tool is safe and non-destructive. The description adds critical behavioral context beyond that: it lists exactly what types of changes are tracked (releases, metadata, screenshots, price, category), the ordering ('newest first'), and the plan requirement. This fully discloses the tool's behavior without contradicting the annotations.

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 description is extremely concise at three sentences, each serving a distinct purpose: stating what the tool returns (first sentence), suggesting when to use it (second sentence), and noting prerequisites (third sentence). There is zero wasted text, and the structure is effective for quick understanding.

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?

Given the tool has 3 parameters (all documented in schema), no output schema, and the annotations indicate read-only, the description covers the key aspects: what changes are tracked, ordering, plan requirement, and parameter clarification. It lacks explicit guidance on pagination or the response format, but for a tool with simple parameters and clear purpose, it is sufficiently complete.

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 each parameter is documented in the schema. The description adds meaning by clarifying that 'app_id' is specifically 'Sonar app UUID — the id returned by sonar_list_apps or sonar_create_product. NOT a store id', which prevents misuse. It also explains the 'type' filter without repeating the enum, but does not elaborate on 'limit' beyond what the schema provides. Overall, it adds value to the schema but could be slightly more detailed.

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 clearly states the tool returns 'Change history for a tracked app' and enumerates the specific change types: 'detected releases, metadata edits, screenshot swaps, price changes, and category moves, newest first'. This distinguishes it from sibling tools like sonar_app_lookup (current state) or sonar_app_rankings (rank history), making the purpose unambiguous.

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 description explicitly says 'Useful for correlating rank movements with what the app (or a competitor) changed', which gives clear context for when to invoke this tool. It also mentions a plan requirement ('Requires an Indie plan (trial counts)'), adding important usage constraints. However, it does not explicitly state when NOT to use it or name alternative tools for related needs, missing the highest score.

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