List Git Branches

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

Annotations already establish readOnly, idempotent, and open-world behavior, so the bar for additional disclosure is lower. The description adds useful behavioral detail: both repository id and name are accepted, matching is case-insensitive, and agents should not invent example values. This goes beyond the annotations and helps correct invocation.

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 compact and front-loaded with the core purpose before usage and parameter guidance. It contains minor redundancy with the schema's repository parameter description, but every sentence adds practical value and there is no irrelevant filler.

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 read-only listing operation with one required parameter, the description covers the main things an agent needs: what the tool does, when to use it, how to obtain a valid repository identifier, and a warning against inventing values. It does not explain output details or pagination, but given the schema's response_format and limit/offset defaults, the description is reasonably complete.

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?

The description reinforces the key repository parameter by explaining that id or name from openl_list_repositories() is accepted and is case-insensitive, but this largely repeats what the schema already states. Limit and offset have no description in the schema and are not addressed in the description, so the 50% schema coverage gap is not fully compensated.

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 action ('List all Git branch names') and a concrete resource ('a repository'), making the core purpose clear. It also gives a use case ('before switching or comparing versions'), but it does not explicitly differentiate itself from sibling tools like openl_list_project_branches.

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 gives clear when-to-use context: to see available branches before switching or comparing versions. It also provides a prerequisite workflow: call openl_list_repositories() first if the repository value is not already in context. It does not mention alternatives or when not to use this tool, but the guidance is otherwise strong.

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