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 repository state, requires branch-creation permission, and lists possible error types (validation, missing-ref, protected-project, already-exists). The openWorldHint annotation is minimal, so the description carries the burden and does so well, though it doesn't detail side effects beyond state change.

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

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

Three sentences with no filler. The core purpose is front-loaded, usage guidance follows, and parameter clarifications are compactly appended. Every sentence earns its place.

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

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

For a 3-parameter tool with no output schema, the description covers purpose, usage, permissions, error cases, and parameter semantics. It doesn't describe the return value shape, but the description already mentions it returns the new branch or an error, which is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds a small amount of context by explaining that project_id accepts a numeric ID or URL-encoded path and that ref selects the starting revision, but this largely mirrors 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 a specific verb and resource ('Create a new branch') and distinguishes it from siblings by naming get_branch/list_branches for inspection and protect_branch for post-creation protection. It clearly identifies what the tool does and how it differs from related branch 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 explicitly says when to use this tool ('Use this to create a branch from a branch, tag, or commit') and names alternatives for inspection and protection. It also states the required permission (branch-creation permission), giving clear context for when this tool is appropriate.

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

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

The description explicitly states that it changes remote GitLab state and requires project/group permissions, and explains that the API returns validation, conflict, permission, and rate-limit errors rather than silently succeeding. Since annotations only contain openWorldHint=true, this behavioral disclosure carries the full burden and does so well.

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

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

The core purpose and side effects are front-loaded and concise, but the generic create-vs-update sentence and the closing boilerplate about required identifiers or pagination are not tailored to this tool and could mislead. Size is reasonable but not every sentence earns its place.

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

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

For a mutation with 10 parameters and no output schema, the description covers state change, permission requirements, and error behavior, but it omits the key upsert semantics (that an existing status with the same name/context is updated) and repeats the confusing update-tool advice. This leaves an agent with enough to act but with a significant ambiguity.

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 documents all 10 parameters at 100% coverage, so no extra parameter detail is needed, but the description adds boilerplate that is not grounded in the schema: it mentions group_id, which is not an accepted input, and references pagination fields that do not exist on this schema. This is actively more confusing than helpful.

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?

Opening sentence names the exact operation and resource: 'Create or update the status of a commit.' This distinguishes it from the read-only sibling list_commit_statuses and leaves no doubt about what resource is acted on.

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

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

It offers a generic rule ('choose the corresponding update or edit tool when the resource already exists') but this is misleading here: the tool itself supports updating commit statuses and there is no update_commit_status sibling. It also does not point to list_commit_statuses for checking existing statuses, so an agent could be steered toward a non-existent alternative.

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

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

With only openWorldHint as an annotation, the description carries the safety disclosure burden. It explicitly says the tool 'changes remote GitLab state,' requires project/group permission, and returns validation, conflict, permission, or rate-limit errors rather than silently applying invalid requests. This adds meaningful context beyond the annotation.

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

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

The description is front-loaded with purpose and side-effect warning, and is not overly long. However, the closing sentence about pagination fields is generic boilerplate that does not apply to this tool's schema, and 'described by the schema' is redundant filler.

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

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

The complex position object is thoroughly documented in the schema, so the description does not need to repeat it. It adds the key operational context: state change, permissions, and error behavior. A short note on draft-note lifecycle (unpublished until publish_draft_note) would strengthen it, but it is reasonably 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 documents all six parameters in detail, including the complex position object. The description's note about numeric IDs or URL-encoded paths mostly restates the project_id schema, and the 'group_id' mention is conditional boilerplate not present in this 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: 'Create a draft note for a merge request.' It also explicitly distinguishes creation from update/edit tools, which separates it from siblings like update_draft_note and delete_draft_note.

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

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

It states 'Use this for a new resource or action' and directs the agent to the corresponding update or edit tool when the resource already exists. It also adds permission prerequisites and error behavior. It could name update_draft_note explicitly or contrast with create_note, but the guidance is clear.

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

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

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

Beyond the sparse openWorldHint annotation, the description discloses that the operation creates remote project data, requires issue creation permission, and returns either the new issue or validation, permission, and duplicate-related errors. This is meaningful behavioral context for a mutation tool, though it could have added more detail about side effects like notifications or idempotency.

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

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

The description is two sentences with no filler. The core purpose is front-loaded, followed by routing guidance and behavioral/error context, and every sentence earns its place.

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

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

For a mutation tool with 8 parameters, a fully documented schema, and no output schema, the description provides the essential extra context: side effect, permission requirement, and expected success/error returns. An agent has what it needs to decide whether to call the tool and what to expect.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description does not add parameter-level detail beyond what the schema provides, so it meets the baseline but does not exceed it.

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

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

The description opens with 'Create a new issue', a specific verb and resource that makes the tool's purpose immediately clear. It further distinguishes itself from update_issue and create_issue_note, ensuring the agent can tell it apart from the most similar 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 explicitly states when to use this tool ('Use this to open a new issue') and when not to: 'use update_issue for an existing issue and create_issue_note to add discussion without changing issue fields'. This gives 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?

With no readOnly or destructive annotations present, the description usefully states that the tool changes remote GitLab state and requires permissions. It also discloses error behavior (validation, conflict, permission, rate-limit) rather than silent failure. This gives an agent important behavioral context beyond the openWorldHint annotation.

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

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

Four sentences, with the core action front-loaded and examples early. The final sentence contains generic filler ('pagination fields', 'described by the schema') that is not applicable and could be trimmed, so it is not 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 simple 3-parameter creation tool, the description covers purpose, mutation, permissions, errors, and identifier format. It is diminished by irrelevant boilerplate about group_id and pagination, and it does not mention what a successful response returns or how to distinguish from note-level emoji reactions. Overall adequate but not complete.

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

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

The schema already describes all three parameters with 100% coverage, so the baseline is 3. The description adds emoji-name examples and repeats URL-encoding guidance for project_id, but its mention of group_id and pagination fields is boilerplate that does not match this schema. It does not meaningfully clarify issue_iid 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 first sentence states a concrete action and resource ('Add an emoji reaction to an issue') with examples of valid emoji names, which is immediately actionable. The follow-up create-vs-update phrasing helps distinguish from edit tools, though it does not explicitly distinguish from sibling note-emoji reaction 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 explicitly advises using this for a new resource or action and choosing an update/edit tool when the resource already exists, and it notes permission requirements. However, the guidance is generic and does not name specific siblings like create_issue_note_emoji_reaction, and the 'update or edit' advice is questionable for this tool since no update_issue_emoji_reaction sibling exists.

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?

Annotations are sparse (only openWorldHint), so the description must carry the transparency burden. It does: it states the operation 'creates remote discussion content,' requires note permission, and returns the note or a missing-issue/thread/permission error. This covers mutation, permissions, 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?

Two tightly packed sentences front-load the core action, then handle alternatives, side effects, permissions, and error cases. There is no filler, repetition, or unnecessary detail.

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

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

Despite having no output schema and only a weak annotation, the description is complete enough for an agent to select and invoke the tool correctly: it covers purpose, when to use alternatives, remote side effects, permission requirements, and expected return/error behavior. The 100% schema coverage handles parameter details.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds only contextual framing around the discussion thread behavior, which is already reflected in the discussion_id schema description. It doesn't enrich parameter semantics beyond the schema.

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

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

The description starts with a specific verb and resource: 'Add a note to an issue, optionally replying to a discussion thread.' It also explicitly distinguishes itself from update_issue and create_note, making its purpose unambiguous against a crowded set of 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 direct routing guidance: 'use update_issue for issue fields and create_note only when the generic endpoint is required.' This tells an agent exactly when to pick this tool and when to pick an alternative.

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

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

With only openWorldHint in annotations, the description carries the behavioral burden and delivers: it states that the tool mutates remote GitLab state, requires project/group permission, and surfaces validation, conflict, permission, or rate-limit errors rather than silently accepting invalid requests. This is valuable beyond the sparse annotations.

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

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

The core purpose is front-loaded in the first sentence, which is good. However, the middle sentences are generic boilerplate ('Use this for a new resource or action...', 'use required identifiers and pagination fields exactly as documented') that could apply to any GitLab tool and add little specific value; the mention of pagination fields is inaccurate for a schema with no pagination parameters.

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

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

For a five-parameter tool with full schema coverage and no output schema, the description addresses the key gaps: the discussion_id nuance, mutation semantics, permission requirements, and error behavior. An agent has enough to call the tool correctly without needing to read the GitLab API docs.

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 marginal value by noting that project_id accepts a numeric ID or URL-encoded path and that discussion_id is the thread-reply differentiator — but most parameter meaning already lives in the schema, and the generic 'pagination fields' remark is boilerplate that doesn't apply to this schema.

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

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

The description states a specific verb and resource ('Add an emoji reaction to an issue note') and clarifies the discussion_id variant for thread replies. It distinguishes creation from update/edit tools, though it doesn't explicitly name the closest siblings (create_issue_emoji_reaction, create_merge_request_note_emoji_reaction) — the resource is specific enough that an agent can disambiguate.

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

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

The description gives an explicit when-to-use rule ('Pass discussion_id for discussion thread replies'), a creation-vs-update routing rule ('choose the corresponding update or edit tool when the resource already exists'), and notes that required identifiers must be used exactly as documented. It lacks an explicit alternative-tool name, but the guidance is concrete 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?

The openWorldHint annotation already implies external side effects, but the description adds valuable specifics: it changes remote GitLab state, requires project or group permission, and returns validation, conflict, permission, or rate-limit errors rather than silently succeeding. This goes beyond the annotation and gives the agent a clear failure model, though it doesn't discuss idempotency or response payload.

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 tight and valuable, but the third sentence includes generic boilerplate about pagination and group_id that doesn't apply to this tool. This wastes tokens and could misdirect the agent, making the description less effective than it could be with a more targeted final sentence.

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

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

Given there is no output schema, the description should explain the return value, but it does not. It also omits behavior for duplicate labels or partial updates, though it does mention conflict errors. The inaccurate group_id and pagination references detract from completeness, making this only minimally adequate for a 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?

The schema already has 100% coverage, so the baseline is 3, but the description's parameter guidance is partly inaccurate. It mentions 'group_id' which is not in the input schema, and refers to 'pagination fields' that have no relevance to this create operation. The only useful addition, that project_id can be a numeric ID or URL-encoded path, merely repeats the schema's description, so it adds confusion instead of clear value.

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

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

The description clearly states 'Create a new label in a project' with a specific verb and resource. It also differentiates from the update/edit siblings by explicitly saying to use those when the resource already exists, so an agent can confidently select this tool versus update_label or create_issue.

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

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

It explicitly says 'Use this for a new resource or action; choose the corresponding update or edit tool when the resource already exists,' giving a direct when-to-use vs. when-not-to-use. It also notes permission requirements and error behavior, which helps the agent decide if this tool is appropriate given its 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?

With only `openWorldHint` as an annotation, the description carries the behavioral disclosure burden. It clearly states that the operation "creates remote review state," requires project access, and returns either the new MR or validation, permission, branch, or duplicate-related errors. It stops short of detailing reversibility or side effects like source branch removal, but this is solid coverage.

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

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

The description is three tightly written sentences with the core action front-loaded. Every sentence adds meaning: what it does, when to use it versus the sibling, and what side effects and outcomes to expect.

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 13-parameter tool with no output schema, the description covers the essential operational facts: purpose, lifecycle relationship to `update_merge_request`, remote state creation, permission requirements, and return/error categories. It could mention that merging an existing MR is handled by `merge_merge_request`, but the sibling names make that reasonably clear.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions source and target branches but adds little semantic depth beyond the schema's own parameter descriptions, which already explain each field.

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

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

The description uses a specific verb and resource: "Create a new merge request." It further specifies that it opens an MR from an existing source branch to a target branch and explicitly distinguishes it from `update_merge_request`, so an agent can tell it apart from sibling MR 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 direct usage guidance: use it to open a new merge request and use `update_merge_request` after the MR exists. It also notes the operation requires project access, which helps the agent decide when it is applicable.

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

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

Annotations only provide openWorldHint, so the description carries most of the behavioral burden. It discloses that the operation creates remote review content, requires note permission, and returns either the new note or missing-discussion/position/permission errors. This adds meaningful context 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?

Three sentences, front-loaded with the core action, followed by routing and consequence details. There is no filler or redundant restatement of the schema.

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

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

For a write-style tool with no output schema, it still tells the agent what to expect (new note or error) and which permission is required. Combined with full parameter schema and sibling differentiation, the description is sufficiently complete; only minor details like created_at behavior are left to the schema, which already documents them.

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 five parameters, so the schema carries the parameter documentation burden. The description reinforces the purpose of discussion_id and body but adds no new parameter-level detail beyond what the schema already provides.

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

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

Description uses a specific verb and resource: 'Add a new discussion note to an existing merge request thread.' It also distinguishes itself from `create_merge_request_thread` and `create_merge_request_note` by naming the exact context (reply inside existing discussion).

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: to reply inside an existing merge request discussion. It names the alternatives for starting a new thread and adding a top-level note, so no inference is needed.

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 behavioral burden. It explicitly says the tool changes remote GitLab state, requires project or group permission, and surfaces validation, conflict, permission, or rate-limit errors rather than silently applying invalid requests.

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

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

The first sentence front-loads the purpose effectively and the error/permission sentence is useful. However, the update/edit alternative and the group_id/pagination boilerplate add noise without corresponding to this tool's actual API surface.

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 three-parameter create tool with no output schema, the description covers the key operational details: side effects, permissions, error behavior, and identifier format. It is not fully complete because it omits a pointer to the note-emoji sibling and does not mention 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?

Input schema coverage is 100 percent and already documents the emoji examples and project_id path format, so the description adds little beyond the schema. The closing note about group_id and pagination fields is generic and not fully relevant to this tool's 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?

States a specific action, Add an emoji reaction to a merge request, with concrete emoji examples. It is clear about the resource but does not distinguish itself from the similarly named sibling create_merge_request_note_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?

Offers only a generic new-resource versus update/edit rule, which does not map cleanly to any real update tool for emoji reactions in the sibling list. It gives no guidance about when to choose this tool over the closely related create_merge_request_note_emoji_reaction.

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?

Description discloses that it mutates remote state, requires permissions, and returns validation/conflict/permission/rate-limit errors. This is valuable since annotations provide only openWorldHint and no safety flags. It doesn't mention potential side effects (e.g., notifications or discussion threading) but covers the core behavior well.

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

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

The description is front-loaded with purpose, then usage, then behavior. It is moderately concise and each sentence earns its place, though the final sentence about identifiers/pagination is somewhat generic and could be trimmed without losing essential information.

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

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

Given the tool's simplicity (3 params, no output schema, minimal annotations), the description covers purpose, usage, permissions, and error handling. It is sufficiently complete for an agent to invoke it correctly, though it could mention the exact response format (since no output schema exists) and any content constraints on the note body.

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 parameters are already documented. The description adds minimal extra meaning; it mentions providing numeric ID or URL-encoded path, but that's already in the schema. It also references 'group_id' which is not a parameter in this tool, creating slight confusion. Value added is marginal.

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 clear verb+resource: 'Add a new note to a merge request.' Explicitly distinguishes from update/edit tools, making the purpose unambiguous and differentiating from siblings like update_merge_request_note.

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

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

Explicitly instructs to use this for new resources/actions and to choose the corresponding update/edit tool when the resource exists. This covers the main alternative, though it doesn't differentiate from other create-type note tools (e.g., create_merge_request_thread or create_draft_note), leaving some ambiguity for those siblings.

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

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

Despite only openWorldHint being set in the annotations, the description explicitly discloses that the tool changes remote GitLab state, requires appropriate project/group permissions, and returns validation, conflict, permission, or rate-limit errors instead of silently succeeding. This gives the agent the essential behavioral expectations for a mutating operation.

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

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

The first two sentences are specific and efficient, but the final sentence is generic boilerplate about group_id and pagination fields that is neither relevant nor accurate for this tool. The overall length is acceptable, but that last sentence does not earn its place.

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

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

The description covers important operational context: discussion_id behavior, remote state mutation, permissions, and error modes. However, it includes irrelevant group_id/pagination wording and gives a misleading update/edit alternative when no such tool exists, leaving the overall picture accurate 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?

Schema coverage is 100%, so the baseline is 3, but the description does not add meaningful parameter semantics and instead introduces inaccuracies: it references group_id and pagination fields that do not exist in this tool's schema. The numeric ID or URL-encoded path advice merely repeats what the project_id schema description already provides.

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

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

The first sentence names a specific verb and resource: adding an emoji reaction to a merge request note. This clearly distinguishes it from related siblings like create_merge_request_emoji_reaction, which targets the merge request itself, and create_merge_request_note, which creates a note without a 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?

It offers some context, such as passing discussion_id for discussion thread replies, but the guidance to 'choose the corresponding update or edit tool when the resource already exists' is misleading: no update or edit tool exists for merge request note emoji reactions in the sibling list, only delete and create tools. It also does not name the closest alternatives like create_merge_request_emoji_reaction or delete_merge_request_note_emoji_reaction.

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, so the description carries the behavioral burden. It discloses that the operation creates remote content, requires note permission, and returns either the discussion or permission/validation errors. This goes beyond the schema and gives an agent a realistic failure model.

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

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

Three tight sentences: purpose, routing to alternatives, and behavioral/error summary. No filler or repeated schema content, and the most important selection information is front-loaded.

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

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

For a complex nested tool there is no output schema, but the description states the success return (discussion) and main error categories. Combined with the very detailed input schema and sibling routing, an agent has enough to invoke and verify the call.

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

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

Schema already documents all five parameters including the nested position object with detailed rules for line_code, shas, and line ranges. The description adds no parameter-level detail, but with 100% schema coverage the baseline of 3 applies.

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

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

Clearly states it creates a new thread on a merge request and explicitly frames it as starting a review thread. Names the sibling tools for unthreaded notes and replies, which distinguishes it from adjacent operations. The verb+resource is specific 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?

Explicitly says when to use this tool: to start a review thread. It also says when not to use it, naming create_merge_request_note for unthreaded notes and create_merge_request_discussion_note for replies to existing threads. The permission requirement provides an additional eligibility check before invocation.

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

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

Annotations only provide openWorldHint=true, so the description carries the behavioral burden. It discloses that the operation mutates remote discussion content, requires note permission, and returns the created note or an error, covering the main behavioral risks even though it omits finer 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?

Three sentences, each earning its place: definition, usage routing, and behavior/return information. No unnecessary detail 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?

Despite lacking an output schema, the description provides the essential return and error information. All required parameters are documented in the schema, and the tool's complexity is modest, so nothing needed for a correct invocation is missing.

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

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

Schema description coverage is 100%, so all four parameters are already fully documented. The description adds context about top-level usage but no additional parameter-level meaning, so 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 opens with a specific verb and resource: 'Create a new note (comment) to an issue or merge request.' It further narrows scope to top-level comments, distinguishing it from threaded note operations and making sibling differentiation 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?

Explicitly states when to use this tool ('for a top-level comment ... when no typed discussion operation is needed') and names alternatives for threaded replies (`create_merge_request_thread` or `create_issue_note`). The when-to-use and when-not-to-use guidance is direct 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 `openWorldHint`, so the description carries the burden of disclosing effects. It explains that the tool writes through a commit, requires repository write permission, and surfaces conflict/validation errors. It stops just short of explicitly stating that an existing file's content will be overwritten.

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

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

The description is four purposeful sentences: purpose, usage rule, encoding default/backward compatibility, and permission/error behavior. It is front-loaded and contains no filler.

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

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

For a 9-parameter mutation tool with no output schema, this description covers selection criteria, write permission, commit semantics, encoding, and the return/error class. The high schema coverage fills in remaining field details, so an agent has what it needs to call the 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 coverage is 100%, so the baseline for parameter semantics is 3. The description mostly restates the `encoding` default already present in the schema and does not clarify the relation between `commit_id` and `last_commit_id` or the rename behavior of `previous_path`.

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') and immediately narrows scope to a single repository file. It also names `push_files` as the multi-file sibling, so an agent can distinguish this tool without inspecting schemas.

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

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

It gives explicit conditions for use: a single repository file when the target path is known to be new or existing. It also calls out the alternative, `push_files`, for multi-file commits, which makes the selection rule 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 description adds value beyond the openWorldHint annotation by disclosing that it changes remote GitLab state, requires permissions, and returns validation/conflict/permission/rate-limit errors instead of silently failing. This is useful behavioral context for the 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 starts with a clear purpose and provides usage guidance, but the final sentence about project_id/group_id and pagination fields is irrelevant and confusing. It adds noise without earning its place, reducing overall 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?

The description covers the core purpose, usage guidance, and error behavior, but the misleading parameter reference creates a gap that could lead an agent to look for non-existent fields. It also does not mention what happens on success (e.g., returned project object), though with no output schema this may be less critical. Overall, it is adequate but not fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description includes a confusing reference to 'project_id' or 'group_id' and 'pagination fields' that do not exist in the schema (only namespace_id is present). This adds misleading guidance that could misdirect the agent, and it does not clarify any of 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 clearly states the verb and resource: 'Create a new GitLab project.' It also distinguishes this from update/edit tools, making it easy for an agent to select this tool for new resources and the update tool for existing ones.

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 ('Use this for a new resource or action') and when not to ('choose the corresponding update or edit tool when the resource already exists'). This directly routes the agent to the correct alternative.

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

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

The description discloses the permanent/irreversible nature of the operation ('permanently removes a remote branch'), the required permission ('requires branch-delete permission'), and the error outcomes ('protected-branch, missing-resource, or permission error'). It adds value beyond the destructiveHint annotation by specifying consequences 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: the primary action and resource are stated in the first sentence, followed by concise usage and behavioral notes. Every sentence earns its place—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?

Given the tool's destructive nature, the description is fully complete: it covers when to use, what to do before, what the operation does, what permissions are needed, and what errors to expect. No output schema is present, but the description adequately signals return shape ('returns the deletion result or ... error') while the error list covers the key failure cases.

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

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

The schema covers 100% of the parameters with descriptions, so the baseline is 3. The description adds clarifying context: it clarifies that `branch_name` refers to the branch being deleted, reinforces that `project_id` is the target, and connects the parameters to the operation's semantics (e.g., confirming the branch name means checking `branch_name`). This slight edge warrants 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 a specific verb ('Delete') and resource ('branch from project'), and clearly distinguishes this tool from siblings like `get_branch`, `list_branches`, `protect_branch`, and `update_default_branch` by specifying the action and scope. It also names the sibling tools explicitly in the usage guidance, so an agent can differentiate it without opening schemas.

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

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

The description provides explicit when-to-use guidance: '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.' It gives clear preconditions, exclusions, and alternatives, which is exemplary.

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?

Annotations already provide readOnlyHint=true-does not say 'is a read-only operation' in description. The description adds that the effect is scoped to the session tool registryrix, that categories are listed in the response, and that GitLab data is untouched. This is useful beyond the annotations, though it doesn't clarify failure modes like invalid category names or whether activation is idempotent.

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 compact paragraph with every sentence earning its place: core action, parameter semantics, usage trigger, side-effect scope, and response content. No filler.

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

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

For a tool with one optional parameter and no output schema, the description covers what the agent needs: available category examples, how to discover vs activate, what the response includes, and the safety boundary. Nothing important 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% with one optional string parameter. The description adds critical semantics: omitting the parameter lists available categories, while providing it activates that category. That usage nuance goes beyond the schema and meaningfully guides the agent.

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: 'Discover and activate additional tool categories for this session.' It clearly differentiates this from the GitLab data-operation siblings by framing it as session tool management.

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

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

The description explicitly states when to use it ('when a needed opt-in category is not currently exposed') and precisely explains the two invocation modes: omit `category` to list, or provide it to activate. This gives an agent direct decision criteria for when this tool beats the 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, 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?

It explicitly states the tool is read-only and does not mutate GitLab data, consistent with readOnlyHint. It also discloses concrete error behaviors (missing resources, invalid identifiers, insufficient permission, rate limits) that are not present in the annotations, adding valuable transparency.

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

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

The first sentence is front-loaded and concise, but the later sentences contain boilerplate about group_id and pagination that are irrelevant to this specific tool. The description could be tighter without losing necessary guidance.

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

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

For a simple getter with two required parameters and no output schema, the description covers the invocation context, safety profile, error behavior, and return-field hints. It is sufficiently complete for an agent to call the tool correctly and understand what to expect.

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

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

Schema description coverage is 100%, so baseline 3 applies, but the description adds no new parameter meaning beyond the schema. It mostly repeats the project_id wording and includes a generic reference to group_id and pagination fields that do not apply to this two-parameter tool, which is slightly misleading.

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

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

The first sentence names a specific verb and resource ('Get branch details') and identifies the key fields returned (commit, protection status). It also distinguishes itself from discovery tools by stating it is for a known resource, separating it clearly from siblings like list_branches and get_protected_branch.

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

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

The description explicitly states when to use this tool ('for a known resource or result') and when to prefer list/search tools (for discovering multiple resources). It does not name the exact sibling tool, e.g., list_branches, but the decision 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 already include readOnlyHint=true, and the description reinforces this by stating 'read-only' and adding error behavior: missing resources, invalid identifiers, insufficient permission, and rate limits returned as errors. This provides useful context beyond the annotation without contradicting it.

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

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

The description is moderately sized with purpose, usage, behavior, and parameter guidance in four sentences. It is mostly front-loaded and every sentence contributes value, though the final sentence's 'exactly as documented' is mildly redundant, so it is not maximally tight.

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

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

Given the tool's moderate complexity, the description covers purpose, usage boundaries, read-only behavior, error conditions, and parameter handling. There is no output schema, but the tool's return values are fairly predictable from the name; the absence of explicit return-format details is a minor gap, not a blocking one.

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 documented in the schema. The description adds a generic note about providing project_id as a numeric ID or URL-encoded path, but it mostly restates what the schema already offers and does not add per-parameter meaning beyond that baseline.

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

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

The description opens with 'Get diffs between two branches or commits', a specific verb and resource. It also adds a scoping clue by contrasting with list/search tools, though it does not name sibling diff tools like get_commit_diff or list_merge_request_diffs, so differentiation is clear but not fully explicit.

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

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

The description explicitly states when to use it ('for a known resource or result') and when not to ('choose the corresponding list or search tool when you need to discover multiple resources'). It offers a clear exclusion but does not name specific alternative tools, so it stops short of maximum explicitness.

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 the description reinforces it while adding concrete error behavior: missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors. This is valuable beyond the annotation, though it does not describe success payloads.

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, front-loads the core action, and keeps usage guidance brief. However, it contains some redundancy ('read-only' vs 'does not mutate') and an irrelevant mention of group_id not present in the schema, which prevents a top score.

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

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

For a single-commit retrieval tool with a complete schema and read-only annotations, the description provides enough context: purpose, usage, identifier format, and error handling. It doesn't explain the return shape, but that is permissible without an output schema. The optional stats parameter is left to the schema, which is acceptable.

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

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

Schema coverage is 100%, so the description is not obligated to repeat parameter meanings. It does add a note about providing numeric ID or URL-encoded path, but that closely mirrors the schema description for project_id. The generic instruction to use identifiers and pagination fields 'exactly as documented' adds little 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 details of a specific commit') and explicitly distinguishes itself from list/search tools by saying to use those for discovery. This differentiates it from siblings like list_commits and get_commit_diff.

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

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

Provides explicit when-to-use guidance: 'Use this for a known resource or result; choose the corresponding list or search tool when you need to discover multiple resources.' This clearly routes the agent to alternatives, satisfying the requirement.

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?

Building on the readOnlyHint annotation, the description adds that the tool does not mutate GitLab data and details error behavior for missing resources, invalid identifiers, insufficient permission, and rate limits. This is useful context beyond the structured annotations, though it does not describe the return payload.

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

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

The purpose is front-loaded and the description is only four sentences, each adding information. The final sentence is somewhat boilerplate and could be tightened, but nothing is redundant enough to hurt 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?

For a small read-only tool with full schema coverage and no output schema, the description covers use case, mutation safety, and error behavior comprehensively. It is complete enough for an agent to select and invoke it correctly.

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

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

The schema already documents all three parameters (100% coverage), so the description needs to add little. It adds the practical note about numeric IDs or URL-encoded paths, but the group_id mention does not match the schema and no new per-parameter semantics are provided.

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

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

The description opens with a specific verb and resource ('Get changes/diffs of a specific commit'), and clarifies scope by contrasting with list/search tools for discovering multiple resources. This distinguishes it from siblings like list_commits and get_commit without requiring the schema.

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

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

It explicitly states to use this when a specific resource/result is already known and to switch to a list or search tool for discovery. It names a category of alternatives rather than specific sibling tools, but the when/when-not guidance 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?

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 already convey readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral detail beyond the schema by explaining the return shape: each entry maps a contiguous source-line range to the commit that last changed them, including id, author, authored_date, and message. This is especially valuable given there is no output schema.

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

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

The description is two sentences with no filler. The core purpose and output structure are front-loaded in the first sentence, and the optional line-range usage is clearly stated in the second. Every sentence earns its place.

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

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

For a read-only operation with fully documented parameters and readOnlyHint/openWorldHint annotations, the description covers what an agent needs: the purpose, the returned data shape, and the optional range restriction. The absence of an output schema is compensated by the explicit entry structure in the description.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including required fields and the paired constraint on range_start/range_end. The description reiterates that range_start/range_end limit blame to specific lines, but does not add substantial new meaning 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 a specific verb, resource, and operation: 'Get git blame for a file at a given ref.' The phrase 'git blame' clearly distinguishes it from sibling file-related tools like get_file_contents or get_repository_tree, since no other tool claims to map lines to commits.

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

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

The description provides clear context: it retrieves blame for a file at a ref, and explains how to scope the operation with range_start/range_end. It does not explicitly name alternative tools or when-not-to-use this tool, but the unique blame semantics make the proper use 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?

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.