Remove matching contacts locally; push with sync mode replace

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

Beyond the readOnlyHint=false/openWorldHint=true annotations, it discloses that nothing is sent unless confirm is true, that there is no server-side dry run, and that the removal is staged locally then pushed via sync mode replace. That is genuinely useful mutation context; it stops short of saying what happens to non-matching rows or whether removals are reversible.

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?

Two compact sentences with the action first and the write-gate second; no filler. The inline raw endpoint path is slightly noisy but earns some place as a routing cue.

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?

For a nested-body write tool with no output schema and only 50% parameter coverage, it adequately covers the safety/dry-run story but omits matching semantics, partial-match behavior, and the shape of the returned preview. Enough to call it, not enough to predict the outcome.

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?

With 50% schema coverage, the description only reinforces the confirm flag and 'matching contacts', which loosely implies rows match by email/phone. It adds nothing about defaultCountryCode, idempotencyKey, the 50,000-row cap, or matching semantics for rows, leaving half the parameters to the schema alone.

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 ('Remove matching contacts locally') plus the endpoint, and the phrase 'push with sync mode replace' distinguishes the local removal from the server-side push behavior. It does not name a specific sibling (audiences_addMembers, audiences_remove, audiences_sync) for contrast, so it falls 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?

The confirm: true gate implies when the call actually executes, and 'push with sync mode replace' hints at a relationship with sync, but no alternative tool is named and no explicit when-not-to-use condition is given. Usage must largely be inferred by comparing with audiences_addMembers/audiences_sync.

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