update_merge_request

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

The only annotation is openWorldHint=true, so the description carries the full behavioral burden for a mutation tool and largely drops it. It never states that this is a mutation, that changes are applied immediately without confirmation, or that state_event can close or reopen an MR, and it says nothing about which settings are left untouched when omitted.

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 short sentences, front-loaded with the action and the routing advice immediately after. Every clause carries information; the only minor cost is that the parenthetical constraint is buried mid-sentence rather than stated as a standalone requirement.

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?

With 15 parameters, a mutation surface, and no output schema, the definition is thinner than the tool's complexity warrants. The fully documented schema compensates for parameter meaning, but the description omits confirmation semantics and the close/reopen side effect that an agent should warn about before calling.

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 would be 3, but the description adds a real constraint absent from the schema: that merge_request_iid or source_branch is required. The schema lists only project_id as required, so this note prevents a validation-level mistake. It adds nothing about the enum-constrained state_event or the merge-time flags.

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?

"Update a merge request" gives a specific verb plus resource, and the parenthetical identifier constraint narrows the target further. It stops short of distinguishing itself from other merge-request siblings by name (e.g. get_merge_request, create_merge_request), so an agent must infer the read/write split.

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?

Explicit when-not guidance is present: creation of new resources goes to the create tool, and commenting goes to a note tool. That routes the two most likely mis-selections. It does not cover the read-side alternative (get_merge_request) or prerequisites such as permissions or MR state.

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