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

The only annotation is openWorldHint=true, so the description carries the burden for a mutation tool. It says nothing about required permissions, whether creation triggers notifications or side effects, what happens on duplicate titles, or what the call returns. Beyond the word 'Create,' no behavior is 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?

Two sentences are useful and one is pure redundancy ('Open a new issue'). The tool-routing sentence is valuable but should lead or merge with the purpose statement to be properly 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?

Nine parameters, no output schema, and a write operation in an open world – the description gives no information about permission requirements, return payload, or side effects. An agent can call this but cannot predict the consequences or interpret the response from the definition alone.

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 enum values for issue_type and guidance on project_id, so the schema does the heavy lifting. The description adds no meaning about parameters, not even the two required ones or the optional result-filtering jmespath. 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?

The first sentence states a specific verb+resource ('Create a new issue'). The second sentence, 'Open a new issue,' is a near-verbatim restatement and adds nothing. Sibling differentiation is handled in the third sentence rather than the purpose line itself, so the intent is clear but not tightly front-loaded.

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 routes the agent: use `update_issue` for existing issues and `create_issue_note` for discussion. That covers the most likely mis-selection among siblings. It stops short of stating preconditions (e.g. project must exist, membership required) or when not to create at all.

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 openWorldHint, so the description carries most of the behavioral burden. It implies a write/append and clarifies the top-level vs threaded-reply outcome, but says nothing about required permissions, whether the note is editable/deletable, rate limits, or idempotency.

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 two sentences are near-duplicates ('optionally replying to a discussion thread' vs 'optionally as a reply'), so a third of the text is wasted. The routing sentence is well-placed at the end but the definition could be half its length.

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 no output schema and six parameters, the description leaves return shape, the purpose of created_at and jmespath, and mutation side effects unaddressed. It is adequate for the core invocation but not complete for a create operation.

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 the schema already documents every parameter including discussion_id and jmespath. The description adds only the reply-vs-top-level distinction, which 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 and resource ('Add a note to an issue') plus the optional reply mode, and explicitly distinguishes itself from update_issue. It does not, however, differentiate itself from other issue-adjacent siblings like list_issue_discussions or get_issue.

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?

Names the alternative tool (update_issue) and the condition that selects it ('for issue fields'), which is genuine routing guidance. It lacks any statement of prerequisites or when not to add a note, so it falls short of full when/when-not coverage.

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 only annotation is openWorldHint=true, so the description carries most of the behavioral burden. It usefully discloses the prerequisite that the source branch must already exist, but says nothing about write-access requirements, draft/squash side effects, cross-project forking, or error behavior when branches are identical or missing.

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 action and followed by scope and the lifecycle handoff. No filler and nothing redundant with the 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 14-parameter write tool with no output schema, the description covers purpose and lifecycle routing but leaves the agent without any statement about return content, permissions, or the meaning of the riskier options (draft, squash, cross-project). Adequate but thin relative to the tool's complexity.

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 all 14 parameters including target_project_id, jmespath, and allow_collaboration are already self-documented. The description adds only the source-to-target branch relationship, which the schema fields already convey, 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 ("Create a new merge request") and adds the key topology detail that it runs from an existing source branch to a target. This distinguishes it from read siblings like get_merge_request and list_merge_requests, though it never names which sibling creates the source branch it depends on.

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 routes the agent to `update_merge_request` for post-creation changes, which is a clear when-to-use-which rule. It does not state any when-not conditions, such as preferring an existing MR path or what to do if an MR already exists for the branch pair.

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 annotations only expose `openWorldHint`, so the description carries most of the behavioral burden. It clearly signals a write operation by saying 'Create' and 'Start a review thread', but it does not disclose permission needs, rate limits, reversibility, or how diff-note positioning affects behavior. It is adequate but has clear gaps.

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 three short sentences, front-loads the primary action, and immediately routes to alternatives. Every sentence contributes to selecting or using the tool, with no filler.

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?

The input schema is unusually rich, including detailed guidance for diff positions and multiline comments, so the description does not need to repeat those semantics. It is complete enough for tool selection and routing, though it could mention that supplying `position` creates a diff note rather than a general MR thread.

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 the schema already documents all six parameters, including the complex nested `position` object. The description adds no parameter-level meaning beyond the high-level distinction between thread, note, and reply, 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?

The description states a specific verb and resource: creating a new thread on a merge request, and explicitly frames it as starting a review thread. It also distinguishes this tool from note-creation and reply alternatives, so an agent can identify its role 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?

It gives explicit routing guidance: use this tool for a new thread, `create_merge_request_note` for an unthreaded note, and `create_merge_request_discussion_note` to reply. The alternatives and their conditions are named directly.

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 and openWorldHint=true, so the bar is lower, yet the description adds real context beyond them: activation is session-scoped and non-persistent, the stateless-mode workaround, and that the response lists already-active toolsets. The one gap is that 'activate a toolset' is a session-state change that sits in mild tension with readOnlyHint=true, and the description never reconciles that — no note that no remote data is modified.

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?

Front-loaded with the core action and the list/enable switch before any caveats, and no sentence is filler — even the long category enumeration is load-bearing since the schema has no enum. It is dense at roughly one paragraph plus a 24-item list, which is near the upper bound of comfortable scanning but justified by the missing enum.

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 no output schema, the description compensates by describing the return ('Response lists already-active ones'), and it covers the persistence model, the stateless-mode alternative, the preferred alternative to all-schemas loading, and the full valid value set. For a two-parameter session tool, nothing an agent needs to call it 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%, so baseline is 3. The description does add genuine value the schema lacks, enumerating all 24 valid category values where the schema only offers two examples ('e.g. pipelines, wiki'), but it adds nothing about the jmespath parameter beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise dual-purpose statement: 'List or activate a toolset for this session,' then immediately disambiguates the two modes ('Omit category to list; pass one to enable'). This is clearly distinct from every sibling tool, which performs GitLab domain operations, so an agent can identify this as a tool-discovery/toolset-management utility 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?

It gives explicit conditional guidance for both arguments (omit vs pass a category) and names the alternative it should replace: 'Prefer this over GITLAB_TOOLSETS=all (loads ~all schemas).' It also supplies the correct substitute path for stateless deployments ('with OAUTH_STATELESS_MODE=true persist `GITLAB_TOOLSETS=core,<category>` instead') and flags 'api is explicit-only,' leaving little to infer.

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 and openWorldHint=true, so safety profile is covered by structured data. The description adds that the result contains commit and protection status, which is useful context, but says nothing about permissions, error behavior, or response shape beyond those two 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?

Two short sentences, no filler, with the core purpose front-loaded before the disambiguation 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?

For a simple read-only single-resource fetch with fully documented parameters and readOnlyHint annotations, the description covers purpose plus partial return content. No output schema exists, so a slightly fuller account of the returned object would help, but it is close to 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 100%, so project_id, branch_name, and the jmespath filter are all documented in the schema itself. The description adds no additional parameter meaning, which is the expected baseline when the schema does the work.

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 branch details") and enumerates the returned fields (commit, protection status), which distinguishes it from mutation tools like update_merge_request. It does not explicitly name the sibling list_branches, so differentiation is only implied.

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 routes the agent to "the matching list or search tool" when it needs to find resources, which sets a usage boundary. However, it never names list_branches or any concrete alternative, so the routing guidance is generic and requires the agent to infer the sibling.

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 and openWorldHint, so the safety profile is covered. The description adds nothing beyond that: no mention of what 'details' includes, that stats are optional, that jmespath filters the payload, or any auth/rate-limit context. For a read tool this is thin but not contradictory.

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 with the core purpose front-loaded and no filler. The second sentence carries mild value as a discovery hint, though it is near-boilerplate.

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 simple read-only tool with no output schema, so the description needn't explain return values. Still, 'details' is underspecified — the agent gets no sense of what fields come back or how stats/jmespath change the result, which would matter for constructing follow-up calls.

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 the parameters are fully documented in the schema itself (sha as hash/branch/tag, stats toggle, jmespath filter). The description contributes no additional parameter meaning. 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 details of a specific commit.' An agent can tell it retrieves a single commit. However, it does not distinguish itself from siblings like get_commit_diff or list_commits, so the agent must infer that this returns commit metadata rather than a diff.

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 line 'To find resources, use the matching list or search tool' implies the SHA must be discovered via list_commits first, which is useful. But it is generic boilerplate, gives no explicit when-not-to-use guidance, and never mentions get_commit_diff as the alternative for diff content.

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 and openWorldHint=true, so the safety profile is covered. The description adds that the payload is a patch rather than metadata, but says nothing about diff size, truncation, or that paging is controlled by full_diff — behavior an agent would want to know before fetching a large commit.

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 with the core purpose front-loaded and the routing hint last. Slight redundancy between 'Get changes/diffs' and 'Return the file diffs' keeps it from being maximally tight.

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 retrieval tool with a fully documented schema and no output schema, this covers purpose, scope, and sibling disambiguation. The only real gap is what a returned diff looks like and whether large diffs are truncated, which 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 all four parameters documented including the full_diff paging flag and jmespath. The description adds no parameter-level 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 and resource ('Get changes/diffs of a specific commit') and reinforces it with 'Return the file diffs for one commit.' It explicitly separates itself from the sibling get_commit, so an agent can choose between them without reading 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?

Names the alternative (get_commit) and the condition that selects it ('metadata without the patch'), which is the exact routing decision an agent faces. It stops short of covering other near-neighbors like get_merge_request_diffs or list_commit_changed_files, so it is clear but not exhaustive.

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 description does not need to repeat safety semantics. It adds behavior beyond the annotations by explaining the entry structure: contiguous source-line ranges map to the commit with id, author, authored_date, and message. It does not cover pagination or edge cases, but the read-only hint plus output-shape context is meaningful.

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 two well-structured sentences. The first front-loads the action and resource; the second communicates the return shape and the optional range limitation. Every phrase contributes information, and there is no filler or duplication of schema text.

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?

Given there is no output schema, the description supplies the essential return semantics by naming the fields a caller can expect in each entry. The schema covers all parameters, and the read-only annotation covers the safety profile. Missing details such as pagination or behavior on nonexistent refs are minor for a straightforward blame call.

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 the schema itself documents all six parameters including range_start, range_end, ref, and file_path. The description adds only a light hint that range_start/range_end limit the blame to specific lines, which is useful but does not materially go beyond the schema. 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?

The description opens with a specific verb and resource: 'Get git blame for a file at a given ref.' This clearly separates it from read-content tools like get_file_contents and commit-history tools like get_commit-repository. It also states the central output concept (line ranges mapped to commits), removing ambiguity about what GitLab blame 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?

The description gives a clear operational context: run blame at a specific ref dat and optionally constrain the result to a range of lines with range_start/range_end. It does not explicitly name sibling alternatives or say when not to use this tool, but 'git blame' is a distinct enough operation that the usage 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 and openWorldHint=true, so safety is covered. The description adds no behavioral context at all: it doesn't say what happens when path points at a directory (listing vs error), what happens if ref is omitted, or whether large files are truncated.

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 well-formed sentence with zero filler and the resource front-loaded. It is efficient, though its brevity comes at the cost of the missing usage and behavioral detail noted elsewhere.

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?

The rich schema covers parameters and the annotations cover safety, but with five parameters, no required fields, and no output schema, the description should clarify the file-vs-directory return shape and default ref behavior. As written it is minimally adequate rather than 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 100%, so all five parameters (including the path/file_path precedence rule and the project_id env fallback) are already documented in the schema. The description contributes nothing parameter-specific, 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 contents of a file or directory') scoped to a GitLab project, which is enough to distinguish it from most siblings like get_file_blame or get_repository_tree. It stops short of explicitly naming how it differs from those adjacent tools, so a 4 rather than a 5.

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 when-to-use or when-not-to-use guidance, and no alternatives are named even though get_file_blame, get_repository_tree, and get_commit_diff all overlap in scope. The agent must infer selection purely from the tool 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?

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds useful behavioral context by disclosing that the milestone is slimmed by default and that full_response=true is needed for the complete object. It does not describe error behavior for a missing issue or permission failures, but the added default-response detail is meaningful 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?

Three short sentences, front-loaded with the core action and the default return shape. The middle sentence ("Use this for issue management") is filler that does not earn 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-only single-resource fetch with no output schema, the description covers the action, the default return shape, how to get the full version, and how to find issues first. Nothing critical for calling it correctly is missing, though error/not-found behavior is unstated.

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 each parameter (including full_response and jmespath) is documented in the schema itself. The description mentions full_response but repeats the schema's own wording rather than adding new semantics, 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?

The description opens with a specific verb+resource ("Get one issue") and immediately states the returned shape (slim nested milestone by default), which separates it from list-oriented siblings. The only weak line is "Use this for issue management," which restates the obvious rather than narrowing scope.

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 explicitly routes discovery to `list_issues` or `my_issues` "first," giving the agent a clear alternative and the condition that selects it. It stops short of stating when-not to use this tool (e.g., bulk retrieval) or any prerequisites such as project membership.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context: the identifier requirement that the schema does not enforce (only project_id is required) and the fact that include_summaries triggers extra API calls, which signals added latency/cost. It does not cover failure behavior when neither identifier is supplied, but the value added beyond annotations is real.

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 purpose, then the identifier constraint, then the optional flag and the discovery alternative. Every sentence carries distinct information with no repetition of 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?

For a read-only fetch tool with a fully documented 5-parameter schema and no output schema, the description covers purpose, required identifiers, and the cost of summaries. The main remaining gap is that it never sketches what 'details' includes (fields, size of payload) or how the jmespath filter interacts with the result, which matters somewhat given no output schema.

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 goes further by stating the cross-parameter constraint (one of merge_request_iid or source_branch must be provided) that the schema's required list does not capture. It also clarifies the practical effect of include_summaries as extra API calls, beyond the schema's 'extra API calls' phrasing. This is meaningful semantics beyond 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?

The description opens with a specific verb and resource ('Get details of a merge request'), which clearly separates it from list_merge_requests and the diff/note/discussion siblings. It does not name a specific sibling it competes with, instead referring generically to 'the matching list or search tool', so it falls short of full sibling differentiation.

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 clear usage conditions: an identifier (merge_request_iid or source_branch) is required, and include_summaries=true should be set when deployment/commit/approval summaries are wanted. It also routes agents to the list/search tools for discovery. There is no explicit when-not guidance, but the 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no further behavioral context — no permission requirements, no note on what happens when no approval rules exist, and no indication of the response shape beyond "details including approvers".

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 verb and result, followed by usage context and the alternative. 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?

A simple three-parameter read tool with full schema coverage and no output schema; the description conveys what comes back (approval rules and approvers) and when to call it. Minor gap: it does not clarify behavior when approvals are disabled or the MR is not in an approvable state.

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 project_id, merge_request_iid, and jmespath are all documented in the schema itself. The description adds no parameter-level meaning, which is acceptable at this coverage level but not above baseline.

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: retrieves merge request approval details including approvers. It also separates itself from the mutating sibling by naming `approve_merge_request`, so an agent can distinguish read vs write 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?

"Inspect approval rules and approvers before merging" gives a concrete usage moment, and the final sentence routes state changes to `approve_merge_request`. It stops short of saying when to prefer it over `get_merge_request`, which may also surface related MR data.

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 and openWorldHint=true, so the safety profile is known. The description adds the useful constraint that one of merge_request_iid or source_branch must be supplied, but says nothing about pagination, diff size limits, or behavior of the excluded_file_patterns filtering.

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 with the core action and the key required-input condition front-loaded. There is no padding, though the sibling-routing sentence is vague rather than pointed.

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 no output schema and six parameters, the description covers the essential invocation contract but omits the filtering and view options and does not clarify result shape or size. It is adequate but leaves gaps relative to the tool's surface area.

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 every parameter including view, jmespath, and excluded_file_patterns is already documented. The description only re-emphasizes the merge_request_iid/source_branch choice, adding marginal meaning beyond the schema, which fits the baseline 3.

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 and resource ('Get the changes/diffs of a merge request') and clarifies the conditional requirement for merge_request_iid or source_branch. It does not, however, differentiate this tool from close siblings such as list_merge_request_diffs, get_merge_request_changed_files, or get_merge_request_file_diff, so an agent cannot distinguish them from the text alone.

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?

'To find resources, use the matching list or search tool' provides only generic routing advice and implies discovery workflow, but it never names the specific alternative (e.g., list_merge_request_diffs) or says when this tool should be preferred for a single merge request.

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 and openWorldHint=true, so the read-only, external-facing profile is covered. The description adds nothing about return shape (e.g., whether the thread's notes are included) or how jmespath affects output, so it is only marginally additive.

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 core purpose front-loaded before the disambiguation clause. 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?

For a fetch-by-id tool with full schema coverage and annotations covering safety, this is nearly complete. The one minor gap is not stating what the returned discussion contains (notes? resolved state?), which the absence of an output schema leaves 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%, so project_id, merge_request_iid, discussion_id, and jmespath are all documented in the schema. The description mentions 'by id' but adds no syntax or semantic detail beyond the schema, making the baseline 3 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 single discussion item for a merge request') and reinforces the singular scope with 'Fetch one discussion by id.' This clearly distinguishes it from the collection sibling mr_discussions and the flat-note sibling get_merge_request_note.

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 both alternatives and the condition selecting each: 'Use `mr_discussions` for a collection and `get_merge_request_note` for a flat note.' The agent knows exactly when this tool is and is not the right choice.

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 and openWorldHint=true, so the safety profile is covered and the description need not repeat it. The description adds the either/or MR identifier constraint, but says nothing about diff size limits, truncation, or response shape — relevant gaps for a diff-returning tool with no output 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?

A single sentence that front-loads the action and resource and ends with the key constraint. Nothing is redundant and nothing needs reordering.

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 six-parameter, read-only retrieval tool with no output schema, the description covers what it returns at a high level and the identifier constraint. It leaves out practical behavior an agent would want — whether all requested paths are returned in one call, how large diffs are handled, and how this differs from the sibling diff tools.

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 would be 3, but the description contributes a genuine cross-parameter constraint: merge_request_iid OR source_branch, neither of which appears in the schema's required list. That is meaning the schema does not enforce on its own.

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 and resource ('Get diffs') plus a narrowing scope ('for specific files from a merge request'), which separates it from the broader list_merge_request_diffs and get_merge_request_diffs siblings. It stops short of naming those alternatives, so the differentiation is inferable 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 parenthetical '(merge_request_iid or source_branch required)' gives a precondition for calling, which is useful. However, it never says when to prefer this over get_merge_request_diffs or list_merge_request_diffs, nor that the file_paths prerequisite (list_merge_request_changed_files) lives only in the schema, so routing guidance is implied rather than stated.

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 and openWorldHint=true, so the safety profile is covered. The description adds useful clarity that this fetches exactly one note by id, but it does not add behavioral detail such as response shape, permissions, or rate limits 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?

Three short sentences, front-loaded with the core purpose, followed by the specific action and alternatives. There is no redundant or low-value text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple read-only retrieval tool with complete schema documentation and annotations covering safety. The description supplies enough context to invoke it correctly and route between the relevant sibling tools, with no output schema required for a basic get-by-id operation.

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 all four parameters are already documented in the schema. The description only reinforces that lookup is by id and does not add syntax, format, or constraint details beyond what the schema 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?

The description states a specific verb and resource: get a specific note for a merge request, fetching one note by id. It also distinguishes the tool from collection and thread-oriented siblings, so an agent can identify its singular-note role without inspecting 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?

It explicitly names alternatives: get_merge_request_notes for a collection and mr_discussions for threads. These conditions directly tell the agent when to choose this tool versus its closest siblings.

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 establish that this is a read-only, open-world operation. The description adds relevant behavioral context by clarifying that returned notes are flat rather than threaded, but it does not mention pagination behavior or any practical limits.

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, with the core purpose and the key exclusion front-loaded. There is no redundant or wasted language.

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 a fully documented schema and annotations, the description is nearly complete. The only minor gap is that it does not describe the return shape or pagination expectations, though the flat-note distinction gives useful context.

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 the input schema already explains all seven parameters. The description adds no parameter-level details beyond the operation itself, which is appropriate baseline behavior when the schema carries the burden.

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 names a specific operation and resource: listing notes for a merge request. It further distinguishes the result as flat notes and explicitly names the sibling tool to use when thread structure is needed.

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 an explicit alternative: use `mr_discussions` when thread structure and resolution state are required. This directly tells the agent when to choose this tool versus a closely related sibling.

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 annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond that—it does not describe what 'details' includes, permission requirements, or any special handling like URL-encoded paths.

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 two concise sentences with the core purpose front-loaded. The second sentence adds useful routing context without unnecessary verbosity.

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 two-parameter retrieval tool with annotations covering safety, the description is minimally adequate. However, it does not explain what project details are returned or how JMESPath filtering affects the response, leaving some contextual gaps.

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 both parameters (project_id and jmespath) are fully documented in the input schema. The description adds no additional meaning beyond what the schema provides, so the baseline of 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?

The description states a specific verb and resource ('Get details of a specific project'), making the tool's purpose clear. It does not fully distinguish itself from sibling retrieval tools like list_projects, but the routing sentence helps clarify its role.

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 explicitly directs the agent to use a matching list or search tool when trying to find resources, implying this tool is for retrieving a known project. This gives clear usage context, though it does not name a specific sibling or state when not to use this 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. Beyond that the description discloses nothing about the behavior that actually matters here: three mutually exclusive pagination modes including a deprecated legacy array, item + next_page_token response shapes, and how recursive affects result size. For a nine-parameter listing tool this is a substantial behavioral gap.

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, and the core purpose lands immediately. It is clean, though its brevity is achieved by omission rather than by tight editing of richer content.

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 nine parameters, no output schema, and a pagination design that includes a deprecated default mode, one sentence is not enough for an agent to call this correctly on large trees. The description should at minimum point at recursive/path scoping and warn against omitting both page and pagination.

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 every one of the nine parameters is already documented, which sets the baseline at 3. The description adds no meaning on top — it says nothing about what recursive returns, what path scoping does, or the three-way pagination choice (keyset, page, deprecated legacy array).

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?

"List files and directories in a repository" gives a specific verb and resource, and it implicitly reads as a tree/listing operation distinct from get_file_contents. However, it never names get_file_contents or get_repository_tree's own scope boundary (e.g. single-file retrieval vs. directory traversal), so sibling differentiation is left to inference.

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?

No guidance on when to prefer this over get_file_contents, get_branch, or search_repositories. Nothing tells the agent to set recursive for deep traversal, to use path to scope a subtree, or which pagination mode to pick — all decisions the caller must guess at.

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 and openWorldHint, so the safety profile is covered; the description earns credit for adding behavior annotations cannot express: the upstream endpoint (GET /api/v4/version) and, notably, that version lookup failures omit those fields rather than failing the call. That partial-degradation contract is exactly the kind of context an agent needs and cannot get from 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?

Three short sentences, zero filler, and the always-present field is front-loaded before the conditional fields. Every clause carries distinct information: what is checked, what is always returned, what is conditionally returned, and what happens on failure.

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?

There is no output schema, and the description compensates by enumerating the returned fields (mcp_server_version always; version, revision, enterprise when authenticated) and the failure mode. It stops short of explaining what the response looks like when unauthenticated beyond 'always includes mcp_server_version', which leaves a small gap for a diagnostic 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% with a single optional jmespath parameter that the schema documents fully with its own description. The tool description adds nothing about the parameter, so the baseline 3 applies — the schema does all the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-plus-resource statement ('Check auth and versions') and immediately clarifies what is always returned versus conditionally returned. It is clearly not a data-fetching sibling, though it never distinguishes itself from whoami, the other auth/identity-adjacent tool in the sibling list.

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: an agent can infer this is the tool to call to verify credentials or server version, and the phrase 'When authenticated' hints at a pre-flight role. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. whoami) that would raise this above implied guidance.

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 and openWorldHint, so the safety profile is covered. The description adds that output is a 'short' guide and that behavior shifts under OAUTH_STATELESS_MODE, which is genuinely non-obvious, but the environment-variable sentences are terse and read more like toolset configuration advice than disclosure about this tool's operation.

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?

Four short sentences, front-loaded with the core purpose and topic list before the routing advice. The trailing environment-variable sentences are the weakest part and could be trimmed or clarified without loss.

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 only two optional parameters and no output schema, the definition covers enough: what it returns, how to select a topic, and how it relates to discover_tools. The absence of any hint about the shape of the returned guide is a minor gap given there is no output schema.

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 topic enum already lists every value with its own description, so the description's topic list and 'omit for the overview' note largely restate structured data. The jmespath parameter, the one piece an agent might want explained, gets no mention here at all.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Return a short GitLab workflow guide') and enumerates the exact topics available, which lets an agent distinguish this documentation tool from the operational siblings (get_project, create_merge_request, etc.). It also names discover_tools as the related-but-different 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 explicit call guidance ('Omit topic for the overview and topic list') and names an alternative tool with a preference rule ('Prefer discover_tools over GITLAB_TOOLSETS=all'). What it lacks is when-not-to-use guidance for the GitLab workflow topics themselves — e.g., when to read a guide versus just calling get_merge_request.

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 and openWorldHint=true, so the safety profile is covered. The description adds only the existence of a search filter, which the schema already documents, and says nothing about pagination behavior, default result size, ordering, or how much data a full listing can return — the practical concerns 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?

Two short sentences, front-loaded with the primary action and followed by the alternative-route hint. Nothing is padded, though the second sentence is slightly awkwardly worded ('the matching get tool') rather than crisp.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple read-only list tool with a fully documented schema and annotations covering safety, so not much is required. Still, for a paginated endpoint with a default of 20 and a max of 100, a brief note on pagination or result-size expectations would close the remaining gap.

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, per_page, search, summary, jmespath and project_id are all documented in the schema itself. The description merely echoes the search filter, adding no format, syntax, or interaction detail beyond what the structured fields provide. 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?

The description gives a specific verb and resource ('List branches in project') plus the scoping modifier ('with search filter'), so an agent immediately knows what the tool returns. It stops short of naming the sibling 'get_branch' explicitly, referring only to 'the matching get tool', which keeps it from a 5.

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?

'For one known resource, use the matching get tool' establishes the list-vs-get split, which is exactly the decision an agent faces here. The guidance is directional but generic — it does not name get_branch or state what counts as a 'known resource' — so it is clear context rather than explicit routing.

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 supply readOnlyHint and openWorldHint, so the description's main job is to add the operational detail they don't cover. It says nothing about pagination defaults, full-vs-summary payload behavior, ordering semantics, or result size limits, so an agent learns nothing about runtime behavior it could not already infer from the 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?

Two short sentences, front-loaded with the verb and resource, no filler adjectives or restated titles. The second sentence is slightly boilerplate and vague, which keeps it out of the top band.

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 and no output schema, the description is thin, but the schema is fully described and the annotations cover the safety profile, so the essential calling information is present. What is missing is guidance on the interaction of paging, summary/jmespath shaping, and traversal flags (all, first_parent) that matter for a commit listing 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%, so every one of the 15 parameters is already documented in the schema, including the nuanced summary, jmespath, and ref_name entries. The description's "filtering options" adds no meaning beyond that, making the baseline 3 correct.

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?

"List repository commits with filtering options" states a specific verb plus resource and implies the filterable axes. It also gestures at separation from the single-resource getter, though it never names get_commit, so the sibling differentiation is suggestive 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?

"For one known resource, use the matching get tool" gives a real when-not-to-use condition (single commit already identified), which is more than nothing. But "matching get tool" is unresolved phrasing among 37 siblings, and nothing says when to prefer filters like path/ref_name/since versus list_branches or search_repositories.

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 and openWorldHint=true, so safety and reach are covered structurally. Beyond that the description adds almost nothing behavioral: it does not say the result is threaded notes, whether pagination is required to collect all discussions, or that empty results mean no discussion thread exists. The word "threaded" is the only behavioral signal, and it merely restates the resource name.

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 two sentences are near-duplicates — "List discussions for an issue" and "List threaded discussions for an issue" — so one is pure waste in a three-sentence description. The routing sentence is well placed at the end, but the tapering redundancy drags down an otherwise short text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple read-only list tool with fully documented parameters and no output schema, so much of the burden is off the description. Still, an agent gets no sense of what a discussion object contains (threaded notes) or how paging interacts with the result set, which are the two things that would round out a listing tool like this.

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 all six parameters (including `page`, `per_page`, `summary`, and `jmespath`) are documented in the schema itself. The description adds no meaning beyond that, 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?

The description names a specific verb and resource ("List threaded discussions for an issue") and explicitly routes issue-record needs to `list_issues`/`get_issue`, so it is distinguishable from the closest siblings. It does not distinguish itself from discussion-oriented siblings such as `mr_discussions` or `get_merge_request_discussion`, but resource scope (issue vs. merge request) 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?

It provides one explicit exclusion — use `list_issues` or `get_issue` for issue records rather than this tool — which is useful negative guidance. It never states the positive trigger case (e.g., reading comment threads on an issue to review feedback) or mentions pagination-driven iteration, so the guidance is partial rather than complete.

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 and openWorldHint=true, so the safety profile is covered. The description adds a genuinely non-obvious behavioral fact — that results are silently filtered to issues created by the current user unless scope='all' — which is not stated in the schema. It does not mention pagination limits or the summary/jmespath output-shaping behavior, but those are documented in 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?

Three short sentences, front-loaded with the scope default that most affects results, followed by alternatives. The middle sentence 'Use this for issue management' is generic filler that could be dropped without loss.

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 23-parameter, no-required-param list tool with full schema descriptions and read-only annotations, the description supplies what the schema cannot: the implicit scope default and sibling routing. Missing only output-shape/pagination expectations, which the schema's page, per_page, and summary fields largely cover.

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. The description adds the missing default value for the scope parameter (created_by_me), which the schema only labels 'Issue scope'. The note that project_id is optional and omitting it spans all accessible projects restates the schema rather than extending it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('List issues') and immediately qualifies the scope with the default behavior (created by current user). It also names the sibling tools get_issue and my_issues so the agent can distinguish the listing role, though the filler sentence 'Use this for issue management' adds nothing.

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 concrete routing: use scope='all' to broaden beyond the default, use get_issue when the iid is known, and use my_issues for assignments. That covers the main decision points, but there is no guidance on when to use this versus other listing tools like list_projects or list_merge_requests, nor when to omit project_id.

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 and openWorldHint=true, so safety is covered, but the description adds essentially no behavior beyond that: nothing on pagination limits, default page size, whether ancestor-group labels are included by default, or how with_counts affects payload size. The one useful nugget — that a targeted get tool exists for single-resource reads — is a routing hint rather than behavioral 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 short sentences with the core purpose front-loaded and the alternative surfaced immediately after. Nothing is wasted or padded.

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 an eight-parameter list tool with no output schema, the description is minimal but the schema carries the parameter burden. It still leaves the agent guessing about default result shape and pagination behavior, which matters given the summary and jmespath options.

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 all eight parameters (page, per_page, search, summary, jmespath, with_counts, include_ancestor_groups, project_id) are already documented in the schema. The description adds no parameter semantics 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 scoped to a project ("List labels for a project"), which is clearly distinct from the merge-request, issue, and branch siblings. It does not name the counterpart get tool explicitly, so the differentiation is directional rather than precise.

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 one routing rule — fetch a single known label via the matching get tool rather than listing — which is genuine when-to-use guidance. However, no guidance is given on when to use the search/per_page/page parameters versus narrowing some other way, and no mention of the non-label siblings an agent might confuse this with.

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 annotations already state readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful behavior by saying no diff content is returned and one MR selector is required, but it omits pagination, ordering, and what happens if both selectors are supplied.

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 definition is a single front-loaded sentence with no filler. The key scope, payload distinction, and selector requirement are all stated efficiently.

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 six-parameter read-only list tool with no output schema, the description adequately conveys the return focus: changed file paths without diff content. It could more fully explain result ordering or pagination, but the schema documents the remaining parameters well.

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 adds a meaningful conditional constraint not expressed in the schema's required list: either merge_request_iid or source_branch must be provided.

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 and resource: list changed file paths in a merge request. The phrase 'without diff content' distinguishes it from diff-oriented siblings such as list_merge_request_diffs and get_merge_request_file_diff.

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 clear context for using this tool when only file paths are needed, and it specifies that merge_request_iid or source_branch is required. It does not explicitly name alternative tools or when not to use it, which keeps it below 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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and the description only needs to add context. It contributes the pagination behavior and the requirement that an IID or source branch be supplied, but says nothing about ordering, diff truncation, size limits, or response shape. Adequate against an already-rich annotation and schema set, but thin on behavior beyond them.

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, and the invocation-critical constraint sits in the opening line ahead of the alternative-tool routing. Every clause carries information an agent needs.

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 8 parameters, no output schema, and readOnlyHint covering safety, the description covers the essentials: what it lists, that it paginates, and the required selector. The main shortfall is the unspecified "matching get tool," which forces the agent to disambiguate among several diff-related siblings on its own.

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 a constraint the schema does not encode: it states merge_request_iid or source_branch is required, while the schema lists only project_id as required. That is real meaning beyond the schema and useful for correct invocation. It leaves page/per_page interaction and the summary/unidiff tradeoffs entirely to 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 description pairs a specific verb and resource ("List merge request diffs") with a scope constraint (pagination; merge_request_iid or source_branch required), which lets an agent distinguish this list operation from the get_merge_request_diffs sibling. It stops short of naming the sibling explicitly, so differentiation is implied by the singular/plural distinction 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?

"For one known resource, use the matching get tool" gives a genuine when-to-use rule: list when the target is not pinned down, get when it is. The gap is that "the matching get tool" is not named, and with siblings like get_merge_request_diffs, get_merge_request_file_diff, and list_merge_request_changed_files available, the agent must infer which one is meant.

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 and openWorldHint=true, so the safety profile is covered; the description adds the scope-switching semantics, which is genuinely useful behavioral context. However it says nothing about pagination defaults, result size, or the summary/jmespath response-shaping options that materially change what comes back.

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, front-loaded with the resource and scope rule, with zero redundant wording. Every clause carries a distinct instruction.

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 27-parameter listing tool with no output schema, the description covers the key scope decision and the alternative tool but skips pagination behavior and the response-shaping options (summary, jmespath) that an agent must understand to get usable output. Adequate, not thorough.

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 enums, mutual-exclusion notes, and the summary/jmespath options, so the schema carries the parameter burden. The description only restates the project_id semantics that the schema already documents. 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 merge requests') and immediately explains the two scoping modes: user's MRs when project_id is omitted, project MRs when supplied. It doesn't enumerate the filterable dimensions (state, scope, labels, dates) that distinguish it from other listing tools, so it falls short of a 5.

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 hand-off rule: for a single known resource, use the matching get tool (get_merge_request). It does not state when-not to use it (e.g. versus search-based sibling listing) or mention pagination expectations, but the core routing decision is 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and reach profile is covered. The description adds only the search capability and the group alternative; it says nothing about pagination behavior, the default exclusion of inherited members, or result shape beyond what the `summary`/`jmespath` params already document.

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 purpose, then the search nuance, then the sibling routing. No filler, and each sentence carries distinct 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?

A read-only list tool with fully documented params and annotations declaring safety — the description covers purpose and the one real routing ambiguity. It omits that inherited members are excluded by default, which matters for a project-member listing, but no output schema is needed to explain returns since `summary` and `jmespath` handle shaping.

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 all nine parameters are already self-documenting. The description's 'search by name or username' merely restates the `query` param, and it offers no extra semantics (e.g., interaction between `user_ids`, `skip_users`, and `include_inheritance`), 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 ('List members of a GitLab project') with explicit scope, then names the sibling it is not ('Use `list_group_members` for a group'). An agent can distinguish project vs group member listing without opening 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 one explicit routing rule to the group-level alternative, which is the main ambiguity an agent would face. It does not state when to use search/filtering versus a plain listing, or note that the referenced `list_group_members` is not in the current toolset, leaving a small inference gap.

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 and openWorldHint=true, so safety and reach are covered. The description adds the access-scoping behavior (results limited to what the current user can see), but says nothing about pagination defaults, result volume, or the fact that the default response is full, potentially large JSON.

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 with zero filler, and the primary scope statement is front-loaded ahead of the alternative redirection. Nothing is redundant or buried.

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 17-parameter list tool with no output schema, the description covers only the core purpose and the get-vs-list split. Subtle knobs like summary vs simple vs jmespath, and paging via page/per_page, are left entirely to the schema; adequate because of full schema coverage, but thin for the tool's complexity.

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 every one of the 17 parameters already carries its own description and enums. The description adds no meaning about the filters (owned, membership, visibility, min_access_level) or the interaction between summary, simple, and jmespath, 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+resource ("List projects") and a scope ("accessible by the current user"), which distinguishes it from the mutation siblings. The second sentence routes away from it for single-resource lookups, though it says "the matching get tool" rather than naming get_project, so differentiation is slightly indirect.

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 (enumerating accessible projects) and an explicit when-not (a single known resource should use the corresponding get tool). It does not address the overlap with other search-style siblings such as search_repositories or list_project_members, nor does it note when filters should be preferred over client-side filtering.

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 and openWorldHint=true, so the safety profile is covered. The description adds only the thread-vs-note distinction and says nothing about pagination semantics (whether paging applies to threads or notes), ordering, or that unresolved/resolvable state is included, which matters for a discussions listing.

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 with no filler; the core listing behavior is front-loaded and the routing hint follows immediately. 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?

Given six fully documented parameters and no output schema, the definition covers purpose and alternative routing adequately. However, with no output schema present, the description would be more complete if it sketched the shape of a discussion thread (id, notes array, resolved flag) so an agent knows what to do with the GitLab JSON.

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%, documenting page, per_page, summary, jmespath, project_id and merge_request_iid fully. The description adds no parameter-level meaning beyond that, 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?

The description names a specific verb and resource ('List discussion items for a merge request') and clarifies the granularity as 'complete discussion threads', which distinguishes it from the singular get_merge_request_discussion. The slight tension between 'discussion items' and 'threads' in the first two sentences introduces a small ambiguity about the returned unit.

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 explicitly names the alternative, `get_merge_request_notes`, and the condition that selects it ('flat notes'). It stops short of stating exclusions or prerequisites such as needing the MR to exist or how resolving threads interacts with the resolve_merge_request_thread sibling.

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