Gitea: Delete tag

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is structured data, not something the description must restate. Beyond that the description adds nothing: no note on irreversibility, required permissions/tokens, whether the tag must exist, or any side effects. For a destructive mutation this is a thin layer of added context.

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?

A single front-loaded sentence with no wasted clauses is appropriate for a simple deletion tool. The only blemish is the redundant "[UNIFIED]" tag, which consumes attention without informing the agent.

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?

This is a destructive, non-idempotent mutation with zero schema documentation and no output schema. The description should carry warnings, identifier formats, and any behavior on missing tags or attached releases, but instead stops at the bare statement of purpose.

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% for four required parameters (site, owner, repo, tag), so the description carries the full burden and provides none of it. It names "tag" and "repository" in prose but gives no format guidance for site (host/URL?), owner (user or org?), or tag (name vs. ref).

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?

States a specific verb and resource ("Delete a tag from a Gitea repository"), which is enough to distinguish it from the n8n/wordpress tag-deletion siblings by provider. The "[UNIFIED]" prefix is noise that adds no meaning, and the description does not clarify the scope of what a tag is here.

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 word "Delete" implies when it applies (removing an existing tag), but there is no explicit when-to-use guidance, no mention of alternatives such as gitea_create_tag, and no preconditions or warnings. An agent must infer everything about invocation context.

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