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

With destructiveHint=true in annotations, the description adds valuable context: it specifies that delete closes the group for everyone, explains ownership transfer requirements, and clarifies the consequence of removing yourself. This goes beyond the annotation by detailing specific destructive and consequential behaviors, which is helpful for an agent deciding whether to invoke this tool.

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 is three sentences, front-loaded with the core purpose, then specific rules. No fluff or redundant information. Every sentence contributes to understanding the tool's behavior.

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?

While the description covers the most critical caveats (ownership transfer, delete impact, self-removal), it does not detail the full effect of each action (e.g., what happens on invite, role change, or decline). Given the tool's complexity with 4 parameters and multiple actions, a bit more detail would help, but the essentials are present.

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?

The schema already describes 75% of parameters (value, action, account), with action enumerating possible values. The description adds context like 'accept invitations before accessing' and default behavior for account, but these are minor and partly redundant with the schema. Given the high schema coverage, the description's added value is limited, so a baseline of 3 is appropriate.

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 states a clear purpose: managing group invitations, membership, and roles. It goes beyond the title by specifying the scope of operations (invite, accept, remove, role, delete) and key constraints, which distinguishes it from groups_create/list/read. However, it doesn't explicitly frame itself as 'update existing group' but the management language conveys that.

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 provides some guidance on when to use this tool, such as 'Accept invitations before accessing a group' and 'Removing yourself leaves; owners must transfer ownership first.' It implies usage for membership/role changes but does not explicitly compare against siblings like groups_create or groups_list, nor state exclusions. The when-to-use context is present but not formal.

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