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

Annotations already declare write (readOnlyHint=false), non-idempotent, non-destructive, open-world. The description adds valuable context beyond annotations: plan requirements (Indie, trial counts), authorization needs (account or API key with write scope), and the prerequisite that the product must have its own app in the same store. It doesn't detail error behavior or rate limits.

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?

Two well-structured sentences that front-load the write nature and core behavior, then layer prerequisites and requirements. Minimal waste; slightly dense but appropriate for the tool's constraint set.

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?

For a mutation tool with no output schema, the description covers the critical preconditions (linked product app, plan level, authorization scope) and the core effect (tracking competitor keywords/rankings). It could mention whether tracking is immediate or async, but the essential context for correct invocation is present.

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 description coverage is 100%, so the schema already documents store, country, store_id, and product_id thoroughly, including the key distinction that product_id is a Sonar UUID (not a store id) and store_id is the competitor's store-specific identifier. The description adds no parameter-level detail beyond what the schema provides, which is the correct baseline when the schema does the heavy lifting.

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 (adds/tracks) and resource (competitor app under a Sonar product) with clear scope: keywords and rankings get tracked alongside the product's own app. It is clearly distinguishable from siblings like sonar_remove_competitor, sonar_scan_competitor, and sonar_analyze_competitors.

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?

Gives clear preconditions for using this tool — the product must already have its own app linked in the same store, and an Indie plan plus authorized account/API key with write scope are required. It does not explicitly name alternative tools (e.g., scan vs analyze vs track), but the when-to-use context is strong.

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