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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral value beyond the annotations: a 1,000-branch truncation cap, alphabetical ordering, and the notable rule that the default branch is included (flagged) even when it sorts past the cap.

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?

Three tight sentences with zero filler. Scope and required input source are front-loaded, and the pagination/ordering caveat follows as the second priority.

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?

An output schema exists, so return-value documentation is not needed, and the description still usefully explains ordering and truncation behavior. The only gap is that two of three parameters (owner, repo) are undocumented anywhere, which is minor given their conventional meaning in a GitHub-scoped API.

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 33% – only installationId carries a schema description ('GitHub App installation id'), while owner and repo have none. The description reinforces that installationId must be numeric and come from list_github_installations, partially compensating, but owner/repo semantics (owner/repo slugs) are left entirely implicit. Baseline 3 is appropriate.

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?

States a specific verb+resource ('List the branches of a GitHub repository') plus its scoping qualifier ('accessible to an installation'), which distinguishes it from sibling tools like list_github_installations and connect_repository. An agent can identify exactly what this returns without opening the schema.

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?

Provides a clear prerequisite and cross-reference: 'Use the numeric installationId from list_github_installations,' which routes the agent to the correct sibling for the required identifier. It lacks explicit when-not-to-use guidance, but for an unambiguous list operation there is little ambiguity to resolve.

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