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

Annotations already signal readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description goes beyond this by clarifying partial-update semantics ('Only the fields you pass change'), the real side effect of enabling ('turns on a real daily email'), and the null-reverts-to-account-email behavior. It also discloses defaults (off, 5) that are not in annotations, providing critical operational context.

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 three sentences, each contributing essential information. It front-loads the purpose, then details each setting, then adds the critical behavioral note about confirmation and partial updates. No redundant phrasing or fluff; every clause earns its place.

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 complexity (4 parameters, all schema-covered, no output schema), the description covers everything an agent needs: the scope, the fields, the defaults, the partial-update behavior, and the mandatory user confirmation. The absence of an output schema is fine since the description doesn't need to explain return values. It is complete 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?

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning: 'enable/disable the daily digest (opt-in, default off)' clarifies the enabled parameter, 'set the moved_up/moved_down position threshold (1-50, default 5)' explains move_threshold semantics, and 'null reverts to the account email' clarifies email_override null handling. These enrich the schema descriptions and guide correct invocation.

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 verb (update), the resource (rank-change alert settings), and the scope (one RankParse website). It enumerates the specific settings (enabled, move_threshold, email_override) and their defaults, making it unmistakable what the tool does. This differentiates it from the read-only sibling get_rank_alert_settings without naming it.

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 implies its use case as the write counterpart to get_rank_alert_settings, but does not explicitly mention when to use it vs alternatives. It does provide an important usage constraint: 'Confirm with the user before enabling' and notes the partial-update behavior, which helps an agent decide when to invoke it. No exclusions or alternative tool names are given, so it's clear but not fully explicit.

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