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

Annotations already signal a mutating/destructive operation. The description adds valuable behavioral detail: cadenceMinutes is restricted to specific values, clamped to the plan's fastest allowed interval, and omission falls back to the plan default. This goes beyond the schema and annotations without contradicting them.

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 tight sentences accomplish the job: the first states the tool's core purpose, and the second packs the essential constraints and default behavior. No filler or redundancy exists.

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 has only two simple parameters, one required, and an output schema. The description, along with the schema and annotations, gives an agent everything needed to call it correctly: required enabled, optional cadence constraints, and mutating behavior.

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 the baseline is 3. The description adds extra semantic value by clarifying the cadenceMinutes allowed set, the plan-based clamping behavior, and the default when omitted, which are not fully captured in the schema field descriptions.

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 uses a specific verb-resource pairing: 'Enable/disable mention email alerts and set the cadence.' This clearly identifies the tool's action and distinguishes it from read-only siblings like get_alert_settings and from unrelated tools like delete_website.

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 gives clear parameter usage guidance, such as valid cadenceMinutes values, plan clamping, and the default behavior when omitted. However, it does not explicitly state when to choose this tool over get_alert_settings, so the usage context is implied rather than directly stated.

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