Remove Spam Whitelist Entry

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

Annotations already declare destructiveHint=true, idempotentHint=true, and non-read-only, so the safety profile is covered. The description adds genuinely new behavior: case-insensitive matching means the stored casing may differ, and sender lists are shared across all domains on the account, so the blast radius is wider than the per-domain `domain` parameter suggests.

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?

Three short sentences, purpose front-loaded, each adding a distinct fact (action, matching semantics, scope). Nothing is redundant or padded.

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?

An output schema exists and annotations cover safety, so the description's job is mostly matching and scope semantics, which it delivers. It leaves one ambiguity unresolved: what happens when the entry is not found (relevant given idempotentHint) and how the required `domain` relates to an account-wide list.

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 both `domain` and `entry` are already documented, including the wildcard pattern syntax. The description only adds the case-insensitivity note, which is useful but does not clarify the domain-vs-shared-list interaction (why `domain` is required when the list is account-wide). Baseline 3 applies.

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 first sentence names a specific verb and resource ('Removes an entry from the spam whitelist'), which is unmistakable against siblings like add_spam_whitelist_entry or remove_spam_blacklist_entry. It doesn't explicitly route against those siblings, so it stops short of a 5.

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?

Removal intent is implied by the verb, and the account-wide scope hint nudges the agent to check before acting. There is no explicit when-to-use/when-not guidance or named alternative (e.g., 'use get_spam_whitelist first to find the exact entry').

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