Link a development branch to a GitHub issue

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

Beyond the annotations (mutation, idempotent, non-destructive, open-world), the description discloses that all work goes through the API with no local fetch or checkout, that existing linked branches are reused (explaining the idempotentHint), and the important side effect that a PR from a linked branch auto-closes the issue on merge without a closing keyword. That auto-close consequence is exactly the kind of non-obvious behavior an agent must know before calling.

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?

Roughly four sentences, front-loaded with the create-or-return contract, then API-only behavior, then parameter rules, then the auto-close caveat — a logical order with no filler. The branch/branch_repo sentence slightly overlaps the schema text, which keeps it from being maximally tight.

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 5-parameter mutation tool with full schema coverage, an output schema, and annotations declaring the safety profile, the description covers the essential unknowns: no local side effects, reuse semantics, and the merge-closes-issue consequence. It omits permission/scoping requirements and any error conditions (e.g., base branch missing, issue closed), which are the remaining gaps.

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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter composition the schema cannot express: with branch the named branch is reused, without it the first linked branch in branch_repo is taken, and a new branch originates from base (which must exist) or the default branch. This clarifies how branch, branch_repo, and base interact rather than restating each field.

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?

"Create a branch on GitHub linked to an issue (its Development panel), or return the linked branch that exists already" states a specific verb (create/link) and resource (branch tied to an issue), plus the get-or-create dual behavior. It is plainly distinct from siblings like github_issue_close, github_issue_relate, or github_issue_edit, which do not touch 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?

It gives explicit selection rules: supply branch to reuse a linked branch of that name, omit it to take the first linked branch in branch_repo, and "use a plain branch when the first merge should not close it" tells the agent when this tool is the wrong choice. It does not name a sibling tool for that alternative, so it stops short of full routing guidance.

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