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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds non-obvious partial-success semantics: a value that is not blocked is counted as skipped rather than failing the call. It also discloses that scope defaults to workspace and that removing an account-wide entry only works from the main workspace, which is a constraint the annotations do not carry. Return shape and any rate limits remain undisclosed.

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 sentences, front-loaded with purpose and capacity, then the input contract, then the scoping constraint. No filler, and the most decision-relevant facts (bulk limit, skipped-not-failed, workspace default) come first.

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?

No output schema exists, and the description adequately implies the outcome (skipped counts, scope removed from). For a destructive bulk tool with annotation coverage for safety, this is nearly complete; only the exact response fields and any throughput limits are unaddressed, which is a minor gap.

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%, so the baseline is 3. The description goes beyond the schema by stating that values are matched case-insensitively, that values and ids can be combined, and by explaining the skipped-on-miss behavior for unmatched values, which the schema does not say.

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?

States a specific verb and resource (unblock domains/email addresses) with a concrete capacity bound (up to 1,000 per call) and an outcome (campaigns can email them again). It is clearly distinguishable from the singular remove_blocklist_entry and from list_blocklist_entries, which it references for sourcing IDs.

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?

Explains when to pass values, ids, or both, and where IDs come from. It also clarifies the default scope behavior and the account-wide constraint. It stops short of explicitly telling the agent when to prefer the singular sibling remove_blocklist_entry over this bulk tool, so it is clear context rather than full routing guidance.

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