delete_announcement

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

With no annotations available, the description must carry the full burden of behavioral disclosure. It clearly states the irreversible, permanent nature of the deletion, which is a critical behavioral trait. However, it does not disclose any other side effects (e.g., cascading deletes, permission requirements) or behavior on missing IDs.

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 no fluff. It front-loads the core action and then reinforces irreversibility. Could be merged into one sentence, but it is appropriately sized for a simple delete operation.

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 simple, and the description covers the essential behavior (permanent deletion). It does not mention required parameters (though present in schema) or any side effects like related announcements or discussion threads. Given the absence of annotations and the simplicity of the operation, a 3 reflects the minimal but sufficient coverage.

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%, so the description must compensate by explaining the parameters. It does not mention course_identifier or announcement_id at all, offering no guidance on formats, types, or how they relate. A clear failure to add value beyond the raw schema.

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 resource ('an announcement'), with the explicit qualifier 'Permanently' and 'cannot be undone.' This clearly differentiates it from update or create operations, and the singular 'an announcement' distinguishes it from bulk_delete_announcements.

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 on when to use this tool versus alternatives like bulk_delete_announcements or update_announcement. The description offers no contextual cues for typical use cases or exclusions.

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