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

Annotations already provide destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds valuable context beyond these: it explicitly labels the tool as a 'WRITE tool', states the need for an Indie plan (trial counts) and a write-scoped API key, and clarifies the id source. No contradiction with annotations; the additional details help the agent understand authorization and constraints.

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: exactly two sentences with no redundant information. It front-loads the purpose and follows with the requirements. Every sentence adds essential value—purpose, identification method, and prerequisites. No wasted words.

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's simplicity (one parameter, no output schema, but with annotations), the description is largely complete. It covers the action, the identifier, the plan requirement, and the API key scope. It does not describe the return value or error cases, but since there is no output schema, this is acceptable. The only minor gap is the lack of explicit mention of what happens if the id doesn't exist, but idempotency implies it's safe. Overall, it provides enough context for correct invocation.

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?

The input schema covers 100% of the single parameter with a clear description in the schema itself. The tool description repeats that the id comes from sonar_app_keywords and is not the keyword_id, which adds minimal value over the schema. The baseline is appropriate since the schema does the heavy lifting, and the description adds only slight reinforcement.

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's purpose: 'stop tracking one keyword/app pair' using the tracked-keyword id. It specifies the action (delete/stop tracking), the resource (tracked keyword), and the context (caller's Sonar workspace). It distinguishes from sibling tools like sonar_untrack_keywords by focusing on a single pair identified by a specific ID, and from sonar_delete_alert by targeting a different entity.

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 provides clear context on when to use this tool: to stop tracking a single keyword/app pair identified by a tracked-keyword id from sonar_app_keywords. It also states prerequisites (Indie plan, write-scoped API key). It does not explicitly mention alternatives (e.g., bulk deletion via sonar_untrack_keywords) but the singular focus and ID source effectively imply the usage scope.

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