Add or remove group members

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

The description goes well beyond the annotations by explaining that HTTP 200 is not a full success receipt and that notFoundResourceNames and canNotRemoveLastContactGroupResourceNames identify skipped changes. It also discloses convergence on re-run and the non-deletion guarantee, which is especially valuable given destructiveHint is true.

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 front-loads the core action and then packs each sentence with non-redundant information: batch capability, resource-name addressing, response caveats, idempotency, and the myContacts exclusion. There is no filler or repetition of schema content.

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?

With no output schema, the description must and does carry the burden of explaining the response semantics and edge cases. It covers partial failures, skipped contacts, the last-group protection, convergence, and non-destructiveness, making the tool's behavior predictable even without an output schema.

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?

Even though schema coverage is 100%, the description adds critical semantics the schema does not: at least one of add/remove must be provided, the combined limit is about 1000 names, and resource names follow people/<id> format contextually. It also adds the behavioral caveat about the myContacts group, which is parameter-relevant for remove.

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 names the exact operation: adding and/or removing contacts in a contact group (label) in one call. It clearly distinguishes this from group-metadata operations like update_contact_group by focusing on membership changes, and even notes the myContacts exception.

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 makes the tool's purpose and the conditions for use clear: at least one of add/remove is required, and up to ~1000 names can be processed. It also gives an explicit when-not case by stating contacts cannot be removed from contactGroups/myContacts this way, and clarifies that removing a contact is not deletion, which helps route deletion intent to delete_contact.

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