github_list_branches

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context beyond that: strict governed routing, that `effect` must be 'read' and is Spring-verified, and the role of `approval_ref` for resuming writes. No contradiction with the annotations exists; a 3 is appropriate since the added behavioral detail is helpful but modest.

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 well-organized: an identity line, a routing sentence, and a clean Args list. The opening line is mildly redundant with the tool name, but it adds the platform tool identifier and the structure front-loads the most important constraint, making it efficient without being bloated.

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?

The output schema covers return values, but for a 7-parameter tool with zero schema documentation and a large sibling set, the description leaves a critical gap: the contents of the `arguments` JSON and the repository targeting semantics are never specified, so the agent cannot invoke the GitHub operation correctly. It also offers no differentiation guidance against github_get_branch or github_list_pull_requests, making the definition incomplete for practical use.

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?

With 0% schema description coverage, the description carries the full parameter-documentation burden, and it does enumerate all seven parameters with brief role explanations (project UUID, account alias, idempotency identity, etc.). However, the operative parameter `arguments` is defined only tautologically as 'JSON string of arguments for the connector operation' — it never specifies what keys GitHub's list_branches call requires (e.g., owner, repo), so an agent cannot construct a correct payload from this description alone.

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 identifies the tool as the GitHub `list_branches` connector operation and names the platform tool path, which conveys verb+resource largely through the tool name itself. However, it never states in plain terms what the operation does (e.g., 'returns all branches of a repository') or what the `arguments` payload must target, leaving the actual domain behavior implied rather than explained.

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 given on when to use this tool versus alternatives such as `github_get_branch`, `github_compare_commits`, or the many other github_list_* siblings. The routing statement ('Routes only through the exact project/account governed connector authority') is a platform constraint, not a tool-selection guideline, so an agent gets no help choosing this over comparable operations.

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