delete_group

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that member models are not affected and that the operation is limited to tag groups, which is critical safety information for a destructive operation. It does not mention error handling, idempotency, or permission requirements, but the key safety properties are transparently conveyed.

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 two short sentences that immediately convey the operation, scope, and caveat about systems. It is front-loaded with the core purpose and avoids redundancy. Every sentence earns its place with actionable information.

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 the essential behavior—what is deleted and what is preserved—making it adequate for a simple delete operation. However, it omits any explanation of server_version, which is a required parameter, and does not mention error conditions (e.g., what happens if the tag doesn't exist) or idempotency. An output schema exists, so return values are not required, but the parameter gap and lack of error handling leave it incomplete.

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 50% (tag_id is described, server_version is not). The description adds no explanation for server_version, its purpose, or its format. The tag_id description in the schema already covers that parameter, so the description contributes nothing beyond what the schema provides. With a missing parameter description and no compensating info, this is a significant gap.

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 the action: 'Delete a tag group' with the specific scope that it affects only the grouping, not member models. This distinguishes it from sibling deletion tools like delete_threat_model or delete_reliance, which target different entity types. The resource (tag group) and verb (delete) are explicit.

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 important usage context: deletion is supported for TAGS ONLY, and systems have no delete endpoint on this API. This implicitly tells the agent not to use this tool for systems and implies alternative tools (e.g., delete_threat_model) for deleting other entities. However, it does not explicitly name alternatives or state when not to use it beyond the systems limitation, so it stops short of a full 5.

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