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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds the substantive behavioral context that this is a pre-aggregated, fan-out-replacing call rather than a raw listing. It does not discuss cost/latency or permission scope for the group, and truncation behavior is left entirely to the schema.

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

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

Two sentences, front-loaded with the scope and output shape, and the closing sentence converts that into a usage decision. No filler or repetition of the title.

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

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

With eight parameters but full schema documentation and no output schema, the main risk is an unknown return shape, and the description fully enumerates it (totals by action type, breakdowns by project, contributor, day). An agent has enough to call this correctly without further reading.

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 every parameter including maxEvents truncation semantics, maxProjects, topContributors, and includeSubgroups is already documented. The description only loosely echoes two of them ("optionally including subgroups", "by contributor"), adding no format or default detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (aggregated activity summary for a group), its scope (whole group, optionally subgroups, over a time window), and exactly what is produced (totals by action type plus breakdowns by project, contributor, and day). This clearly separates it from analytics_user_summary and from the raw event listings.

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 frames the use case ("answer 'what did this team do'") and names the alternative it replaces (fanning out across list_project_events). It does not mention when to prefer analytics_user_summary for a single person or when to drop to list_project_events for raw detail, so sibling routing is only partially covered.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it only considers open non-draft MRs, returns per-reviewer queues, an age histogram, stalest MRs by updatedAt, and buckets unassigned MRs under '(unassigned)'.

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 tight sentences with no filler. The core action and output shape are front-loaded before the unassigned-bucket 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?

There is no output schema, but the description adequately explains the return shape: per-reviewer queue stats, age-bucket histogram, and stalest MRs. It does not clarify the behavior if neither group nor project is supplied, despite zero required parameters, which is a minor remaining gap.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the input schema. The description mentions group/project aggregation and the stalest output, but does not add parameter-level meaning beyond the schema's own mutual-exclusivity, defaults, and truncation notes.

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: aggregate open (non-draft) merge requests across a group or project to surface review bottlenecks. It also names the exact output categories, making it clearly distinguishable from simple MR-listing siblings like get_merge_requests.

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 phrase 'to surface review bottlenecks' gives clear context for when to use this tool rather than raw MR retrieval. However, it does not explicitly exclude alternatives or name sibling analytics tools such as analytics_user_summary or analytics_group_summary.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the shape of the result (totals by action type plus project and day breakdowns), which is not derivable from the annotations. It stops short of covering truncation behavior or auth fallback, though both are documented in the schema.

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

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

Two sentences, both earning their place: the first defines the output, the second routes against the sibling. The scoping information is front-loaded and there is 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?

With no output schema, the description usefully sketches the return content (action-type totals, project and day breakdowns), which is the main thing an agent needs to know before calling. It is slightly incomplete on result-envelope details such as truncation, but that is disclosed via the maxEvents schema entry.

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 user, since, until, maxEvents and userCredentials are all fully documented in the schema, including defaults and the truncation flag. The description adds no parameter-level detail (e.g. the time-window semantics of since/until or the maxEvents cap), so this sits at the baseline where the schema does the work.

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

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

The description names a specific verb and resource ('Aggregated activity summary for a user over a time window') and enumerates exactly what is aggregated: totals by action type, breakdown by project and by day. It also explicitly separates itself from the raw-event sibling list_user_events, so an agent can pick it without opening either schema.

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

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

It gives an explicit routing rule: 'Use this instead of list_user_events when you want counts rather than a raw event feed.' Both the alternative and the condition that selects it are stated, leaving nothing to inference.

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

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

Annotations only declare the non-read-only, non-idempotent, non-destructive profile; the description adds genuinely new behavior: the notification side effect and that the recipient may need to accept before it appears on their profile. It does not describe failure modes or rate limits, but it generously extends the annotation profile.

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, each front-loaded with a distinct fact: action, permission gate, duplicate behavior, notification consequence. 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 mutation tool with no output schema, the description gives the permission gate, idempotency-friendly duplicate note, and the recipient acceptance flow. It could mention what a successful award returns or error conditions, but the key decision inputs are covered.

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 75%, and the schema already documents achievementId formats and userCredentials fallback behavior. The description adds no parameter-level detail beyond naming the username target, so the baseline 3 for schema-heavy coverage 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 ('Award an achievement to a GitLab username'), which the agent can immediately distinguish from sibling tools like revoke_achievement and create_achievement. The target entity (username) is 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?

It states the prerequisite permission (group Maintainer/Owner) and clarifies that repeated awards to the same user are permitted, which is exactly the kind of edge case an agent needs. It stops short of explicitly naming when to prefer revoke_achievement or create_achievement, so no explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds nothing beyond that: no disclosure of whether the listing is recursive or one level, whether it is paginated or capped, or how the credential fallback behaves — all behaviorally relevant for a browse call.

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?

A single short, front-loaded sentence with no redundancy — the resource and purpose come first. The trailing 'essential for' framing is mild filler and the brevity borders on under-specification rather than tight completeness.

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 annotations covering the safety profile and the schema fully documented, the minimum is met. However, for a browse tool with no output schema, the description omits the shape of the result (file/folder entries) and depth/pagination behavior, which an agent needs to use the output 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%; all four parameters (projectPath, path, ref, userCredentials) are documented in the schema, so the baseline is 3. The description adds no semantics beyond that, such as default root behavior or ref handling, so it cannot push higher.

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 ('Browse repository files and folders') and adds the intent ('exploring codebase structure'), so an agent knows it is a structural listing operation. It never distinguishes itself from siblings like get_file_content or resolve_path, which are natural alternatives for related tasks.

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 phrase 'essential for exploring codebase structure' implies the usage context but gives no explicit when-to-use rules. It does not say when to prefer this over get_file_content (for reading a file) or resolve_path (for locating a path), leaving routing to the agent's inference.

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

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

Annotations already declare the non-read-only, non-idempotent, non-destructive profile, so the description only needs to add context — and it does: permission level required, the feature-flag gate ('enabled Achievements'), and the limitation that avatars must be set in the UI. It does not describe failure behavior when the feature is disabled or whether the name must be unique.

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

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

Three short sentences, zero filler, with the capability stated first and the constraints (permissions, feature gate, avatar limitation) trailing in priority order.

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

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

For a creation tool with annotations present and no output schema, the definition covers prerequisites and the main capability gap agents would hit (no file upload). It omits any mention of what the create call returns or whether the achievement name must be unique within the group.

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 50%: group and userCredentials carry schema descriptions, while name and description do not. The description only restates 'name and optional description' with no added format, length, or constraint detail, so it does not fully compensate for the undocumented params.

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?

Specific verb ('Create') plus resource ('group achievement') with the fields it accepts ('name and optional description'). It is clearly distinguishable from sibling mutations such as update_achievement, award_achievement, and revoke_achievement without opening any schema.

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

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

Gives concrete prerequisites ('Requires group Maintainer/Owner and enabled Achievements') and one explicit exclusion ('file uploads are not supported by this tool'). It does not, however, explicitly route to or away from siblings like award_achievement or update_achievement.

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 this is a non-readonly, non-idempotent, non-destructive write, so the mutation profile is covered structurally. The description adds the meaningful extra context that administrator privileges are required, but says nothing about what is returned on success (e.g., an ID needed for later update/delete) or any 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 short sentences with zero filler; the action is front-loaded and the prerequisite follows immediately. Nothing in the description is redundant or 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?

For an 11-parameter creation tool with no output schema, the description is thin: it does not mention the scheduling window, page targeting, or credential fallback behavior, all of which materially shape a correct call. It is adequate because the schema is fully documented, but it leaves the agent to infer how the optional parameters interact.

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%, including enum values for broadcast_type and access-level meanings, so the schema carries parameter semantics fully. The description adds no parameter-level information beyond what is already documented, which is the expected baseline when coverage is complete.

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 ("Create a GitLab broadcast message"), which cleanly separates it from siblings like update_broadcast_message, delete_broadcast_message, and list_broadcast_messages. It does not explicitly name those alternatives, but the create/broadcast pairing 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 admin-privilege prerequisite is stated, which is genuinely useful before an agent attempts the call. However, there is no guidance on when to create vs. update an existing message, or on how scheduling (starts_at/ends_at) affects whether a new message is the right choice.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds genuine value by disclosing the write-permission/auth requirement, but it does not explain what happens on duplicate titles, how failures surface, or that the operation is non-idempotent — context the agent must infer.

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?

A single front-loaded sentence with no filler; the action is stated first and the prerequisite follows. It is efficient, though so terse that it forgoes the chance to add routing or behavioral 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile for a non-destructive mutation. Combined with the auth note, what remains missing (permission failure modes, non-idempotency implications) is minor for a straightforward create tool.

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

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

Schema description coverage is 100%, including the projectPath format example and the userCredentials env-token fallback, so the schema carries the parameter burden. The description only implies that a project and title are needed and adds no format or constraint detail beyond the schema — baseline 3.

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

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

States a specific verb and resource ('Create a new issue in a GitLab project') that clearly separates it from siblings like get_issues, update_issue, and delete_issue. It does not explicitly name or contrast against any sibling, but the verb+resource pairing 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 parenthetical prerequisite ('requires user authentication with write permissions') gives useful context for when the call will succeed, but there is no explicit guidance on when to use this versus update_issue or create_note, nor any exclusions. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the auth/permission requirement, which is genuinely useful context, but says nothing about what a repeat call does, what happens when the source branch is missing, or whether the MR is created as draft.

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?

A single front-loaded sentence with the auth caveat attached — zero waste and nothing buried. It is, however, thin enough that conciseness shades into under-specification rather than crispness.

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 an output schema present and full parameter coverage, the description needn't explain returns or fields. But for a mutating create tool, it leaves unaddressed obvious agent questions — duplicate-MR behavior, branch-missing failure, and draft support — so it is only minimally 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% and every parameter carries its own description, including the userCredentials env-token fallback, so the schema carries the burden. The description adds no meaning beyond that, which is the expected baseline-3 outcome at full coverage.

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

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

States a specific verb+resource ("Create a new merge request in a GitLab project"), which is unambiguous and clearly the write counterpart to update_merge_request. It does not explicitly differentiate itself from sibling write paths like execute_rest_write or the update variant, keeping it short of a 5.

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

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

The parenthetical "requires user authentication with write permissions" gives a real precondition for use, but there is no guidance on when to pick this tool versus update_merge_request or a generic REST write, and no exclusions. Usage is implied rather than stated.

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 this as a non-read-only, non-idempotent, non-destructive write, and the description adds the authentication requirement, which is valuable. It does not flag the practical consequence of non-idempotency (calling twice creates duplicate notes) or what happens on failure, which for a create tool would be genuinely useful.

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?

A single front-loaded sentence with no filler and the auth caveat immediately adjacent to the action. It is efficient, though the terseness leaves little room for the usage distinctions an agent would benefit from.

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

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

For a 6-parameter write tool with full schema coverage and no output schema, the description covers what the tool does and that auth is needed. It omits what the tool returns (note ID? body?) and the duplicate/retry behavior implied by non-idempotency, which leaves a moderate gap.

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

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

Schema description coverage is 100%, including the notable 'internal/confidential' visibility semantics and the noteableType enum, so the schema carries the parameter burden. The description adds only the issue/MR targeting hint, which the schema already states, so baseline 3 applies.

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

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

The description states a specific verb ('Add') and resource ('comment/note') plus the two target types (issue or merge request), which is enough to separate it from create_issue, create_merge_request and get_notes. It does not explicitly distinguish itself from update_note, but the 'add' framing makes the difference readable.

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 adds a real prerequisite ('requires user authentication'), which is useful context for an agent. However there is no when-to-use guidance relative to siblings like update_note or delete_note, and no note on how to choose between issue and merge_request targets beyond the enum in the schema.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds meaningful context beyond that: deletion cascades to all awarded and revoked instances and requires Maintainer/Owner permissions. It could further clarify irreversibility or response behavior, but the key behavioral risk is disclosed.

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

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

Two compact sentences with no waste. The destructive scope is front-loaded, followed by the permission requirement, making the most important facts immediately visible.

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 destructive delete tool with full schema coverage and explicit annotations, the description covers the essential cascade and authorization details. It does not describe the return value, but with no output schema this is a minor gap rather than a blocking omission.

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

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

Schema description coverage is 100%, and the schema already explains that achievementId accepts a numeric ID or GitLab GID and that userCredentials falls back to the environment token. The description adds no parameter-specific detail, so the baseline of 3 is appropriate.

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

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

States a specific verb (delete) and resource (group achievement), and adds scope detail: every related awarded or revoked instance. This clearly distinguishes it from sibling tools such as create_achievement, update_achievement, award_achievement, and revoke_achievement.

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 operational context by declaring the action destructive and requiring group Maintainer/Owner permissions. It does not explicitly say when to use revoke_achievement instead of deleting the whole achievement, but the scope difference is strongly implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is structured. The description adds the admin-requirement context, which the annotations do not carry, but says nothing about irreversibility, confirm-deletion behavior, or error responses.

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 short sentences, zero waste, with the resource and identifier front-loaded and the privilege constraint second. Nothing here could be trimmed without losing 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 single-entity delete with a fully described two-parameter schema, explicit destructive/idempotent annotations, and no output schema, the description covers what an agent needs to call it. Only the failure/missing-record behavior is unstated, which is a minor gap.

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

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

Schema coverage is 100%: both the integer `id` and the optional `userCredentials` fallback are fully documented in the schema. The description's "by ID" restates the schema and adds no format or behavioral detail beyond it, so 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?

The description names a specific verb and resource ("Delete a GitLab broadcast message") plus the lookup key ("by ID"), which separates it from get_broadcast_message and list_broadcast_messages. It does not explicitly route to update_broadcast_message or list_broadcast_messages, but the operation 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 admin privilege line implies a precondition for calling it, but the description never states when to use it versus alternatives (e.g., update to hide a message instead of deleting it) or what happens when the ID does not exist. Usage is only implied from the verb.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description earns credit for adding context the annotations lack: the authorization model (issue author or maintainer, user token). It stops short of stating that deletion is permanent or what happens to attached notes and todos.

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 short sentences with zero waste; the action comes first and the permission constraint follows immediately. Nothing is redundant with the name or title.

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

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

For a three-parameter destructive tool with full schema coverage and rich annotations, the definition covers purpose and authorization adequately. The remaining gap is minor: it never says the deletion is permanent and unrecoverable, which an agent weighing the call would want.

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

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

Schema coverage is 100%, and the schema itself explains iid, projectPath, and the userCredentials fallback, so the description carries no additional parameter burden. Baseline 3 applies since the description adds nothing beyond the structured fields.

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 ("Delete a GitLab issue"), which cleanly separates it from create_issue, update_issue, and delete_note in the sibling list. It does not explicitly call out sibling boundaries, but the verb+resource pairing 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?

Usage is implied by the verb, and the description adds a prerequisite (permission to delete). However it gives no when-not guidance — e.g., closing an issue instead of deleting it — and no note about confirming intent before an irreversible removal.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description adds useful permission context by stating the token must belong to the note author or a maintainer, though it does not discuss permanence or cascading 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 two sentences, front-loads the core action, and uses the second sentence for an important auth constraint. There is no redundant or wasted text.

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

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

For a simple destructive delete tool with full schema coverage and annotations covering destructiveness and idempotency, the description is nearly complete. It could mention irreversibility or error behavior for unauthorized tokens, but those gaps are minor given the structured metadata.

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

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

Schema coverage is 100%, and the schema fully documents noteId and userCredentials. The description only restates the credential requirement at a high level and adds no syntax or format details beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Delete a comment (note) on a GitLab issue or merge request.' This clearly distinguishes it from sibling tools such as create_note, update_note, get_notes, and other delete_* 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 provides clear context for use and an explicit prerequisite: the token must belong to the note author or a maintainer. It does not explicitly compare against update_note or state when not to delete, but the context is clear and has no misleading exclusions.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the agent knows this is not a safe repeatable read; the description adds genuine behavioral context about timeouts and pagination, which is not in the annotations. It does not disclose that arbitrary mutations can be issued, that mutations are write-gated, or anything about error/empty-result behavior, so it neither contradicts nor fully complements the annotation profile.

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

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

Three short sentences, front-loaded with the purpose, then the usage trigger, then the performance caveat – no filler. The embedded example with bracket notation is slightly noisy but still illustrative rather than wasteful.

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

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

There is no output schema, so the description could have said something about return shape or error semantics for arbitrary GraphQL, and it omits any pointer to get_available_queries/get_type_fields for discovering valid query structure despite those siblings existing. With 4 parameters including a nested credentials object, the definition is workable but leaves real gaps for an agent composing a query blind.

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 schema already explains query, variables, requiresWrite, and userCredentials. The description's example adds a small amount of extra meaning (labelName filtering, which is absent from the schema example), but it says nothing about variables or credentials handling beyond what the schema already states.

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

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

The description gives a specific verb and resource ("Execute custom GraphQL queries") plus a concrete example (issues filtered by assigneeUsernames/labelName), so an agent knows exactly what operation this performs. It does not distinguish itself from the low-level siblings execute_rest_read/execute_rest_write or explain how it relates to get_available_queries, so it falls short of full sibling differentiation.

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 an explicit trigger – "Use this for structured filtering by assignee/author/labels when search tools return 0 results" – and adds a performance caveat about pagination and query complexity. However, it never names the specific search alternatives (search_issues, get_issues, search_gitlab) nor says when NOT to use raw GraphQL, leaving the routing decision partly to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by calling this an arbitrary GET escape hatch and specifying that the path must omit host and /api/v4 prefix, though it does not discuss rate limits or 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?

The description is three tight sentences with the core purpose front-loaded, followed by path/query instructions and the write-tool alternative. Every sentence contributes directly to correct invocation.

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 generic REST escape hatch with no output schema, the description covers purpose, path format, query usage, and the write alternative. It does not explain authentication fallback or response format, but those are either schema-documented or inherently endpoint-dependent.

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 path, query, and userCredentials in detail. The description reinforces the path format and optional query object but does not add meaning beyond what the schema provides, making the baseline 3 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: execute an arbitrary GET request against the GitLab REST API at /api/v4. It explicitly frames the tool as an open-ended escape hatch for read endpoints not covered by dedicated tools, which distinguishes it from the many specific get_* siblings and from execute_rest_write.

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 clear when-to-use guidance: read endpoints not covered by a dedicated tool, with concrete examples such as repository files, pipeline test reports, and /admin/*. It also names the alternative for writes, execute_rest_write, so the agent knows when not to use this tool.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and non-idempotent, so the safety profile is covered structurally; the description reinforces it with "DELETE is permitted, so check the path" which tells the agent how to mitigate. It does not cover remaining behavioral unknowns such as required token scopes/permissions, rate limiting, or what an error from the underlying endpoint looks like.

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

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

Four short sentences, front-loaded with the operation and the destructive caveat, then the sibling routing, then nothing else. No restatement of the schema and no padding.

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

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

With annotations covering safety, a fully documented 5-parameter schema, and no output schema, the description covers the decision-relevant information for a generic escape hatch. The one gap is that it never says what comes back (raw GitLab response body vs. wrapped) or how non-2xx responses are surfaced, which matters for an arbitrary-endpoint tool.

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

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

Schema description coverage is 100% and the schema itself is unusually detailed (path must start with "/", no /api/v4 prefix or query string; body as JSON value or JSON-encoded string; credentials fall back to env token). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (execute) and resource (arbitrary GitLab REST write request at /api/v4) with the allowed methods enumerated in the first sentence. It explicitly distinguishes itself as an escape hatch for endpoints not covered by dedicated tools, which separates it cleanly from the long list of specific write siblings like create_issue or update_merge_request.

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

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

"Open-ended escape hatch for write endpoints not covered by a dedicated tool" states the selection condition, and "For reads, use execute_rest_read" names the alternative and the boundary that routes to it. It also adds a pre-invocation check ("check the path before invoking") tied to the destructive path, which is actionable guidance rather than filler.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered without the description. Beyond saying it reads the GitLab schema, the description adds no behavioral context: no indication of whether the result is a flat name list or full query signatures, whether it is filtered by permission/license, or how large it may be.

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?

One sentence, front-loaded with the verb and resource, with no filler or redundancy. It is tight but arguably under-specified rather than deliberately minimal, which keeps it from a 5.

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

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

For a zero-required-parameter discovery tool with full annotation coverage this is minimally adequate. However, with no output schema, the description should say what the agent gets back (names, signatures, categories) and how to act on it; that omission is the main gap.

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

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

There is a single optional parameter (userCredentials) with 100% schema description coverage, including the env-token fallback, so the schema carries the semantics. Per the high-coverage baseline, 3 is the ceiling without compensating detail in the description.

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

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

Specific verb plus resource: lists available GraphQL queries and mutations from the GitLab schema, which is clearly a schema-introspection operation rather than execution. It does not, however, differentiate itself from closely related siblings such as get_type_fields, resolve_path, or execute_custom_query, which an agent must reconcile on its own.

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?

There is no statement of when to reach for this tool versus execute_custom_query or get_type_fields, and no described workflow such as 'call this first, then execute a discovered query.' The name implies a discovery step, but nothing in the description confirms or constrains that usage.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the basic read operation, but it also does not contradict the annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. It is appropriately sized for a simple by-ID lookup tool.

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

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

For a simple read-by-ID tool with full schema coverage and annotations covering safety, the definition is largely complete. It could mention return shape or authentication fallback, but those are relatively minor for this operation.

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 'id' parameter is already documented in the schema. The description reinforces that the ID refers to a broadcast message, but it adds no syntax or format details beyond what the schema provides.

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

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

The description states a specific verb and resource ('Get a specific GitLab broadcast message') and clarifies lookup by ID. It is clear, though it does not explicitly distinguish itself from sibling tools like list_broadcast_messages.

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 phrase 'by ID' implies the tool is used when the broadcast message ID is known, but it does not explicitly compare against list_broadcast_messages or other sibling tools. Usage is inferable rather than stated.

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, idempotentHint and destructiveHint=false, so the safety profile is fully structured. The description adds the useful nugget that it resolves the identity from the authenticated session (no subject ID needed), but says nothing about which credential is used when both env token and userCredentials exist, or about failure behavior when unauthenticated.

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?

One short sentence, front-loaded with the verb and resource, zero filler. Nothing to trim.

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 zero-required-parameter read tool with an output schema, the description need not explain return values. It is nearly complete; the only meaningful omission is guidance on credential precedence and what 'current user' means when running under a service account token.

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 single userCredentials parameter already documents the env-token fallback, so the description adds no parameter-level meaning. Baseline 3 applies.

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

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

States a specific verb and resource ('Get information about ... user') and constrains it to the 'current authenticated' identity, which separates it from sibling lookups like search_users and get_project. It stops short of naming that distinction explicitly, so the differentiation is inferred rather than stated.

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

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

Usage is only implied: an agent can reasonably infer this is the tool for 'who am I / what account is this token tied to'. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as search_users for looking up other people.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds nothing behavioral beyond that — nothing about what happens for missing files, whether content is returned raw or truncated, how large files are handled, or how 'ref' defaults interact with retrieval.

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?

A single front-loaded sentence with the core action first. The trailing clause 'crucial for code analysis' is promotional filler rather than actionable guidance, which keeps it from a 5.

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

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

For a four-parameter read tool with full schema coverage and complete annotations and no output schema, the essentials are present. However, the description omits how to choose between this and browse_repository and says nothing about the shape of the returned content, leaving meaningful gaps for an agent.

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 all four parameters documented (projectPath, filePath, ref default HEAD, optional credentials). The description adds no syntax or semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the content of a specific file from a GitLab repository'), so an agent can tell it retrieves file contents rather than metadata. It does not explicitly distinguish itself from the sibling browse_repository, which likely overlaps, leaving some ambiguity.

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

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

The only usage cue is the vague phrase 'crucial for code analysis', which gives no condition for choosing this tool over browse_repository or execute_rest_read. No when-not-to-use, no prerequisites, no alternatives named.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds nothing further — it does not say whether subgroup projects are included, whether results are paginated by default, or what happens with a nonexistent fullPath.

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?

A single front-loaded sentence with no filler. It is efficient, though arguably so terse that it drops information an agent would want.

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?

Five parameters, one required, fully documented schema and annotations, and no output schema to explain. That covers the mechanics, but the description leaves open what a 'group project' includes (subgroups vs direct children) and how this differs from sibling listing tools — reasonable but incomplete for a listing endpoint.

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%, including detailed pagination semantics for `after` and the fullPath example, so the description need only mirror that. It mentions searchTerm filtering but adds no meaning beyond the schema, making 3 the correct 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?

Specific verb (List) plus resource (projects) and scope (inside a GitLab group), with the optional search filter noted. It does not distinguish itself from close siblings such as get_projects or search_projects, so an agent still has to guess which of the three to pick.

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?

No guidance on when this tool is preferred over get_projects or search_projects, nor on prerequisites (membership/permission level needed to list a group's projects). The parenthetical only restates the optional filter, which is already in the schema.

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/idempotentHint/non-destructive, so safety is covered; the description adds real value by disclosing the aggregation behavior, the maxNotes pagination cap, and the scope of 'related' MRs (mentioning only) versus closing MRs. It stops short of describing behavior when the issue is missing or whether notes are truncated silently, so not a 5.

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

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

Two sentences, both dense with information: the first front-loads what is returned, the second immediately routes the agent away from the fan-out alternative. 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?

With no output schema, the description usefully enumerates the response contents and relation types, which is the main thing an agent needs to know. Errors or behavior on a nonexistent/restricted issue are not addressed, a minor gap for a 5-param read tool.

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

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

Schema description coverage is 100%, so all five parameters including maxNotes and includeSystemNotes are already documented in the schema. The description only alludes to the maxNotes cap, adding marginal 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?

States a specific aggregation verb and enumerates exactly what is bundled: issue body, notes, related/closing merge requests, linked issues with relation types. This is clearly distinguishable from get_issues, get_notes, and search_merge_requests, which return only one slice each.

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 'instead of fanning out across get_issues + get_notes + search_merge_requests when investigating an issue', naming the alternatives and the condition that selects this tool. Little is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so '(read-only)' merely repeats structured data. The description adds nothing about pagination behavior, result completeness, or auth fallback — all of which live only in the schema, not the description.

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?

A single front-loaded clause with zero filler. It is efficient, though it is arguably too terse for a six-parameter tool with non-obvious pagination tradeoffs.

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?

An output schema exists and the schema documents pagination and the fetchAll-vs-after tradeoff, so much of the burden is carried elsewhere. Still, the description alone gives an agent no sense of result paging or that fetchAll is capped at 100, leaving it minimally viable rather than 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 every parameter (sort, after, first, fetchAll, projectPath, userCredentials) is already documented thoroughly, including pagination semantics. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get issues') and narrows scope to a specific GitLab project, which distinguishes it from get_user_issues and search_issues. It does not explicitly name those siblings or explain the boundary, so it stops short of a 5.

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

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

There is no statement of when to use this versus search_issues, get_user_issues, get_issue_context, or list_work_items, and no preconditions or exclusions. The parenthetical '(read-only)' is the only usage-adjacent cue.

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/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds a real behavioral fact beyond the schema: merge commits are excluded, which affects counts and results. It says nothing about auth or rate limits, so not a 5.

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

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

A single sentence with zero filler, front-loading the action and resource and appending the one non-obvious constraint (merge commits excluded). Nothing to trim.

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 should say more about what comes back; 'with commit count and details' is vague about response shape (list of commits plus total?). Pagination and fetchAll caveats live only in the schema, so an agent reading just the description lacks the completeness picture.

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%, including detailed pagination semantics for 'after'/'first'/'fetchAll', so the schema carries parameter meaning. The description adds no syntax or format guidance beyond what the schema already states — 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?

States a specific verb and resource (get commits for a merge request) plus a meaningful scope qualifier: merge commits are excluded. An agent can distinguish it from get_merge_request_diffs or get_merge_request_pipelines without opening the schema, though no sibling is named explicitly.

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

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

Usage is implied by the resource name — call it when you need the commit list of a known MR — but there is no explicit when-to-use/when-not or named alternative (e.g., versus get_merge_request_context or the diffs tool). The agent must infer selection from the tool name.

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, idempotentHint=true, and destructiveHint=false, so safety is covered structurally. The description adds useful behavioral context the annotations do not: notes are paginated up to maxNotes and system notes are excluded by default, which tells the agent the result may be a filtered/truncated view. It stops short of saying what happens when the cap is hit (truncation signal, ordering), so it is strong but not complete.

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

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

Two sentences, zero filler. The inventory of bundled data comes first and the disambiguation rule second, which is the right order for an agent deciding whether to call it.

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

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

There is no output schema, so the description carries the burden of describing the return shape, and it does so by enumerating the bundled sections. That is sufficient for an agent to know what comes back, though it does not describe nesting or per-section shapes, leaving a small gap for a multi-section aggregate tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by calling out the pagination cap (maxNotes) and the default non-system-notes filtering, reinforcing the two behavioral parameters beyond their inline schema text. It does not explain maxCommits or the credential fallback, but the schema covers those.

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 ("Bundle") and enumerates exactly what is bundled: MR body, notes, commits, pipeline summary, reviewers with approval state, and closing issues. It names the sibling tools it replaces, so an agent can distinguish it from get_merge_requests, get_notes, or get_merge_request_commits without opening a schema.

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

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

It gives an explicit routing rule: "Use this instead of fanning out across get_merge_requests + get_notes + get_merge_request_commits + get_merge_request_pipelines when investigating an MR." That names both the alternative tools and the condition (investigating an MR) that selects this one.

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 this as a safe read-only, idempotent, non-destructive operation. The description adds useful context by specifying that it returns diff statistics and diff refs rather than full diff content, but it does not describe pagination, response shape, or any limits 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 a single efficient sentence with the core purpose front-loaded. It contains no redundant or filler language.

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

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

For a simple read-only retrieval tool with fully documented parameters and annotations covering safety, the description gives an adequate high-level account of the returned data. It does not fully specify the response structure, but with no output schema present, this is a minor gap rather than a blocking omission.

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

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

Schema description coverage is 100%, so the schema already documents projectPath, iid, and optional userCredentials. The description adds no additional parameter semantics or constraints beyond what the schema provides, which is the baseline expectation.

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

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

The description gives a specific verb and resource: get diff statistics for a merge request. It also identifies the returned content as per-file additions/deletions and diff refs, making the purpose clear, though it does not explicitly distinguish itself from related siblings such as get_merge_request_context or browse_repository.

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

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

The description states what the tool returns but gives no guidance on when to use it versus alternatives. It does not mention prerequisites, exclusions, or related tools, so the agent must infer usage from the name and purpose alone.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that results include status, duration and stages, which is useful return-shape context, but says nothing about pagination behavior or result limits (those live only in the schema).

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

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

A single front-loaded sentence with zero filler that immediately conveys the resource and the payload contents. Nothing could be removed without losing information.

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

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

For a read-only list tool with full annotation coverage and a rich schema, the description is nearly sufficient: it states the source, scope and returned fields. The only minor gap is not hinting that results are paginated, though the schema documents that thoroughly.

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 detailed guidance on after/first/fetchAll pagination and credential fallback, so the description adds no parameter meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Get) and resource (CI/CD pipelines) scoped to a merge request, plus names the returned fields (status, duration, stages). An agent can distinguish it from get_pipeline_jobs and manage_pipeline, though it does not name those siblings explicitly.

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

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

No explicit when-to-use guidance, no alternatives named, no prerequisites. Usage is only implied by the phrase 'for a merge request', leaving the agent to infer that this is the read-only listing counterpart to manage_pipeline and get_pipeline_jobs.

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds that the result includes approval status and review states, but says nothing about pagination, ordering, or whether unapproved reviewers are included.

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?

A single front-loaded sentence with the resource and the returned content; nothing is wasted. It is slightly terse for a tool whose output shape an agent must anticipate, but it is 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?

With no output schema, the description carries the burden of describing return data, and it does so at a high level (approvers, review states). Given 100% schema coverage and full annotation coverage, the remaining gap — exact return structure — is minor.

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

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

Schema description coverage is 100%, so projectPath, iid and userCredentials are already documented in the schema. The description contributes no parameter-level meaning beyond that, which matches the baseline-3 expectation when the schema does the heavy lifting.

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

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

Clear specific verb+resource: 'Get approval and reviewer status for a merge request', with added detail on what is returned (who approved, review states). It distinguishes itself from siblings like get_merge_request_context or get_merge_requests implicitly, but never names an alternative to sharpen the boundary.

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

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

Usage is implied by the purpose — an agent needing approval/reviewer data would pick this. However, there is no explicit when-to-use guidance or comparison against related tools such as get_merge_request_context, so the selection relies on inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description merely repeats '(read-only)' and adds no further behavioral context such as pagination behavior, default sorting, or fetchAll limitations.

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 short sentence with no wasted words and is front-loaded. However, its extreme brevity leaves important usage context unstated, which borders on under-specification rather than optimal 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?

An output schema exists and the input schema is fully documented, so return values and parameters need not be explained. Still, for a list tool surrounded by many merge-request siblings, the description should at least indicate when this project-scoped listing is preferable to search_merge_requests or get_user_merge_requests.

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 thoroughly, including pagination and fetchAll caveats. The description adds no parameter-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb and resource (get merge requests) and scopes it to a specific GitLab project. It is clear what the tool does, but it does not distinguish itself from sibling tools like search_merge_requests or get_user_merge_requests.

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 no guidance on when to use this tool versus alternatives such as search_merge_requests, get_user_merge_requests, or get_merge_request_context. The only usage signal is the read-only nature, which is already covered by annotations.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope detail by noting that system notes and inline MR comments are included, but it does not discuss permissions, pagination behavior, or rate limits beyond what the schema already says.

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 front-loaded sentence with no redundant or filler content. Every phrase adds relevant scope 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 rich schema and read-only annotations, the description is largely complete for selecting and invoking the tool. The main gap is the absence of usage guidance relative to sibling tools like search_notes, but the core retrieval behavior is 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 all seven parameters are already documented in the schema. The description reinforces the issue/merge-request targeting but does not add syntax, format, or filtering 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 uses a specific verb and resource: 'Get notes (comments)' on an issue or merge request, and it clarifies that system notes and inline MR comments are included. It is clear what the tool does, though it does not explicitly distinguish itself from the sibling search_notes 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 states what the tool retrieves but gives no explicit guidance on when to use it versus alternatives such as search_notes, nor does it mention prerequisites like project access. Usage is only implied by the issue/MR context.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds that returned job records carry status, stage, duration and retry/cancel info, which is useful, but it stays silent on ordering, pagination behavior, and auth fallback — though the schema covers the latter two.

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?

A single tight sentence with the core operation front-loaded and the return contents tacked on compactly. Nothing wasted, nothing buried.

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 brief enumeration of returned job fields is genuinely valuable. The main gap is that pagination semantics — the schema's most important behavioral nuance — aren't echoed in the description, but the schema spells it out thoroughly.

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%, including the pagination/vs-fetchAll tradeoff and credential fallback, so the baseline is 3. The description contributes no additional parameter meaning beyond what the schema already states.

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

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

Specific verb+resource: 'Get jobs for a specific pipeline', plus an enumeration of what the payload contains (status, stage, duration, retry/cancel). It doesn't distinguish itself from pipeline-related siblings like manage_pipeline or get_merge_request_pipelines, but the resource 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?

Usage is implied — you call it when you have a projectPath and pipelineIid and want that pipeline's jobs. There is no explicit when-to-use/when-not, no mention of pagination strategy, and no routing away from manage_pipeline or get_merge_request_pipelines.

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)' suffix merely restates readOnlyHint=true, so it earns no credit beyond the annotations. Nothing is said about lookup failure behavior for unknown fullPath, permission requirements on private projects, or whether the call is cached — the description adds essentially nothing over structured fields.

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

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

A single front-loaded sentence with no padding and no waste. It is appropriately sized for a simple getter, though the trailing parenthetical is redundant filler against the annotations.

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?

An output schema exists, annotations cover safety and idempotency, and both parameters are fully documented, so the definition is minimally callable. Still missing is the retrieval scope relative to list/search siblings, which is the one thing an agent must resolve before choosing this tool.

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

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

Schema description coverage is 100%, including the fullPath example format and the userCredentials env-token fallback, so the schema already carries parameter meaning. The description contributes nothing further about either parameter, which is the expected baseline at full coverage.

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

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

States a specific verb and resource: 'Get detailed information about a specific GitLab project'. An agent can distinguish it from get_projects (plural list) and search_projects by name alone, but the description never names those siblings or contrasts scope, so differentiation is left to inference.

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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as get_projects / search_projects / get_project_statistics, all of which are plausible near-neighbors in the sibling list. The only hint is the implied 'specific project' 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 declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds genuinely non-schema information: results are limited to what the authenticated user can see, and private projects require auth. Pagination behavior is left entirely to the schema rather than repeated here, which is acceptable.

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?

One short, front-loaded sentence with no filler or repetition of schema detail. It is efficient, though arguably thinner than a 5-parameter listing tool warrants.

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?

An output schema exists and parameters are fully documented, so return values and inputs need no prose. The remaining gap is selection context: with get_project, get_group_projects, and search_projects as siblings, the definition never clarifies which listing scope this returns.

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 each parameter (sort, after, first, fetchAll, userCredentials) is thoroughly documented in-schema. The description adds no parameter meaning of its own, so the baseline 3 applies.

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

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

Clear verb+resource ("List projects") plus a scope qualifier ("accessible to the user"). It does not distinguish itself from nearby siblings such as get_project, get_group_projects, or search_projects, so an agent must infer the boundary itself.

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

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

The only guidance is a precondition ("requires authentication to see private projects"), not a when-to-use rule. There is no mention of when to prefer get_group_projects (scoped listing) or search_projects (filtered lookup) over this general list.

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 carry readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the shape of the result (a bundle of aggregate counts plus last pipeline status and language breakdown), which matters because there is no output schema. It does not mention whether private-project metrics need elevated scopes or that the call fans out across multiple endpoints.

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?

A single front-loaded sentence with a verb, the resource, and a compact enumeration of returned fields. No filler, no restatement of the title.

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

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

With no output schema, the field enumeration substitutes effectively for a return-value section, and annotations cover the safety contract. What's missing is minor: expected cost/latency of an aggregation call and whether results are cached or point-in-time.

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% — projectPath is documented with a concrete 'group/project-name' example and userCredentials is documented with the env-token fallback. The description adds nothing about either parameter, so the schema does all the work; 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?

Names a specific verb (get) and resource (aggregate project statistics) and enumerates the exact metrics returned — open issues/MRs, stars/forks, storage, commits, pipeline status, releases, languages. That enumeration is what separates it from get_project (single-project detail) and the analytics_* siblings, though it never names those alternatives explicitly.

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

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

There is no explicit when-to-use/when-not-to-use statement and no reference to any sibling tool. Usage is only implied by the word 'aggregate' and by the count-oriented field list, which suggests a rollup rather than a detail fetch. An agent must infer the routing decision itself.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is handled. The description adds the useful detail that estimate, spent, and timelogs are all returned, but says nothing about authentication behavior, permissions needed, or that totals require full pagination.

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?

A single front-loaded sentence naming the verb, the resource, the returned data, and the applicable resource types. Zero filler; every clause carries information.

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

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

For a read tool with no output schema, the description names the three data categories the caller receives, which is the main gap it needed to fill. Minor omission: it doesn't signal that pagination is required for accurate totals, though the schema's cursor parameter text covers that.

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 seven parameters including pagination, resourceType enum, and credential fallback are already documented. The description's list of returned data categories loosely maps to includeTimelogs but adds no syntax or format detail 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 (Get) and resource (time tracking) and enumerates the returned fields (estimate, spent, timelogs), scoped to an issue or merge request. No sibling tool covers time tracking, so differentiation is implicit rather than stated.

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 scopes usage to issues or merge requests, which tells the agent where the tool applies, but it gives no when-to-use vs. when-not guidance and no mention of when to set includeTimelogs versus pulling only totals.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the operational prerequisite that introspection must have run first. It does not describe the error behavior when the schema is not introspected or what the returned field entries contain.

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?

A single sentence with the action and prerequisite front-loaded and no filler. The trailing parenthetical is slightly redundant with itself, but nothing is wasted.

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

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

For a simple read-only introspection helper with full schema coverage and complete annotations, the definition covers what the tool does and its prerequisite. No output schema exists, so a hint about the shape of the returned field list would help, but the core is present.

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

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

Schema description coverage is 100%, so typeName and userCredentials are already documented in the schema, including the env-token fallback for credentials. The description adds no syntax, naming-convention, or lookup details beyond what the schema provides, so baseline 3 applies.

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

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

Uses a specific verb 'List' with a precise resource 'available fields on a GraphQL type', and names the mechanism (introspected schema). It is distinguishable from data-fetching siblings, though it does not explicitly point at the closest relative, get_available_queries.

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 parenthetical states a real prerequisite (schema must already be introspected), which is useful context for when the call will succeed. However, it gives no guidance on when to choose this over get_available_queries or other schema-exploration paths, leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the GraphQL-filtering claim, but omits behaviorally significant facts: results are paginated (default 20, max 100) and 'all issues' is only true if the caller paginates, which is disclosed only in the schema.

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

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

A single front-loaded sentence with the core scope stated first. The trailing clause about GraphQL filtering is a soft claim rather than actionable detail, so it does not fully earn its place, but nothing is bloated.

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 7 parameters, no output schema, and a default that returns only 20 of possibly many issues, the description should warn that completeness requires pagination and should position this tool against get_issues/search_issues. Those gaps are partially mitigated by unusually rich schema descriptions.

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 pagination/fetchAll/state/credentials params are documented in detail in the schema itself. The description adds no parameter-level meaning beyond the verb, so the baseline 3 applies.

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

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

States a specific verb and resource (get issues) with an explicit filter (assigned to a specific user) and names the underlying mechanism (GraphQL filtering). However, it does not distinguish itself from near-identical siblings like get_issues or search_issues, so an agent must guess between them.

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?

No explicit when-to-use guidance and no named alternatives, despite the sibling list containing get_issues, search_issues, get_issue_context, and get_user_merge_requests. The phrase 'for reliable results' hints at a preference over another tool but never says which one or when.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds nothing behavioral beyond that — no note about the default 'opened' state, default page size, or the fact that `fetchAll` is not exhaustive; that critical caveat lives only in the schema. 'Uses proper GraphQL filtering' is unexplained filler.

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?

It is a single short sentence and front-loads the resource, which is good. But the dangling '- uses proper GraphQL filtering' does not earn its place; it neither guides selection nor explains behavior.

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, fully-documented listing tool with no output schema, the description plus schema give an agent enough to call it correctly — pagination, defaults and limits all live in the schema. The only real gap is the absence of sibling routing guidance against `get_merge_requests`.

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

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

Schema description coverage is 100%, so all eight parameters including the pagination cursor and fetchAll caveat are documented in the schema. The description only restates the author/assignee duality already captured by the `role` enum, adding no syntax or format detail on top.

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 with its defining scope: merge requests for a specific user, either as author or assignee. That clearly separates it from the general `get_merge_requests` sibling, though the description never names that sibling to make the contrast 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?

There is no statement of when to prefer this over `get_merge_requests` or `search_merge_requests`, and no exclusions or prerequisites. The trailing clause 'uses proper GraphQL filtering' hints at a reliability advantage but never explains what it means for the caller.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description earns credit for adding the return shape: the raw widgets array and which fields it exposes (epic hierarchy, health, iteration, milestone, dates). That is real behavioral context an agent cannot get from the annotations, though nothing is said about auth fallback or errors.

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

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

Three sentences, front-loaded with the action and identifier, then return shape, then accepted id formats. No filler and nothing buried.

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 usefully explains what comes back (raw widgets) and for a 2-parameter read tool that is nearly sufficient. The only meaningful gap is routing guidance relative to sibling tools like list_work_items or get_issue_context.

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

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

Schema description coverage is 100%, and the description only restates the numeric-or-gid format already documented in the `id` schema field. It adds no help beyond the schema for the optional credentials parameter, 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?

States a specific verb and resource ('Fetch a GitLab work item ... by global ID') and enumerates the concrete subtypes it covers (issue, task, epic, incident, OKR). This distinguishes it from the many sibling list/search tools that also return issue-like data.

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

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

The 'by global ID' framing implies single-item lookup versus the list_work_items / get_issues / search_issues siblings, but the description never explicitly says when to use this instead of them or what prerequisites apply. Usage is inferred rather than stated.

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/idempotentHint/non-destructive, so the safety profile is covered; the description goes beyond that by disclosing an instance-level enablement requirement and the single-page semantics of the recipient previews. It leaves out auth fallback behavior (covered by the schema) and any rate-limit or result-size caveats.

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

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

Three short sentences with zero filler: purpose first, then the hard prerequisite, then the one non-obvious semantic caveat. Every sentence carries usable 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 7-parameter read tool with no output schema, the definition covers purpose, prerequisite, pagination model, and the subtle preview behavior — enough to call it correctly. It is slightly thin on what the returned achievement records contain, though the annotations relieve it of explaining safety.

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 86%, so the baseline is 3; the description earns an extra point by disambiguating includeRecipients — clarifying that each achievement gets only one page of recipient previews and that each preview carries its own pageInfo, which prevents an agent from assuming previews are fully paginated. It adds nothing for the remaining parameters, which the schema already documents well.

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

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

States a specific verb and resource ("List group achievements") plus the retrieval mechanism (cursor pagination), which distinguishes it from the mutation siblings like create_achievement, award_achievement, and revoke_achievement. It never names a sibling or a scope boundary explicitly, so it falls short of a 5.

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

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

Adds a real precondition ("Requires Achievements to be enabled on the GitLab instance") and signals that recipient previews are a bounded single page rather than a full expansion, which helps an agent decide whether to set includeRecipients. However, there is no explicit when-to-use/when-not-to-use guidance and no named alternative among the many list_* and search_* siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, and the description's "Read-only" merely restates them. It adds the useful scope note that results are instance-wide, but omits permission requirements, pagination behavior beyond the schema defaults, and whether the list is ordered — all relevant for a paginated admin-level feed.

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 short sentences, scope stated first, zero padding. Nothing could be removed without losing 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 zero-required-param list tool with fully documented schema and safety annotations, the definition covers what the resource is and its read-only nature. The one meaningful gap is the admin/credential requirement, which the userCredentials parameter hints at but the description never confirms.

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 every parameter (page, perPage, userCredentials) is documented in the schema with defaults and bounds, so the description needs to add nothing and adds nothing. Baseline 3 applies.

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

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

Clear verb+resource ("List all GitLab broadcast messages") with a parenthetical that explains the domain concept ("instance-wide announcements"). This distinguishes it from the singular get_broadcast_message and the create/update/delete siblings by implication, though it never names those siblings explicitly.

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

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

Usage is only implied: you call it to enumerate broadcast messages. There is no statement of when to prefer get_broadcast_message (single record) over this list, and no note that broadcast messages are typically admin-scoped in GitLab, which materially affects whether an agent should attempt the call.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that results include access levels, which is useful context, but says nothing about pagination behavior or the fetchAll-vs-after tradeoff that dominates this tool's semantics.

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

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

A single front-loaded sentence with no filler. It is efficient, though its terseness means some of the tool's real complexity (paging, fetchAll) is left entirely to 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 read-only listing tool with a fully documented schema and explicit annotations, the description covers what the tool returns and its filter. Pagination nuance lives in the schema, so nothing critical is missing, though a one-line note on paging would make it complete.

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

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

Schema description coverage is 100%, so all six parameters are documented in the schema, including the pagination and credential fallback semantics. The description only restates the search filter, adding no syntax or defaults beyond the schema — baseline 3 applies.

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

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

States a specific verb (List) and resource (group members) plus what is returned (access levels) and an optional filter. It does not distinguish itself from nearby siblings such as search_users or get_group_projects, but the resource 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 word 'optionally' hints at the filtered/unfiltered modes, but there is no explicit when-to-use guidance, no mention of prerequisites (needing groupPath scope or credentials), and no pointer to alternative tools when the agent wants cross-group user search.

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 establish that this is a safe, read-only, idempotent operation. The description adds two relevant behavioral facts beyond annotations: it returns cadence information and requires a Premium or Ultimate GitLab tier. It omits pagination behavior, but that is fully documented in the schema.

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

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

The definition is two sentences, front-loads the core operation, and adds the licensing prerequisite without padding. Every phrase carries useful information for an agent deciding whether and how to call the tool.

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

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

For a six-parameter read-only tool with rich schema descriptions, the definition supplies the essential purpose, return hint ('cadence info'), and licensing prerequisite. It does not detail return values, which is a modest gap because no output schema exists, but the schema already covers all parameter-level behavior an agent needs.

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 six parameters, including pagination, state filtering, groupPath, and credentials fallback, are already documented in the input schema. The description adds only the implicit notion that a group is required and does not provide parameter 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 gives a clear verb and resource: 'List iterations (sprints) for a group with cadence info.' It also clarifies that iterations are sprints, which helps disambiguate from milestone-related siblings, but it does not explicitly differentiate itself from the nearby list_milestones 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 only contextual guidance is the licensing prerequisite ('Requires GitLab Premium/Ultimate'), which is useful but does not explain when to choose this tool over alternatives. There is no mention of when not to use it, how it relates to milestone listing, or what to do if the feature is unavailable.

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, idempotentHint and destructiveHint=false, so safety is covered by structured data. The description adds one real piece of beyond-schema behavior — that results include aggregated progress statistics rather than raw milestone records — but says nothing about the pagination/accuracy caveat or whether the aggregate respects the state/search filters.

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?

A single sentence with zero filler, front-loading the verb and scope before the payload detail. Nothing repeats the name or the annotations.

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 9 parameters, two of them pagination-related and one a credential object, the schema and annotations do most of the work and the description needn't restate them. The remaining gap is small but real: it doesn't clarify whether the progress statistics are computed over the filtered result set (state/search/includeAncestors) or the full milestone set.

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 parameter docs are unusually strong (pagination cursor loop, fetchAll non-exhaustiveness, state enum values, fullPath/isProject coupling). The description adds no parameter meaning of its own; baseline 3 is correct when the schema carries this much.

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?

Specific verb ('List') plus resource ('milestones') plus the two scopes it supports (project or group), and it adds a distinct payload detail: progress statistics with total/closed issue counts. No sibling tool lists milestones, so an agent can place it unambiguously.

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

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

Usage is implied by the resource ('for a project or group'), but the description names no alternatives and gives no when-to-use vs when-not guidance (e.g., versus get_project_statistics or get_issues for issue-level data). The agent must infer the boundary from the tool name.

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, idempotentHint and destructiveHint=false, so safety is covered externally. The description adds useful context that user authentication is required and what event categories come back, but says nothing about pagination behavior or volume, and "requires user authentication" sits slightly uneasily with the optional userCredentials parameter.

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

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

Three short clauses with the resource and its contents front-loaded; no filler. The auth sentence is brief and earns its place as a prerequisite note.

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 nine optional parameters, four enums and no output schema, the description covers purpose and auth but omits any hint of the filtering/paging surface or result shape. It is adequate to identify the tool, but thin for a tool whose value depends on filter combination.

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 four enum parameters are fully documented in the schema, so the baseline of 3 applies. The description contributes no additional meaning about filters (action, target_type, scope, after/before) or paging beyond what the schema already states.

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

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

Names a specific verb and resource ("List the authenticated user's GitLab activity feed") and enumerates the event kinds returned (pushes, MRs, comments, approvals, issue actions). The scope word "authenticated user's" implicitly separates it from list_user_events and list_project_events, but it never names those siblings explicitly.

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

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

"Primary tool for 'what did I just do'" gives a use-case cue, which is better than nothing. However, there is no when-not guidance and no routing to nearby alternatives such as list_user_events (other users), list_project_events (project-wide), or list_my_todos (actionable items), so the agent must infer selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral detail — the authentication requirement — but does not mention pagination behavior or result shape beyond what the schema already exposes via the after/fetchAll params.

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

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

Three compact, front-loaded sentences that define the resource, enumerate filters, and flag the auth prerequisite. Slight looseness from 'etc.' but no wasted sentences.

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

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

For a 12-param read-only list tool with no output schema but full schema coverage and safety annotations, the description covers purpose, filter scope, and auth. It omits pagination/return expectations, but the schema's after/fetchAll descriptions handle that, so it is largely 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 12 parameters thoroughly. The description only names the filter categories (state, action, target type, group/project), which largely restates schema content without adding format or interaction guidance, so baseline 3 applies.

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

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

States a specific verb (List) and resource (authenticated user's GitLab to-do items), and clarifies what a to-do is with concrete examples (issues, MRs, mentions, reviews requested). Clear enough to distinguish from read tools like get_issues, but it does not explicitly name the mutation siblings (mark_todo_done, restore_todo) that share the resource.

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 filter dimensions imply when to reach for this tool, and 'Requires user authentication' flags a precondition. However, there is no explicit when-not guidance or routing to alternatives (e.g., use mark_todo_done to modify, list_my_events for activity rather than to-dos), leaving selection to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context by naming the event types returned, but says nothing about pagination behavior, result caps, or permission requirements.

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

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

Two tight sentences with the resource scope front-loaded and the identifier format immediately after. 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 read-only list tool with full schema coverage and annotations covering safety, the description gives an agent enough to call it correctly. The only small gap is omitting how results are shaped or paged, but with no output schema and rich parameter docs this is minor.

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

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

Schema description coverage is 100%, so all nine parameters are documented in the schema, including enums for action, target_type, and sort. The description only restates that 'project' accepts a full path or numeric ID, adding nothing 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 (list) and resource (activity events) scoped to a single GitLab project, and enumerates the event categories (commits, MRs, issues, notes). The 'single project' scoping distinguishes it from siblings like list_user_events and list_my_events.

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 single-project scope implies when this tool applies, but it never explicitly names an alternative (e.g., list_user_events for cross-project activity) or states exclusions. Usage must be inferred from scope wording alone.

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, idempotentHint and non-destructive, so safety is covered. The description adds one genuinely useful behavioral detail — only *public* activity is returned — but says nothing about pagination or result volume beyond what the schema shows.

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

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

Two tight sentences, front-loaded with the scope and then the purpose. No filler, though the second sentence adds little beyond what the first already implies.

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

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

For a read-only list tool with a fully described schema and clear annotations, the main missing piece is mention of the filtering capabilities (date range, action, target type) and pagination, which an agent would only learn from the schema.

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

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

Schema description coverage is 100%, so all nine parameters including enums for action, target_type and sort are already documented. The description only echoes the `user` format (username or numeric ID), adding no new parameter meaning.

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

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

States a specific verb and resource (list a user's activity feed) plus the identifier forms accepted. The phrase "a specific user's" implicitly separates it from list_my_events and list_project_events, but no sibling is named explicitly.

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

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

"Use for tracking what a teammate has been working on" gives one positive usage context, but there is no guidance on when to prefer list_my_events or list_project_events, or any prerequisite/exclusion.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the pagination model (cursor plus fetchAll) and the filter dimensions, which is useful context beyond annotations. However, it says nothing about ordering behavior, cross-subgroup scope for a group fullPath, or what the response contains despite there being 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?

Two sentences, front-loaded with the resource and its scope before the optional capabilities. Every clause maps to a real capability (filters, pagination) and there is 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?

With 8 parameters, no output schema, and no return-value documentation, the description should carry more weight than one line on filters and pagination. It never states whether a group fullPath includes descendant projects or what a page of results looks like. Annotations cover safety, but result-shape and scope semantics are left open.

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 every one of the 8 parameters is documented in the schema itself. The description restates the type and state filters but omits two valid enum members (TEST_CASE, REQUIREMENT) and adds no format or syntax detail for after/first/fetchAll. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource (list work items) and pins the scope to a namespace fullPath, which implicitly separates it from get_work_item and the search_* tools. It enumerates the type and state filters, so an agent knows this is the namespace-scoped work item lister. It never names a sibling outright, so the differentiation is inferred rather than 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?

Usage is only implied: 'within a namespace' plus the supported filters tells an agent roughly when this fits, but there is no statement of when to prefer search_issues, get_issues, or get_work_item instead. No prerequisites or exclusions are mentioned. It is adequate but leaves routing decisions to inference.

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

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

Annotations already declare non-read-only, non-idempotent, and non-destructive behavior. The description adds useful auth context (write permissions required), but does not explain the side effects of retry/cancel or what the response contains.

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?

A single sentence, front-loaded with the actions and resource, with a brief parenthetical auth note. There is no wasted text.

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

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

For a simple two-action mutation with fully described parameters and safety annotations, the description covers purpose and authentication. It omits return/effect details, but with no output schema and annotations covering safety, this is a minor gap.

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