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

With only readOnlyHint:true in annotations, the description carries full weight and exceeds expectations by disclosing the feed's identity (same as the in-app Recent Alerts panel and email digest), the once-daily detection cadence, the type-specific payload shape (app/keyword names, old vs. new values), and the dependency on enabled alert rules. This gives the agent a realistic model of data freshness and availability that annotations could never convey.

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?

Every clause is information-dense and earns its place, but the entire description is essentially one 80-word run-on sentence held together by colons and em-dashes. It would benefit from breaking into 2-3 sentences to improve scannability, though the front-loading is decent since it leads with the core resource and ordering.

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 there is no output schema and only minimal annotations, the description covers an impressive amount of necessary ground: what the payloads contain, when data becomes available (once daily), prerequisites (alert rules enabled), ordering semantics, and authentication requirements (Indie plan). This is nearly complete for an agent to use the tool effectively without additional discovery.

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 provides 100% param coverage with clear documentation (enum values for type, 1-200 and default 50 for limit, ISO 8601 format with examples for since, and filtering semantics for app_id), which holds the baseline at 3. The description adds only marginal param value beyond the schema, such as reinforcing the since polling pattern ('Use your last poll time to fetch only new events' in the schema vs. 'Poll with since' in the description). No contradictions, but no meaningful semantic lift either.

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 identifies the resource (workspace alert events), the ordering (newest first), and enumerates the distinct event types (rank drops/gains, top-10 entries/exits, rating drops, etc.), which effectively differentiates it from sibling alert tools. It loses a point because the lead is a noun phrase ('The detected alert events for your workspace') rather than an explicit imperative verb+resource construction like 'Lists the alert events...', making the invocation intent slightly less immediate.

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 strong contextual guidance: events only exist for alert types with enabled rules (referencing sonar_set_alert), detection runs once daily (setting cadence expectations), and it prescribes the 'Poll with since' pattern for programmatic reaction. It also flags the Indie-plan requirement as a prerequisite. However, it never explicitly names an alternative tool for when NOT to use this one, missing the chance to contrast with siblings like sonar_list_alerts or the alert configuration tools.

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