Merge pull request at exact head

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

Even though annotations already flag destructiveHint and readOnlyHint, the description adds significant context: 'Destructive write' frames the mutating scope, 'Ordinary write authorization and the separate PR-merge fine gate are required' reveals the fine-grained auth prerequisite, and the head-SHA match discloses the concurrency-safety condition. The explicit list of non-behaviors (no admin bypass, no branch deletion, no forced revision, no blind retry) prevents dangerous assumptions. No contradiction with 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 tight sentences, each carrying distinct weight: sentence one declares action + conditions, sentence two covers authorization, sentence three enumerates explicit exclusions. It front-loads the critical signal ('Destructive write'), uses a parallel structure for the negatives ('cannot... , delete... , force... , or blindly retry'), and contains zero filler words.

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 high-stakes destructive write operation with output schema present, the description is complete: it covers the safety condition (head SHA), the authorization model (write + fine gate), and what the tool explicitly will not do (bypass, force, retry). The schema and output schema cover parameters and return shape, so the description focuses exactly where the risk lies — the happy-path and refusal semantics.

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?

The schema already covers 100% of parameters with descriptions, setting baseline at 3. The description adds modest value by priming expected_head_sha and method as the central safety and strategy controls — helping the agent understand which parameters matter for authorization vs. layout. However, it never names individual parameters like body, subject, owner, or repo, so the marginal semantic contribution over the schema is limited.

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 opens with 'merge exactly one pull request using the explicit merge strategy only,' combining a specific verb, resource, and the key safety mechanism (head SHA match). It unambiguously differentiates this from all 61 siblings — none of which perform merges — and the constraint 'while its head matches expected_head_sha' captures the tool's unique scope.

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 provides clear operational context: it names the required authorization level ('ordinary write authorization'), the special 'PR-merge fine gate,' and lists what the tool cannot do ('cannot use administrator bypass, delete the branch, force a changed revision, or blindly retry'). This effectively communicates when the tool will refuse work, giving the agent strong decision signals. It stops short of naming explicit alternative sibling tools, though the negative-capability list implies when to seek alternatives.

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