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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds substantial behavioral context beyond that: the 'delivers' field is framed as 'the honest answer' with the warning that only in-app actually sends while the rest queue with no draining job, webhook URLs are never returned and webhook_hint is masked intentionally, and fan-out semantics differ by scope (personal = once per recipient, shared = once per firing). This is exactly the kind of non-obvious behavior a caller must know.

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 longer than average but every sentence carries distinct information with no filler: inventory, scope semantics, delivery honesty, security masking, then exclusions. The logical ordering is strong, and the length is justified by the subtlety of the domain. Minor deduction for the indirect opening line, which delays the concrete subject.

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?

The tool takes zero parameters and has an output schema, so the remaining burden is conceptual — and the description covers everything: the four-channel model, why scope matters for delivery behavior, the misleading 'delivers' field, the webhook masking constraint, and where excluded data (thresholds, digest) lives. Nothing an agent needs to invoke or interpret this tool correctly is missing.

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?

With zero parameters, the baseline is 4, and the description exceeds it by defining the semantics of the returned concepts: 'scope' as the distinguisher, 'delivers' as the truthful send-status indicator, and 'webhook_hint' as a masked identifier. An agent can correctly interpret the response rather than misreading fields like 'delivers' as actual delivery.

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 never uses an explicit retrieval verb ('returns', 'lists'), but it exhaustively characterizes the resource — the four channels, their scopes, and the Slack/Discord connections — making the purpose unmistakable. It also distinguishes itself from siblings by exclusion, stating that thresholds and the weekly digest are not here. The metaphorical opening ('Where anything the product wants to tell this person goes') is informative but less direct than a standard verb+resource formulation.

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?

Explicitly routes to alternatives: 'Per-tool thresholds are not here, and neither is the weekly digest... see list_alerts and get_digest.' It names both siblings and the reason they exist elsewhere (they require a scope). An agent knows exactly when this tool is the wrong choice and which sibling to select instead.

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