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 declare readOnlyHint=true, and the description reinforces this with 'read-only and does not mutate GitLab data'. It adds useful behavioral context beyond annotations by listing error conditions: 'missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors.'

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 front-loaded with the purpose and usage guidance, and each sentence contributes. The final sentence is somewhat generic boilerplate about identifiers and pagination that could be trimmed, but overall it is concise.

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 when to use, safety, errors, and identifier format. With no output schema, it gives a hint of return content ('commit, protection status') but doesn't enumerate all fields. Still, for a simple get-one-resource tool, this is sufficiently complete.

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

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

Schema description coverage is 100%; the description adds no new meaning for branch_name or jmespath. It repeats the project_id format ('numeric ID or complete URL-encoded path') that the schema already documents, so it stays at the baseline of 3.

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

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

The description opens with a specific verb and resource: 'Get branch details (commit, protection status)'. It also distinguishes from discovery tools by stating this is for a known resource or result, making it clear which sibling tools (list_branches, search) are alternatives.

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 the tool versus alternatives: 'Use this for a known resource or result; choose the corresponding list or search tool when you need to discover multiple resources.' This removes ambiguity and routes the agent to the appropriate sibling.

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

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

Annotations already declare readOnlyHint, and the description reinforces non-mutating behavior while adding useful error conditions: missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors. This goes beyond the annotation baseline without contradicting it.

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

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

The first sentence is concise and front-loaded, and the second provides useful routing. However, the final sentence includes generic boilerplate about group_id and pagination fields that do not apply to this tool's schema, adding noise. The description is adequate but not tightly scoped to this specific tool.

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

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

For a simple read-only lookup with no output schema, the description covers the core need: what it does, when to use it, important error behaviors, and identifier requirements. The only minor gap is lack of any hint about the return value shape, but this is not necessary for such a straightforward get-by-id tool.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds only a slight reinforcement of the project_id identifier format and a generic instruction to use identifiers/pagination as documented. It does not meaningfully explain sha, stats, or jmespath beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description begins with a precise verb and object: 'Get details of a specific commit.' It also explicitly scopes the tool to known resources/individual results and contrasts it with list or search tools for discovery, clearly distinguishing it from siblings like list_commits.

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 states when to use the tool ('for a known resource or result') and when not to ('choose the corresponding list or search tool when you need to discover multiple resources'). It also provides concrete guidance on identifier formats, which helps the agent choose and populate the correct call.

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 non-redundant behavioral details: missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors. This clarifies the error contract beyond what annotations provide. It does not describe return formatting, but that is covered by schema fields like full_diff.

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

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

The description is a few sentences long but each sentence earns its place: purpose, usage delineation, read-only/error note, parameter guidance. It is front-loaded with the primary action and then adds necessary context. Slightly verbose but not bloated; it avoids redundancy with annotations by noting error behavior instead of repeating read-only (though it does repeat read-only). Overall, well-structured and efficient.

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 specific-commit diff tool with no output schema, the description covers purpose, usage boundaries, error behavior, and parameter guidance. It lacks explicit mention of the response format, but the full_diff parameter implies pagination and the diff itself is a standard git structure. Given the schema covers all parameters and annotations cover safety, this description is sufficiently complete 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?

Schema coverage is 100%, so baseline is 3. The description adds extra guidance on parameter usage: 'provide the numeric ID or complete URL-encoded path described by the schema' and 'use required identifiers and pagination fields exactly as documented'. This goes beyond the schema's basic field descriptions, clarifying the expected format and constraint that parameters must be used exactly as documented.

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 specific verb 'Get changes/diffs' and resource 'a specific commit'. Clearly differentiates from list/search tools by explicitly saying 'Use this for a known resource or result' and directing to 'the corresponding list or search tool' for discovery. Distinguishes from siblings like get_commit or list_merge_request_diffs without ambiguity.

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 when-to-use (known resource) and when-not-to (discover multiple resources) guidance, and mentions error conditions. Does not name specific sibling tools but the 'corresponding list or search tool' is contextually clear. Overall, strong usage direction with only minor lack of exact sibling names.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to repeat safety semantics. It adds behavior beyond the annotations by explaining the entry structure: contiguous source-line ranges map to the commit with id, author, authored_date, and message. It does not cover pagination or edge cases, but the read-only hint plus output-shape context is meaningful.

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so the schema itself documents all six parameters including range_start, range_end, ref, and file_path. The description adds only a light hint that range_start/range_end limit the blame to specific lines, which is useful but does not materially go beyond the schema. Baseline 3 applies.

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

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

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

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

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

The description gives a clear operational context: run blame at a specific ref dat and optionally constrain the result to a range of lines with range_start/range_end. It does not explicitly name sibling alternatives or say when not to use this tool, but 'git blame' is a distinct enough operation that the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this while adding useful behavior: missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors. This is valuable context beyond the structured annotations, though it partially duplicates the read-only 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 sentences with the core purpose and usage guidance front-loaded. The description is efficient, but some boilerplate like 'exactly as documented' and the duplication of the readOnlyHint annotation keep it just short of perfect conciseness.

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

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

For a read-only fetch tool with no required parameters and no output schema, the description covers selection criteria, error behavior, and identifier formatting. It leaves the exact shape of file versus directory output somewhat implicit, but the name and first sentence convey the core return type adequately.

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 parameters and the baseline is 3. The description adds little beyond that, mostly reiterating identifier-format guidance already present in the schema and mentioning group_id even though it is not a schema 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?

States a specific action ('Get contents of a file or directory') with a clear resource scope ('from a GitLab project'). It also distinguishes itself from list/search siblings by positioning itself as the tool for a known resource or result rather than discovery.

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 instructs to use this tool for a known resource/result and to choose the corresponding list or search tool when discovering multiple resources. This gives a usable decision rule for tool selection without leaving the agent to infer when this tool applies.

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?

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 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?

The annotations already declare readOnlyHint=true, and the description reinforces this by stating the operation does not mutate GitLab data. It adds useful behavioral context by enumerating error conditions: missing resources, invalid identifiers, insufficient permission, and rate limits. This is meaningful added value beyond the structured 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 appropriately sized and front-loaded with the core purpose. The final sentence about identifiers and pagination fields is somewhat boilerplate and adds limited value, but overall the structure is clear and readable.

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-resource retrieval tool with read-only annotations, the description covers the core behavior, the intended invocation context, error outcomes, and identifier requirements. Nothing critical is missing for an agent to select and invoke this tool 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 the schema already documents both project_id and jmespath. The description mostly restates the project identifier guidance ('numeric ID or complete URL-encoded path') that the schema already provides, offering little additional semantic 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?

The description clearly identifies a specific verb ('Get details') and resource ('a specific project'), and explicitly contrasts itself with list/search tools for discovering multiple resources. This makes it easy to distinguish from siblings like list_projects or search_repositories.

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

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

It explicitly says to use this tool for a known resource or result and to choose a list or search tool when discovering multiple resources. The guidance is clear, though it refers to 'the corresponding list or search tool' generically rather than naming exact sibling alternatives.

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

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

Annotations already provide readOnlyHint and openWorldHint, lowering the bar. The description adds valuable context by confirming no mutation and enumerating error conditions (missing resources, invalid identifiers, insufficient permission, rate limits), which goes 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 four sentences, each serving a distinct purpose: action, usage guidance, behavioral transparency, and parameter handling. It is front-loaded with the primary purpose and contains 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?

For a tool with 8 parameters, 100% schema coverage, annotations, and no output schema, the description adequately covers purpose, usage, safety, and error behavior. Minor gaps: the unsupported reference to group_id could confuse, and it does not explicitly describe the return structure, but the schema and clear purpose compensate.

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 parameters; the description only reinforces how to provide project_id/path and pagination. The mention of 'group_id' is extraneous since it is not in this schema, but it does not materially harm parameter understanding.

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 and resource: 'List files and directories in a repository.' It also differentiates from discovery-focused siblings by advising to use other list or search tools when discovering multiple resources, making the tool's niche clear.

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

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

It explicitly says to use this tool for a known resource or result and to choose 'the corresponding list or search tool' when discovery is needed. It also instructs to use required identifiers and pagination fields exactly as documented, giving actionable usage direction.

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, so the description's read-only claim adds limited value. However, it goes beyond annotations by disclosing that missing resources, invalid identifiers, insufficient permission, 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?

The purpose is front-loaded in the first sentence, and the usage guidance follows immediately. The final sentence about 'project_id or group_id' is a bit generic and slightly redundant with the schema, keeping it from 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?

The description covers what the tool does, when to use it, error behavior, and parameter identification guidance, which is sufficient for a simple list operation. There is no output schema, but for a branch-listing tool this is not a serious 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 carries the parameter documentation burden. The description adds some guidance about project_id being a numeric ID or URL-encoded path and reminds about pagination, but this is largely restating or slightly genericizing the schema content.

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 action ('List branches in project') and a distinguishing detail ('with search filter'), and explicitly contrasts with the corresponding get tool for single resources. This makes it easy to tell apart from sibling tools like get_branch and list_protected_branches.

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 guidance: use for a collection of resources, and choose the get tool when the single resource is already known. It also clarifies read-only behavior and error conditions, leaving little room for agent misselection.

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 goes beyond that by enumerating failure modes (missing resources, invalid identifiers, insufficient permission, and rate limits returned as errors). It does not describe response shape or pagination internals, but the added error behavior 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?

Three sentences are front-loaded with the core action and usage rule, then safety and error details. The last sentence is slightly redundant ('described by the schema' and 'exactly as documented') but the overall length is tight and focused.

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?

Covers purpose, usage boundary, read-only safety, error behavior, and identifier/pagination care, which is enough for a list operation without an output schema. The group_id reference is a flaw, and the description does not explain filter interactions, leaving minor gaps for a 14-parameter 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?

The schema already covers all 14 parameters, so the bar for added meaning is modest. However, the description's identifier guidance mostly repeats the schema, and its claim that 'project_id or group_id is accepted' is not supported by the schema, which lists only project_id. This makes the parameter guidance partially misleading.

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 repository commits with filtering options.' It explicitly positions this tool as the collection-level operation and distinguishes it from the corresponding get tool for a single resource, so an agent can tell it apart from get_commit and similar 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?

Directly says when to use this tool ('Use this for a collection of resources') and when to choose an alternative ('choose the corresponding get tool when you already know the single resource to inspect'). It also adds operational context: read-only behavior, error conditions, and identifier/pagination care.

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?

The description adds that the tool is read-only and does not mutate GitLab data, which aligns with readOnlyHint=true. It goes beyond annotations by disclosing that missing resources, invalid identifiers, insufficient permission, and rate limits are surfaced as errors, which is useful behavioral context. 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?

The description is front-loaded with the purpose and usage guidance, but the third sentence mixes generic identifier advice with pagination and includes a conditional about group_id that does not apply to this schema. It is relatively concise but could be tightened by removing the irrelevant group_id clause.

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 is a simple read-only list with all parameters documented in schema, the description covers the key distinctions and error behavior. It doesn't describe the return format, but for a list tool that may be acceptable. The advice about projection and pagination is present, so an agent has enough to invoke 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?

All 7 parameters already have descriptions in the schema (100% coverage), so the description's role is supplementary. It reiterates that project_id accepts a numeric ID or URL-encoded path (already in schema) and advises using pagination fields as documented, adding little new meaning beyond the schema.

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

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

The description names the action ('List labels') and the resource ('for a project'), which is specific. It also distinguishes this collection-oriented tool from the get tool for single resources, differentiating it from siblings like get_label. The mention of group_id is slightly tangential because the schema only accepts project_id.

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

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

It explicitly states when to use this tool ('for a collection of resources') and when to choose the alternative ('when you already know the single resource to inspect'). This is direct usage guidance versus siblings. It also instructs to use required identifiers and pagination fields as documented, reinforcing correct invocation.

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 read-only claim repeats what readOnlyHint already provides. The description does add some behavioral context by stating that missing resources, invalid identifiers, insufficient permissions, and rate limits are returned as errors, and by calling out pagination fields. However, these are generic API behaviors and no unexpected effects are disclosed beyond that; the added value over the annotations is modest.

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 reasonably organized, leading with the main purpose and then giving usage context. However, the read-only sentence largely duplicates the existing annotation, and the closing instruction about identifiers and pagination is vague filler. The group_id mention also creates confusion without adding useful 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?

Given 26 documented parameters, full schema coverage, and no required parameters, the schema does most of the heavy lifting. The description covers the key decision point (project_id vs no project_id) and general error behavior, but it does not describe the return shape, which matters here because there is no output schema. It also omits any mention of the list_group_merge_requests alternative, so the overall context is adequate but not complete.

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

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

Schema description coverage is 100%, so the baseline is 3 because the schema already documents all 26 parameters. The description adds only a high-level explanation of project_id's optional role and a generic instruction to follow documented identifiers and pagination fields. The mention of 'group_id' is misleading because group_id is not in the schema, slightly reducing the semantic value of the description.

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

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

The description clearly states the tool's purpose: listing merge requests, with behavior depending on presence or absence of project_id. It also distinguishes this from single-resource 'get' tools via the collection-vs-single framing. However, it does not explicitly distinguish itself from the closely related sibling list_group_merge_requests, and the mention of group_id is confusing since group_id is not in the input 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 description gives practical guidance: use this for a collection of resources and use the corresponding get tool when a single resource is already known. It also explains the project_id vs no-project_id scoping. It stops short of naming the specific alternative tool (get_merge_request) or addressing when list_group_merge_requests should be chosen, so guidance is good but not fully 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 annotations already declare readOnlyHint=true, and the description reinforces the read-only/non-mutating nature. It adds useful behavioral context beyond the annotations by stating that missing resources, invalid identifiers, insufficient permission, and rate limits are surfaced as errors. No contradiction with annotations exists.

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 usage guidance are front-loaded in three sentences, and the text avoids parameter-by-parameter repetition. The final sentence is somewhat generic ('exactly as documented') and the group_id mention adds slight noise, preventing a 5.

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 8 parameters and no output schema, the description supplies the safety profile, error behavior, and identifier formatting guidance while leaving field details to the high-coverage schema. The stray group_id reference and the unnamed single-resource alternative leave a small completeness gap, but the tool remains safely invocable.

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 description is not required to document each parameter and adds little beyond the schema. The identifier guidance largely restates the schema's project_id description, and the reference to group_id is potentially misleading because this schema only accepts 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?

Opens with 'List members of a GitLab project', a specific verb+resource statement that clearly states what the tool does. The collection-vs-single-resource contrast further distinguishes it from the get_* siblings before the schema is even considered.

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 when-to-use guidance: use it for a collection and prefer a get tool when a single resource is already known. However, the alternative is only named generically ('the corresponding get tool'), and it does not explicitly contrast this tool with the sibling list_group_members.

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 explicitly states it is read-only and does not mutate GitLab data, and enumerates error conditions: missing resources, invalid identifiers, insufficient permission, and rate limits. While annotations already convey readOnlyHint, the description adds concrete error semantics, which is valuable for an agent deciding how to handle failures.

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, scope, usage guidance, safety note, and error behavior are all conveyed efficiently, with the most important information 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?

The description is complete enough for a list tool: it covers scope, read-only behavior, error semantics, and points to the schema for identifiers and pagination. It does not describe the return shape, but given no output schema and the obvious meaning of 'list projects,' the omission 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 baseline is 3 even without additional parameter details in the description. The description's mention of project_id/group_id and URL-encoded paths is generic and not directly applicable to this tool's actual schema, so it adds little beyond the structured parameter descriptions.

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 projects accessible by the current user.' It also distinguishes the collection-oriented purpose from a single-resource get tool, saying to choose the 'corresponding get tool when you already know the single resource.' This makes the tool's intent unambiguous and separates it from siblings like get_project.

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 clear context: use for a collection of resources, and choose a get tool for a known single resource. It also instructs to use required identifiers and pagination fields as documented. However, it does not explicitly differentiate when to use this over the sibling list_group_projects, so the guidance is good but not fully exhaustive.

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

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

Annotations already declare readOnlyHint=true, 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?

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 provide readOnlyHint=true and openWorldHint=true, so the bar is lower. The description adds useful behavioral detail: it is read-only, does not mutate GitLab data, and returns errors for missing resources, invalid identifiers, insufficient permissions, and rate limits. This is solid but not exhaustive; for example, no detail on result ordering or empty searches is given.

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 front-loaded with the core purpose and includes routing, safety, and error semantics in a compact form. The last sentence is somewhat generic and mentions identifiers not present in the schema, so it is not perfectly tight, but overall every sentence contributes.

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 search tool with readOnly/openWorld annotations and full schema coverage, the description covers purpose, routing, safety, and error behavior. It does not describe what fields are searched or how matches are ranked, and there is no output schema, so an agent may still need to infer some return 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 schema already documents all parameters and the baseline is 3. The description adds general guidance about numeric IDs/URL-encoded paths and pagination fields, but project_id/group_id are not actually present in the schema, so that guidance is somewhat detached from the real 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 uses a specific verb and resource ('Search for GitLab projects') and explicitly contrasts discovery with typed get/list tools when the identifier is already known. This clearly distinguishes search_repositories from siblings such as get_project and list_projects.

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 says when to use the tool ('discover matching content') and when not to ('choose a typed get or list tool when the target identifier is already known'). This gives an explicit routing rule 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 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.

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 15 parameters. The description adds meaningful semantics for `full_response` by explaining the default slim confirmation and the specific fields it returns, which goes beyond the schema's one-line description. This warrants a 4 rather than a baseline 3.

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

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

The description states a specific verb ('Update') and resource ('an issue'), and clearly identifies the tool's scope: changing fields on an existing issue. It also distinguishes itself from sibling tools like `update_issue_description_patch` and `create_issue_note`, so an agent can tell them apart 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?

The description explicitly says when to use this tool ('change fields on an existing issue') and names two alternatives with their use cases: `update_issue_description_patch` for targeted description edits avoiding full-body sends, and `create_issue_note` for discussion. This gives both positive and negative 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?

With only openWorldHint in annotations, the description carries the transparency burden and does well: it discloses the side effect ('changes the issue description when not dry-running'), the permission requirement ('requires issue-edit permission'), and possible outcomes ('patch result or a mismatch/validation/permission error'). This goes well beyond the sparse 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 front-loaded with the core action and is generally efficient. However, the dry_run/create_note functionality is stated twice ('supports dry_run... create_note' and 'use dry_run... create_note'), creating slight redundancy without much added 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?

Given no output schema, the description adequately covers the return value ('returns the patch result or ... error') and the key side-effect/permission context. It relies on the thoroughly documented schema for parameter details, which is reasonable at 100% coverage, though a bit more detail on duplicate-match failure for allow_multiple could strengthen it.

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 mild value by explaining dry_run as 'preview changes' and create_note as 'summarize updates,' and by mapping patch_type to 'search/replace or unified diff,' but it does not substantially extend what the schema already documents.

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: 'apply a patch ... to an issue description.' It also distinguishes itself from a full-description update by noting it 'reduces token usage by allowing small changes without sending the full description,' which differentiates it from sibling tools like update_issue.

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

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

It explicitly says 'use this for a targeted search/replace or unified-diff change to an issue description' and gives conditional guidance for dry_run and create_note. It does not explicitly name the alternative full-update tool or state 'do not use for full rewrites,' but the targeted-change framing makes the intended use clear.

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