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

The annotation openWorldHint: true is non-standard and gives the agent little safety information, so the description carries the full burden for this state-changing operation. It discloses that review state is mutated, that auth/permission may be required, and that either an updated result or a permission/state error is returned — meaningful behavioral context beyond the generic annotation. Slight deduction for not addressing idempotency or double-approval behavior, but this is well above the minimum viable bar.

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 their place: the first states the core action, the second handles scope and sibling differentiation, and the third covers side effects, permissions, and return behavior. Front-loaded and free of redundancy. This is textbook economical writing.

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 mutation with 4 documented parameters and no output schema, the description discloses the critical operational aspects: what it doesn't do, what state it changes, what permissions matter, and what the caller can expect in return. The lack of an output schema raises the burden, and the description meets it by noting the return value. Could have added error taxonomy (e.g., not-found vs. already-approved cases), but nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters (project_id, merge_request_iid, sha, approval_password). The description makes a passing connection to the permission semantics of the approval_password parameter, but adds no genuinely new parameter-level information. Baseline of 3 is correct since the schema does the heavy lifting.

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

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

Uses a specific verb and resource ('record an approval on an existing merge request') and explicitly declares what it does NOT do ('does not merge the request or change its source branch'). This directly differentiates it from the sibling merge_merge_request, letting an agent route correctly without opening either schema.

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

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

Provides clear context on when this is appropriate by contrasting with merging, and warns about preconditions ('may require re-authentication or approval permission'). It stops short of naming the exact sibling (merge_merge_request) to delegate to, so the alternative is implied rather than explicit.

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

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

States that it mutates remote GitLab state, requires project/group permission, and that GitLab returns validation, conflict, permission, and rate-limit errors rather than silently proceeding. This is genuinely useful operational guidance. Annotations add limited behavioral detail, so the description does real work here, though it stops short of describing the success response shape.

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

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

Front-loaded with the core action, but the middle sections repeat boilerplate ('for the specific operation described', 'exactly as documented') that could be cut without losing information. Adequately organized, mildly padded.

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

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

Covers the core action, optional fields, version constraints, permission, and error behavior. It doesn't clarify which identifier must be real vs. which scope (project_id vs group_id) is expected when both are accepted, and it stops short of describing the success response. Given mutation semantics and no output schema, these are moderate gaps, but the core call is well-constrained.

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 the GitLab 19.2+ version gates for note/internal/reviewer_state fields, which is value beyond the enum descriptions)Skip: the numeric-ID-vs-URL-path line only restates what the schema already says, so it contributes nothing.

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?

Action and resource are explicit: publishes draft notes for a merge request, with optional reviewer_state and internal note. The phrase 'choose a sibling tool' is generic, not a real discriminator, so it doesn't fully pin down when this tool differs from publish_draft_note — but the core operation is unmistakable.

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

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

The guidance 'choose a sibling tool when you need a different resource or lifecycle action' is generic filler applicable to literally every tool in the catalog; it names no specific sibling. It does add useful version gating (GitLab 19.2+ for note/reviewer_state) and permission requirements, but the routing advice carries no concrete signal.

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 operation changes remote state and requires branch-creation permission, and lists possible errors. However, the readOnlyHint is not present in annotations; the openWorldHint doesn't contradict anything. The description adds behavioral context beyond annotations, but doesn't detail side effects beyond errors. With minimal annotations, it could do slightly more, but it does mention mutation and permission requirements.

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, information-dense, front-loaded with purpose and usage. The parameter details are appended at the end but do not bloat. Slight redundancy with schema descriptions for parameters, but overall 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?

Given 3 simple parameters, full schema coverage, and no output schema, the description covers purpose, usage alternatives, side effects, permissions, and errors. It lacks explicit mention of return value format, but error list and typical behavior suffice. No output schema means some return detail might be useful, but is not critical.

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 documents all three parameters. The description adds minimal extra meaning: it explains that project_id accepts numeric ID or URL-encoded path, branch is the new name, and ref selects the starting revision. This matches schema descriptions, so adds small value but does not exceed baseline.

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

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

States a specific verb (create) and resource (branch) and distinguishes from siblings by naming alternatives and noting branch creation is distinct from inspecting or protecting. Clearly identifies the operation's scope.

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

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

Explicitly says when to use and provides alternatives: use get_branch or list_branches to inspect, protect_branch for protection afterward. Also implies when not to use (for inspection). Provides clear 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 only carry openWorldHint=true, which is minimal. The description adds meaningful behavior details: it changes remote GitLab state, requires permissions, and GitLab returns specific validation/conflict/permission/rate-limit errors rather than silently applying invalid requests. It also notes identifier encoding requirements. 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 a single dense block of four sentences, front-loaded with the core action. It's moderately concise but packs a lot of guidance into one paragraph. Could be slightly tighter, but every sentence contributes meaningful routing or behavioral info.

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 10 params (3 required), no output schema, and only openWorldHint annotation, the description covers mutation behavior, error handling, permission needs, and identifier formatting. It doesn't mention return values but that's minor for a state-changing tool. It's reasonably complete for the tool's complexity.

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

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

Schema describes all 10 parameters with detailed descriptions (100% coverage), so the bar is lower. Still, the description adds useful guidance on project_id/group_id formats and the name/context alias relationship, which supplements the schema. It could go deeper on state values, but the enum handles that.

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 clear action ('Create or update the status of a commit') with a specific resource ('commit status'), and explicitly contrasts with update/edit tools. It distinguishes from the sibling list_commit_statuses by its mutation-focused wording.

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

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

It explicitly says 'Use this for a new resource or action; choose the corresponding update or edit tool when the resource already exists.' This provides both when-to-use and when-not-to-use guidance, plus a mention of required permissions and covered error cases.

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 include openWorldHint, so the description carries most of the behavioral disclosure burden. It clearly states that this tool changes remote GitLab state, requires project or group permissions, and surfaces validation, conflict, permission, or rate-limit errors instead of silently applying invalid requests. This is useful beyond the structured annotation data, though it doesn't clarify the draft note's unpublished/pending state and its relationship to publishing workflows.

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 relatively short and contains only a few sentences, but the final sentence is verbose and introduces references to 'group_id' and 'pagination fields' that are not immediately relevant to this schema. It front-loads the main purpose well, but some content could be tightened for clarity.

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 permissions, state mutation, and common error behavior, which is helpful given that no output schema exists. However, for a complex tool with a nested position object, it does not explain the conceptual difference between a draft note and a published merge request note, nor how this tool fits with publish_draft_note and list_draft_notes. It is sufficient for a basic create attempt but incomplete for an agent deciding whether to use this or a sibling tool.

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

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

The input schema covers 100% of parameters and already provides detailed descriptions, including strong guidance for nested fields like line_range and line_code. The description only adds a generic instruction about providing numeric IDs or URL-encoded paths, which mostly repeats the schema's project_id description. It does not add meaningful semantics for the other parameters.

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

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

The description clearly states that this tool creates a draft note for a merge request and explicitly contrasts it with update or edit tools for existing resources. However, it does not differentiate from sibling creation tools like create_merge_request_note or create_merge_request_discussion_note, relying mainly on the word 'draft' in the tool 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?

The description provides a direct usage rule: use this for new resources/actions and switch to an update or edit tool when the resource already exists. It also notes that the operation changes remote GitLab state and requires permissions, but it does not give guidance on when a regular merge request note or a published note would be more appropriate than a draft.

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=true, so the description carries the burden. It discloses that the tool changes remote state, requires permissions, and returns errors instead of silently failing—valuable context beyond the annotation. Lacks detail on partial success or atomicity, but sufficient.

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 moderately long but each sentence adds value: purpose, usage differentiation, behavior, and parameter tips. It is front-loaded with the core purpose and does not waste words.

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 creation tool with 5 parameters, no output schema, and minimal annotations, the description covers purpose, usage, behavior, and parameter guidance. It doesn't mention return value, but that's not required without an output schema. Adequate for an agent to call 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% with descriptions for all parameters. The description's parameter guidance (numeric ID or URL-encoded path) is generic and references project_id/group_id not present in the schema. Adds little beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Clearly states 'Create new group or subgroup' with a specific verb and resource, and differentiates from update/edit tools by explicitly noting when to use them instead. This distinguishes it from sibling create tools like create_issue or create_repository, which are for different 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?

Provides explicit guidance: use for new resources, choose update/edit for existing ones. Also mentions permission requirements and error behavior, giving clear context on when and how to invoke it. 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?

Annotations are sparse (only `openWorldHint`), so the description carries the burden. It states that the operation 'creates remote project data', requires permission, and lists error types (validation, permission, duplicate-related). This goes beyond what the schema or annotations reveal, giving the agent realistic expectations. It could mention reversibility or idempotency, but for a create operation, this is sufficient 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 description is two sentences, front-loaded with the purpose ('Create a new issue.'), followed by usage guidance and behavioral notes. Every word earns its place; no filler. The structure makes it easy to scan and act on.

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 (8 params, all schema-documented) and absence of an output schema, the description covers what an agent needs: the action, when to use it (vs. alternatives), a permission prerequisite, and the possible error modes. There is no missing piece that would prevent 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 fully documents all 8 parameters. The description adds no extra parameter-level detail, which matches the baseline of 3. It does not reference any parameter by name, so it provides no additional 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 opens with the crisp statement 'Create a new issue.' and immediately differentiates it from `update_issue` and `create_issue_note` by naming them. The verb-resource pair is exact, and the sibling contrast removes any ambiguity about which tool does what.

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

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

It explicitly says 'Use this to open a new issue; use `update_issue` for an existing issue and `create_issue_note` to add discussion without changing issue fields.' This is a clear when-to-use with named alternatives and the condition that selects each. No inference is required.

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

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

Annotations only include openWorldHint: true, which is sparse. The description compensates by disclosing that it changes remote GitLab state, requires permissions, and returns errors instead of silently applying invalid requests. This adds value beyond annotations. However, it doesn't detail side effects like duplicate reactions or rate limits specifics, but it mentions rate-limit errors. With minimal annotation, 3 is fair.

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 moderately sized but packs useful guidance: usage context, permissions, error behavior, and identifier handling. It front-loads the purpose and usage instruction. Could be slightly more concise but each sentence contributes 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 complexity (3 params, all required, no output schema), the description covers usage, permissions, error cases, and parameter details. It lacks explicit examples beyond emoji names and doesn't mention pagination (not applicable here). The sibling list shows many similar emoji tools, but the description helps distinguish by saying 'new resource' vs 'update/edit'. Overall complete for safe invocation.

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

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

Schema description coverage is 100%, so all three parameters (name, issue_iid, project_id) are documented in the schema. The description adds clarity for name ('e.g. thumbsup') and project_id ('numeric ID or complete URL-encoded path'), but that is already in the schema. It emphasizes providing identifiers as documented, which is marginal. Baseline is 3 because schema does the heavy lifting.

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

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

Description clearly states the action: add an emoji reaction to an issue, with verb 'Add' and specific resource 'emoji reaction to an issue'. It explicitly differentiates from siblings by contrasting with 'create' versus 'update/edit' tools, especially emoji-related tools like list_issue_emoji_reactions and delete_issue_emoji_reaction.

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

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

The description explicitly says when to use this tool: 'Use this for a new resource or action; choose the corresponding update or edit tool when the resource already exists'. It gives context about permission requirements and error handling, but does not explicitly name sibling alternatives or provide exclusions for other create tools like create_merge_request_emoji_reaction. Still 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?

Discloses that the operation changes remote GitLab state, requires specific permissions, and returns validation/conflict/permission/rate-limit errors rather than silently failing. This goes beyond the openWorldHint annotation and gives agents a realistic expectation of 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 concise and front-loads the core purpose. It includes useful side-effect and error information, but the final sentence about group_id and pagination fields is extraneous and slightly repetitive, reducing overall focus.

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 needn't explain return values. It covers side effects, permissions, errors, and usage guidance, which is sufficient for a create operation. It omits edge cases (e.g., self-linking) but these are not critical for basic 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?

The input schema already provides descriptions for all five parameters (e.g., project_id as 'Project ID or URL-encoded path'), so schema coverage is 100%. The description adds minimal extra meaning, mostly a generic note about providing numeric IDs and pagination, which is redundant with the schema and includes an irrelevant mention of group_id.

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

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

Clearly states it creates an issue link between two issues, a specific verb and resource. Distinguishes from siblings like list_issue_links, get_issue_link, and delete_issue_link, and explicitly instructs to use update tools when the resource already exists.

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 clear when-to-use guidance for new resources, and indicates using update/edit tools for existing ones. Mentions permission requirements and error behavior, but does not name a specific update tool (there is no update_issue_link sibling), and the generic instruction about pagination fields is not applicable here.

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

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

The description discloses that the operation creates remote discussion content, requires note permission, and returns either the note or specific missing-issue/thread/permission errors. Since annotations only include `openWorldHint: true`, this behavioral detail adds meaningful transparency beyond structured data.

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 at three sentences and front-loads the core purpose, but the second sentence partially repeats the first ('Add a note to an issue' vs 'add a note to an existing issue'). Minor redundancy keeps it from being maximally 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?

For a straightforward 5-parameter create operation with no output schema, the description covers the operation's effect, permission requirement, error returns, and alternatives. It does not elaborate on `created_at` behavior, but the schema already describes the parameter.

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 parameters clearly. The description adds semantic value by tying `discussion_id` to the optional-reply behavior and clarifying the topic of notes versus generic notes, which enriches parameter understanding without repeating 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 verb-resource pair: 'Add a note to an issue,' with an important qualifier, 'optionally replying to a discussion thread.' It distinguishes itself from nearby siblings by explicitly calling out `update_issue` for issue fields and `create_note` for the generic endpoint.

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 when-to-use guidance and names alternatives: use this for notes on issues, use `update_issue` for issue fields, and use `create_note` only when the generic endpoint is required. This is clear and actionable 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?

The description transparently notes that the operation changes remote GitLab state and requires appropriate permissions. It also mentions that errors like validation or rate-limit are returned rather than silent failures. This goes beyond the sparse 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 overly verbose with boilerplate about 'use required identifiers and pagination fields exactly as documented,' which is irrelevant since there are no pagination fields. The key purpose is stated first, but the rest contains filler that reduces conciseness.

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

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

It covers the essential aspects: purpose, usage nuance, state change, permissions, and error handling. However, it omits details about the response format and includes irrelevant pagination advice. Given the schema's completeness, the description is adequate but not exhaustive.

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 each parameter in detail (e.g., emoji name without colons, IDs). The description only restates the discussion_id condition already present in the schema, adding little new meaning. It also includes generic advice about providing IDs that duplicates 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 tool's function: adding an emoji reaction to an issue note. It also clarifies the nuance about discussion_id for thread replies, 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?

It provides basic usage guidance, such as using this tool for new reactions and preferring an update tool for existing ones. It also explains when to include discussion_id, which aids in correct invocation. However, it doesn't explicitly distinguish from sibling tools like listing or deleting reactions, but the primary use case is evident.

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 annotations present (openWorldHint: true), the description goes beyond by noting that it changes remote GitLab state, requires permissions, and returns specific error types instead of silently applying invalid requests. This is useful context. It does not mention idempotency or reversibility, but given the annotation, the bar is lower. The description adds value.

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

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

The description is a single paragraph but covers multiple aspects: purpose, usage distinction, permissions, errors, and ID handling. It is not overly long, but the sentence structure could be tighter. It front-loads the purpose and usage distinction, which is good. Slight redundancy in mentioning permissions and errors twice, but overall concise enough.

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 create operation with 5 parameters, 100% schema coverage, and no output schema, the description adequately covers purpose, usage, permissions, and error behavior. It does not explain the return value, but since there is no output schema, that is expected. It also does not list prerequisites like existing project existence, but that is implicit. Overall, it is complete for an agent to call this correctly.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description adds guidance on how to format project_id (numeric ID or URL-encoded path) and emphasizes using exactly as documented for identifiers and pagination fields, but it doesn't add new semantic details 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 states the verb 'Create', the resource 'label', and the container 'project', which is clear. It distinguishes from update/edit tools by indicating when to use the create version. It could be slightly sharper about whether group labels are supported (the description mentions group permission, but the schema only has project_id), but overall the purpose 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 explicitly says to use this for a new resource and to choose the update/edit tool when the resource already exists. It also mentions permissions and errors, and provides guidance on how to provide identifiers. However, it does not elaborate on when to use a group path versus a project ID, despite mentioning group permission. This is a minor gap.

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

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

The description discloses meaningful behavioral context beyond the sparse `openWorldHint` annotation: it creates remote review state, requires project access, and returns either the new merge request or a validation/permission/branch/duplicate-related error. It does not go into exhaustive detail like reversibility or rate limits, but it gives an agent a clear picture of the operation's 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 compact and front-loaded: purpose, usage, then behavioral notes. Every sentence earns its place, and the most decision-relevant information—what the tool does and when to use it—appears first.

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

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

Given the tool's 13 parameters and no output schema, the description provides sufficient context: what the tool does, when to use it, required access, and likely error categories. It does not detail the response structure beyond 'returns the new merge request', but that is still enough for an agent to understand the primary outcome. Minor gaps like exact permission scopes and response fields prevent a perfect score.

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 well. The description adds only a small amount of semantic framing around branches ('existing source branch' and 'target branch'), but it does not meaningfully improve on the property descriptions already present in the input 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 verb and resource: 'Create a new merge request' and specifies the exact operation scope: opening a merge request from an existing source branch to a target branch. It also explicitly differentiates from the sibling `update_merge_request`, so an agent can distinguish it from related tools.

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

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

It gives direct usage guidance: use this tool to open a new merge request, and use `update_merge_request` after the request exists. This explicit when-to-use and when-to-use-alternative guidance leaves little room for confusion.

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 a minimal `openWorldHint` annotation, the description carries the burden of disclosing side effects. It explicitly states that the operation 'creates remote review content', requires note permission, and can return errors for missing discussion/position/permission. This goes beyond a simple 'creates a note' by specifying permission and failure modes. A slight gap is the lack of mention of reversibility or notification side effects, but the core mutation behavior is clear.

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 extraneous words. It front-loads the core action, then provides sibling differentiation and side-effect/error information. Every sentence earns its place, and the structure is 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?

Given the tool's moderate complexity (5 params, all required ones documented), the description covers the essential aspects: what it does, when to use it, permission requirements, and return/error behavior. It does not have an output schema, so mentioning the return value is helpful. It could arguably include more about the `created_at` parameter, but the schema covers that. Overall, an agent has enough context 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 description coverage is 100%, so all parameters have descriptive text. The description does not add extra meaning beyond the schema, such as explaining the relationship between discussion_id and merge_request_iid. However, since the schema already covers parameter semantics, a baseline of 3 is appropriate—the description simply doesn't need to repeat 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 action ('Add a new discussion note to an existing merge request thread') and differentiates it from siblings by explicitly naming `create_merge_request_thread` and `create_merge_request_note` with their distinct purposes. This removes any ambiguity about which tool to use.

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 when-to-use and when-not-to-use guidance by stating 'Use this to reply inside an existing merge request discussion' and contrasting it with starting a new thread or a top-level note. It also mentions permission requirements and possible errors, giving the agent a clear decision frame.

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, which is a minimal signal. The description compensates strongly by stating 'It changes remote GitLab state', requiring permissions, and listing possible error types (validation, conflict, permission, rate-limit). This discloses side effects and failure modes beyond what annotations convey. 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 longer than typical but every sentence adds value: purpose, usage, behavior, error handling, and parameter guidance. It is front-loaded with the core action and example. Slightly verbose in the final sentence about pagination, which isn't relevant to this tool, but overall it is well-structured and not redundant.

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 simplicity (3 params, no output schema), the description covers all necessary aspects: purpose, usage distinctions, side effects, permissions, error behavior, and parameter format. An agent has everything needed to call this tool correctly without further inference. The mention of pagination is a minor irrelevant addition, but completeness is high.

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% (all 3 parameters have descriptions). The description adds context on how to supply project_id ('numeric ID or complete URL-encoded path') and emphasizes using required identifiers exactly as documented. While schema already covers parameter meaning, the description reinforces format nuances, providing marginal added value above baseline.

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

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

The description states a specific verb ('Add an emoji reaction') and resource ('merge request') with concrete examples ('thumbsup, rocket, eyes'). It clearly distinguishes from related tools by noting when to use update/edit tools instead, so an agent can differentiate it from siblings like create_merge_request_note_emoji_reaction or update_merge_request without needing to inspect schemas.

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

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

The description explicitly provides usage context: 'Use this for a new resource or action; choose the corresponding update or edit tool when the resource already exists.' It also mentions permission requirements and error behavior, giving clear guidance on when and how to invoke this tool versus alternatives. No ambiguity remains.

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 several important behavioral aspects that go beyond the single annotation `openWorldHint: true`. It notes that the operation 'changes remote GitLab state', which implies it is not a read-only operation, and it warns that GitLab returns validation, conflict, permission, or rate-limit errors instead of silently applying an invalid request. It also mentions required permissions ('requires the necessary project or group permission'). The annotation `openWorldHint` is vague, but the description adds concrete behavioral transparency about state change and error handling. There is no contradiction; the description does not contradict 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 a single paragraph of moderate length, but it is dense with useful information. It front-loads the primary purpose ('Add a new note to a merge request') and then provides usage, behavior, and parameter guidance. There is no redundancy; every sentence contributes to the agent's understanding. It loses one point because it is not as tightly structured as a two-sentence description could be, and it mixes several pieces of guidance in one run-on sentence, but it remains 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?

Given that the tool has only three parameters, all required, with 100% schema coverage, and no output schema, the description covers the essential usage, behavior, and parameter directives. It does not explicitly state the return value (e.g., the created note object), but since there is no output schema, the description could have mentioned that it returns the note, but it does not. However, the description is sufficient for an agent to call the tool correctly: it knows what it does, when to use it, what parameters to provide, and what errors to expect. The lack of return-type disclosure is a minor gap, but the overall completeness is high.

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 description adds meaningful parameter guidance beyond the schema. For `project_id` and `group_id`, it explicitly instructs to 'provide the numeric ID or complete URL-encoded path described by the schema', which reinforces the schema but adds usage nuance. It also says 'use required identifiers and pagination fields exactly as documented,' adding a caution. However, the description doesn't explain the meaning of each parameter beyond what the schema already says (e.g., `body` is the content, `merge_request_iid` is the IID). Given that schema coverage is 100%, the description supplements it with usage directives, so a score of 4 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 verb ('Add') and resource ('new note to a merge request'), which distinguishes it from update/edit tools that modify an existing resource. It also explicitly names its sibling purpose by pointing to the 'update or edit tool when the resource already exists.' However, the distinction from `create_merge_request_note` versus `create_merge_request_discussion_note` or `create_draft_note` is not directly addressed, though the 'new note' language and the mention of `merge_request_iid` suggest a direct note rather than a thread or draft.

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 when-to-use guidance: 'Use this for a new resource or action; choose the corresponding update or edit tool when the resource already exists.' This clearly routes the agent away from update scenarios, but it does not explicitly list alternative tools (like `create_merge_request_discussion_note` or `create_draft_note`) where a note might also be created. The guidance is clear but not exhaustive regarding sibling alternatives, so it earns a 4 rather than a 5.

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

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

Annotations only include openWorldHint: true, which indicates the tool may have side effects. The description goes beyond this by stating 'It changes remote GitLab state and requires the necessary project or group permission' and that GitLab returns errors for invalid requests. This adds useful context about side effects and error behavior, but it does not detail specific error types or rate limits, and the description does not contradict annotations, so a 3 is appropriate.

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 single paragraph of about 3 sentences. It is focused and avoids fluff. The key purpose is front-loaded. However, it packs a lot of information into a long first sentence that could be broken up for readability, so it's a 4 rather than a 5.

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

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

The description covers the core purpose, usage context, permission requirements, and error behavior. It also mentions discussion_id handling and identifier formats. However, it lacks details on what the response looks like (though no output schema is provided) and how the tool behaves regarding idempotency or rate limits. Given the complexity of the GitLab API, a bit more detail would improve completeness, so it's a 3.

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 has 100% coverage for all 5 parameters, so the schema already documents each parameter. The description adds some context about using discussion_id for thread replies and mentions using numeric IDs or URL-encoded paths for project_id, but these are already partially in the schema descriptions. Since coverage is high, baseline is 3, and the description provides minimal extra value beyond what the schema says.

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 an emoji reaction to a merge request note', specifying the verb (add), resource (emoji reaction), and target (merge request note). It distinguishes from sibling tools by mentioning discussion_id for thread replies, but there are many closely related sibling tools (create_merge_request_emoji_reaction) that are not explicitly differentiated, so it loses a point.

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 guidance on when to use this tool: 'Use this for a new resource or action; choose the corresponding update or edit tool when the resource already exists.' It also mentions the need for discussion_id for thread replies and correct identifiers. However, it does not explicitly name alternative sibling tools or list conditions for when not to use it, so it's a 4 not a 5.

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

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

The annotations only provide `openWorldHint: true`, so the description carries the burden of behavioral disclosure. It states that the operation creates remote review content, requires note permission, and returns the discussion or a position/permission/validation error. This gives useful side-effect and failure-mode context, though it does not cover details like idempotency or rate limits.

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

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

The description is three sentences with no filler: purpose first, sibling routing second, and behavioral disclosure third. Every sentence earns its place and the structure supports quick scanning by an agent.

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 tool has a complex nested `position` schema and no output schema, so the description reasonably covers the action, permission requirement, and return/error behavior. A minor gap is that it does not mention that `position` is optional for MR-level discussions, though this is inferable from the required field list 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 description coverage is 100%, so the schema fully documents the parameters, including the nested `position` object. The description adds no per-parameter meaning beyond what the schema already provides, which is acceptable at the baseline for full 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 clearly states a specific action ('Create a new thread') and a specific resource ('on a merge request'). It also differentiates itself from the sibling tools `create_merge_request_note` and `create_merge_request_discussion_note`, so an agent can select it over alternatives without opening the schema.

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

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

The description explicitly says when to use this tool: to start a review thread on a merge request. It also names the sibling tools for the alternative cases — unthreaded notes and replies to existing threads — leaving no ambiguity about routing.

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

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

Annotations only include openWorldHint, which provides no behavioral safety info. The description fills this gap by disclosing that the operation creates remote discussion content, requires note permission, and returns the created note or errors. This is more than typical and covers key behavioral aspects though not exhaustive details like rate limits or reversibility.

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

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

Two sentences, with the core purpose in the first and usage guidance in the second. Nothing extraneous; front-loaded with the key information. Highly efficient and clear.

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 tool with no output schema and minimal annotations, the description covers purpose, usage distinction, permission requirement, and return behavior. It doesn't mention potential side effects or edge cases, but it's sufficiently complete for an agent to use 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 all parameters are already well-described. The description doesn't add significant semantics beyond the schema, but it does hint at the permission requirement and return behavior, which is a minor addition. Baseline of 3 is appropriate when schema carries the load.

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?

Description clearly states the action ('Create a new note (comment)') and specifies the target resources (issue or merge request). It also distinguishes from siblings by naming alternatives for threaded replies, making its scope 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?

Explicitly states when to use this tool (top-level comment) and when not to (threaded replies), naming the two sibling tools that should be used instead. This leaves no ambiguity about selection.

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

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

Beyond the minimal `openWorldHint` annotation, the description discloses the requirement for repository write permission and the possible outcomes ('returns the commit result or a conflict/validation error'). This adds meaningful behavioral context not present in 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 compact and well-structured: it opens with the core functionality, then provides usage guidance, encoding details, and permission/error expectations in a logical order without superfluous text.

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

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

Given the schema richness and the presence of sibling tools, the description covers the essential usage context (single file vs multi-file, permission requirement, error behavior). It does not mention the file move/rename capability via `previous_path`, but that is adequately described in the schema, so the description remains sufficiently complete for effective selection and 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?

The input schema already provides comprehensive descriptions for all parameters (100% coverage), including the encoding default and the purpose of commit_id/last_commit_id. The tool description adds little beyond repeating the encoding default, so it does not significantly enhance parameter understanding.

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

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

The description states a specific verb and resource: 'Create or update a file in a GitLab project.' It also differentiates from the sibling tool `push_files` by explicitly mentioning when to use each, making the purpose unambiguous.

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

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

It clearly instructs when to use this tool versus `push_files': 'Use this for a single repository file... use `push_files` for a multi-file commit.' This provides explicit selection criteria among alternatives.

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

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

Annotations only include openWorldHint, with no readOnly or destructive hints, so the description carries the burden. The description discloses that the tool changes remote GitLab state, requires permissions, and returns validation/conflict/permission/rate-limit errors rather than silently failing. It does not describe the return payload, but no output schema is 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?

The first two sentences are useful and front-loaded with purpose and behavior, but the third sentence is boilerplate referencing nonexistent parameters and pagination. The description is longer than necessary for a create tool whose schema already documents every parameter.

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

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

The description covers what the tool does, when to use it, its side effects, and error handling, which is sufficient given the fully described schema. It omits return format, but since there is no output schema and errors are explicitly addressed, no critical context 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?

Input schema descriptions cover 100% of parameters with clear meanings, so the baseline is 3. The description's third sentence references project_id/group_id and pagination fields that are not in the schema, adding no value and potentially distracting from the actual parameters.

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

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

The description opens with the imperative 'Create a new GitLab project,' clearly stating the verb and resource. It explicitly contrasts with update/edit tools for existing resources, making selection unambiguous among many sibling tools.

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

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

It gives an explicit condition: use this tool for a new resource, and choose the corresponding update or edit tool when the resource already exists. It also states permission requirements and error outcomes, providing clear when-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, so the description extends that by detailing the permanent nature ('permanently removes a remote branch'), the permission requirement ('requires branch-delete permission'), and the possible error cases (protected-branch, missing-resource, or permission error). This adds meaningful context beyond the structured 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 a single, information-dense sentence that front-loads the purpose ('Delete branch from project') and then provides usage and behavioral details. It is somewhat long but every clause earns its place, avoiding redundancy.

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

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

For a destructive tool with no output schema, the description covers the return type (deletion result or errors), permission requirements, and pre-condition checks (confirm branch, use get/list first). Nothing essential is missing 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% with both parameters documented. The description does not add extra semantic detail about the parameters themselves beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete branch from project' with a specific verb and resource. It distinguishes itself from sibling tools like get_branch and list_branches by focusing on deletion, leaving no ambiguity about its 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?

Explicit usage guidance is provided: 'Use this only after confirming the branch name and intended data loss; use get_branch or list_branches before deletion and never use it to remove branch protection.' This gives clear when-to-use and when-not-to-use instructions, naming alternatives directly.

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

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

Annotations already include destructiveHint: true, so the description adds value by stating irreversibility, permission requirements, and specific error responses (validation, conflict, permission, rate-limit). This goes beyond the annotation by detailing consequences and failure modes, though it does not describe effects on related data.

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

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

The description is front-loaded with the core action and then provides necessary warnings and usage context. It is slightly verbose but every sentence adds relevant guidance. It could be trimmed, but it remains efficient and well-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 destructive, irreversible operation, the description covers verification, permissions, error modes, and parameter formatting. There is no output schema, so return values need not be described. All essential guidance for safe and correct invocation is present, making it 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%, so the schema already fully documents all three required parameters. The description adds a redundant note about providing numeric IDs or URL-encoded paths, which is already in the schema. No new meaning beyond the schema is introduced, 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 a clear verb + resource: 'Delete a draft note.' It explicitly distinguishes itself from inspection operations by instructing to 'choose a get or list tool first', which differentiates it from siblings like get_draft_note and list_draft_notes. The purpose is unambiguous and specific.

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 guidance: 'Use this only after verifying the target' and directs to alternative tools for inspection. It also mentions the need for permissions and possible error types, providing a clear context for when and how to use it.

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 include destructiveHint=true, but the description adds crucial context: the operation permanently removes data, requires delete permission, and returns specific error types (missing-resource, permission, policy). This goes beyond annotation-specified safety.

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 (two sentences) and front-loaded with the core action and usage caveat. Every sentence adds value, with no filler or redundancy.

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

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

For a two-parameter destructive operation with a full schema and annotations, the description covers the essential context: permissions, irreversibility, and error handling. No significant gaps remain 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 describes the required parameters. The description does not add extra parameter-level detail, but since the schema handles this, 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 this tool deletes an issue, with a specific verb and resource. It explicitly contrasts with update_issue for closing or editing, making its purpose distinct from the sibling tool.

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

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

The description provides explicit when-to-use guidance: 'Use this only after confirming the issue and intended permanent removal' and clearly says to use update_issue for non-destructive changes. This is ideal for routing the agent to the correct tool.

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

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

The description states that the tool 'changes or removes remote GitLab data and may be irreversible' and that it 'requires the necessary project or group permission' and returns specific error types. This elaborates on the destructiveHint annotation, providing additional context about side effects and error conditions, which exceeds the annotation's minimal hint.

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

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

The description is somewhat lengthy but each sentence serves a purpose: stating the action, advising on pre-verification, describing side effects and permissions, and providing identifier formatting. It is well-structured with the core purpose first, followed by usage caveats. No redundant fluff, though it could be slightly more concise by removing the generic pagination mention.

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 delete operation, the description covers the key aspects: what it does, when to use it (and when not to), side effects, permissions, and potential errors. It does not describe the response format, but no output schema is provided, so that is not required. It is complete enough for an agent to safely decide on and execute the call, though it could have mentioned a success indicator.

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 descriptions cover all parameters (project_id, issue_iid, award_id) and the description echoes the schema's guidance about providing numeric IDs or URL-encoded paths. It adds a generic note about 'pagination fields' which is not relevant here. Since schema coverage is 100% and the description does not significantly enhance parameter meaning beyond the schema, the baseline score of 3 is appropriate.

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

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

The description clearly states the specific action: 'Remove an emoji reaction from an issue.' It distinguishes this from the many sibling emoji tools by explicitly naming the resource (issue) and the operation (delete/remove). The verb and resource are 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 gives explicit guidance on when to use it: '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 to use a read-only tool first if inspection is needed, and also implies it is a destructive action. It further mentions permissions and error types, providing clear usage 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 mark destructiveHint and openWorldHint, so the description adds value by specifying the real-world effect ('changes issue relationships'), the required 'issue-edit permission', and error cases for missing links or denied access. It does not elaborate on reversibility, but deletion is inherently destructive and hinted.

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 tightly written sentences: action and purpose first, verification guidance second, and side effects/permissions/error behavior third. Every clause contributes information, with no filler or repetition.

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 delete operation with no output schema, the description adequately covers purpose, preconditions, verification path, permission requirements, and error scenarios. Nothing essential is missing for an agent to decide whether and how to invoke it.

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

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

Schema description coverage is 100%, and the description adds no parameter-specific semantics beyond what the input schema already provides for project_id, issue_iid, and issue_link_id. 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 the specific verb 'Delete' and resource 'issue link', and clarifies the action as removing an existing relationship between two issues. This clearly distinguishes it from sibling tools like create_issue_link, list_issue_links, and get_issue_link.

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

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

It explicitly states when to use the tool: to remove an existing issue relationship, and it recommends verifying with list_issue_links or get_issue_link first. It stops short of naming the inverse alternative (create_issue_link) explicitly, but the usage context is clear.

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

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

Without annotations, the description would carry the full burden — but here annotations already declare destructiveHint=true and openWorldHint=true. The description adds valuable behavioral context: states the operation 'changes or removes remote GitLab data and may be irreversible', mentions permission requirements ('requires the necessary project or group permission'), and enumerates possible errors ('validation, conflict, permission, or rate-limit errors'). This meaningfully extends the annotations, so a 4 is justified. It doesn't contradict the destructiveHint in any way (annotation_contradiction = false).

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 single dense paragraph with front-loaded purpose. Every sentence adds value: action, usage guardrail, destructive disclosure, error types, and parameter clarifications. Slightly long (one compound sentence with multiple semicolons), but nothing is filler. It could be broken into bullets or separated into two paragraphs for easier scanning, but it remains 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?

Given the tool has a destructive hint, open-world hint, 5 parameters (4 required), and no output schema, the description covers the critical aspects an agent needs: target semantics (issue vs discussion), safety warnings, error types, and identifier formatting. The only minor gap is return value expectations (tool has no output schema, and the description doesn't describe what a successful deletion returns). For a deletion tool where the action is clear, this is a minor omission. Overall complete enough.

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 real value beyond the schema: it clarifies the optional discussion_id ('Pass discussion_id for discussion thread replies'), states that discussion_id is 'Required for notes that are discussion replies; omit for top-level notes' — going beyond the schema's terse wording. It also clarifies the ambiguous project_id ('provide the numeric ID or complete URL-encoded path'). This is a solid improvement over schema-only knowledge, earning a 4.

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 the specific verb-resource pair ('Remove an emoji reaction from an issue note') and names the sibling it is not ('use a get or list tool first...'). It is clearly differentiated from create_issue_note_emoji_reaction and the merge_request variants present in the sibling list. The opening sentence 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 gives clear context: 'Use this only after verifying the target; choose a get or list tool first when you need to inspect state without changing it.' This directs when not to use the tool. However, it doesn't explicitly name a specific sibling alternative tool by name (e.g., 'use list_issue_note_emoji_reactions first'), and doesn't cover when to prefer deletion over other operations. The guidance is clear but a touch generic.

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 and openWorldHint, but the description adds critical context: it 'changes or removes remote GitLab data and may be irreversible,' requires 'the necessary project or group permission,' and 'returns validation, conflict, permission, or rate-limit errors.' This goes beyond the annotations by describing irreversibility, authorization needs, and error types, which helps the agent 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 three sentences long, front-loaded with the core purpose and safety caution. The second sentence packs usage and behavioral guidance into one clause, and the third gives parameter instructions. It is reasonably concise, though the final sentence's generic 'use required identifiers and pagination fields exactly as documented' is slightly redundant and could be trimmed 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 destructive tool with no output schema, the description covers the essential aspects: purpose, when to use, behavioral consequences (irreversibility, permissions, errors), and parameter guidance. It does not describe return values, but none are specified, and the description adequately prepares the agent to call the tool safely. A minor omission is not specifying that the label must exist, but that is implicit in deletion operations.

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% for both required parameters, so the schema already explains project_id and label_id. The description's advice to 'provide the numeric ID or complete URL-encoded path described by the schema' repeats this information without adding new meaning. It also mentions 'project_id or group_id' even though group_id is not in the schema, slightly muddying parameter semantics. Overall, it adds little beyond the schema, justifying a baseline score 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 clearly states the action ('Delete a label from a project') with a specific verb and resource. It distinguishes from sibling tools like list_labels, get_label, create_label, and update_label by focusing exclusively on deletion and explicitly instructing to use get/list tools first for inspection. This makes the tool's purpose 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 provides explicit when-to-use 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 directly contrasts with inspection tools and sets a clear precondition. It also mentions permission requirements, giving further practical context for when it is appropriate to invoke.

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?

Although destructiveHint is already true, the description adds valuable context: remote GitLab data may be changed or removed, the action may be irreversible, permissions are required, and specific error classes such as validation, conflict, permission, and rate-limit errors may be returned. This goes well beyond the annotations without contradicting 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 description is front-loaded with the primary purpose and keeps safety guidance compact. The only slight weakness is the generic 'project_id or group_id' phrasing, since group_id is not present in this tool's schema, making that part mildly extraneous.

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 four-parameter operation with no output schema, the description covers usage timing, irreversibility, permissions, error behavior, and identifier formatting. It does not explicitly describe success behavior or distinguish itself from other note-deletion siblings, but it is otherwise well-rounded.

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

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

Schema description coverage is 100%, so the schema already documents all four required parameters. The description adds only generic guidance about numeric IDs, URL-encoded paths, and exact identifier usage, which is helpful but does not add parameter-specific 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 opens with a direct, specific statement: 'Delete a discussion note on a merge request.' This clearly identifies the verb, resource, and scope. It also distinguishes this from related sibling note tools by naming the 'discussion note' target.

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 guidance to verify the target first and to use a get or list tool when inspection is needed rather than changing state. It could name specific sibling alternatives, but the general 'get or list' routing is clear and actionable.

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

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

Annotations provide only destructiveHint and openWorldHint. The description goes well beyond: it warns that remote GitLab data 'may be irreversible,' states the permission requirement, and enumerates possible error classes (validation, conflict, permission, rate-limit). This is genuinely useful behavioral context consistent with the destructive 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 sentence order is effective: purpose, then usage guardrail, then destructive-safety and error context, then parameter reminder. While the final sentence is a bit boilerplate-heavy, every section earns its place and the core message 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 tool with three fully documented parameters and no output schema, the description covers safety, permission prerequisites, and error behavior. The only real gap is the absence of a statement about what a successful response looks like.

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 project_id, merge_request_iid, and award_id; the baseline is 3. The description's instruction about numeric IDs or URL-encoded paths mostly duplicates the schema's own text, and its mention of 'group_id' and 'pagination fields' does not match this tool's actual parameters. The added semantic value is minimal.

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

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

The description opens with a specific verb-resource pair: 'Remove an emoji reaction from a merge request.' This clearly differentiates it from siblings like delete_merge_request_note_emoji_reaction and the create/list emoji reaction variants. The purpose is precise and immediately recognizable.

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

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

It explicitly states when to use the tool ('only after verifying the target') and instructs the agent to 'choose a get or list tool first' when needing to inspect state. This provides a clear when/when-not split, though it does not name a specific sibling such as list_merge_request_emoji_reactions as the verification tool.

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

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

Annotations already include destructiveHint and openWorldHint, but the description adds valuable context: dangerous irreversibility ('may be irreversible'), permission requirements, and specific error types (validation, conflict, permission, rate-limit). This goes beyond the simple destructive flag and helps the agent set 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, followed by caution and usage rules. It is free of fluff, and every sentence earns its place by conveying essential operational or safety information.

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

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

For a simple 3-parameter tool with no output schema, the description covers the key aspects: what it does, when to use it (and not), permissions, irreversibility, and error handling. It doesn't describe the return value, but with no output schema that is not required. The mention of pagination fields is slightly incongruous since the schema has none, but it does not harm completeness.

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 has 100% coverage with each parameter described ('The ID of a thread note', etc.), so the baseline is 3. The description adds no new parameter-specific meaning, only a generic reminder to provide numeric IDs or URL-encoded paths exactly as documented, which merely echoes 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 opens with a specific verb and resource: 'Delete an existing merge request note.' This clearly distinguishes it from sibling tools like get_merge_request_note (read) and create_merge_request_note (create). The scope is precise and 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 advises using get or list tools first when inspection is needed, which frames when not to use this tool. It also mentions verifying the target before deletion, providing clear conditional guidance. It doesn't name specific alternatives like delete_merge_request_discussion_note, but the cautionary context 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?

Beyond the annotations (destructiveHint), the description details the destructive nature: 'It changes or removes remote GitLab data and may be irreversible; it requires the necessary project or group permission and returns validation, conflict, permission, or rate-limit errors.' This adds important behavioral context not covered by annotations alone.

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 somewhat verbose but well-structured, starting with the core action, then parameter nuances, usage guidance, and consequences. Each sentence adds necessary information, though some redundancy with schema descriptions could be trimmed. It is appropriately sized for the tool's complexity.

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

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

Given there is no output schema, the description covers all necessary aspects: purpose, usage, parameters, permissions, and error types. It is complete for an agent to understand when and how to invoke the tool correctly without additional 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?

The description adds value beyond the schema by clarifying when discussion_id is needed ('Pass discussion_id for discussion thread replies') and the format for project_id ('provide the numeric ID or complete URL-encoded path described by the schema'). It also emphasizes using required identifiers and pagination fields correctly, which is useful.

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 specific action: 'Remove an emoji reaction from a merge request note.' It also distinguishes this from other note-related tools by specifying the context and the necessary parameters like discussion_id for thread replies.

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 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.' It also mentions passing discussion_id for thread replies, giving a clear condition. However, it does not explicitly compare with alternative delete tools for other resources, but the naming clarifies the scope.

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 contradicts the annotation readOnlyHint: true. The description claims the tool 'changes only the session's tool registry' which is a state-changing action, whereas readOnlyHint indicates a read-only operation. This conflict undermines trust.

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 somewhat verbose, repeating the category list and the idea of changing the registry. It could be tightened without loss of meaning, but it is not excessively long.

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 main functionality and how to invoke it. However, the contradiction with readOnlyHint creates confusion about side effects, and there is no mention of the response format. Overall it is mostly complete but not fully reliable.

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 description covers 100% of the parameter (category), and the description adds examples of valid values. While this is helpful, it does not significantly enhance the schema's explanation, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to discover and activate additional tool categories. It lists the available categories and distinguishes between listing and activating, providing a clear verb-resource relationship.

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

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

It explicitly states when to use the tool: 'Use this when a needed opt-in category is not currently exposed.' It also explains the two modes (omit category to list, provide category to activate), leaving no ambiguity.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate read-only. It adds valuable behavior: images returned as base64 in remote mode, local_path saves to disk, requires project access, and returns content or an attachment/permission error. It does not contradict annotations. Slight gap: no detail on what happens if filename is not found, but the error mention covers it partially.

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 at a few sentences, front-loads the core purpose and the key base64 detail, and avoids redundancy. The mode explanation is useful but slightly repetitive; still, every 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 (download with modes and error handling) and that there is no output schema, the description covers the key aspects: what it does, the modes, the read-only nature, and required access. It doesn't detail the exact response structure beyond base64/URL, but that's acceptable for a download tool with a simple return. The openWorldHint annotation implies permissions might vary, and the description mentions 'requires project access' to complement it.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including local_path's optional behavior. The description adds meaning by explaining the mode distinction (remote vs local) that ties into project_id and filename, but doesn't add syntax or format details 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 clearly states the tool downloads an uploaded file from a project, and distinguishes it from related operations like upload_markdown or get_file_contents. It specifies the read-only nature and the different behaviors in remote vs local mode, making it distinct from siblings in the project/file domain.

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 explains when to use it: 'to retrieve a previously uploaded project attachment.' It also contrasts remote mode (returns inline base64 or download URL) with local mode (saves to path), providing practical context. However, it does not explicitly mention when NOT to use it or name alternative tools like get_file_contents for repository files, though the focus on 'uploaded attachments' implies that distinction.

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, so the description carries the burden of behavioral disclosure. It clearly states the operation creates a new project, requires fork permission, and returns either the forked project or a namespace/permission error. This gives the agent important information about side effects, authorization requirements, and error behavior beyond what annotations provide.

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

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

The description is three sentences with no waste: the action is front-loaded, the alternative tools are named in the second sentence, and the third provides essential behavioral context. Every sentence earns its place and the structure is easy to scan.

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

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

For a simple two-parameter tool with no output schema, the description covers the core need: what the tool does, when to use it, what side effects occur, what permission is required, and what return/error behavior to expect. An agent has enough context to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, with both parameters already documented: namespace is 'Namespace to fork to (full path)' and project_id is 'Project ID or complete URL-encoded path to project.' The description adds only marginal context like 'permitted namespace' and 'current user's namespace,' but does not add significant meaning beyond the schema. 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 a specific verb and resource: 'Fork a project to your account or specified namespace,' which clearly identifies the operation. It also distinguishes itself from siblings by noting that search_repositories and get_project are for inspecting without copying, so an agent can tell this tool apart 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?

The description explicitly states when to use this tool (to create a copy of an existing project) and names alternatives for when not to use it: use search_repositories or get_project to inspect projects without copying them. This gives clear routing guidance that leaves nothing to inference.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this and adds valuable behavior: "missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors." This goes beyond the structured hints without contradicting 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 description is concise at three sentences and front-loads the core purpose. However, the final sentence contains generic parameter/pagination guidance that is not tool-specific, adding slight noise.

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

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

For a simple 2-parameter read-only getter with full schema coverage and helpful annotations, the description covers usage, error behavior, and return payload highlights. The only minor gap is the lack of a concrete response shape, but the description's high-level return details are sufficient 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 description coverage is 100% and both parameters already have clear descriptions. The description's parameter sentence is generic boilerplate ("When `project_id` or `group_id` is accepted...") and adds little beyond the schema, especially since `group_id` is not even a parameter of this tool.

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

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

Description begins with a specific verb and resource: "Get branch details (commit, protection status)". It also distinguishes itself from discovery tools by stating "Use this for a known resource or result; choose the corresponding list or search tool when you need to discover multiple 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?

Explicitly states when to use the tool (known resource) and when to use alternatives (discovering multiple resources). It also adds contextual constraints like read-only behavior and error conditions, giving an agent clear routing guidance.

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

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

The description discloses it is read-only and does not mutate data, and explicitly lists error conditions: missing resources, invalid identifiers, insufficient permission, and rate limits. While annotations already provide readOnlyHint, the description adds the error behavior specifics which is genuinely useful beyond the annotations. 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, no redundancy. It front-loads the purpose, then routes alternatives, then disclaimers and identifier guidance. Every sentence adds distinct value; could be slightly trimmed but it is 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 diff tool with 5 params and no output schema, the description covers usage discrimination, error behavior, and parameter use. It doesn't describe return format, which is implied by the tool name, and annotations cover read-only and open-world hints. Slightly short of a 5 because it doesn't hint at what the diff result contains (e.g., files changed, patches), but strong overall.

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 this is the baseline 3. The description adds value by noting 'provide the numeric ID or complete URL-encoded path described by the schema; use required identifiers and pagination fields exactly as documented' — reinforcing correct identifier format and emphasizing exact documentation for required/pagination fields. This is useful guidance beyond the schema alone.

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 'Get diffs between two branches or commits' — a specific verb and resource. It differentiates from siblings by explicitly contrasting with list/search tools for discovery, and its name distinguishes it from get_merge_request_diffs and related MR diff tools.

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

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

Explicitly instructs when to use this tool ('Use this for a known resource or result') versus alternatives ('choose the corresponding list or search tool when you need to discover multiple resources'). This is clear routing guidance 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 already declare readOnlyHint and openWorldHint. The description reinforces the read-only nature ('It is read-only and does not mutate GitLab data') and adds transparency about error responses (missing resources, invalid identifiers, insufficient permission, rate limits are returned as errors). This goes beyond the annotations by detailing failure modes, so while the annotations lower the bar, the description adds meaningful 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 description is concise, with two sentences that front-load the purpose and usage. It efficiently covers read-only status, error conditions, and a general identifier/pagination note. The final sentence about `project_id`/`group_id` is slightly off-topic and could be removed, but overall it is well-structured and not verbose.

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?

Since there is no output schema, the description does not need to explain return values. It adequately covers error handling (missing resources, invalid identifiers, insufficient permission, rate limits) and mentions pagination fields. It does not elaborate on component or version limits beyond the schema, but those are self-explanatory. The description is sufficiently complete for a read-only getter with known parameters.

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% (each parameter has a description), so the baseline is 3. The description does not add significant semantic information beyond the schema. It includes a generic note about 'use required identifiers and pagination fields exactly as documented' but this is redundant with the schema descriptions. The mention of `project_id` or `group_id` is confusing because these are not actual parameters in this tool, but it does not clarify the inputs further.

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

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

The description clearly states the tool's function: 'Get details for a GitLab CI/CD Catalog resource, including versions and components.' It also distinguishes it from the list tool by specifying when to use it: 'Use this for a known resource or result; choose the corresponding list or search tool when you need to discover multiple resources.' This makes the purpose unambiguous and differentiates it from siblings like 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?

The description explicitly provides usage guidance: 'Use this for a known resource or result; choose the corresponding list or search tool when you need to discover multiple resources.' It also notes the tool is read-only and mentions error conditions (missing resources, invalid identifiers, insufficient permission, rate limits). This gives clear direction on when to invoke 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 declare readOnlyHint=true and openWorldHint=true, and the description reinforces that reading does not mutate GitLab data. It additionally documents error behavior for missing resources, invalid identifiers, insufficient permission, and rate limits, which is useful context beyond the annotations. It stops short of fully describing the success return shape, but the safety and error profile is well covered.

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

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

The description is concise and well-structured: it leads with purpose, gives usage guidance, then states safety and error semantics. Each sentence contributes useful information without wasted words.

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

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

The description is sufficiently complete for a simple, read-only 3-parameter tool: it covers intended use, error behavior, and identifier requirements. The absence of an output schema means the return shape is not explicitly described, but the tool name and 'Get details of a specific commit' provide enough context for selection and 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?

The schema documents all 3 parameters, so the description does not need to repeat their semantics. It only adds generic ID/path guidance and mentions 'project_id or group_id' even though only project_id appears in this schema, plus a generic pagination reference. Schema coverage is sufficient, so the baseline score of 3 applies.

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

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

The description states a clear verb+resource combination: 'Get details of a specific commit.' It also communicates that the tool is for a known commit or result rather than for discovery, which distinguishes it from sibling list/search tools.

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

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

The description gives explicit guidance: use this tool when you have a known resource or result, and use the corresponding list or search tool when you need to discover multiple resources. This clearly routes an agent between get_commit and discovery-oriented siblings like list_commits.

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 readOnlyHint annotation, the description discloses error behavior: 'missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors.' It also reaffirms read-only status and adds context about pagination fields. This goes beyond the annotation by specifying failure modes, which is valuable for an agent.

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

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

The description is compact: a purpose statement, a usage guideline, a behavioral/error note, and a parameter format note. It is front-loaded with the core action and no unnecessary fluff. Each sentence earns its place, though the group_id reference could be seen as extraneous, it doesn't bloat length.

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

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

For a read-only getter with no output schema, the description covers purpose, usage, error conditions, and parameter format. It doesn't describe the return shape, but that's not required when no output schema exists. The mention of pagination fields implies some control over result size. The group_id off-schema reference is a minor completeness gap, but overall it's sufficient.

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 a note about providing 'numeric ID or complete URL-encoded path' for project_id, which reinforces schema but adds little new meaning. It also mentions group_id, which is not in this schema, potentially confusing. Overall, marginal value beyond 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 tool's function: 'Get changes/diffs of a specific commit.' It uses a specific verb and resource, and differentiates from discovery tools by saying to use list/search tools for multiple resources. This distinguishes it from siblings like list_commits or get_branch_diffs.

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 and concisely directs usage: 'Use this for a known resource or result; choose the corresponding list or search tool when you need to discover multiple resources.' This provides clear when-to-use and when-not-to-use guidance, though it doesn't name specific sibling tools, the principle is unambiguous.

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

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

The read-only claim duplicates readOnlyHint, but the description adds useful error semantics: missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors. This goes beyond the annotations and helps the agent anticipate failure modes.

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

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

The description is front-loaded and readable, with purpose and usage appearing early. However, the final sentence contains boilerplate about group_id and pagination fields that do not apply to this tool's schema, adding noise and diminishing conciseness.

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

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

For a single-resource getter with three required identifiers, the description sufficiently covers when to use it, its read-only nature, and error behavior. No output schema exists, but the missing return-format details are a minor gap for a straightforward draft-note retrieval.

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 the three parameters. The description mostly repeats the URL-encoded path guidance and adds generic instruction about pagination fields, which are not present in this schema. It provides little 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?

States a specific verb and resource: 'Get a single draft note from a merge request.' It also distinguishes itself from list/search tools by positioning this as the option for a known resource or result, which separates it from siblings like list_draft_notes.

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 tool for a known resource and to choose the corresponding list or search tool when discovery is needed. It does not name a specific sibling such as list_draft_notes, but the selection rule is clear and actionable.

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

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

Annotations indicate read-only and open world. Description adds detail on output structure (each entry maps a range to commit with id, author, authored_date, message), which is beyond schema.

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

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

Two sentences, front-loaded with purpose and key detail, no extraneous 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 read-only tool with no output schema, the description adequately explains return values and parameter behavior, making it 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%. Description reinforces range parameter usage but does not add significant new meaning beyond 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 tool retrieves git blame for a file at a given ref, and distinguishes it from file-content tools by specifying it returns commit mappings for line ranges.

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 mentions using range_start/range_end to limit blame, but does not explicitly guide when to use this tool over siblings like get_file_contents or get_commit.

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 readOnlyHint annotation, the description specifies that it does not mutate data and lists common error conditions (missing resources, invalid identifiers, insufficient permission, rate limits), giving 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 compact, with the core purpose stated first, followed by targeted usage guidance and error behavior. No redundant or tangential information is present.

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 get operation with no output schema, the description covers purpose, usage, error conditions, and parameter guidance adequately. The schema's mention of 'file_path' precedence is present, so no critical gaps exist.

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?

While the schema already includes descriptions for each parameter, the description adds guidance on how to provide identifiers (e.g., numeric ID or URL-encoded path) and mentions using required identifiers and pagination fields, which adds practical usage context.

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 'get' and the resource 'contents of a file or directory from a GitLab project', and explicitly contrasts with list/search tools for discovery, making the purpose unambiguous.

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

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

It explicitly instructs to use this tool when the resource is known, and to choose list/search tools for discovery, providing clear decision criteria relative to sibling tools.

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