gitea_create_tag

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 mentions targeting a 'specific commit' (mapping to the target parameter) but fails to explain critical behaviors: whether creating an existing tag fails or overwrites, what happens when target is null (likely defaults to HEAD), whether the message parameter creates an annotated vs lightweight tag, or required permissions.

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 appropriately brief at one sentence, but the '[UNIFIED]' prefix is structural cruft that adds no value for tool selection. The core sentence is front-loaded with the verb, though the prefix detracts from immediate clarity.

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?

Given 6 parameters with zero schema descriptions and no output schema or annotations, the description is insufficient. It lacks explanation for 4 of 6 parameters, provides no error handling guidance, and omits return value description, leaving significant gaps in the agent's understanding of how to invoke and handle results.

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%, leaving all 6 parameters undocumented in the structured schema. The description only implicitly references two parameters: 'repository' (repo) and 'specific commit' (target). It completely fails to explain site (Gitea instance URL), owner (user/organization), tag_name, or message (annotation), leaving the agent to guess their semantics.

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 (Create), resource (tag), and domain (Gitea repository). The phrase 'at specific commit' adds useful scoping. However, the '[UNIFIED]' prefix is noise, and it could better distinguish from sibling create_tag tools in other services (n8n_create_tag, wordpress_create_tag) beyond just naming.

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 no guidance on when to use this tool versus alternatives like gitea_list_tags or gitea_delete_tag. It does not mention prerequisites (e.g., authentication requirements) or when-not-to-use conditions (e.g., if the tag already exists).

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