merge_merge_request

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

Annotations already declare destructiveHint=true, but the description adds substantial concreteness: 'may squash commits, schedule auto-merge, or delete the source branch,' requires merge permission, and 'returns GitLab's merge result or a mergeability error.' It also discloses the GitLab version-specific `sha` requirement, which the annotation does not convey. There is no contradiction between description and 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?

The description is four dense sentences, each earning its place: purpose, usage conditions and alternative, side effects and permission, then the `sha` tip. No filler or redundancy; material is front-loaded with the core action first.

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 destructive tool with 9 parameters and no output schema, the description covers the essential decision factors: preconditions (approval/conflict/pipeline checks), the alternative tool, behavioral consequences, permission requirements, return type (result or error), and a parameter-source hint. Nothing an agent needs to call this tool safely is missing.

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 baseline is 3, but the description enriches parameter understanding far beyond the schema. It tells the agent to source `sha` from `get_merge_request` (`sha` or `diff_refs.head_sha`), explains why GitLab 19.2+ groups may require it, and clarifies that `merge_when_pipeline_succeeds` is deprecated in favor of `auto_merge`. This is meaningful cross-parameter guidance the schema does not provide.

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 a merge request,' a clear verb+resource pairing. It explicitly distinguishes itself from `approve_merge_request`, telling agents to use that tool for approval instead, and names the state checks (approval, conflict, pipeline) that precede merging, making its scope unambiguous relative to the many merge-request siblings.

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 precise when-to-use guidance: 'Use this only after checking the merge request approval, conflict, and pipeline state' and explicitly routes to `approve_merge_request` for approvals. It also calls out the merge-permission prerequisite and instructs to pass `sha` from `get_merge_request`, covering both sequencing and alternatives.

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