Delete A Single Group

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

The description adds behavioral context beyond annotations by stating permanence ('cannot be undone') and the condition for failure (active children). However, it does not clarify idempotency despite the annotation hint, and the mention of returning a list of IDs is partially useful but incomplete.

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 verbose and contains redundancy (e.g., 'This cannot be undone' repeated, 'Permanently removes' twice). It also has a trailing ellipsis indicating truncation. Could be significantly streamlined.

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 covers key preconditions (cannot delete if active children) and hints at error response (list of IDs). However, it does not describe the success response (e.g., empty body or confirmation), nor does it explain authentication or other error cases, leaving gaps for a delete operation.

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?

Both parameters (company_id, group_id) are fully described in the input schema, so the description adds minimal new meaning. It mentions they are required and gives their role as path parameters, which is already evident from the endpoint.

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 clearly states it deletes a single group by ID and includes a helpful constraint about not deleting groups with active projects/people. However, there is minor inconsistency when it refers to 'Resource Planning records' instead of 'Group', which could cause confusion.

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 guidance on when deletion will fail (if group has active projects/people) and hints at alternative actions (remove the group ID from those entities). However, it does not explicitly compare with sibling tools like 'delete_group' or specify when to use this specific endpoint.

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