Remove Keyword Exclusions from a Niche

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond that: mutation scope ("Only the exclusions change — every other niche setting is kept"), idempotency ("safe to repeat: entries that are not excluded come back under `unchanged`"), cost ("Free"), and a rate limit ("30 calls per minute per niche"). Nothing here contradicts the destructive annotation — the destructive effect is precisely bounded to the exclusion list.

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?

Single paragraph, front-loaded with the purpose and its sibling relationship, then semantics, then limits and return contract. Every sentence carries distinct information — no restatement of the tool name or the title.

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, so the description discharges that burden by naming the return fields (`removed`, `unchanged`, and the resulting `exact`/`phrase` lists). Combined with the rate limit, idempotency, and mutation scope, an agent has everything needed to call this correctly and interpret the result.

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 per-field semantics of `exact`, `phrase`, and `nicheId` are already carried by the schema (baseline 3). The description adds value on top: the cross-tool format contract (match `list_keyword_exclusions` output verbatim) and a combined constraint not in the schema ("Send 1–100 entries in total across `exact` and `phrase`"), which the schema only expresses as a per-array maxItems.

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?

Opens with a specific verb+resource framed as the inverse of a named sibling: "Use this to undo `add_keyword_exclusions`, so the keywords an exclusion hid show in the niche's Master Keyword List (`get_niche_keywords`) again." An agent can distinguish this from add_keyword_exclusions, list_keyword_exclusions, and remove_niche_keywords without opening any 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?

States the trigger (undo a prior exclusion), the source of the input values ("Pass the entries exactly as `list_keyword_exclusions` shows them"), and explicit exclusions ("removing a phrase does not touch an exact entry for the same text"). The exact-vs-phrase separation and the "already hidden by another exclusion" case close the ambiguity an agent would otherwise have to guess.

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