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

Annotations only provide openWorldHint, so the description carries most of the behavioral disclosure burden. It clearly states the operation creates remote project data, requires issue creation permission, and returns the new issue or validation/permission/duplicate errors. This gives an agent meaningful expectations about side effects and failure modes.

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 short and front-loaded, with the primary action first and the usage alternatives following. The only minor redundancy is 'Create a new issue' followed by 'Use this to open a new issue,' but overall it is tightly written and information-dense.

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

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

Despite having 9 parameters and no output schema, the description covers the core behavioral contract: creation, permission requirement, expected return value, and likely error categories. Optional parameters are fully covered by the schema, so nothing essential is missing for agent decision-making.

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 parameters are already well-documented in the input schema. The description adds no parameter-specific semantics beyond the high-level mention of the result and error cases, which is consistent with the baseline 3 for full schema coverage.

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 uses a specific verb and resource ('Create a new issue') and immediately differentiates itself from sibling tools: update_issue for existing issues and create_issue_note for discussion-only additions. An agent can confidently select this tool without inspecting sibling 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?

Explicit guidance is provided: use this tool to open a new issue, update_issue for an existing issue, and create_issue_note for adding discussion without changing issue fields. This directly answers when-to-use and when-not-to-use, with named alternatives.

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

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

Annotations only include openWorldHint, which is a minimal hint about side effects. The description carries the burden and discloses that the operation 'creates remote discussion content', requires note permission, and returns the note or a missing-issue/thread/permission error. This goes beyond the sparse annotation and gives the agent a clear behavioral model, including side effects, authorization, and error cases.

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 sentences, but the second sentence partially repeats the first ('add a note to an existing issue, optionally as a reply to a discussion') before adding the guidance. It is still concise and front-loaded with the primary action, though the redundancy prevents a perfect score.

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 the tool's moderate complexity (6 parameters, no output schema, minimal annotations), the description covers the core purpose, usage guidance, permission requirement, and error outcomes. It doesn't explain the jmespath or created_at parameters, but the schema already defines them, and the description is otherwise sufficient for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents all 6 parameters with descriptions (100% coverage). The description adds no parameter-specific detail beyond what the schema provides; the only related phrase, 'optionally replying to a discussion thread', merely restates what discussion_id already says in the schema. With full schema coverage, a 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 clearly states 'Add a note to an issue, optionally replying to a discussion thread', which is a specific verb+resource action. It explicitly differentiates from siblings by naming update_issue for issue fields and create_note for the generic endpoint, so an agent can immediately distinguish this tool from related ones without inspecting 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?

It provides explicit when-to-use guidance: 'Use this to add a note to an existing issue, optionally as a reply to a discussion; use update_issue for issue fields and create_note only when the generic endpoint is required.' This also covers when not to use it and names the alternatives, leaving no ambiguity.

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 include openWorldHint, so the description carries the behavioral burden. It discloses that the operation 'creates remote review state' (side effect), 'requires project access' (permission prerequisite), and describes return behavior including error categories. These are meaningful, non-obvious behavioral traits not in 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 sentences with no fluff. The purpose is front-loaded, followed by usage guidance, then behavioral context. 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 14-parameter creation tool with no output schema, the description adequately covers purpose, lifecycle sequencing, side effects, permission requirements, and error outcomes. It provides enough for an agent to invoke the tool and interpret the response correctly without needing the schema for high-level semantics.

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 baseline is 3. The description only reuses terms like 'source branch' and 'target branch' that are already explained in the schema; it adds no additional parameter-level meaning, but does not need to given full schema coverage.

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 the specific action ('Create a new merge request'), the resource ('merge request'), and the context (from existing source branch to target branch). Explicitly differentiates from the sibling `update_merge_request` by stating the lifecycle order, so an agent can clearly distinguish when to create vs. update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: 'Use this to open a new merge request from an existing source branch to a target branch; use `update_merge_request` after it exists.' This gives a clear when-to-use condition and names the alternative, making tool selection 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 provide only openWorldHint=true, so the description carries most of the behavioral burden. It states that the operation 'creates remote review content,' requires note permission, and returns a discussion or error. This adds useful transparency about side effects and failure modes, beyond what openWorldHint implies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the first states the core action, the second distinguishes siblings, and the third covers behavior and errors. No filler or redundancy; the structure front-loads the purpose.

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

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

Given the complex nested schema and openWorldHint annotation, the description covers purpose, alternatives, permissions, and expected return/error behavior. It does not explain how to construct a position object, but the schema covers that in depth, so the description is complete enough for correct invocation.

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 rich descriptions on position, line_range, and required fields. The description itself adds no parameter-level meaning beyond the schema, 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 uses a specific verb and resource: 'Create a new thread on a merge request.' It explicitly differentiates from siblings by naming create_merge_request_note for unthreaded notes and create_merge_request_discussion_note for replies, so an agent can immediately tell them apart.

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 explicit when-to-use guidance: 'Use this to start a review thread' and names the exact alternatives for other cases. It also mentions the permission requirement ('requires note permission'), which is essential context for deciding whether this is the right 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, but the description adds meaningful context: it changes only the session's tool registry, returns an active-tool summary, and does not modify GitLab data. This resolves the apparent tension between 'activate' and readOnlyHint, and discloses the explicit-only-toolset limitation. It stops short of detailing return shape beyond a summary, so a 4 rather than 5.

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 category enumeration is long but earns its place as a discoverable value list, and the operational instructions are front-loaded before the behavioral notes. Slightly dense, but no sentence is wasted on restating the title.

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 partially compensates by stating it returns the active-tool summary and lists already-active categories in the response. For a session-registry tool with only two optional params and full schema coverage, this is nearly complete, missing only finer detail on the return payload.

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, and the description genuinely adds meaning for `category`: it names example values and explains the omit-to-list / supply-to-activate semantics. `jmespath` is left to the schema, which is acceptable but leaves a small gap.

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

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

The description states a specific verb and resource ('Discover and activate additional tool categories for this session') and enumerates the exact categories available, making it immediately distinguishable from the GitLab data-operation siblings. An agent knows precisely what this tool is for 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 trigger conditions ('Use this when a needed opt-in category is not currently exposed') and a concrete workflow ('omit `category` to inspect available categories, then call it with a category to activate that group'). It also flags the alternative for omitted toolsets (GITLAB_TOOLSETS), leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, but the description adds genuinely useful behavior: read-only, and that missing resources, denied access, and rate limits surface as errors. It also clarifies accepted identifier formats. It does not describe pagination or payload shape, but that is minor here.

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 purpose, then routing, then behavioral notes; tight and free of filler. The identifier-format note at the end is slightly out of place but still earns its space.

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

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

For a three-parameter read with no output schema, the description names the returned fields, error conditions, and identifier formats, which is close to complete. The stray group_id mention is the only loose end.

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 all three parameters are already documented; the description only reinforces the project_id format ('numeric ID or URL-encoded path'). It also references `group_id`, which is not a parameter of this tool, adding slight confusion rather than new meaning.

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

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

States a specific verb and resource ('Get branch details') and even enumerates the payload ('commit, protection status'), which an agent can distinguish from list_branches. The contrast with the list/search family is implied by the routing sentence.

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 the matching list or search tool to find resources, implying get_branch is for when the branch name is already known. It gives clear context but no explicit statement of when this tool is the wrong choice beyond that.

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, and the description reinforces read-only while adding genuinely new context: missing resources, denied access, and rate limits surface as errors. That error-surface disclosure is useful behavioral detail 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, front-loaded sentences; the core purpose leads and the routing and error notes follow. The closing project_id/group_id sentence carries a stray group_id mention that doesn't apply here.

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, so the description carries the burden of explaining what 'details' contains, yet it never sketches the returned commit fields despite having stats and jmespath parameters that shape the payload. Safety and routing context is complete; return-value context is thin.

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 each of the four parameters is already documented. The added note that project_id takes a numeric ID or URL-encoded path largely restates the schema entry, and it even references 'group_id', which is not a parameter of this tool.

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 distinguish it from get_commit_diff and list_commits by the singular resource and detail framing, though it never names those siblings explicitly.

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' gives clear routing guidance toward list_commits/search_repositories. It stops short of naming the exact sibling or stating when this tool is the wrong 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?

With readOnlyHint/openWorldHint annotations already covering the safety profile, the description still adds value by disclosing error behavior for missing resources, denied access, and rate limits, plus ID/path format conventions. It stops short of describing return shape or whether diff is paginated beyond the schema hint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with zero filler, front-loading the core purpose before behavioral and parameter notes. 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 read-only retrieval tool with full schema coverage and no output schema, the description covers purpose, error semantics, and ID conventions adequately. Minor gap: no note on diff size/pagination behavior despite the full_diff parameter implying the diff can be large.

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 params (sha, jmespath, full_diff, project_id) are already documented in the schema. The description only adds the project_id/group_id numeric-or-URL-encoded-path convention, which is a marginal addition over the schema's own wording.

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?

Clear verb+resource ('Get changes/diffs of a specific commit'), and it is distinguishable from siblings like get_commit (metadata) and get_merge_request_diffs (MR scope). It does not explicitly name or contrast with those siblings, keeping it 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?

Usage context is only implied by the purpose statement. No explicit when-to-use vs get_commit or get_merge_request_diffs guidance, and no exclusions are stated, so it sits at the minimum-viable level.

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 and openWorldHint, so the safety profile is covered by structured data. The description adds genuinely useful behavior beyond that: missing resources, denied access, and rate limits surface as errors rather than partial results. It does not address return shape or large-file handling, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the core purpose front-loaded and zero filler. Minor deduction: it references `group_id`, which does not exist in the input schema, so that clause spends words on something misleading rather than useful.

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 does some of the return-value work by disclosing error conditions. It stops short of explaining what a directory result looks like versus a file result, or whether content is truncated for large files, which an agent would benefit from knowing for a five-parameter retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all five parameters are already documented, including the project_id ID-or-URL-encoded-path convention that the description restates. The description adds no information about ref, the path/file_path alias precedence, or the jmespath filter, so it does not exceed the schema 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?

Names a specific verb (Get), resource (contents of a file or directory), and scope (a GitLab project), which cleanly separates it from siblings like get_repository_tree, get_file_blame, or get_commit_diff. An agent can identify the right tool 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?

The tool's read-only nature is stated, which implies a read/retrieve use case, but there is no explicit when-to-use guidance and no named alternative (e.g., use get_repository_tree to enumerate a directory, get_file_blame for line ownership). Usage is implied rather than directed.

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, but the description adds real value beyond them: issue read permission requirement and explicit failure modes (invalid identifier, missing issue, access denied). The 'read-only' restatement is redundant, but the permission and error context lift it above baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core action and return shape, then usage routing, then permissions/errors. Every sentence earns its place 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?

No output schema exists, yet the description covers what is returned (issue with slim/full milestone), the flag that changes it, permission prerequisites, and error conditions. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description usefully clarifies the full_response default behavior (slim milestone vs. complete object) at the top level rather than only in the schema. It adds slight reinforcement rather than new syntax detail.

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

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

States a specific verb and resource ('Get details of a specific issue') and explicitly names the sibling tools to use for discovery (list_issues, my_issues), letting an agent distinguish it from them without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('inspect one issue's fields') and when-to-use-alternatives ('use list_issues or my_issues to discover issues first'). The routing between single-item fetch and list tools 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 and openWorldHint, so safety is covered; the description still adds value by stating the failure modes (missing resources, denied access, rate limits return errors). The include_summaries flag's cost (extra API calls, larger response) is disclosed in the schema, not here, so the description doesn't carry that part.

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 dense sentences, front-loaded with the required-parameter rule and the summaries flag, with no filler. Minor waste: it mentions `group_id`, which is not a parameter of this tool, which could momentarily confuse the caller.

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 tool with no output schema, the description covers the required-input rule, the summary-expansion option, discovery alternatives, and error behavior. It does not indicate response shape or pagination, but nothing essential to invoking 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 coverage is 100%, so baseline is 3. The description adds semantics the schema does not encode: the either/or requirement between merge_request_iid and source_branch (schema only marks project_id required), and the accepted ID-or-URL-encoded-path form for project_id.

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

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

The opening sentence states a specific verb and resource ("Get details of a merge request"), which implicitly separates it from siblings like get_merge_request_diffs, get_merge_request_note, and get_merge_request_approval_state. It is clear, though it never explicitly names a sibling to distinguish the MR entity payload from those adjacent read tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a concrete precondition ("merge_request_iid or source_branch required") and a clear opt-in condition for include_summaries ("for deployment/commit/approval summaries"). It also routes discovery cases to list/search tools. No explicit when-not-to-use statement, so not 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 provide readOnlyHint=true, and the description reinforces this by saying 'It is read-only.' It adds useful behavioral detail by listing error conditions: missing requests, unsupported GitLab versions, and permission failures are reported as errors. It does not describe the full shape of the approval-state response, but the error disclosure 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?

The description is two sentences with no filler. It front-loads the core purpose, then provides usage guidance, safety confirmation, and error behavior in a compact, well-ordered way. 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 read-only retrieval tool with rich annotations and complete schema coverage, the description covers purpose, usage, safety, and error conditions. The only minor gap is that it does not describe the specific fields contained in the 'approval-state response,' which would be more important if no output schema existed. Still, the essential context for correct selection and invocation is present.

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 three parameters. The description adds no additional parameter-specific meaning, such as how project_id is resolved or how jmespath interacts with the result. Baseline 3 is appropriate because the schema carries the parameter documentation 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 clearly states the verb-resource relationship: 'Get merge request approval details including approvers.' It also names the inspection purpose ('inspect approval rules and approvers before deciding whether a merge request can be merged'), which distinguishes it from sibling tools like approve_merge_request and unapprove_merge_request.

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 tells the agent when to use this tool ('before deciding whether a merge request can be merged') and points to the alternative for changing state ('use `approve_merge_request` to change approval state'). This is direct, actionable guidance with no ambiguity.

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 meaningful behavior beyond that: the identifier requirement, and that missing resources, denied access, and rate limits surface as errors, which helps an agent anticipate failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, all front-loaded with the core action first and constraints after; no filler. Slightly dense parentheticals but nothing wasted.

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

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

For a 6-parameter read tool with no output schema, the description covers the access pattern and error behavior but says nothing about the shape of the returned diff (e.g., per-file change objects, truncation, large-diff handling) nor how it relates to the sibling diff tools. Adequate but with clear 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 description coverage is 100%, so the baseline is 3 and the schema already documents every parameter including the view enum and jmespath. The description mostly repeats structured content ('project_id/group_id take a numeric ID or URL-encoded path'), and even references group_id, which is not in the schema, adding little net value.

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 the changes/diffs of a merge request') and clarifies the required identifier choice, which is clear enough to act on. However, it does not distinguish itself from close siblings like list_merge_request_diffs or get_merge_request_file_diff, so an agent must still infer which diff tool applies.

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 one useful routing hint ('To find resources, use the matching list or search tool') and notes that merge_request_iid or source_branch is required. It stops short of stating when to prefer this over list_merge_request_diffs or get_merge_request_file_diff, leaving the key selection decision to inference.

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

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

The readOnlyHint annotation already covers safety, and the description reinforces it with 'It is read-only.' It also adds behavioral context beyond annotations by describing the outcome: returns the discussion item or an error for invalid identifier, missing discussion, or insufficient permission.

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 compact and front-loaded with the core purpose, then adds targeted usage and behavior information. Every sentence earns its place with no filler or redundancy.

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

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

For a single-discussion read tool with three required identifiers and a fully documented schema, the description covers selection, alternatives, return behavior, and error conditions. Nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds little beyond restating that a discussion is fetched by identifier, so it provides no meaningful extra parameter meaning.

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

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

The description states a specific verb and resource: 'Get a single discussion item for a merge request.' It also explicitly distinguishes itself from siblings by naming `mr_discussions` for collections and `get_merge_request_note` for flat notes, so an agent can clearly tell this tool apart.

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 explicit when-to-use guidance: fetch one known discussion by discussion identifier. It names the exact alternatives for collection and flat note use cases, leaving no ambiguity about which sibling tool to choose.

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 cover read-only (readOnlyHint=true) and open-world scope, but the description adds genuinely new behavioral context: missing resources, denied access, and rate limits surface as errors. It does not describe pagination or response shape, but the error behavior is useful value beyond the structured hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with the core action and the key requirement front-loaded, and no filler. The only wasted element is the dangling `group_id` reference, which is irrelevant to this tool's parameters.

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

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

For a 6-parameter read tool with no output schema, the description covers the required selector, ID formatting, error behavior, and the read-only nature. The schema already points to list_merge_request_changed_files for discovering paths, so the remaining gap (return format) is minor.

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, establishing a baseline of 3. The description mostly repeats schema content (URL-encoded path handling) and even references a `group_id` parameter that does not exist in this schema, which weakens rather than strengthens parameter guidance.

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 diffs for specific files from a merge request), which is clearly narrower than the sibling get_merge_request_diffs/list_merge_request_diffs. It stops short of explicitly naming those siblings or explaining the scope contrast, so differentiation must be inferred from the word 'specific files'.

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 concrete prerequisite — merge_request_iid or source_branch is required — which tells the agent when this call is applicable. It does not name the alternative tools (get_merge_request_diffs, list_merge_request_diffs) or state when to prefer them, so exclusions are absent.

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 the description reinforces this by saying 'It is read-only.' It adds useful behavior beyond the annotation: it returns the note object or an error for invalid identifier, missing note, or insufficient permission. This helps set expectations without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The primary action is front-loaded, and the usage guidance and behavioral expectations are packed efficiently into the second sentence.

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

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

For a single-object read tool with no output schema, the description is complete: it states the resource, the lookup key, the read-only nature, the return value, likely error conditions, and relevant alternatives. No additional context is needed for correct invocation.

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 already documented in the input schema. The description adds little beyond identifying note_id as the identifier to use, but it does not provide additional semantics or format details beyond what the schema already contains.

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 uses a specific verb and resource: 'Get a specific note for a merge request.' It clearly differentiates this tool from get_merge_request_notes and mr_discussions by scope (single known note vs collection vs threaded context).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use this tool ('fetch one known merge request note by note identifier') and directly names the alternatives ('use get_merge_request_notes for a collection and mr_discussions for threaded context'). This gives an agent clear routing 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=true, and the description reinforces this with 'It is read-only.' It adds useful behavioral context beyond annotations by specifying that the tool returns note records and that GitLab reports invalid identifiers, missing resources, pagination, and permission errors. This helps set error-handling expectations, though it does not detail response shapes or pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler. The core action is front-loaded, the sibling distinction follows immediately, and the behavioral/error note is concise. 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?

The description is complete for tool selection and invocation: it states behavior, scope, the key sibling alternative, and error reporting. With no output schema, saying it 'returns note records' is a minimal but sufficient return-value hint. It could mention that results are flat and how pagination manifests, but this is a minor 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 the parameters are already documented in the schema. The description adds no parameter-specific meaning (e.g., how `sort` or `order_by` interact, or what `jmespath` filters). Baseline 3 is appropriate because the schema carries the full parameter-semantics 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 states a specific verb and resource ('List notes for a merge request') and immediately differentiates from the sibling tool `mr_discussions` by characterizing itself as returning flat notes. This makes the tool's scope unmistakable and distinct from discussion-thread operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use this tool vs. an alternative: 'use mr_discussions when thread structure and resolution state are required.' This gives the agent a clear decision rule and excludes the overlapping sibling, leaving no ambiguity about selection.

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 description's "Read-only" is partly redundant. It nonetheless adds genuine behavioral context the annotations don't carry: missing resources, denied access, and rate limits all surface as errors. Minor wart: it references `group_id`, which is not a parameter of this tool.

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 before routing and error behavior. Nothing is padded, though the group_id clause is dead weight that dilutes an otherwise tight definition.

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

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

For a two-parameter read tool with no output schema, the definition covers purpose, routing, error modes, and ID format expectations. It does not describe the returned project shape or what jmespath does to the result, but the schema carries the parameter detail.

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 project_id description already says "Project ID or URL-encoded path," so the description's restatement adds no new meaning. It ignores the `jmespath` parameter entirely and mentions a nonexistent `group_id`, which can only confuse rather than inform.

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 details of a specific project"), which is clearly distinct from siblings like list_projects or get_issue. It does not explicitly name list_projects as the counterpart, but the resource scope 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?

"To find resources, use the matching list or search tool" routes the agent away from this tool when discovery is the goal, which is real usage guidance. However, the alternative is described generically rather than by name (list_projects/search_repositories), and no when-not conditions beyond discovery are given.

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, but the description adds genuine behavioral context: missing resources, denied access, and rate limits all surface as errors. That failure-mode disclosure is value the annotations do not provide, though nothing is said about result size or truncation behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the core action front-loaded and zero filler. However, the trailing '`project_id`/`group_id`' note mentions group_id, which is not a parameter of this schema, adding a small bit of noise.

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 8-parameter read tool with no output schema and full schema coverage, the description covers the operation, safety profile, and failure modes adequately. Return-shape and pagination semantics are handled by the schema, so little is genuinely 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 all eight parameters including pagination, jmespath, and recursive are already documented in the schema. The description's note about project_id accepting a numeric ID or URL-encoded path merely restates the schema, 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+resource (list files and directories) clearly, so an agent knows exactly what it retrieves. It does not explicitly contrast itself with near siblings like get_file_contents or get_branch, so it falls just 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?

The description never states when to use this tool versus alternatives such as get_file_contents (single file) or search_repositories. Usage is only implied by the word 'List', with no conditions or exclusions 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 only declare readOnlyHint/openWorldHint, but the description goes far beyond: it discloses that version lookup failures are non-fatal and omit fields, that a 403 insufficient_scope sets user_api_warning and stays ok, that rate-limit/ban 403s stay unauthenticated, and that transport failures return status error plus a typed error object (tls/dns/timeout/network). This is unusually rich failure-mode disclosure for a read-only probe.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the sibling alternative are front-loaded, and the dense error-code catalog is high-value rather than filler. It is nonetheless long for a health probe and the final sentence partially restates the opening ('returns server/authentication status'), leaving mild trimming headroom.

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 takes on the burden of describing returns and does so thoroughly — version fields, conditional omission, warning flags, and per-kind error objects. An agent has everything needed to interpret any outcome correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single `jmespath` parameter has full schema description coverage and is a generic post-filter, so the schema carries the semantics. The description adds no parameter-specific syntax or examples, which is the baseline 3 when schema coverage is 100%.

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

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

The opening sentence states a specific verb and resource ('Verify server status and authentication') and immediately names the alternative sibling (`whoami`) with the condition that selects it. An agent can distinguish it from the identity-oriented sibling without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('verify server connectivity and authentication before making GitLab requests') plus an explicit when-not/alternative ('use `whoami` when the authenticated user's identity is the goal'). Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds real behavioral context: missing resources, denied access, and rate limits all surface as errors. It also notes the ID-or-URL-encoded-path acceptance, which is operationally useful. Minor noise: it references `group_id`, which is not a parameter in this 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?

Front-loads the core action and scope in the first clause, then layers routing and error behavior in short sentences. It is compact and free of filler, though the trailing ID/path sentence is somewhat 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?

With no output schema, the description appropriately carries the burden of disclosing error semantics and ID formats, and pagination is covered by the schema. Nothing critical is missing for a filtered list call, though it could say more about result ordering or page-size behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so page, search, jmespath, per_page and project_id are all already documented in the schema, establishing a baseline of 3. The description's ID/path note largely restates the schema's project_id description and introduces a `group_id` that does not exist as a parameter, so it adds little net value.

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 branches in project') plus the scoping modifier ('with search filter'). It also distinguishes itself from the single-resource sibling by routing 'for one known resource' to the matching get tool, so an agent can separate it from get_branch without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit alternative and the condition that selects it ('for one known resource, use the matching get tool'), which is exactly the branch vs. branch-list routing decision. It stops short of stating when-not to use search or how results differ from other list tools, so it is clear context rather than 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?

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true), so the description's "Read-only" earns no credit. It does add value beyond structured data by disclosing failure behavior: missing resources, denied access, and rate limits all surface as errors. Pagination limits are left to 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?

Four short sentences, front-loaded with the core purpose before the routing hint and error notes. The final project_id/group_id sentence is largely redundant with the schema and carries the erroneous group_id mention, keeping it out of 5 territory.

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, no-output-schema list tool, the description covers purpose, a sibling alternative, error modes, and ID formatting — enough for correct invocation, with per_page/page limits handled by the schema. The dangling group_id reference is the only real 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 the schema already documents all 14 parameters and the baseline is 3. The description restates the project_id format (already in the schema) and actually introduces a `group_id` parameter that does not exist in the input schema, which is a minor misleading signal rather than added meaning.

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

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

The description opens with a specific verb+resource ("List repository commits") and notes the filtering scope, so an agent can distinguish it from the many get_* and list_* siblings. It falls short of a 5 only because "with filtering options" is generic and the sibling it contrasts with (get_commit) is referred to obliquely as "the matching get 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 one routing rule — use the matching get tool for a single known resource — which is genuinely useful, but it never names get_commit and gives no guidance on which filters (path, ref_name, since/until, all) to combine or when to prefer list_branches/get_repository_tree for related lookups. Usage context is implied rather than explicit.

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

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

The description states it is read-only (matching readOnlyHint=true) and adds error behavior: invalid identifiers, missing issues, and permission failures are reported as errors. It also says it returns discussion items. While annotations already cover the read-only safety profile, the error reporting adds value beyond annotations. It doesn't contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The core purpose is front-loaded, and the sibling differentiation and error behavior are compactly included. Every word 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?

The description covers purpose, usage, and error behavior, and the schema covers parameters and pagination. It does not describe the exact structure of returned discussion items, but for a list tool with no output schema, this is a minor gap. The tool is adequately specified for correct invocation.

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 are already fully documented in the schema. The description adds no extra parameter-level detail, but given the complete schema, 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 clearly states the action (list discussions) and the target (an issue), and explicitly differentiates it from `list_issues` and `get_issue`, so an agent can immediately tell what this tool does and how it differs from close siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage guidance: use this to inspect threaded discussions, use `list_issues` for issue records, and `get_issue` for single issue fields. This provides both when-to-use and when-not-to-use with named alternatives.

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

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

Even though annotations already mark readOnlyHint=true, the description adds meaningful behavioral context: it is paginated, requires issue read permission, and returns issue records or GitLab errors for invalid identifiers, missing resources, or rate limits. This goes beyond the annotation and helps the agent anticipate failure modes.

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 sentences with no wasted words. It front-loads the core purpose, immediately covers the default behavior, then adds alternative routing and safety/error context in a tight structure.

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 22-parameter tool with no output schema, the description covers the essential context: what it lists, how scope works, when to use siblings, pagination, permissions, and expected return/error behavior. The rich schema fills in the remaining parameter details, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and every parameter already has a meaningful description. The tool description adds only light semantic value by mentioning the default scope and optional project_id filtering, but it does not need to explain the many other parameters.

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

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

The description clearly states a specific verb and resource: 'List issues' and 'list GitLab issues, optionally scoped with project_id'. It also gives the default scope and explicitly distinguishes itself from get_issue and my_issues, so an agent can confidently select it over sibling tools.

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 guidance is explicit: it says to use get_issue when the issue iid is already known and my_issues for issues assigned to the current user. It also clarifies the default behavior (created by current user) and how to broaden it with scope='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 already declare readOnlyHint and openWorldHint, but the description adds genuinely new behavioral context: missing resources, denied access, and rate limits all return errors. That error-profile disclosure goes beyond the structured annotations and is useful for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with the core purpose front-loaded, followed by the alternative and error semantics. Tight overall, with only the redundant ID-format sentence detracting slightly.

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 full schema coverage and no output schema, the description covers purpose, the list-vs-single-resource choice, and error behavior. Pagination and filtering details are left to the schema, which documents them, so nothing critical 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 the schema already documents all seven parameters. The description's note that project_id/group_id take a numeric ID or URL-encoded path merely repeats the schema's own wording, and it even mentions group_id, which is not a parameter here.

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 labels for a project'), which is unambiguous. It does not differentiate from an actual sibling because no label-listing sibling exists, and the referenced 'matching get tool' is generic rather than named, 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?

Provides a clear alternative direction: for a single known resource, use the matching get tool rather than this list tool. However, it does not name a concrete sibling (no get_label appears in the sibling list), so the routing is clear in spirit but not fully actionable.

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

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

The annotation already declares readOnlyHint=true, so the redundant 'Read-only' adds little, but the description goes further by disclosing error behavior (missing resources, denied access, rate limits return errors), which the annotations do not cover. No return format detail, but meaningful behavioral context beyond 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?

Three tight sentences, front-loaded with the core action and scope, then constraints and behavioral notes. No filler; each clause 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?

For a 5-parameter list tool with no output schema, the description covers purpose, the diff-free return shape, selector requirements, and error conditions. Pagination or exact return envelope is unstated, a minor gap given the tool's simplicity.

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%, setting a baseline of 3, but the description adds a real constraint the schema does not enforce: that either merge_request_iid or source_branch is required despite only project_id being marked required. It also restates the numeric-ID/URL-encoded-path format for project_id.

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 changed file paths in a merge request) and immediately distinguishes scope by noting 'without diff content', which separates it from the diff-oriented siblings like get_merge_request_diffs and get_merge_request_file_diff. An agent can identify the right tool 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?

Clarifies the selector requirement (merge_request_iid or source_branch) and the diff-free nature that routes it away from diff siblings. It lacks an explicit 'use X instead when...' exclusion, so it is clear context rather than fully prescriptive 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful non-obvious context: missing resources, denied access, and rate limits return errors, plus the project_id/group_id ID-or-path format. Lacks pagination mechanics, but adds real value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences, each earning its place: scope/routing, error behavior, and parameter format. Front-loaded with the required identification constraint.

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 paginated list tool with no output schema, the definition covers routing, error behavior, and param format adequately. It could better describe the return shape or pagination expectations, but nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all seven parameters are documented in the schema. The description adds the ID-or-URL-encoded-path accepted format for project_id, which is helpful, but pagination params (page, per_page) are left to the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List merge request diffs') and distinguishes itself from the singular sibling by naming 'the matching get tool' for one known resource. An agent can pick list vs get without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a clear when-to-use rule: use this for listing, use the matching get tool for one known resource. It stops short of naming the exact alternative (get_merge_request_diffs) but the routing rule is explicit.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: missing resources, denied access, and rate limits all surface as errors, which an agent needs to anticipate.

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 tight sentences, each load-bearing: scope semantics, sibling routing, error behavior, and parameter format. The most decision-relevant fact (scope of project_id) is front-loaded.

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

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

For a 26-param read tool with no output schema, the description covers scope, the get/list boundary, error conditions, and ID formatting. An agent can call it correctly; pagination behavior (page/per_page defaults) is left to the schema, which is acceptable.

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 26 parameters are already documented. The description's note that project_id/group_id accept a numeric ID or URL-encoded path largely repeats the schema's own wording, so it adds only marginal value; baseline 3 applies.

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

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

States a specific verb (List) and resource (merge requests) and then disambiguates scope: without project_id it returns the user's MRs, with project_id it returns project MRs. It also explicitly routes single-resource lookups to the matching get tool, distinguishing it from get_merge_request.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for the two modes and points to the alternative ('use the matching get tool') when a single known resource is needed. It stops short of naming get_merge_request explicitly or describing when to prefer other list siblings like list_merge_request_diffs.

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 genuinely useful behavioral context beyond that: error behavior for missing resources, denied access, and rate limits. Minor flaw: it references `group_id`, which is not a parameter 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, front-loaded sentences with no padding; the core action leads. The stray `group_id` reference is a small blemish on otherwise efficient structure.

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 listing tool with 100% schema coverage, no output schema, and annotations covering safety, the description supplies the needed error-behavior context. It omits pagination behavior and includes a param (group_id) that doesn't exist, but neither blocks correct invocation.

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 schema already documents all eight parameters. The description's note that project_id takes a numeric ID or URL-encoded path merely restates the schema's own description, adding no new meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ("List members of a GitLab project"), which an agent can distinguish from siblings like get_project or list_projects. It doesn't name a directly competing member-listing alternative, so no sibling routing is provided, keeping it just below 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?

Usage is implied by the resource (list the members of a given project), but there is no explicit when-to-use/when-not guidance and no alternative named. Adequate but with clear gaps.

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 genuinely new context by disclosing error behavior: missing resources, denied access, and rate limits all return errors. It does not describe pagination or return shape, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with no waste; scope is front-loaded, then the alternative, then the error behavior. 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 16-parameter list tool with no output schema, the description covers scope, safety, and errors but says nothing about the shape of returned projects or pagination behavior. Params are fully covered by the schema, but the absent output schema leaves a real 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% across all 16 parameters, so the schema fully documents pagination, filters, sorting, and enums. The description adds no parameter guidance beyond what is already structured, so the baseline 3 applies.

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

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

States a specific verb and resource ('List projects') plus the scope ('accessible by the current user'), and explicitly routes single-resource lookups to the sibling get tool. An agent can distinguish this from get_project without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a clear usage rule: use this to list, use the matching get tool for one known resource. No explicit when-not beyond that (e.g., when to prefer my_issues or search_repositories), 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 the description reinforces this while adding valuable context: it returns threaded discussion items and reports invalid IDs, missing resources, and permission failures as errors. This goes beyond the structured annotations and helps the agent anticipate failure modes.

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 concise and front-loads the core purpose, then adds usage guidance and behavioral context. There is minor redundancy between 'List discussion items' and 'list complete discussion threads,' but overall each sentence contributes useful information without excessive 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?

For a read-only list tool with a well-covered schema and no output schema, the description provides enough context: what it returns, when to use an alternative, and how errors surface. It does not describe response shape, but that is not required here given the tool's simplicity and the absence of side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% description coverage for all five parameters, so the baseline is 3. The description does not add parameter-specific meaning beyond its general references to merge requests, but it also does not need to since the schema fully documents each parameter.

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

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

The description clearly states the verb and resource: 'List discussion items for a merge request' and specifies that it returns 'complete discussion threads.' It distinguishes itself from the sibling tool `get_merge_request_notes` by contrasting flat notes with threaded discussions, making the purpose unmistakable.

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 explicitly provides usage guidance: use this tool for complete discussion threads and use `get_merge_request_notes` when only flat notes are needed. This gives an agent a clear decision rule between two closely related tools.

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?

Beyond the annotations (readOnlyHint, openWorldHint), it discloses authentication requirement, the specific permission scopes needed (classic read_user or fine-grained User:Read), pagination, and the failure modes (permission/rate-limit errors). It restates read-only, which the annotation already covers, but the auth and error information is genuine added value.

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 purpose and compact overall, but the clause 'Use this for issue management: list issues assigned to the authenticated user' repeats the opening sentence verbatim and 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 12-parameter read-only list tool with no output schema, it covers the essentials: what is returned (assigned issue records), auth requirements, pagination, and error outcomes. 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% across all 12 parameters, so the schema already documents pagination, state, labels, date filters, and project_id. The description adds no parameter-level detail (e.g., how project_id interacts with the 'assigned to me' scope), 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?

The description names a specific verb and resource plus a scope qualifier: issues assigned to the authenticated user. It explicitly distinguishes itself from the closest siblings by naming `list_issues` (project-wide/author-scoped) and `get_issue` (single issue), so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the selecting condition (mine = assigned to me) and names the two alternatives with their respective conditions, effectively covering when-not-to-use-this. Nothing about tool selection is left to inference.

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

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

Annotations provide only openWorldHint=true, so the description carries the burden. It clearly states the operation changes review state, requires permission to resolve discussions, and returns the updated discussion or a missing-thread/permission error. This discloses side effects, authorization needs, and failure modes. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, purpose first, then usage distinctioncomm and behavior/error summary. Every clause is informative with no filler. Front-loaded with the action and resource.

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?

Despite having no output schemacorpor, the description explains the return value and error cases. It covers purpose, usage boundaries, permissions, state-change impact, and failure modes. Required parameters are all schema-documented, and optional jmespath needs no special explanation. Highly complete for a tool of this 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 the baseline is 3. The description adds general context (review thread, state change) but does not add parameter-level semantics beyond what the schema already provides for project_id, merge_request_iid, discussion_id, or resolved. It is adequate but not compensatory.

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 action (resolve), a precise resource (existing merge request review thread), and immediately distinguishes it from the sibling update_merge_request_discussion_note. An agent can tell exactly what this tool does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use this tool (to mark a thread resolved) and when to use the alternative update_merge_request_discussion_note (when note text must change). This is direct when-to-use and when-not-to-use guidance, naming the exact sibling tool. No inference required.

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 structurally. The description adds genuinely new behavioral context by disclosing error behavior ('missing resources, denied access, and rate limits return errors'), which tells the agent how failures surface. It doesn't cover result formatting, but that's a minor gap given the annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero filler, and the most decision-relevant fact (routing to typed tools) is front-loaded right after the purpose. 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 paginated, read-only search with a fully documented schema and no output schema, the description covers purpose, routing, and error behavior. Return-shape details are absent but partially inferable from the jmespath parameter's JSON filter; overall it is complete enough to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters (page, query, search, jmespath, per_page) are already documented in the schema, including the query/search alias relationship and the per_page max. The description adds nothing about parameter semantics, so the 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 gives a specific verb+resource ('Search for GitLab projects') and immediately scopes the tool against alternatives ('If the identifier is known, use a typed get or list tool'). The only wrinkle is the terminology shift from the tool name's 'repositories' to 'GitLab projects', which is a minor ambiguity but easily reconciled for a GitLab-aware agent.

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 states the key when-not condition: if you already know the identifier, don't search – use a typed get or list tool. That is real routing guidance. It stops short of naming the exact siblings (get_project, list_projects), so it's a strong 4 rather than a 5.

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

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

Annotations only carry `openWorldHint: true`, so the description carries the full behavioral disclosure burden. It discloses that the operation mutates issue state, requires issue-edit permission, returns the updated issue or validation/permission/conflict errors, and explains the slim vs. full response behavior. This substantially exceeds what annotations alone provide and contains no contradiction.

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 sentences and front-loads the primary action and response behavior before moving to usage distinctions and side effects. Every sentence earns its place: no filler, no repetition of schema details, and the most decision-relevant information appears first.

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

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

Given no output schema and sparse annotations, the description is thorough: it covers mutability, permission requirements, return values, error types, and response-shape options. It also provides enough usage context to route between related tools. Nothing an agent needs to call this correctly and safely is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.