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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data and the description carries a lighter burden. The description adds workflow framing (a pre-flight check) but says nothing about pagination behavior or result ordering, which would be genuinely useful beyond the 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?

Two short sentences, zero waste, with the core purpose front-loaded ahead of the workflow hint. Nothing is repeated from the schema or annotations.

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?

An output schema exists so return values need no explanation, and the annotations plus a fully documented schema cover the mechanics. The description supplies the one non-obvious thing an agent needs (why to call this before creating an MR); only pagination-as-workflow nuance is left implicit.

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 100%, with page, perPage, search, and project all documented inline including the path-encoding note. The description adds no parameter meaning of its own, so the baseline 3 applies.

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?

States a specific verb and resource ("List a project's branches"), which is immediately distinguishable from sibling list tools like gitlab_tags_list or gitlab_commit_list. An agent knows exactly what the tool returns without opening the schema.

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?

Explicitly names the workflow context (before gitlab_mr_create) and the two concrete reasons to call it: confirming the source branch exists and finding the target branch. It stops short of stating when this tool is the wrong choice versus, say, gitlab_project_get, so it is clear context rather than a full when/when-not rule.

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

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

The readOnlyHint annotation already declares the safety profile, so the description's job is lighter. It adds no detail about ordering, default ref behavior, or result size limits; the pagination hint lives only in the schema, not the description. Adequate but thin beyond 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?

Two sentences, zero filler, with the core action front-loaded before the usage hint. 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?

An output schema exists, so return-value explanation is unnecessary, and the readOnly annotation covers the safety profile. What remains unstated — commit ordering and default-ref behavior — is minor for a simple list tool.

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 100%, with each parameter (ref, page, perPage, project) documented including encoding and page-size caps, so the baseline is 3. The description's phrase 'on a ref' adds no syntax or format detail beyond what the schema already provides.

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?

Specific verb ('List') plus resource ('repository commits') and scope ('on a ref') make the purpose unambiguous. It stops short of explicitly distinguishing itself from near siblings such as gitlab_mr_changes, though the 'beyond the diff' phrasing gestures at the boundary.

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 second sentence gives a concrete when-to-use scenario: inspecting a merge request's source branch contents beyond the diff, which implicitly positions it against gitlab_mr_changes. No explicit when-not or prerequisite guidance is offered, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the default-branch fallback and the self-disclosing output cap with truncation signal. A rate limit or size ceiling beyond maxChars is not stated, but the core behavior is well disclosed.

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 short sentences, front-loaded with the core action, then the ref tip, then the output caveat. Nothing repeats the name or wastes space.

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 an output schema present, return values need no prose, and the description still flags the truncation behavior. Combined with 100% schema coverage and a read-only annotation, an agent has everything needed to call this correctly.

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 is 3. The description adds meaning beyond the schema by explaining the MR source_branch ref pattern, a workflow the schema's generic 'branch, tag or commit SHA' wording does not convey.

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?

States a specific verb and resource: 'Read one file from the repository at a ref.' This is clearly distinct from sibling tools like gitlab_project_get, gitlab_mr_changes, or gitlab_commit_list, and the ref scoping makes the access model unambiguous.

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?

Gives concrete when-to-use guidance: pass ref=<the MR source_branch> to read the file as the merge request sees it. It does not name alternative siblings or state when-not to use this tool, so it stops short of a full routing guide.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds one meaningful behavioral detail, that results include subgroups (recursive scope), but says nothing about ordering, limits, or auth requirements beyond that.

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?

A single tight sentence, front-loaded with the action and resource. Slight redundancy between 'of a group' and 'from a group', but nothing wasted.

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?

An output schema exists so return values need not be explained, and pagination is covered by the schema. However, the required 'group' parameter is undocumented and no guidance is given on result size or filtering breadth, leaving minor gaps for a list tool.

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 75%, with page, search, and perPage documented in the schema; only the required 'group' param lacks a description. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

Specific verb+resource: 'List the projects of a group' with scope qualifier 'including its subgroups'. An agent can identify this as a group-scoped project lister, though it does not explicitly contrast with the nearby gitlab_project_search sibling.

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?

Provides a use case ('to find a project path from a group') which implies when the tool is useful, but gives no explicit when-not guidance or named alternatives for finding projects by other means.

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

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

readOnlyHint=true already establishes the safe read profile, and an output schema covers return values. The description adds the useful 'project-scoped iid' scoping note, but says nothing about error behavior (e.g. missing project or iid) or auth needs. With annotations carrying the safety burden, a 3 fits.

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?

A single front-loaded sentence with zero filler; every word (verb, resource, scope, key) 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?

For a simple read tool with full schema coverage, an output schema, and readOnlyHint, the description covers what is needed to invoke it correctly. Only minor behavioral context (error cases) is absent, and that is not essential here.

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% and both parameters are thoroughly documented in the schema (project id/path forms, iid semantics). The description's 'project-scoped iid' phrasing adds no meaning beyond what the schema already states, so baseline 3 applies.

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?

States a specific verb (Get) and resource (issue) with scope ('one issue', 'project-scoped iid'), which distinguishes it from the list-oriented sibling gitlab_project_issues. It does not explicitly name the sibling, but the singular/plural contrast makes the intent clear.

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?

Usage is only implied: the mention of a project-scoped iid signals 'fetch a single known issue', but there is no explicit when-to-use, no prerequisites, and no pointer to alternatives like gitlab_project_issues for listing. Adequate but leaves routing to inference.

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

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

readOnlyHint=true already declares the safe-read profile. The description adds a real caveat about unknown-label behavior when setting labels, but it is cryptically worded ('11.3') and describes a neighboring operation rather than this tool's own filtering or pagination behavior.

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, front-loaded with the purpose before the caveat, with no wasted filler. The second sentence is slightly opaque but earns its place as a warning.

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?

An output schema exists, so return values need not be explained, and all parameters are documented by the schema. The description covers purpose and a pre-use caveat adequately, though it could tie the caveat more directly to this tool's output.

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 100%, so page, perPage, search, and project are all self-documented. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb ('List') and resource ('a project's labels'), which cleanly separates it from siblings like gitlab_tags_list and gitlab_branches_list. An agent knows exactly what it returns.

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?

Explicitly says to check this tool before setting labels, giving a clear triggering condition. It does not name the sibling tool that actually sets labels, so routing is implied rather than spelled out.

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

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

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds real context beyond annotations: output is per-file summarised and patches are 'capped', and it hints at a larger cap when path is supplied. It does not restate truncation flags, which the schema already carries.

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 sentences, front-loaded with what the tool returns, then the usage trigger, then the parameter hint. No filler; every sentence 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?

With an output schema present and readOnlyHint covering safety, the description need only convey scope, usage trigger and the path shortcut — all of which it does. Nothing an agent needs to invoke this correctly 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. The description goes beyond the schema by explaining the meaningful effect of 'path': it pulls one file's patch 'at a larger cap', which is behavioural guidance the schema's terse 'return only this file' does not convey.

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?

States a specific verb+resource ('the merge request diff') and enumerates what it returns per file (status, added/removed counts, capped patch). This clearly distinguishes it from siblings like gitlab_mr_get and gitlab_mr_versions without needing to name them.

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?

Explicitly states when to use it: 'Read this before commenting on a line, and to learn which paths and lines exist', which routes the agent away from blind commenting. It does not explicitly name gitlab_mr_comment_on_line or gitlab_mr_versions as alternatives, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false, so the agent knows this is a write. The description adds that the comment attaches to the MR itself rather than a diff thread, which is meaningful behavioral context. However, it says nothing about permissions, editability, or side effects beyond the schema and annotations, so it is adequate rather than rich.

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 with zero filler. The primary action is front-loaded and the disambiguation follows immediately, so every sentence 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?

With a full output schema present, the description need not explain return values, and all three parameters are schema-documented. The only minor gap is that it does not mention adjacent comment tools like gitlab_mr_reply, but for a three-parameter comment tool the description is complete enough to invoke correctly.

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 100%, so iid, body, and project are already documented in the schema (including the project-scoped iid clarification). The description adds no additional parameter meaning beyond what the schema provides, so the baseline of 3 applies.

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?

States a specific verb and resource ('Post a comment on the merge request itself') and immediately contrasts with the sibling that handles the other case (line-level comments). An agent can distinguish it from gitlab_mr_comment_on_line without opening either schema.

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?

Explicitly names the alternative (gitlab_mr_comment_on_line) and the condition that selects it (commenting on a specific line of the diff). It does not address the other comment-adjacent siblings (gitlab_mr_reply, gitlab_mr_discussions), but the routing guidance given is clear and actionable.

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

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

With only readOnlyHint=false in the annotations, the description carries real behavioral weight: it discloses that base/start/head SHAs and the old-side line number are auto-resolved from the latest diff version, and that a stale SHA or out-of-diff line is reported rather than silently sent. It also reveals the return linkage (discussion_id) for follow-up calls — context well beyond the annotation.

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 dense sentences, front-loaded with the purpose, followed by parameter sourcing guidance and the threading handoff. No filler; every sentence contributes actionable information.

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 6-parameter write tool with an output schema, the description covers the difficult parts an agent cannot infer: how to source path/line from a sibling tool, how SHAs are resolved, and how validation failures surface. Return values need not be enumerated given the output schema, and the discussion_id note covers the one essential output field.

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 is 3, but the description adds cross-parameter meaning the schema does not: `path` must match the format reported by gitlab_mr_changes, and `line` is interpreted relative to the chosen side of the diff. That is genuine added semantics over the structured fields.

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?

States a specific verb+resource+granularity: 'Comment on one line of the merge request diff, as a normal review comment.' This differentiates it from the sibling gitlab_mr_comment (general MR comment) and gitlab_mr_reply (thread continuation) without the agent needing to open any schema.

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?

Gives concrete usage context: derive `path` exactly as gitlab_mr_changes reports it, supply the line on the relevant side, and pass the returned discussion_id to gitlab_mr_reply to continue the thread. It names the alternative for threading, but never states explicit exclusions (e.g., when to choose gitlab_mr_comment over this tool for non-line comments).

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

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

Annotations only declare readOnlyHint=false (mutation), so the description must carry the rest. It discloses a concrete failure mode (409 on duplicate open MR) and version quirks (11.3 lacks reviewers/draft handling), which is real behavioral value beyond the annotation. Auth requirements and rate limits are not covered.

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?

Purpose is front-loaded in the first sentence, followed by caveats and the error case. Three sentences, each earning its place, though the version-specific detail is somewhat dense.

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?

An output schema exists, so return values needn't be explained. For an 11-parameter mutation tool the description covers purpose, the key failure mode, and version caveats adequately; only minor gaps (permission/auth context) remain.

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 82%, so the schema already documents most parameters. The description's draft note ('pass draft:true and the required WIP: title prefix is applied') largely restates the schema's own draft description rather than adding new syntax or constraints, so the baseline 3 applies.

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?

States a specific verb and resource ('Create a merge request') and the exact scope ('from source_branch into target_branch'). The 409 sentence implicitly routes the agent to gitlab_mr_update, distinguishing it from read/update 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?

Gives a clear when-not ('creating an MR whose branches already have an open one fails with 409') and the alternative action ('update that one instead'), plus version-specific guidance for 11.3. It stops short of naming the sibling tool explicitly or covering general preconditions, so not a full 5.

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

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

Annotations only declare readOnlyHint=true, yet the description discloses genuinely non-obvious behavior: system notes are filtered by default, `resolved` is derived from thread notes, and the returned page can be shorter than pagination.total. This last caveat about a raw-count vs filtered-page mismatch is exactly the kind of behavioral context that prevents agent confusion.

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 tight sentences: the first front-loads purpose and output shape, the second carries the behavioral caveats. No filler, and the most decision-relevant information is placed 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?

With readOnlyHint covering safety, a 100%-covered schema, and an output schema handling return values, the description supplies the remaining needed context (default filtering and the pagination caveat). Nothing essential for correct invocation 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 the baseline is 3, but the description adds real meaning by explaining the interaction between the default filtering (includeSystem=false) and derived `resolved`/onlyUnresolved semantics and the resulting pagination discrepancy. It enriches parameter understanding beyond the per-field schema text.

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?

States a specific verb ('List') and resource ('discussion threads of a merge request') and adds the payload detail ('each diff comment's file and line'). This is clearly distinguishable from siblings like gitlab_mr_comment, gitlab_mr_changes, or gitlab_mr_get.

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 implies its use case (inspecting MR discussion threads) but never states when to prefer it over alternatives such as gitlab_mr_changes or the reply/resolve siblings. Usage is inferable from the behavior described, but there are no explicit when/when-not rules or named alternatives.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral value beyond that: it warns that a merged MR still reports merge_status can_be_merged and clarifies that work_in_progress signals draft status, which are non-obvious field semantics an agent would otherwise misread.

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, front-loaded with the purpose before the state-reading caveats. No filler, though the second and third sentences pack several distinct caveats together with limited separation.

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?

An output schema exists, so return-value detail is unnecessary. The description covers the key gotchas of the returned state fields and is sufficient for an agent to call and interpret the tool. It does not touch on pagination or error cases, but those are minor for a single-resource get.

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 100%, with both project and iid fully documented in the schema (including the !123 vs global-id distinction). The description adds nothing about parameters, so the baseline 3 applies.

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?

States a specific verb and resource ('Get one merge request'), making scope clear. It implicitly distinguishes itself from gitlab_mr_list via 'one' but never names the sibling it pairs with or contrasts against, so the differentiation is inferred rather than explicit.

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 'Read state before anything else' guidance gives a reason to call this tool and implies the merge workflow context. However, it never names alternatives (gitlab_mr_list, gitlab_mr_merge, gitlab_mr_changes) or states when-not to use this tool, leaving selection to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context: the default state=opened exists because the raw API would otherwise return every state, and it discloses missing filter capabilities plus the workaround.

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 short sentences, front-loaded with the core purpose, then defaults, then limitations. Every clause earns its place with no redundancy.

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?

An output schema exists, so return values need no explanation, and the rich schema covers the 14 parameters. The description adequately flags the state default and the missing reviewer/draft filters, though it could say more about pagination 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 86%, so the schema documents the parameters well. The description only echoes the state default and notes absent filters, adding little semantic detail beyond what the schema already provides; baseline 3 is appropriate.

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?

States a specific verb and resource ('List a project's merge requests'), clearly distinguishable from write operations like gitlab_mr_create or gitlab_mr_merge. It does not name a sibling alternative directly, but its scope as a listing tool is unambiguous.

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?

Explains the state default and warns that reviewers/draft filters are unavailable, directing the agent to read work_in_progress on each item instead. However, it gives no explicit guidance on when to choose this over siblings such as gitlab_mr_get or gitlab_raw_api.

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

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

Annotations only supply readOnlyHint=false, so the description carries the behavioral burden and does so richly: precondition (must be opened), failure semantics (405 when not mergeable due to conflicts or a running pipeline; 409 when the source branch moved since read), and the mitigation (read first, pass sha). This is exactly the beyond-annotation context an agent needs.

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, front-loaded with the action and then the failure modes and remedy. Dense but every clause earns its place; nothing is redundant with the name or schema.

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 mutation tool with an output schema (so return values need not be explained), it covers preconditions, error modes, and the sha-pinning workflow well. Minor gaps remain around permissions and the purpose of merge_commit_message / should_remove_source_branch.

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 67%, above the midpoint baseline. The description adds real meaning to the sha parameter (pinning the merge, mismatch rejected into 409) beyond the schema text. However, merge_commit_message and should_remove_source_branch remain undocumented in both schema and description.

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?

Opens with a specific verb+resource ('Merge a merge request') that is unambiguous and clearly distinct from sibling mutators like gitlab_mr_update, gitlab_mr_create, or gitlab_mr_resolve. An agent can identify the operation without opening a schema.

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?

Gives strong operational context: the MR must be opened, and it prescribes a workflow ('read the merge request first and pass its sha to pin the merge'). That implicitly points at gitlab_mr_get as a prerequisite, though it never explicitly names an alternative tool or contrasts merging with creating/updating.

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

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

readOnlyHint=true already establishes the safe-read profile, and the description adds genuine extra context: the MR-scoped nature and the merge-blocking behavior of GitLab 11.3 when a pipeline is running or failed. It stops short of describing pagination or result shape, though the schema/output schema cover those.

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 tight sentences: the purpose leads, and the pre-merge rationale follows. No filler, and the most decision-relevant information is front-loaded.

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 an output schema present, return values need not be explained, and the description covers what the tool returns (MR pipelines) and why it matters. It is complete for calling the tool correctly, missing only minor pagination framing that the schema already supplies.

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 100%, so iid, project, page, and perPage are all documented in the schema itself. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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?

States a specific verb ('List') and resource ('pipelines') scoped to 'this merge request'. This cleanly distinguishes it from siblings like gitlab_project_pipelines (project-wide) and gitlab_pipeline_jobs (job-level detail).

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?

Gives a clear when-to-use signal: 'Read before merging', plus the reason (11.3 refuses the merge while one is running or failed). It does not name an explicit alternative tool, but the pre-merge context is unambiguous.

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

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

The readOnlyHint=false annotation already tells the agent this mutates state, so the bar is lower. The description usefully clarifies that the comment is nested inside an existing thread rather than creating a new one, but says nothing about permissions required, whether the discussion must still be open, or failure behavior when discussion_id is invalid.

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, zero filler, with the action front-loaded and the routing guidance immediately after. Every sentence 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?

An output schema exists, so return values need not be explained, and the four required parameters are fully documented in the schema. For a simple reply tool the description is nearly sufficient, though it omits any note on what happens when the discussion_id is stale or not found.

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 100%, including the non-obvious iid vs global id distinction and the origin of discussion_id (gitlab_mr_discussions or comment_on_line). The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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?

States a specific verb (reply) and a specific resource (an existing discussion thread), and the second sentence distinguishes the behavior from the alternative of opening a new thread on the same line. An agent can tell it apart from gitlab_mr_comment / gitlab_mr_comment_on_line conceptually without opening schemas.

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?

"Use it to answer a review comment instead of starting a second thread on the same line" gives a clear when-to-use condition and an implicit when-not (don't open a new thread). It does not name the sibling tool that creates a new thread, so the routing is behavioral rather than explicit.

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the behavioral burden. It usefully explains the CE 11.3 no-approve-API context and the reply-first convention, but says nothing about permissions required, idempotency of resolving an already-resolved thread, or what the operation returns.

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, front-loaded with the operation and followed by the rationale and the sequencing caveat. Nothing is padded, though the CE 11.3 version detail is niche context that could be trimmed for some audiences.

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 an output schema present, return values need not be described, and the description covers what the tool does, why it exists, and the reply-first workflow. The main remaining gap is behavioral detail (permissions, idempotency) for a mutation tool with thin annotations.

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 50%: iid and project are well documented in the schema, while resolved and discussion_id have no schema description. The description's 'resolve or unresolve' phrasing hints at the purpose of the `resolved` boolean but never explicitly maps it or explains discussion_id, so it only partially compensates for the gap.

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 states a specific verb pair (resolve/unresolve) and resource (a discussion thread), so the agent knows exactly what operation it performs. It does not explicitly name which sibling it contrasts with (e.g. gitlab_mr_discussions), though the 'reply to the thread first' line implicitly points at the reply tool.

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 a clear when-to-use rationale ('this is how review state is recorded on CE 11.3, which has no approve API') plus an actionable sequencing rule (reply first if an explanation is needed). There is no explicit when-not or named alternative tool, which keeps it short of a 5.

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

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

Annotations only supply readOnlyHint=false, so the description carries most of the burden and does well: it discloses patch semantics, sentinel values (labels:[] clears, assignee_id:0 unassigns), and the non-obvious draft/title read-then-write interaction. It omits permission requirements and any indication of what the response returns.

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 dense sentences with no filler. The core update purpose and the most surprising interaction (draft/title) are front-loaded, and the sentinel rules follow compactly.

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 13-parameter mutation tool with an output schema, the description covers the risky, non-obvious behavior (patch semantics, sentinel values, draft/title coupling). Return values need no explanation given the output schema; only auth/permission expectations are unaddressed.

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 69%, and the description adds genuine meaning beyond it: the 'omitting a field leaves it alone' patch contract and the draft-with-no-title read-first behavior are not in the schema. Sentinel semantics for labels/assignee_id largely restate schema descriptions, so it is not a 5.

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?

States a specific verb and resource ('Update a merge request'), which distinguishes it cleanly from siblings like gitlab_mr_create, gitlab_mr_merge, and gitlab_mr_get. It does not, however, explicitly name those siblings or delimit scope against them.

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?

Usage is implied rather than stated: the tool is for modifying an existing MR, and the description clarifies patch semantics ('omitting a field leaves it alone'). There is no explicit when-to-use/when-not or routing to gitlab_mr_merge for state transitions versus state_event here.

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

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

With readOnlyHint=true already covering the safety profile, the description adds real behavioral context: results are ordered newest-first and reflect GitLab's native ordering. It does not add anything about pagination or auth, but those gaps are minor against the annotation coverage.

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, no waste, with the purpose stated before the usage caveat. 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?

An output schema exists, so return values need no explanation, and the description covers purpose, ordering, and the routing decision. Nothing an agent needs to call this niche debug tool correctly 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 description coverage is 100% and the schema already documents iid, project, page and perPage in detail. The description adds no parameter guidance, so the baseline 3 applies.

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?

Specific verb ('List') plus resource ('diff versions of a merge request') and an ordering guarantee ('newest first as GitLab returns them'). It also distinguishes itself from the sibling gitlab_mr_comment_on_line, which is the tool most likely to be confused with it.

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?

Explicitly states when this is needed ('only needed to debug comment positions') and when it is not, naming the alternative that handles the common case itself. This is a textbook when-to-use/when-not-to-use statement.

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

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

The readOnlyHint annotation already establishes this as a safe read. The description adds genuine value by disclosing a limitation — job logs are text and not reachable from this JSON layer — but it says nothing about pagination behavior or data freshness beyond the schema.

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 tightly written sentences that front-load the capability and then immediately qualify it. 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?

An output schema exists, so return values need not be explained, and the description covers both capability and the log-access boundary. It is complete enough for an agent to call correctly, with only minor gaps around pagination intent.

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 75%, so the schema documents project, page and perPage while pipelineId carries no description. The description adds no parameter-level meaning, so the baseline 3 applies.

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?

States a specific verb ("List") and resource ("jobs of a pipeline") and even names the returned fields (status, stage, failure reason). It is unambiguous, though it does not point at any sibling since there is no direct job-listing alternative.

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?

Usage is implied by the resource description, and the note that job logs are unreachable from this JSON layer is a useful exclusion, but there is no explicit when-to-use framing or comparison against alternatives like the raw API tool.

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

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

The readOnlyHint annotation already establishes the safety profile, and the description adds genuine behavioral context: it resolves names to the path form other tools expect and exposes default_branch. It stops short of covering error behavior or auth requirements, but that is beyond the typical bar for a simple getter.

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 tight sentences, with the core action front-loaded and the value proposition following. No filler or redundancy.

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 single-parameter read tool with an output schema already describing return values, the description is essentially complete. It could note the search alternative for discovery, but nothing required for correct invocation 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% and the single 'project' parameter is fully documented as accepting an id or full path with automatic URL-encoding. The description's 'id or path' phrasing merely restates the schema, so baseline 3 is appropriate.

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?

States a specific verb and resource ('Get a project by id or path') and adds the practical intent of resolving a name to a path. It does not explicitly name the adjacent sibling (gitlab_project_search), so differentiation is implied rather than stated.

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?

Gives clear positive usage context ('turn a project name into the path the other tools take, and to read default_branch'), which tells the agent when this tool is the right entry point. No explicit when-not or named alternative is provided, keeping it short of a 5.

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

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

The description says 'Read-only', but readOnlyHint=true already declares that, so it adds nothing beyond the annotation. No mention of pagination behavior, default result size, filtering semantics, or what happens for missing projects, leaving the behavioral burden entirely on structured fields.

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 first sentence is tight and front-loaded, but the second sentence is internal implementation commentary about endpoint declarations and 'costing no code' that gives an agent no actionable information and dilutes the definition.

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?

An output schema exists, so return values need not be explained, but for a list tool with three undocumented filter parameters the description should at minimum cover filtering and pagination semantics. Instead it omits both and spends its second sentence on irrelevant meta-commentary.

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 50%: state, labels and search are $ref aliases with no documentation at all. The description does not explain these filters (valid state values, label syntax, search scope), so it fails to compensate for the gap and adds no meaning over the schema.

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 opening sentence gives a specific verb and resource ('List a project's issues'), which is unambiguous on its own. However it does nothing to distinguish this tool from siblings such as gitlab_issue_get or gitlab_project_search, and the second sentence muddies rather than sharpens the purpose.

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?

There is no statement of when to use this tool versus alternatives. The only hint at context is the cryptic remark about merge-request tools, which does not tell an agent when this listing is the right call versus gitlab_project_search or gitlab_raw_api.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the useful detail that returned ids feed MR assignment, but says nothing about pagination, ordering, or default page size (which is only implied elsewhere). Adequate but not rich against the annotation coverage.

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?

A single, front-loaded sentence with the core purpose first and the payoff (assignee_id ids) second. No filler or redundancy.

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 a 100%-documented schema, an output schema covering the response, and a read-only annotation, the agent has nearly everything it needs. Only minor gaps remain, such as pagination/ordering expectations not being stated in the prose.

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% and every parameter (page, search, perPage, project) is documented in the schema itself. The description adds no parameter-level detail, so the baseline of 3 applies.

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?

States a specific verb and resource ('List a project's members') plus the fields returned ('access level and numeric user id'), and clarifies the downstream use of those ids for assignee_id. This distinguishes it from the nearby gitlab_users_search alternative.

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?

Clearly signals the context in which the tool is needed - obtaining numeric user ids to pass as assignee_id in gitlab_mr_create/update. It does not, however, explicitly state when to prefer this over gitlab_users_search or mention exclusions.

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

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

The readOnlyHint annotation already establishes the safe read-only nature, so the bar is lower. The description adds a useful routing note about MR pipelines and mentions optional filters, but does not disclose anything about pagination, rate limits, or result ordering beyond what the annotations and schema provide.

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 tightly written sentences with zero waste. The core list/filter behavior is front-loaded, followed by the sibling-routing note.

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 read-only list tool with an output schema and readOnlyHint annotation, the description covers the essential purpose, filters, and MR pipeline alternative. It omits pagination guidance, but the schema and output schema already carry that detail, so it is largely complete.

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 80%, so the schema already documents project, ref, page, and perPage. The description only confirms that ref and status act as filters; it adds no status enum values or format details beyond the schema, fitting the baseline 3 for high-coverage schemas.

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 states a specific verb ('List') and resource ('a project's pipelines') and immediately narrows scope with optional ref/status filters. It also differentiates from the sibling gitlab_mr_pipelines by routing merge-request pipelines there.

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 names an explicit alternative for MR pipelines ('a merge request's own pipelines come from gitlab_mr_pipelines'), which is clear routing guidance. However, it does not explain when to use this tool versus gitlab_pipeline_jobs or when to prefer ref vs status filtering, leaving some context to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read; the description usefully adds that results are permission-scoped to the current token. It says nothing further about result shape or paging, but the output schema and parameter descriptions cover those.

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 filler, with the scope constraint and the usage condition front-loaded. Nothing could be removed without losing information.

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 simple read-only search tool with an output schema, full parameter documentation, and annotations covering safety, the description supplies everything an agent needs to select and call it correctly.

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 100%, so page, perPage, and search are fully documented in the schema. The description's 'by name' adds marginal meaning about what the search string matches, which is the baseline expectation when the schema does the heavy lifting.

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?

States a specific verb and resource (search projects), the matching field (by name), and the scope constraint (visible to this token). This is enough for an agent to separate it from gitlab_project_get, which requires an exact path.

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?

Gives an explicit trigger condition — 'when the exact project path is unknown' — which implies the alternative (fetching a project by path). It stops short of naming the sibling tool outright, but the decision rule is unambiguous.

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

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

Annotations supply only readOnlyHint=false; the description adds the important trait that this tool performs no validation and forwards a wrong path or field verbatim to the instance. It does not mention auth requirements, rate limits, or that non-GET methods mutate state (only implied by the method enum), so it stops short of full disclosure.

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 tight sentences with no filler; the escape-hatch purpose comes first and the routing warning is front-loaded immediately after it.

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?

An output schema exists, so return values need no explanation, and the description covers purpose, alternatives, and the main risk. It leaves unstated who may call it and what permissions each HTTP method requires, a minor gap for an unvalidated write-capable tool.

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 75% and the schema already documents path format, query stringification, and body shape. The description adds the pass-through/no-validation semantics for all parameters but no per-parameter syntax or constraints, so baseline 3 applies.

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?

States a specific verb and resource ('call any API v4 endpoint directly') and frames it as the escape hatch for endpoints without dedicated tools, naming concrete example domains. An agent can distinguish it from the ~30 dedicated gitlab_* siblings at a glance.

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?

Gives both sides of the routing decision: use this when no dedicated tool exists, and 'Prefer a dedicated tool when one exists.' That is an explicit when-not plus an alternative-selection rule, which is exactly what usage guidance should do.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lower. The description adds that the call is scoped to the current token's instance, but says nothing about auth requirements, rate limits, or failure behavior.

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 waste, with the core action front-loaded and the rationale following. 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?

A parameterless read tool with an output schema and readOnlyHint annotation needs little more than what is given. The description covers what it returns conceptually and why it matters, so an agent has everything required to call it correctly.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.

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?

States a specific verb+resource (get the GitLab version) and scopes it to the instance answering the current token via GET /version. No sibling tool covers instance metadata, so the agent can distinguish it immediately.

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?

Gives a clear reason to call it — confirming the instance version before trusting public docs that describe newer releases — which implies the right context. It stops short of naming an explicit alternative or a when-not-to-use case, but no sibling overlaps.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds nothing beyond that — no mention of pagination behavior, ordering, or result shape, despite pagination being a real concern for a list endpoint.

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 words, front-loaded and free of filler. It is efficient, though the brevity shades into under-specification rather than pure conciseness.

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?

An output schema exists, so return values need not be explained, and annotations cover the read-only nature. What is missing is any usage context or routing hint among the many sibling list tools, leaving the definition merely adequate for a simple read endpoint.

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 100%, with project, page, and perPage all documented in the schema itself, so the baseline of 3 applies. The description contributes no additional parameter meaning.

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?

States a specific verb (List) and resource (repository tags), so an agent knows exactly what it does. It does not, however, differentiate itself from near-identical siblings like gitlab_branches_list or gitlab_labels_list, which list other project-scoped resources the same way.

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?

There is no guidance on when to use this tool, what prerequisites exist (e.g., project access), or which sibling to prefer for adjacent data. The agent must infer usage entirely from the name.

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

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

readOnlyHint=true already declares this is a safe read, and the description adds the useful context that results exist to bridge to numeric ids. It says nothing about result volume, matching behavior (substring vs exact, per the schema), or ordering beyond what the schema and output schema already provide.

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, the purpose front-loaded before the rationale. The '11.3' reference is terse and assumes internal context, which costs a little clarity but no wasted prose.

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 an output schema present, return values need not be explained, and the schema covers all three parameters plus pagination. The only gap is the absence of explicit guidance on when this beats other lookups, which is minor for a simple read tool.

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 'search', 'page' and 'perPage' are fully documented in the schema itself. The description's 'by name or username' loosely maps to the search parameter but adds no syntax or format detail beyond it. Baseline 3 applies.

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?

States a specific verb and resource ('Find users by name or username') and explains why it exists relative to the id-based filtering elsewhere. It does not name a sibling alternative, but no sibling tool overlaps with user lookup, so the purpose is unambiguous.

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 rationale ('11.3 assigns and filters by numeric user id and never by username') implies when to reach for this tool — resolving a username to an id — but it is stated as a justification rather than explicit usage guidance. There is no when-not condition and no named alternative such as gitlab_whoami for the current user.

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

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

Annotations provide readOnlyHint=true, so safety is covered. The description adds valuable behavioral context: that this is the cheapest auth/URL validation and should precede writes. It doesn't describe rate limits or return shape, but the output schema exists and an auth check needs little more.

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 compact sentences, zero waste, front-loaded with the core action and then the routing rationale. Every clause carries information.

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 zero-parameter, read-only identity check with an output schema and annotations covering safety, this is fully complete. An agent knows what it does, when to call it, and why.

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?

Zero parameters, so there is nothing to document; baseline is 4. The description correctly implies no inputs are needed to identify the caller from the token.

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?

States a specific verb+resource: 'Get the authenticated user.' This is unmistakably distinct from every sibling (which are all about projects, MRs, pipelines, etc.), and the response semantics are clear.

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?

Explicitly says when to use it ('Call this first') and why ('cheapest way to prove the token and base URL work before any write'), effectively routing the agent to this tool as a connectivity/auth check rather than to a heavier sibling.

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