merge_pull_request

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

DestructiveHint=true annotation already declares this mutates/destroys. The description adds valuable context: the head-SHA safety precondition, that a merge method is required, and that commit text via stdin is 'not audited' — a meaningful behavioral caveat beyond what the schema provides. It discloses the non-audit of commit text which is a genuine transparency point.

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?

Two sentences, zero fluff. The critical safety constraint is front-loaded in the first sentence, and the behavioral caveat about auditing is tucked efficiently in the second. Every clause earns its place.

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?

This is a destructive, high-stakes operation with 8 parameters and no output schema. The description covers the essential guard (head SHA equality), required method, and the stdin/audit quirk. Minor gaps: no mention of what happens on SHA mismatch or whether the tool fails gracefully, and which of the 5 required params map to the account/hostname distinction. Reasonably complete for the risk profile but could add failure-mode behavior.

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 only 13%, so the description bears responsibility. It adds meaning for expectedHeadSha (the safety guard), mergeMethod (required), and commit text (via stdin, not audited). However, it doesn't clarify account vs repository vs hostname structure, commitTitle semantics, or how mergeMethod options differ — some burden left unaddressed. The description compensates at the baseline level but doesn't go beyond.

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 verb and resource ('Merge an open pull request'), plus the critical scoping constraint ('only when its current head exactly matches expectedHeadSha'). This distinguishes it from siblings like review_pull_request and update_pull_request, and the head-match guard is specific and unique.

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 clearly conveys when to use this tool (merging an open PR) and includes the essential precondition of head SHA matching. It implicitly signals this is the merge operation distinct from review/comment/update siblings, though it doesn't explicitly name an alternative tool or state 'don't use this unless head matches' as an exclusion.

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