Rename a group or change who is in it

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

Annotations already mark destructiveHint=true, but the description adds crucial context: removing a member only affects the grouping, not the contact, and no version history means a person is asked first. This explains the confirmation flow and non-destruction of underlying contacts beyond the structured annotations.

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 with no filler. The first sentence states the core function, the second clarifies a critical non-destructive nuance, and the third explains the confirmation reason. Everything earned its place.

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 description combines with the schema's confirm_token and set_members descriptions and the output schema to give a reasonably complete picture. It could add explicit guidance on how add_members/remove_members/set_members interact, but the schema already covers the crucial constraint on set_members.

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 coverage is only 43%, so the description must compensate. It clarifies the roles of name/note and add/remove_members, but it doesn't explain set_members as a wholesale membership replacement nor the confirm_token mechanism directly. The schema does cover set_members and confirm_token, but the description only partially bridges the gap for the remaining parameters.

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?

Description uses a specific verb ('Changes') and names the exact resources affected: group name, note, and membership. It clearly differentiates the tool from sibling create_group/delete_group/get_group by describing what it modifies on an existing group.

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?

Description makes the usage context clear: use it to update a group's name/note or add/remove members. It doesn't explicitly name alternatives or when-not-to-use, but the wording strongly implies modification of existing groups and distinguishes itself from deleting contacts or creating groups.

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