openl List Branches

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. The description adds the note about using display names but does not disclose additional behavioral traits beyond what annotations indicate. This adds some context but not beyond the annotations.

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 extremely concise with two sentences, both of which add value: one states the purpose and output, the other gives a critical usage instruction. No wasted words.

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?

For a list tool with good annotations and schema coverage, the description covers purpose, usage context, and a key parameter hint. It does not detail pagination or output format beyond mentioning metadata, which is acceptable given the schema defines limit/offset and the annotations ensure safety. Slightly more detail on output could push it to 5.

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 50% (repository and response_format have descriptions, limit and offset do not). The description does not elaborate on parameter semantics beyond what is in the schema, such as the role of limit/offset for pagination. It does reinforce the repository naming convention, but overall, the description does not significantly compensate for the missing 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 clearly states 'List all Git branches in a repository' and specifies that it returns 'branch names and metadata (current branch, commit info).' It further differentiates by advising to use it 'to see available branches before switching or comparing versions,' distinguishing it from sibling tools like openl_create_project_branch.

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 explicitly says when to use this tool ('see available branches before switching or comparing versions') and provides a key usage hint: use the repository display name, not ID. While it does not list explicit alternatives or exclusions, the context is clear and helpful.

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