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

Annotations only provide openWorldHint: true, so the description carries the burden of behavioral disclosure. It states that the operation changes review state, may require re-authentication or approval permission, and returns an updated approval result or an error. This adds meaningful context beyond the annotation and aligns with the openWorldHint without 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 two sentences with no redundancy. The first sentence states the core purpose and the key exclusion (does not merge), and the second covers side effects, authentication, and return type. Information is front-loaded and 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?

Given the tool has 5 parameters and no output schema, the description adequately covers the return value ('updated approval result or a permission/state error') and the key side effect (review state change). It doesn't elaborate on parameter usage, but the schema covers that. The only minor gap is not mentioning the `sha` concurrency check, but that is documented in the schema.

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

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

Schema coverage is 100%, so all five parameters are already documented in the input schema. The description does not add extra parameter-level detail, which is acceptable given the schema's thoroughness. Baseline 3 is appropriate because the schema handles the parameter explanations.

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 (approve), the resource (merge request), and the exact scope: it records an approval and explicitly clarifies it does not merge or change the source branch. This distinguishes it from sibling tools like merge_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?

The description says 'Use this to record an approval on an existing merge request' and contrasts with merging, so the agent knows when to call it. It also mentions potential re-authentication and permission requirements, giving practical usage context. It doesn't explicitly name alternatives like unapprove, but the core distinction from merge is sufficient.

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

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

The annotations only provide openWorldHint=true, which is a weak signal. The description adds valuable context: it changes remote GitLab state, requires permissions, and returns validation/conflict/permission/rate-limit errors instead of silently failing. It also discloses the non-obvious behavior of setting reviewer_state without drafts. This goes beyond the annotation and helps agents anticipate side effects.

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 primary action, followed by optional features, then guidance and behavioral notes. It is not excessively long, but the sentence 'Use this for the specific operation described; choose a sibling tool when you need a different resource or lifecycle action' is somewhat redundant and adds little information. Overall, it is reasonably tight and structured.

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

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

For a mutation tool with no output schema, the description covers the essential aspects: what it does, optional parameters, permission requirements, and error behavior. It does not describe the success response, but this is not critical given the clear operation and the presence of many sibling tools with similar patterns. The description is sufficient 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 schema already documents each parameter. The description's only parameter guidance is a generic instruction to provide project_id as numeric ID or URL-encoded path and to follow schema exactly. This adds minimal value beyond the schema and does not give per-parameter insights, so it meets the baseline but not more.

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 'Publish all draft notes for a merge request', clearly stating the verb, resource, and scope. The use of 'all' and the tool name 'bulk_publish' distinguish it from the sibling 'publish_draft_note' (singular). It also mentions optional actions (reviewer_state, summary note) without obscuring the core purpose.

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

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

The guidance to 'choose a sibling tool when you need a different resource or lifecycle action' is too generic and does not name any specific alternative (e.g., publish_draft_note for a single note). It does mention the specific condition 'Can set reviewer_state even with no drafts', which is a useful behavior but not a tool-selection guideline. Overall, it lacks explicit when-to-use versus sibling distinctions.

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 behavioral disclosure burden. It states the operation changes remote repository state, requires branch-creation permission, and returns the new branch or specific error types (validation, missing-ref, protected-project, already-exists). It does not cover default ref behavior or idempotency, but it is substantially transparent.

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

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

Three dense sentences, front-loaded with the core action, followed by usage routing, behavioral disclosure, and parameter clarifications. No filler or repeated schema text; 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?

Covers what the tool does, when to use it, what can go wrong, and key parameter semantics. Since there is no output schema, explicitly naming the returned new branch or errors is valuable. Minor omissions such as default ref behavior keep it just short of fully 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 coverage is 100% for all four parameters, so the baseline is 3. The description adds modest value by clarifying ref can select from a branch, tag, or commit, and that project_id accepts a numeric ID or URL-encoded path, but the jmespath parameter is not mentioned and the schema already documents the properties well.

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 'Create a new branch' with a specific verb and resource, and distinguishes itself from branch-related siblings by naming get_branch/list_branches for inspection and protect_branch for later protection. The scope is clear and an agent can differentiate it 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?

Explicitly says 'Use this to create a branch from a branch, tag, or commit' and points to get_branch/list_branches for inspection and protect_branch for configuring protection. This gives concrete routing guidance and clarifies when to choose this tool over relevant 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?

The description explicitly says the tool changes remote GitLab state, requires project or group permission, and surfaces GitLab's error behavior (validation, conflict, permission, rate-limit) instead of silently applying invalid requests. This adds real behavioral context well beyond the minimal readOnly/destructive annotations, which here are absent; it covers mutation, auth needs, and error mode without contradicting the openWorldHint annotation.

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

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

The description is front-loaded with purpose and contains a good behavioral sentence about state change and errors. However, the final sentence drifts into boilerplate about 'required identifiers and pagination fields' and mentions group_id where the schema does not accept one, making the structure less disciplined than it could be.

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 11 parameters, no output schema, and minimal annotations, the description still covers what the tool does, when to use it, that it mutates remote state, what permissions are needed, and how errors surface. It is incomplete only in that it does not resolve the discrepancy between the described update behavior and the absence of a dedicated update alternative in the sibling tool list.

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 parameters and parameter semantics, which sets a baseline of 3. The description adds a useful note about numeric IDs or URL-encoded paths, but it also references group_id and pagination fields in a way that is generic and not represented in the schema, so its added value over the schema is only partial.

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

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

The first sentence names a specific resource ('status of a commit') and an explicit action ('Create or update'), so the agent can tell what the tool acts on. It also tries to position this against an update/edit alternative, distinguishing it from list-only commit status tools. It loses a point because 'create or update' is immediately undercut by the instruction to prefer an update/edit tool for existing resources, and no corresponding update_commit_status sibling exists in the tool list.

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

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

The description states a clear new-vs-existing rule: use this for a new resource or action, and choose the update or edit tool when the resource already exists. However, the alternative is referenced generically rather than by name, and the sibling set has no update_commit_status tool, making the guidance less actionable and slightly inconsistent with the claim that this tool can already update.

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 minimal annotations (only openWorldHint), the description carries the behavioral disclosure burden and does so well: it states that the tool 'changes remote GitLab state,' requires necessary project/group permission, and reports validation, conflict, permission, or rate-limit errors instead of silently applying invalid requests. This gives agents a clear picture of side effects and failure behavior, though it does not explicitly mention that draft notes remain unpublished until a separate publish action.

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, followed by usage, side-effect, and identifier guidance. It is not bloated, though the final sentence contains somewhat boilerplate wording about pagination fields that does not apply to this 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?

Given a complex nested schema with 7 parameters and no output schema, the description adequately covers the essential context: what the tool does, when to use it, that it mutates remote state, that permissions are required, and how errors surface. It does not explain the draft-note lifecycle or how position/discussion parameters relate to GitLab semantics, but the schema itself provides detailed documentation for those fields.

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 thoroughly and the baseline is 3. The description adds only generic guidance about providing numeric IDs or URL-encoded paths and using required identifiers; this mostly restates the schema's project_id description. The mention of 'group_id' and 'pagination fields' is not directly relevant to this tool's schema, so it adds little 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 opens with a specific verb and resource: 'Create a draft note for a merge request.' It also distinguishes this creation tool from update/edit tools by stating to use it for new resources and to choose the corresponding update/edit tool when the resource already exists. This clearly separates it from siblings like update_draft_note and publish_draft_note.

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

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

The description provides explicit guidance: use it for a new resource or action, and choose the corresponding update or edit tool when the resource already exists. However, it does not name the specific sibling tools or explain when to prefer this over related create tools like create_note or create_merge_request_note, so the exclusion guidance is generic rather than concrete.

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 provide openWorldHint, so the description carries the burden of behavioral disclosure. It does this well by stating that the tool 'changes remote GitLab state,' requires permission, and that GitLab returns validation, conflict, permission, and rate-limit errors rather than silently accepting invalid requests. It does not cover idempotency or duplicate handling, but the major behavioral traits are disclosed.

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

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

The description is reasonably brief and front-loads the core purpose, but the final sentence about identifiers and pagination is boilerplate that does not apply to this schema. It adds noise without earning 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, when to use, mutation side effects, permissions, and error behavior. However, with no output schema, it never states what a successful create returns, and the irrelevant parameter guidance leaves a gap. It is sufficient for a competent call, but not fully 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 coverage is 100%, so the baseline is 3, but the description adds a confusing and partially misleading sentence referencing 'project_id' or 'group_id' and 'pagination fields' that do not appear anywhere in the input schema. It also adds no real semantic value to important parameters like parent_id beyond what the schema already states.

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

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

The description opens with a specific verb and resource: 'Create new group or subgroup.' This unambiguously distinguishes it from sibling creation tools like create_repository, create_issue, or create_merge_request, and clarifies that it covers both top-level groups and subgroups.

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 new resources and to choose the corresponding update or edit tool when the resource already exists. The guidance is clear, though it does not name the exact sibling update tool, which keeps it from being a full 5.

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

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

Annotations only 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 provide openWorldHint, so the description carries the behavioral burden. It explicitly discloses that the tool changes remote GitLab state, requires permissions, and surfaces validation, conflict, permission, or rate-limit errors rather than silently succeeding. This is useful beyond the annotations and matches the annotation semantics.

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 core action and examples are front-loaded and readable, but the description includes boilerplate such as 'use required identifiers and pagination fields exactly as documented' and a generic new-vs-update rule that is not specifically tailored to emoji reactions. Some sentences add noise rather than tool-specific value.

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 create operation with no output schema, the description covers the essential facts: mutation, permission needs, error behavior, and identifier format. It does not describe the response or duplicate-reaction behavior, but this is not required given the tool's simplicity and the schema coverage.

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

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

Schema description coverage is 100% and the schema already documents all parameters including the emoji name examples. The description restates the project_id format mentioned in the schema and adds no new parameter-level semantics. Baseline 3 applies because the schema already carries the documentation weight.

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 and resource: 'Add an emoji reaction to an issue', with concrete examples ('thumbsup', 'rocket'). The issue scope distinguishes it from sibling reaction tools for merge requests and notes, so an agent can identify the correct target 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 a clear creation context: use this for a new resource/action and prefer update/edit tools for existing resources. It also notes permission requirements and error behavior. It does not explicitly name alternate siblings like create_issue_note_emoji_reaction, so it stops short of full alternative 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?

With only openWorldHint=true in annotations, the description does valuable work by stating that the call 'changes remote GitLab state,' requires permissions, and that GitLab returns validation/conflict/permission/rate-limit errors rather than silently accepting invalid requests. It does not describe idempotence or the side effect on existing links, but the error and permission context is strong.

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 action, then supplies when-to-use guidance and side-effect/error behavior. The final 'use required identifiers and pagination fields' sentence is slightly boilerplate and references a pagination concept not reflected in the schema, costing a top 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?

For a state-changing create tool with no output schema and minimal annotations, the description covers purpose, when to use, permissions, and failure behavior. It could add what happens on success or how defaults like link_type behave, but nothing essential for invoking the tool 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?

The schema already describes 100% of parameters, so the description is not required to re-document them. It adds only a generic reminder to use numeric IDs or URL-encoded paths, which mostly restates the schema, so the baseline 3 applies.

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

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

The opening sentence names a precise action and resource: 'Create an issue link between two issues.' It is clearly distinct from sibling tools like get_issue_link, delete_issue_link, create_issue, and update_issue, so an agent can select it 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?

It explicitly says to use this tool for a new resource or action and to choose the corresponding update/edit tool when the resource already exists. That is an explicit when/when-not rule plus a pointer to alternatives, exceeding the minimum.

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?

The description explicitly discloses that the call mutates remote GitLab state, requires project/group permission, and surfaces validation, conflict, permission, or rate-limit errors rather than failing silently. The openWorldHint annotation is weak, so this behavioral and error-mode context is meaningful and goes beyond the annotation.

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

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

The first two sentences are sharp, but the third and fifth are generic boilerplate that could apply to any create tool, and the final sentence references group_id and pagination not present in the schema. The core information is front-loaded, but the extra sentences dilute the description.

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 mutating tool with no output schema and only an openWorldHint annotation, the description provides the key operational facts: what resource is targeted, when discussion_id is required, what permissions are needed, and what error classes to expect. It does not describe the success return value, but that is a minor gap for a create action whose schema already documents required identifiers.

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 six parameters are already described in the schema, so the baseline is 3. The description adds a useful clarification for discussion_id ('required for notes that are discussion replies') but repeats project_id schema text and introduces irrelevant references to group_id and pagination fields that do not exist in this schema.

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

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

The opening sentence names the exact action and resource: adding an emoji reaction to an issue note, which distinguishes it from issue-level reaction and MR note reaction siblings. The discussion_id mention further clarifies the target as a note in a discussion thread.

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 only tool-selection guidance is a generic 'use this for a new resource... choose update/edit tool when it already exists' line, which is not tailored to this resource and is misleading because no update-emoji-reaction sibling exists. It does not explicitly route agents away from create_issue_emoji_reaction or create_merge_request_note_emoji_reaction, and the discussion_id guidance is about a parameter rather than tool 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 only openWorldHint in annotations, the description carries the disclosure burden and meets it well: it states that the tool 'changes remote GitLab state,' requires 'the necessary project or group permission,' and that GitLab returns 'validation, conflict, permission, or rate-limit errors instead of silently applying an invalid request.' This gives concrete behavioral expectations.

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 is reasonably compact. However, the final sentence contains boilerplate about identifiers and pagination fields that adds little specific value and could be trimmed.

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 timing, side effects, permissions, error behavior, and identifier format, which is strong for a create operation. Since there is no output schema, it could have explicitly stated that the created label is returned, but the absence is a minor gap given the otherwise thorough context.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds only general guidance about numeric IDs or URL-encoded paths, which mostly repeats the schema's project_id description; the mention of 'pagination fields' is generic and not represented in this schema, so it does not meaningfully improve 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 opens with a specific verb and resource: 'Create a new label in a project.' It also distinguishes itself from update/edit tools by saying to 'choose the corresponding update or edit tool when the resource already exists,' which separates it from siblings like update_label and delete_label.

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 this tool ('for a new resource or action') and when not to ('choose the corresponding update or edit tool when the resource already exists'). It also adds operational context about required permissions and remote state changes, giving an agent clear selection criteria.

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, leaving behavioral disclosure to the description. The description clearly states that the operation creates remote review content, requires note permission, and returns either the new note or specific error types. This meaningfully exceeds what the annotation alone communicates.

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: purpose, sibling differentiation, and behavioral/auth/error disclosure. The most important usage constraint is front-loaded and there is no unnecessary repetition of schema or annotation content.

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

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

With no output schema, the description still covers the return value and error cases. Combined with full schema descriptions for all six parameters, the tool definition gives an agent everything needed to select and 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?

Schema description coverage is 100%, so the baseline is 3. The description adds contextual framing like 'existing' and 'reply', but it does not add substantive parameter-level semantics beyond 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 uses a specific verb ('Add') and a clear resource ('a new discussion note to an existing merge request thread'). It also explicitly contrasts the tool with create_merge_request_thread and create_merge_request_note, so an agent can distinguish it from its nearest siblings 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?

The description states exactly when to use this tool: to reply inside an existing merge request discussion. It names the alternatives for starting a new thread and for creating a top-level note, giving clear routing 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?

Beyond the openWorldHint annotation, the description explicitly states it 'changes remote GitLab state' and requires permission, and discloses that GitLab returns validation, conflict, permission, or rate-limit errors rather than silently applying invalid requests. This provides meaningful behavioral context beyond the annotation.

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

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

The description is structured and front-loads purpose, but contains some fluff and inaccuracies, such as referencing 'group_id' when the schema only includes project_id, and mentioning 'pagination fields' which are irrelevant. It could be tightened without losing value.

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 tool with no output schema, the description covers purpose, usage guidance, side effects, permission requirements, and error behavior. Minor confusion from the group_id/pagination references doesn't hinder overall completeness, but the omission of return value specifics is acceptable given no output schema.

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

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

Schema coverage is 100%, so the description adds limited value. It does clarify the project_id format ('numeric ID or complete URL-encoded path'), which is already in the schema, and mentions 'pagination fields' that don't apply to this tool (no pagination). No significant extra meaning is added.

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 ('Add an emoji reaction to a merge request') with examples (thumbsup, rocket, eyes), and explicitly differentiates from update/edit tools for existing resources. This clearly distinguishes it from siblings like delete_merge_request_emoji_reaction and list_merge_request_emoji_reactions.

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 guidance: use for new resources/actions, and use an update/edit tool when the resource already exists. This tells the agent when to use it vs alternatives, though it doesn't name specific alternative tools. It also notes permission requirements and error behavior, which helps in deciding applicability.

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 discloses that the tool changes remote GitLab state, requires permissions, and returns validation/conflict/permission/rate-limit errors. This goes beyond the openWorldHint annotation, which only indicates the world is open. 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?

The description is concise and front-loaded with the primary action. It includes necessary usage guidance and error behavior without excessive detail. Slightly dense but each sentence adds value.

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 complexity (4 params, no output schema), the description covers the key aspects: action, usage, permissions, errors, and identifier format. It doesn't explain return values, but with no output schema and a simple note-creation operation, this 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 the schema already documents all parameters. The description adds guidance on providing numeric ID or URL-encoded path for project_id/group_id, which is useful but not extensive. 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 clearly states the action ('Add a new note to a merge request') and distinguishes it from update/edit tools for existing resources. It also differentiates from sibling tools like create_merge_request_discussion_note and create_issue_note by specifying the merge request 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 says to use this for a new resource/action and to choose the corresponding update or edit tool when the resource already exists. It also mentions required permissions and error behavior, giving clear context for when to use this tool.

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

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

With only openWorldHint in annotations, the description carries the burden of behavioral disclosure. It clearly states that the call changes remote GitLab state, requires project/group permission, and returns validation, conflict, permission, or rate-limit errors instead of silently succeeding. It also notes the discussion-thread behavior. Idempotency and response format are not covered, but the main operational risks are disclosed.

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

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

The first sentences are tight and front-loaded with the core purpose and the discussion_id tip. The later sentences, especially 'When project_id or group_id is accepted...', read as generic boilerplate not specific to this tool and add unnecessary length. Reasonably organized but not lean.

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

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

Given six parameters, no output schema, and minimal annotations, the description covers a lot: purpose, mutation safety, permissions, error behavior, discussion replies, and new-vs-update selection. It does not name exact sibling tools or describe the returned object, but those are minor gaps for a create-reaction 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 the baseline is 3. The description reiterates the discussion_id behavior that the schema already explains and adds generic project_id/group_id identifier guidance, though group_id is not actually a parameter of this tool. This adds only marginal value 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 opening sentence states a specific verb and resource: 'Add an emoji reaction to a merge request note.' This immediately distinguishes it from siblings like create_merge_request_note or create_merge_request_emoji_reaction. The description also contrasts it with update/edit tools for existing resources.

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 to use this tool for a new resource or action and to choose the corresponding update/edit tool when the resource already exists, which provides clear when/when-not guidance. It also explains when discussion_id is needed. However, it does not name the specific sibling tools or mention when deletion would be the right alternative.

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 only provide openWorldHint, so the description carries the burden of behavioral disclosure. It adds useful context: the operation creates remote discussion content, requires note permission, and returns the created note or a target/permission/validation error. This goes beyond the minimal 'creates a note' statement.

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 waste. The opening states the operation and resource, the second sentence routes to alternatives, and the third covers remote effect, permissions, and return value. 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 creation tool with full schema coverage and no output schema, the description gives the key operational details: top-level scope, alternatives, remote side effect, permission requirement, and possible return/error outcomes. Nothing essential is missing 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 schema already documents all five parameters including the enum for noteable_type. The description adds no per-parameter syntax or format detail but reinforces the overall purpose; 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 ('Create') and resource ('a new note (comment) to an issue or merge request'), and distinguishes itself from sibling tools by explicitly framing itself as the top-level comment operation. The description clarifies it is not for threaded replies, so an agent can tell it apart from create_merge_request_thread and create_issue_note.

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

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

Provides explicit when-to-use guidance: 'Use this for a top-level comment on an issue or merge request when no typed discussion operation is needed'. It also names alternatives for threaded replies, giving clear routing and exclusions.

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

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

With no readOnly/destructive annotations to rely on, the description discloses that the operation mutates remote content in a commit, requires repository write permission, and returns a commit result or conflict/validation error. This gives the agent the key safety and outcome information it needs.

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

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

Three sentences, all functional: purpose/routing, encoding behavior, and permission/return summary. No filler or repeated 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?

Despite having 10 parameters and no output schema, the description covers what an agent needs: when to use it, what it does, required permissions, and the kind of result or error to expect. Optional parameters are fully covered by the schema.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds the encoding default and permission context but does not meaningfully enrich the other parameters beyond 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?

The description opens with a clear verb-resource pair ('Create or update a file in a GitLab project') and explicitly positions itself as the single-file counterpart to `push_files`. An agent can distinguish this from its siblings immediately.

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

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

It states the intended use case (single repository file) and names the alternative (`push_files` for a multi-file commit), which is explicit routing guidance. It also adds the encoding default behavior for backward compatibility, giving practical context for existing callers.

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 sparse openWorldHint annotation, the description discloses that the call changes remote GitLab state, requires project/group permission, and reports validation, conflict, permission, or rate-limit errors rather than silently succeeding. This is substantial behavioral context.

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 core purpose and usage are front-loaded and each sentence serves a distinct function. The final sentence is somewhat generic boilerplate, but the overall description remains compact.

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 moderate-complexity create tool with no output schema, the description covers lifecycle state, permissions, error behavior, and alternative-tool usage. The schema handles parameter details, though the description could have named update_project or clarified namespace_id instead of mentioning absent project_id/group_id.

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 only generic advice about project_id/group_id and pagination fields, which are not present in this input schema, so it does not meaningfully enrich the parameter semantics.

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 'Create a new GitLab project', which names a specific verb, resource, and lifecycle stage. It also explicitly distinguishes this create action from update/edit tools, so it is unambiguous against siblings like update_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 says to use this for a new resource and to choose the corresponding update/edit tool when the resource already exists, providing an explicit when-not condition. It does not name update_project directly, but the alternative is clear from context.

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 flag destructive behavior, and the description adds operationally important context: deletion is permanent, it applies to a remote branch, it requires branch-delete permission, and it can return protected-branch, missing-resource, or permission errors. 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?

Three sentences deliver the core action, safety caveats, permission requirement, and expected results with no filler. The most important warning 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 three-parameter, side-effectful deletion tool, the description covers prerequisites, irreversibility, permissions, and the possible result/error classes without requiring an output schema. 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 description does not need to repeat parameter details. It adds only contextual reassurance about branch confirmation rather than new parameter-level semantics, which matches the baseline for fully covered schemas.

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

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

The description opens with a clear action and target ('Delete branch from project') and later specifies the effect ('permanently removes a remote branch'). It distinguishes delete_branch from get_branch/list_branches/protect_branch rather than merely restating the name.

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 prerequisites ('use get_branch or list_branches before deletion'), a required confirmation step, and a clear exclusion ('never use it to remove branch protection'). The when-to-use guidance 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 only indicate destructiveHint and openWorldHint. The description adds crucial behavioral context: 'may be irreversible,' 'requires the necessary project or group permission,' and 'returns validation, conflict, permission, or rate-limit errors.' This goes beyond what annotations convey, directly informing the agent of risks and error handling.

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 multi-sentence but every sentence carries weight: purpose, safety, usage, and parameter guidance. It's front-loaded with the core action and includes relevant caveats. Slightly verbose due to the combined guidance, but 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 destructive tool with no output schema, the description covers safety, permissions, error types, and parameter usage. It doesn't specify the success response format (e.g., 204 No Content), but that's a minor gap given the other rich context. The description is complete enough for an agent to call it safely and 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 covers all 4 parameters at 100% coverage, so the schema already documents each field. The description adds a general note to 'provide the numeric ID or complete URL-encoded path described by the schema' and 'use required identifiers and pagination fields exactly as documented,' which is helpful but doesn't elaborate beyond the schema. 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 opens with a clear verb+resource ('Delete a draft note') and explicitly contrasts it with get/list tools for inspection. It distinguishes from siblings like update_draft_note and publish_draft_note without needing to name them, 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?

Provides explicit guidance: 'Use this only after verifying the target' and 'choose a get or list tool first when you need to inspect state without changing it.' It also mentions prerequisites (project/group permission) and the irreversible nature, covering both when-to-use and when-not-to-use.

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, the description specifies permanent data removal, the need for delete permission, and the categories of errors that may be returned (missing-resource, permission, policy). This is exactly the kind of behavioral context that annotations alone do not convey, and it does not contradict 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, no filler. The first sentence states the action and the key qualifier; the second provides usage routing and behavioral warnings. Every clause earns its place and the most critical scoping information is front-loaded.

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

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

For a destructive operation with full schema coverage and the key annotation already present, the description covers purpose, when to use, permanence, permission requirement, and possible errors. It does not detail the exact shape of the deletion result, but with no output schema that is not strictly required. Slightly more could be said about the result payload, hence 4 rather than 5.

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 and their descriptions already carry the full semantic load. The tool description adds no extra parameter-specific explanation, so 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 opens with the specific verb-resource pair 'Delete an issue,' and goes further to contrast with `update_issue`, making the tool's scope unmistakable. This clearly distinguishes it from the many issue-related siblings such as `get_issue`, `create_issue`, and `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?

The description gives explicit when-to-use guidance: only after confirming the issue and intended permanent removal. It explicitly names the alternative, `update_issue`, for closing or editing without deletion. This leaves no room for an agent to guess when this tool is appropriate.

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 meaningful behavioral context beyond the destructiveHint annotation: it clarifies the operation may be irreversible, requires the necessary project or group permission, and returns validation, conflict, permission, or rate-limit errors. This is consistent with 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 organized and front-loaded with the purpose, followed by usage guidance and behavior. The final sentence is somewhat boilerplate and repeats schema wording, but the description remains appropriately sized 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 simple delete operation, it covers purpose, when to use, side effects, permission requirements, and error classes. It does not describe the success return value, but the absence of an output schema makes that a minor gap rather than a serious omission.

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 mostly echoes the schema's project_id guidance and adds a general 'pagination fields' clause that is not actually schema-specific, adding little extra 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 opening sentence states a specific verb and resource: 'Remove an emoji reaction from an issue.' It is clearly distinguished from MR reaction tools, though it does not explicitly call out the closely related note-reaction sibling, so a fully explicit sibling differentiation is missing.

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

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

It gives a clear usage condition: 'Use this only after verifying the target' and directs agents to get/list tools when inspection is needed. This is helpful but does not name the specific sibling (e.g., list_issue_emoji_reactions) that would provide the needed award_id.

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

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

While annotations declare destructiveHint and openWorldHint, the description goes further by stating the operation changes issue relationships, requires issue-edit permission, and returns an error when the link is missing or access is denied. These details add meaningful behavioral context 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 sentences, front-loaded with the action, then the verification recommendation, then permission and error behavior. Every sentence carries relevant information and there is no padding.

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 delete operation with no output schema, the description covers the mutation, permission requirement, and error conditions. It also tells the agent how to verify the link exists before deleting. It does not detail the exact response shape, but the 'returns the result or an error' statement is sufficient for an agent to invoke and interpret the 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 parameters are already documented by the schema. The description adds the useful framing that an issue link is a relationship between two issues, but it does not explain individual parameter formats or the link ID lookup beyond naming list_issue_links/get_issue_link. This matches the baseline 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 states a precise verb and resource: 'Delete an issue link' and clarifies it removes 'an existing relationship between two issues.' It distinguishes the tool from siblings like list_issue_links and get_issue_link by explicitly naming them as verification steps, and the destructive intent is 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?

The description gives explicit when-to-use guidance: remove an existing relationship between two issues. It also directs the agent to list_issue_links or get_issue_link to verify the link first, providing a concrete workflow. It does not explicitly contrast with create_issue_link, but the 'remove existing relationship' phrasing makes the usage boundary clear enough.

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 mark destructiveHint, but the description adds irreversibility, permission requirements, and specific error types (validation, conflict, permission, rate-limit), going well beyond the structured data. 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 core action, then provides conditions and warnings in a logical order. It is appropriately sized without redundancy, though slightly longer than strictly necessary.

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 guidance, destructive nature, permissions, errors, and parameter guidance. Lacks return-value details, but that is acceptable for a delete operation without an output schema.

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

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

Schema provides full descriptions for all 6 parameters (100% coverage). The description adds a minor clarification about project_id/group_id formats and pagination, but does not add significant new semantics 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?

States the specific action: removing an emoji reaction from an issue note, and clarifies the discussion_id case. It clearly distinguishes from sibling tools that target merge request notes or issue-level emoji.

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 to verify the target first and use get/list tools for inspection before mutation. Also explains when to pass discussion_id. However, it does not name specific alternative tools for note-level vs issue-level emoji removal, leaving some inference to the agent.

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 mark destructiveHint=true and openWorldHint=true, but the description adds meaningful behavioral context: it changes or removes remote GitLab data, may be irreversible, requires permissions, and may return validation, conflict, permission, or rate-limit errors. This is valuable beyond the annotations and does not contradict them.

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

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

The first sentence is strong and front-loaded, and the safety and error information is useful. However, the final sentence contains redundant boilerplate ('described by the schema', 'exactly as documented') and references pagination fields irrelevant to this tool, making the definition less tight than it should be for a simple delete operation.

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 definition covers purpose, when to use it, destructive scope, irreversibility, permissions, and likely error types. The main gaps are the absence of a success return description (no output schema is present) and the misleading mention of group_id/pagination, which slightly undermines completeness for such a simple 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 baseline is 3. The description mostly restates the schema's project_id guidance ('numeric ID or complete URL-encoded path'), and it mentions group_id and pagination fields that do not exist in this tool's schema, adding confusion rather than concrete parameter 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 opening sentence uses a specific verb and resource: 'Delete a label from a project.' It clearly distinguishes this from read-only siblings and from update_label/create_label by naming the destructive action and stating it operates on a project label.

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 instructs when to avoid using the tool ('only after verifying the target') and directs the agent to get or list tools when inspection is needed. It also frames destructive usage with permission requirements, giving the agent a clear decision boundary.

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 destructiveHint annotation, the description states that the operation 'changes or removes remote GitLab data and may be irreversible,' requiring permissions and returning specific error classes. This adds meaningful context about side effects and failure modes that annotations alone do not convey.

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 purpose in the first sentence and usage guidance in the second. The final sentence contains some generic boilerplate about 'pagination fields' that is not fully relevant to the schema, slightly reducing efficiency.

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 destructive nature and the absence of an output schema, the description covers purpose, usage verification, permissions, irreversibility, and error types. It does not describe success return values, but for a delete operation this is a minor omission amid strong contextual coverage.

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 parameters. The description adds guidance on project_id format but mentions group_id and pagination fields that do not appear in the schema, introducing a slight mismatch. Overall, the description contributes little beyond the schema's existing parameter documentation.

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 'Delete a discussion note on a merge request,' stating a specific verb and resource. This clearly distinguishes the operation from sibling tools like delete_merge_request_note or update_merge_request_discussion_note by narrowing to the discussion-note 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?

The description explicitly instructs to verify the target first and to choose a get or list tool when inspection is needed without changing state. It also names the permission requirement and outlines the error types, giving clear when-to-use and when-not-to-use 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 destructiveHint=true and openWorldHint=true, and the description reinforces that it changes or removes remote GitLab data and may be irreversible. It adds context about permission requirements and possible error responses (validation, conflict, permission, rate-limit), 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 reasonably concise and front-loaded with the core action, then adds usage guidance and parameter notes. It is slightly dense but every sentence adds value; 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 destructive mutation tool with no output schema, the description covers the key context: when to use it, safety caveats, permissions, error types, and identifier handling. It does not detail the return value, but that is less critical for a delete operation and the annotations cover the destructive nature.

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 adds guidance on providing numeric IDs or URL-encoded paths and using required identifiers exactly as documented, but it does not add significant 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 clearly states the action ('Remove an emoji reaction from a merge request') with a specific verb and resource, and it is distinguishable from sibling tools like create_merge_request_emoji_reaction and delete_merge_request_note_emoji_reaction. The target resource (merge request emoji reaction) is unambiguous.

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

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

The description explicitly instructs to verify the target first and suggests using a get or list tool when inspection is needed without changing state. It also notes the required permissions and error types, giving clear context for when to use this tool versus 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 mark this as destructive, and the description adds useful details: it changes or removes remote GitLab data, may be irreversible, requires permissions, and may return validation/conflict/permission/rate-limit errors. 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 appropriately sized and front-loaded with the core action, followed by relevant safety and permission guidance. Each sentence adds value, though the project_id/group_id sentence is slightly more verbose than necessary.

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 destructive tool with four well-documented parameters and no output schema, this description covers the essential operational context: safety, reversibility, permissions, error behavior, and identifier format. A response-format note would be a minor addition but is not required.

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 carries the parameter documentation burden. The description adds minor guidance about project_id/URL-encoded paths and required identifiers, but mostly repeats or references schema content rather than enriching 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: 'Delete an existing merge request note.' It is clearly distinct from create/update note tools, though it does not explicitly name or differentiate itself from the closely related delete_merge_request_discussion_note sibling.

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

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

The description gives concrete usage context: verify the target first, and use a get/list tool instead when inspection is needed without mutation. It does not explicitly enumerate all alternative delete/update tools, but the condition for choosing a read-only tool 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 include destructiveHint=true and openWorldHint=true. The description adds context beyond these: it states the operation 'changes or removes remote GitLab data and may be irreversible,' mentions required permissions, and enumerates possible error types (validation, conflict, permission, rate-limit). This is valuable behavioral information that goes beyond the annotation flags and helps the agent understand consequences and error handling.

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 concise and front-loaded with the core action, followed by usage guidance, risks, and parameter notes. Each sentence adds value, though it is slightly verbose. The structure is logical: action, special case, when-to-use, risk/permission, and parameter format. It is not as tight as the best examples but is not bloated either.

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 the essential aspects for a destructive tool: what it does, when to use it, risks, permissions, and error handling. It does not explicitly describe the success response, but that is often not critical for a delete operation, and the annotations cover safety. The mention of pagination fields is slightly ambiguous for a delete tool, but overall the description is adequate given the schema richness and annotation context.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description does not add significant meaning beyond the schema. It repeats the discussion_id guidance ('Pass discussion_id for discussion thread replies') which the schema already states, and it mentions URL-encoded paths for project_id which is already in the schema. No new parameter semantics are provided beyond what the structured schema offers.

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: 'Remove an emoji reaction from a merge request note.' It uses a specific verb and resource, and distinguishes from sibling tools like delete_merge_request_emoji_reaction by scoping to notes and mentioning discussion_id for thread replies. An agent can immediately understand what this tool does and how it differs from similar delete 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?

The description provides explicit usage guidance: 'Use this only after verifying the target; choose a get or list tool first when you need to inspect state without changing it.' This tells the agent when to avoid this tool and what alternative category to use. It also explains when to pass discussion_id. However, it does not name specific sibling tools (e.g., list_merge_request_note_emoji_reactions) as alternatives, which would be more 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?

Annotations already provide readOnlyHint and openWorldHint, but the description adds critical context: it only changes the session's tool registry, returns an active-tool summary, and does not modify GitLab data. This goes beyond the annotations and fully discloses side effects, so the agent can safely invoke it without concern for persistence.

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 a necessary list of categories. While the category list is long, it is directly relevant for the agent to know valid values. The phrasing is efficient, with no fluff, though it could be slightly tightened by moving the category list to the end.

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 meta-tool with no output schema, the description explains the return (active-tool summary), the session-scoped mutation, and the two-phase usage pattern. All information needed to decide and call the tool correctly is present, including the exact categories and the no-data-change guarantee.

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

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

Schema coverage is 100% and both parameters are well-documented. The description adds value by enumerating all valid category names and explaining the omission behavior for `category`, which is not in the schema. It also clarifies the optional JMESPath filtering role implicitly by context, though the schema already covers it.

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

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

The description clearly states the tool discovers and activates tool categories, lists the exact available categories, and explains its meta-purpose of managing the session's tool registry. It distinguishes itself from sibling tools by being the only one that modifies the available toolset, not operating on GitLab data.

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: when a needed opt-in category is not exposed, and gives a two-step workflow: omit `category` to inspect, then call with a category to activate. It also clarifies session-scoped behavior and that it does not alter GitLab data, leaving no ambiguity about 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?

It discloses behavior beyond the readOnlyHint annotation: read-only with respect to GitLab, remote mode returning base64 for images or a download URL, local mode saving to a path, and possible attachment/permission errors. This gives the agent a clear model of side effects and output. 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 tightly written sentences front-load the core purpose and key mode hint, then add behavioral and error context. No redundant filler; every clause contributes useful 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 tool with no output schema, the description covers return format, modes, save behavior, read-only guarantee, and error cases. The main minor gap is that the mapping from 'remote mode' vs 'local mode' to specific parameters is implicit rather than explicit, though local_path makes this reasonably clear.

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 explains all parameters. The description adds value by clarifying local_path's role and the mode-based behavior, but it does not add meaningful detail about secret, filename, project_id, or jmespath beyond what the schema provides.

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

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

The description uses a specific verb and resource: 'Download an uploaded file from a project' and 'retrieve a previously uploaded project attachment'. It clearly identifies the tool's function and differentiates it from file/content-related siblings like get_file_contents or push_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?

The description explicitly states when to use it ('Use this to retrieve a previously uploaded project attachment'), describes the two modes, and notes the access prerequisite ('requires project access'). It does not name exclusions or alternatives, but there is no obvious sibling for attachment retrieval, so the guidance is sufficient.

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 most behavioral disclosure. It discloses the side effect (creates a new project), a permission prerequisite (fork permission), and the possible return/error outcomes (forked project or namespace/permission error). It does not explicitly say the original project is untouched, but 'copy' implies this and the key behavioral facts are present.

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, no filler; the core action and destination are front-loaded, followed by alternatives and behavioral notes. Every sentence contributes useful 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 tool with only one required parameter and no output schema, the description covers the operation, destination, permission requirement, and likely error cases. It could add more on idempotency or output details, but it is sufficient for correct invocation in most cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by clarifying that `namespace` defaults to the current user's namespace and must be permitted, and that `project_id` refers to an existing project to be copied. This goes beyond the raw schema entries.

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 ('fork a project'), the resource ('existing project'), and the destination ('your account or specified namespace'). It also names the siblings it is not (`search_repositories`, `get_project`) for inspection without copying, so an agent can disambiguate.

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

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

It gives an explicit when-to-use ('Use this to create a copy...') and names alternative tools for inspection (`search_repositories` or `get_project`). This directly tells an agent how to choose this tool over related siblings.

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

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

Annotations 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 mark readOnlyHint=true, but the description adds concrete detail: 'It is read-only and does not mutate GitLab data' and enumerates error conditions like missing resources, invalid identifiers, insufficient permission, and rate limits. This goes beyond the annotations and gives the agent actionable expectations.

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 usage guidance, safety, and parameter notes in a logical order. Every sentence contributes useful information, though the final sentence about path encoding and pagination is slightly generic and could be trimmed without losing much.

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 simple read-only nature, the annotations, and the fully documented schema, the description covers the main use case, alternatives, error behavior, and parameter handling. It doesn't describe the output format, but no output schema exists and the diff structure is likely evident from the tool name. Overall it is sufficient for an agent 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?

Schema coverage is 100%, so the schema already explains each parameter. The description adds value by specifying that project_id should be a numeric ID or complete URL-encoded path and by reminding the agent to use required identifiers and pagination fields exactly as documented. It doesn't deeply elaborate each parameter, but it supplements the schema meaningfully.

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 diffs between two branches or commits.' It also distinguishes itself from discovery tools by stating it is for a known resource or result, which separates it from siblings like list_merge_request_diffs and 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?

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'). This gives clear routing guidance without needing to infer context.

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 read-only claim is redundant, but the description adds valuable behavioral context: missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors. This goes beyond the annotations and is useful for an agent deciding whether to call the tool or 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?

The first two sentences are concise and high-value, but the final sentence is generic boilerplate that references nonexistent parameters and does not earn its place. The description would be stronger if it ended after the error-handling sentence or corrected the parameter guidance.

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 single-resource retrieval tool with 100% schema coverage, the description is largely complete: it explains scope, alternatives, error behavior, and safety. The main gap is the stale parameter note, which slightly undermines the otherwise solid context. An output schema is absent, but the description at least names the returned content (versions and components).

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds misleading guidance: it references `project_id` or `group_id`, which do not exist in the schema (the schema uses `id` and `full_path`). The instruction to 'use required identifiers and pagination fields' is also vague and not backed by the schema, which has no required parameters. The description does not clarify the actual id/full_path trade-off beyond what the schema already states.

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

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

The description states a specific verb and resource: 'Get details for a GitLab CI/CD Catalog resource, including versions and components.' It also explicitly distinguishes itself from list/search discovery tools by saying to use those when discovering multiple resources. This clearly differentiates it from the sibling list_ci_catalog_resources.

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 when-to-use guidance: 'Use this for a known resource or result; choose the corresponding list or search tool when you need to discover multiple resources.' This names the condition and points to an alternative, leaving little inference for the agent.

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 mark readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context beyond that: it is read-only, does not mutate GitLab data, and documents that 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.