imap_remove_spam_domain

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

No annotations are provided, so the description carries full responsibility for disclosing side effects. It says the domain is removed, but does not mention whether the change is persistent, whether removing a non-existent domain errors, whether authentication/special permissions are needed, or whether this only affects local spam filtering. The description adds little beyond what the tool name already conveys.

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 a single concise, front-loaded sentence. Every word contributes to the tool's purpose, with no filler or redundant detail.

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 operation is very simple and the only parameter is fully documented in the schema. However, because there are no annotations and no notes on side effects or fallback behavior, the description is minimally acceptable rather than fully contextual for an agent deciding whether and how to invoke it.

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 description coverage is 100%, and the schema already explains that 'domain' is the domain to remove from the spam list. The tool description does not add new parameter-level meaning, so the baseline of 3 is appropriate.

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 ('Remove') and identifies the exact resource ('custom spam list'), so an agent can immediately understand the tool's function. It also clearly differentiates from siblings like imap_add_spam_domains and imap_list_spam_domains without needing to inspect the schema.

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 when to use the tool: when a domain needs to be removed from the custom spam list. However, it does not explicitly state when not to use it or mention alternatives such as imap_delete_by_domain or the whitelist counterpart. The usage context is reasonably inferable but not stated.

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