Delete a group

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

Annotations already mark the action destructive, and the description adds safety-critical context beyond that: member accounts survive while the access they got from the group is lost. It also discloses the two-step confirmation-token requirement, aligning with idempotentHint=false and adding value over 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 short sentences, each carrying distinct information: the action, the membership consequence, and the command prerequisite. It is front-loaded with the core operation and contains no filler or repetition.

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 destructive, non-idempotent delete operation, the essential invocation facts are all present: what is deleted, how members are affected, and how the confirmation token is obtained. There is no output schema, but none is needed for the agent to call and interpret the two-step flow correctly.

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 schema already documents group_id as the numeric Wiki.js id and confirm_token as the token from the previous unconfirmed call. The description only restates the token requirement and does not add meaning beyond the parameter descriptions.

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 opens with a specific verb-resource pair, 'Removes a group,' and immediately clarifies the boundary with user deletion by stating 'members keep their accounts but lose whatever access the group gave them.' This distinguishes delete_group from sibling delete_* tools and avoids ambiguity with update_group or unassign_user_from_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?

The use case is implied: this is the tool for permanently removing a group, and the confirmation-token line tells an agent what the call flow looks like. However, it never explicitly contrasts this with alternatives such as unassign_user_from_group or update_group, so a caller is not told when not to choose this tool.

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