open_branch

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the meaningful behavioral detail 'Does not reload the editor,' which is not captured in the annotations and helps an agent predict side effects. It does not exhaustively describe what happens if the branch is already open, but that is a minor gap given 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?

Three short sentences, each earning its place: the core action, the discovery method, and the key exclusion. The most important content is front-loaded. There is no fluff or repetition.

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 single-parameter tool with rich annotations, the description is fully sufficient. It tells the agent what the tool does, how to obtain the required identifier, which related tool is not appropriate, and the key side-effect characteristic. No output schema exists, but the description need not explain return values for this simple operation.

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 100%, and the branchId parameter already includes 'from list_branches with closed:true.' The main description repeats this same guidance rather than adding genuinely new parameter semantics. This meets the baseline for parameter clarity but does not go beyond what the schema already provides.

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 verb and resource: 'Re-open a previously closed branch.' It distinguishes itself from the related switch_branch tool by explicitly saying that switching the editor onto the branch is a different operation. The mention of list_branches({ closed: true }) further reinforces its exact role in the branch lifecycle.

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 tells the agent how to find the closed branches to operate on via list_branches({ closed: true }). It also provides a clear 'When NOT to use' condition with the correct alternative tool, switch_branch. This is strong, unambiguous routing guidance.

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