bb_delete_comment

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals only that confirmation is returned ('Returns confirmation') and implies destruction via the verb 'Delete', but it does not state whether deletion is permanent, whether replies are cascade-deleted, what permissions are required, or whether the action is reversible. For a destructive operation with zero annotation coverage, this is a meaningful gap.

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 with zero wasted words, and the action verb is front-loaded. It is lean and easy to parse, though arguably terse to the point of under-specification. On purely structural grounds it scores well for efficiency.

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 tool is structurally simple (four flat scalar parameters, no nesting), but it is destructive, has no annotations, no output schema, and 0% schema description coverage. The description leaves the agent unaware of side effects, permissions, and how this operation compares to bb_update_comment or bb_resolve_comment. 'Returns confirmation' is the only nod to output behavior, which is insufficient 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?

Schema description coverage is 0% and the description mentions none of the four parameters. The parameter names themselves (projectKey, repoSlug, prId, commentId) are reasonably self-explanatory for a Bitburger context, which prevents a total failure, but the description contributes nothing to parameter understanding and does not compensate for the absent schema 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 states a specific verb ('Delete') and a specific resource ('a comment'), so an agent immediately knows what operation is being exposed. The verb itself distinguishes it from the comment-related siblings like bb_update_comment and bb_resolve_comment, since none of those perform deletion. However, it does not explicitly call out that distinction or clarify which comment is targeted, relying on the parameter names to convey scope.

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?

No guidance is provided about when to delete a comment versus when to update or resolve it. Given siblings like bb_update_comment and bb_resolve_comment operate on the same resource, an agent gets no decision support for choosing among them. There is no mention of prerequisites, exclusions, or a preferred alternative.

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