List GitLab merge requests

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the project scoping ('one GitLab project') but does not detail pagination behavior, default ordering, or whether it returns full MR objects or summaries. As annotations are strong, a 3 is appropriate because the description adds some context (project scope) but not significant behavioral detail.

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 a single sentence, very concise with no wasted words. It front-loads the purpose and includes the key focus area. However, it is brief to the point of being under-specified, but that does not hurt conciseness. A 4 is given because it is efficient while still delivering the core purpose.

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 18 parameters and an output schema present, the description is far too minimal. It does not explain what the returned data contains (though output schema might handle that), nor does it mention pagination, sorting, or the meaning of filters. It also lacks guidance on how to combine filters (e.g., state+labels). The description is incomplete for the complexity, scoring a 2.

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 6% (only `project` described), leaving 17 parameters unexplained. The description says 'common review and triage filters' but does not list or elaborate on any of the specific filter parameters (state, scope, labels, order_by, branches, date ranges, usernames, etc.). This is a significant gap since the description is the only source for parameter meaning beyond names/enums, and it fails to provide meaningful detail.

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 tool lists or searches merge requests within a single GitLab project, with the phrase 'common review and triage filters' suggesting filtering. It distinguishes itself from sibling tools like create, merge, update branch by focusing on listing/searching. There is no explicit mention that it's a read-only query, but that's implied by 'list or search' and aligned with annotations.

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 gives no explicit guidance on when to use this tool versus alternatives such as `get_merge_request`, `list_merge_request_diffs`, or `search_gitlab`. It implies usage for listing/searching MRs in a project but does not mention exclusions or direct comparisons. The lack of any contextual recommendation lowers the score.

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