list_branches

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: full pagination, workspace resolution precedence, requirement for explicit repo, and the name filter semantics (partial match via Bitbucket's query language). This goes beyond what annotations provide, though it doesn't detail pagination size or error behavior, which is a minor gap.

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 sentences, each carrying distinct information: what the tool does, how workspace resolution works, and what parameters are required/optional. No fluff, no repetition of schema details. The most important information (lists every branch, fully paginated) is front-loaded.

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 list tool with no output schema, the description covers the essential aspects: purpose, pagination, parameter requirements, and filter behavior. It doesn't describe the return format, but since there's no output schema and the tool is a simple list operation, this is a minor gap. The workspace resolution precedence is a nice touch that prevents common errors.

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%, so the description must compensate. It does: it explains that `repo` is required, `workspace` is resolved via standard precedence if not provided, and `name` is an optional partial-match filter using Bitbucket's query language. This adds meaning beyond the bare schema properties. However, it doesn't explain the exact format of the `name` filter (e.g., query language syntax), which is a minor gap.

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 the tool lists every branch in a repository, with full pagination. It distinguishes itself from siblings like get_branch (which fetches a single branch) and list_repositories (which lists repos, not branches). The verb 'lists' plus the resource 'branches in a repository' is specific and unambiguous.

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 states when to use this tool: to list all branches in a repository. It also provides clear usage constraints: requires an explicit `repo` argument, resolves `workspace` via standard precedence if not provided, and accepts an optional `name` filter. While it doesn't explicitly name alternatives, the sibling list makes the distinction clear (e.g., get_branch for a single branch), and the usage conditions are precise enough for an agent to select this tool correctly.

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