gitea_list_branches

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

With no annotations provided, the description carries the full burden. It adds valuable context about returned data ('commit information and protection status') but fails to disclose other behavioral traits: it does not mention the read-only nature (implied but not stated), pagination behavior, or what occurs if the repository doesn't exist.

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 a single sentence and generally efficient, but the '[UNIFIED]' prefix is unnecessary metadata that doesn't assist tool selection. Every other word earns its place, though the sentence could be front-loaded to remove the prefix.

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 0% schema coverage, no annotations, and no output schema, the description is insufficient. It mentions return content but fails to explain the pagination controls (critical for a 'list all' operation with 5 parameters) or provide safety profiles, leaving significant gaps for an AI agent attempting to invoke the tool correctly.

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%, requiring the description to compensate heavily. While 'Gitea repository' implicitly maps to site/owner/repo, the description provides no explanation of what 'site' refers to (URL vs name), does not mention the pagination parameters (page/limit), and offers no syntax guidance for any parameter.

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 identifies the action ('List'), resource ('branches in a Gitea repository'), and distinguishes from sibling tools like gitea_get_branch by specifying it returns 'all' branches with 'commit information and protection status'. However, the '[UNIFIED]' prefix is implementation noise, and claiming 'all' branches without mentioning pagination behavior is slightly imprecise given the page/limit parameters.

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 versus gitea_get_branch (for single branch lookups) or how to handle pagination. The description does not indicate that results are paginated or explain the relationship between 'list all' and the page/limit parameters.

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