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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds valuable context beyond annotations, such as 'In-flight jobs will be interrupted' and that cancelling a finished pipeline is a no-op. This complements the destructive hint without contradicting annotations.

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

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

The description is concise, with the main purpose in the first sentence. It uses a short paragraph structure, includes a clear example, and avoids unnecessary detail. Every sentence adds value.

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

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

Given the tool's complexity (2 parameters, simple behavior) and the presence of both annotations and an output schema, the description is complete. It covers purpose, usage, side effects, and provides a concrete example, leaving no ambiguity.

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

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

The input schema has 100% coverage with clear descriptions for both parameters (pipeline_id and project_path). The description does not add extra semantic meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a running pipeline' and specifies that in-flight jobs are interrupted. It distinguishes the tool from siblings like gitlab_retry_pipeline by noting that cancelling a finished pipeline is a no-op.

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

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

The description provides explicit guidance on when to use the tool (to cancel a stuck or running pipeline) and when not to (for finished pipelines). It also directs the user to gitlab_retry_pipeline as an alternative, fulfilling the when-to-use/alternatives criteria.

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

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

Discloses limit of 30 commits and that it returns changed files. Annotations already indicate readOnly and idempotent; description adds behavioral detail without contradiction.

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

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

Concise, front-loaded with purpose, then usage guidance and examples. No irrelevant content.

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

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

Covers purpose, usage, exclusions, and behavioral limits. Output schema exists, so return format need not be explained. Complete for a comparison 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 covers all 3 parameters with descriptions (100% coverage). Description adds only usage examples for source and target, not new semantic detail. Baseline 3 is appropriate.

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

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

Clearly states it compares two branches and returns commits (up to 30) and changed files. Provides a concrete use case (release-note drafting) and differentiates from sibling gitlab_get_merge_request_changes.

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

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

Explicitly tells when to use (comparing branches, release notes) and when not to use (full MR diffs, with alternative tool named). Includes examples with parameters.

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 indicate idempotentHint=false, readOnlyHint=false. The description adds the clear warning that it's not idempotent and creates a new MR each call, which aligns with and reinforces the annotations. No contradictions.

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

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

The description is concise and front-loaded with the core purpose. It includes important warnings and examples in a structured manner. Slightly more structured formatting could improve it, but it's efficient.

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

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

Given the tool has 7 parameters (1 required), 100% schema coverage, and an output schema, the description covers key behavioral aspects: non-idempotence, duplicate avoidance, and alternative tools. It does not mention permissions or return values, but the output schema exists, so it's fairly complete.

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

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

Schema coverage is 100%, so all parameters have descriptions in the schema. The description provides examples that illustrate parameter usage but does not add significant new semantic meaning beyond the schema.

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

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

The description clearly states it creates a merge request from source_branch to target_branch. It distinguishes from siblings by advising not to use for merging an open MR (use gitlab_merge_mr) and suggesting to check existing MRs via gitlab_list_merge_requests to avoid duplicates.

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 provides when to use (create a new MR), when not to use (don't use to merge an open MR), and suggests checking for duplicates first via gitlab_list_merge_requests. Also names the alternative gitlab_merge_mr for merging.

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

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

Discloses non-idempotent behavior ('duplicate calls create duplicate schedules with auto-incrementing IDs'), which goes beyond annotations. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false).

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

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

Concise: one-line purpose, a behavioral note, and two well-structured examples. Front-loaded with key information, every sentence adds value.

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

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

Given 7 parameters and nested objects, the description covers purpose, non-idempotency, usage alternative, and a practical example. Output schema exists, so return values need not be described.

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

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

Input schema has 100% coverage with clear descriptions. The description adds an illustrative example showing parameter usage together, enhancing practical understanding beyond schema alone.

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

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

The description clearly states 'Create a new CI/CD schedule' with specific verb and resource, and differentiates from sibling tools by explicitly noting not to use for updates, referencing gitlab_update_schedule.

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 warns 'Don't use to update existing schedules — use gitlab_update_schedule instead', and notes non-idempotency, providing clear guidance on when to use and when not.

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 indicate destructive=True. Description adds 'Cannot be undone' which reinforces irreversibility. No contradiction, but little additional context beyond annotations.

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

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

Two short sentences plus a concise example. No unnecessary words, front-loaded with key 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?

Description covers purpose, behavior, and alternative usage. With simple parameters and output schema present, no gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. Description includes an example mapping for schedule_id but no extra details beyond schema. No mention of project_path.

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

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

Description clearly states 'Delete a schedule by ID' with a specific verb and resource. Also distinguishes from gitlab_update_schedule for pausing, making purpose unambiguous.

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

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

Explicitly tells when to use (to delete) and when to use an alternative (gitlab_update_schedule with active=False to pause). Provides actionable guidance.

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

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

Beyond annotation signals (readOnly, idempotent, openWorld), the description discloses truncation to 500 lines and binary decoding behavior (UTF-8 with errors replaced leading to garbage). This adds valuable behavioral context without contradicting 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 very concise: two short paragraphs plus bulleted examples. The first sentence delivers the core purpose and key constraint (truncation). Every sentence adds necessary information with no fluff.

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

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

For a tool with 3 parameters (1 required) and an output schema, the description covers purpose, usage limits, binary caveats, when to avoid, and parameter examples. It is fully self-contained for correct selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value with direct examples mapping intents to parameters (e.g., file_path='src/app.py') and clarifies that project_path defaults from environment when omitted, surpassing the schema's mere default null.

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

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

The description clearly states 'Read a text file from the repository, truncated to 500 lines,' which is a specific verb+resource. It also contrasts with binary usage and explicitly distinguishes from the sibling tool gitlab_list_repository_tree, ensuring no confusion.

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

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

The description explicitly says 'Don't use for listings — use gitlab_list_repository_tree,' providing a clear when-not-to-use and alternative. Examples illustrate typical usage, guiding the AI on how to map natural language to parameters.

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 indicate readOnly, idempotent. The description adds behavioral details: how tail and grep modes work, including the fallback to literal substring for invalid regex. No contradictions with annotations.

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

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

The description is highly concise, starting with a clear one-liner, then splitting into two modes, followed by practical examples. Every sentence adds value, and the structure is logically organized.

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

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

Given the tool has 5 parameters, a rich input schema, and an output schema, the description covers all necessary aspects: purpose, modes, parameter hints, and examples. No gaps identified.

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%, providing clear parameter descriptions. The description adds value by explaining how parameters interact (e.g., grep_pattern and grep_context) and providing concrete usage examples that illustrate parameter semantics.

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

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

The description clearly states it fetches job logs, with two distinct modes (default tail and grep). It uses specific verbs ('Fetch the trace/log') and resource ('of a job'). While it does not explicitly distinguish from siblings, the purpose is unique and unambiguous.

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

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

The description provides explicit usage guidance with examples for each mode (e.g., 'Why did job 789 fail' → default tail, 'Find every Traceback' → grep). It explains when to use each mode but does not mention when not to use the tool or alternatives among 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 provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds context about returned fields (state, branches, etc.) and no side effects are mentioned, reinforcing safe read behavior.

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

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

Six concise lines with front-loaded purpose, clear structure, and no superfluous text. Every sentence earns its place.

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

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

Given robust annotations, full schema coverage, and presence of output schema, the description provides all necessary context: purpose, scope, usage guidance, and differentiation from siblings.

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

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

Schema coverage is 100% with good descriptions, but the description adds value by giving usage context (e.g., example showing mr_iid=42, note about project_path default) 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?

Description clearly states it gets full information about a merge request by internal ID (iid) and lists included details. It distinguishes from sibling gitlab_get_merge_request_changes by explicitly saying not to use for changed files.

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

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

Provides explicit examples of when to use (e.g., 'Show me the description and state of !42') and directs away from use for changed files, naming the alternative tool.

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

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

The description discloses the 2KB truncation per file and directs to gitlab_get_file for full content, adding behavioral context beyond the annotations (readOnlyHint, etc.). No contradiction with annotations.

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

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

The description is concise, uses a brief introductory sentence, then provides a bullet list of examples and use cases. Every sentence adds value without redundancy.

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

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

Given the output schema exists, the description need not detail return values. It covers the key behavior (truncated diffs) and provides context for when to use alternative tools. The tool is simple (2 params, read-only), and the description is 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?

Input schema has 100% coverage with descriptions. The description adds value by providing an example (mr_iid=42) and explaining the project_path default and environment variable usage, going beyond the schema.

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

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

The description clearly states the tool lists changed files in a merge request with truncated diffs, using specific verbs and resources. It distinguishes from siblings like gitlab_get_merge_request and gitlab_get_file by specifying 'list changed files' vs. full details or raw file retrieval.

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

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

The description explicitly provides when to use this tool ('code-review-style queries') and when not to use it for full content, directing to gitlab_get_file. It includes examples and mentions the 2KB truncation limit.

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

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

Annotations declare readOnlyHint, destructiveHint, idempotentHint. Description adds context on return fields (durations, timestamps) and contrasts with list summaries. No contradictions.

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 concise paragraphs: purpose, usage context, examples. Each sentence adds value, no redundancy.

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

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

Given output schema exists, description adequately covers when to use, what it returns, and how it differs from siblings. No gaps.

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 already describes both parameters (pipeline_id and project_path). Description does not add further meaning 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?

Description clearly states 'Get a single pipeline with full timing details' and lists specific fields. It distinguishes from sibling tools like gitlab_list_pipelines and gitlab_get_pipeline_jobs.

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 suggests using after gitlab_list_pipelines and directs to gitlab_get_pipeline_jobs for jobs. Provides examples for common use cases like checking pipeline slowdown or status.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds value by detailing output contents (stage, status, duration, web URL) and the intended drill-down use case. No contradiction, but could mention pagination or rate limits.

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

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

Concise and well-structured with examples, alternatives, and exclusions in a few sentences. Every sentence adds value.

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

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

Given the presence of an output schema, description effectively covers purpose, usage, alternatives, and examples. Complete for a list 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 schema already documents parameters. Description adds minimal extra semantics beyond examples; 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?

Description clearly states 'List jobs of a pipeline with stage, status, duration and web URL', specifying the resource and returned fields. It distinguishes from siblings by explicitly saying not to use for overall pipeline status, pointing to gitlab_get_pipeline instead.

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

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

Provides explicit when-to-use: 'after noticing a failed pipeline to drill down into which specific job broke and fetch its log via gitlab_get_job_log'. Includes examples with parameter values and a clear exclusion: 'Don't use for overall pipeline status — use gitlab_get_pipeline instead.'

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

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

The description supplements annotations (readOnlyHint=true, etc.) by detailing what the response includes (default, protected, merged flags, tip commit details). No contradictions; adds valuable behavioral context beyond 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?

The description is highly concise: two sentences for purpose/details, then examples and anti-pattern. No fluff, every sentence earns its place, and the structure is front-loaded with the most essential information.

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

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

Given the presence of annotations and full input schema, the description covers purpose, usage, and behavioral traits well. Minor gaps like explicit pagination behavior are covered by examples. Output schema likely handles return values, so overall completeness is high.

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

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

Input schema already fully describes all 4 parameters (100% coverage). The description adds usage examples but does not introduce new parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the action (list branches), the resource (project), and the optional substring filter. It distinguishes from sibling tools like gitlab_list_tags and gitlab_list_merge_requests by focusing on branches and including specific flags and commit info.

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 concrete examples for common use cases (search, pagination) and explicitly warns against using this tool for exact branch existence checks, recommending gitlab_get_file as an alternative. This is excellent usage guidance.

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

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

Annotations already indicate read-only, idempotent, and open-world behavior. The description adds context on state filtering, pagination (page/per_page), and default project from env, which supplements the annotations without contradiction.

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

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

Concise at about 100 words, well-structured with a clear first sentence and bullet-like examples. Every sentence serves a purpose; no fluff.

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?

Complete for a list tool with 4 parameters and an output schema. Covers purpose, scope, filtering, pagination, project context, and alternative tool. No gaps.

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

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

Schema coverage is 100%, so parameters are well-documented there. The description adds examples and some usage context (e.g., state='merged' requiring client-side filtering) but no fundamentally new semantic info beyond the schema.

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

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

The description clearly states the tool lists merge requests of a project with optional state filtering. It distinguishes from sibling tool gitlab_get_merge_request by specifying when to use the latter for individual MR details.

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

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

Explicit guidance: 'Don't use when you have an MR IID — use gitlab_get_merge_request for detail.' Provides examples for different use cases (open, merged, all) and mentions client-side filtering for date ranges.

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?

Declares 'Read-only and idempotent', which aligns with annotations (readOnlyHint, idempotentHint, destructiveHint). Adds details about output format (markdown table, PipelinesListOutput) and pagination, providing context beyond 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?

Efficient and well-structured: opens with purpose, then usage guidance, output description, and examples. Every sentence earns its place with no redundancy.

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

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

Given 6 parameters (0 required), 100% schema coverage, and an output schema, the description covers usage, output shape, examples, and sibling differentiation completely. No gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value through concrete examples (e.g., 'status='failed', ref='master'') that illustrate parameter usage, going beyond schema field descriptions.

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

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

The description clearly states 'List recent pipelines of a project, newest first', providing a specific verb and resource. It further distinguishes itself from the sibling tool gitlab_get_pipeline by noting when not to use it.

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

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

Explicitly states use cases: triage, release readiness checks, feeding pipeline IDs into follow-up calls. Also provides a clear when-not: 'Don't use when you have a specific pipeline ID — use gitlab_get_pipeline instead.'

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 indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds minimal behavioral context beyond the schema, such as the recursive option example. It does not discuss pagination, rate limits, or other traits, but the annotations cover safety adequately.

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 extremely concise: a single clear sentence followed by three succinct bullet examples. Every word serves a purpose, and it is front-loaded with the core action. 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?

Given the simple purpose, full schema coverage, and presence of an output schema, the description is complete. It covers usage boundaries (not for file content) and includes practical examples. Nothing essential is missing.

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

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

Schema coverage is 100%, so parameters are already documented. The description enhances understanding by providing usage examples (e.g., using recursive=True with filtering) that go beyond the schema descriptions. This adds practical value without redundancy.

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

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

The description clearly states the tool lists files and directories at a given path, which is a specific verb and resource. It provides an explicit distinction from a sibling tool ('Don't use for full-text content — use gitlab_get_file for that'), making its purpose unambiguous.

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

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

The description includes a clear when-not-to-use directive with an alternative tool. It provides examples of usage contexts (top-level files, recursive with filter). It does not contrast with other list tools, but the given guidance is sufficient for typical scenarios.

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, destructiveHint=false, and idempotentHint=true. The description adds behavioral context about variable masking: 'Variable keys whose name hints at a secret... keep the key but have the value replaced by `***`,' which is useful beyond annotations.

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

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

The description is front-loaded with the main purpose, followed by essential behavioral info (variable masking) and a clear usage example. It is concise with no unnecessary words, every sentence adds value.

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

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

The description covers tool purpose, secret handling, and usage boundaries. An output schema exists (signal true), so return value details are not needed. Annotations cover safety. The description is complete for the tool's complexity.

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

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

Schema coverage is 100% with a description for the single parameter project_path that includes default behavior via env var. The tool description does not add extra parameter 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?

The description clearly states 'List all CI/CD schedules of a project,' using a specific verb and resource. It distinguishes from siblings like gitlab_create_schedule and explicitly contrasts with gitlab_trigger_pipeline.

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

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

The description provides explicit when-to-use guidance via an example and a don't-use scenario: 'Don't use to *run* a schedule now — use `gitlab_trigger_pipeline` with the schedule's variables instead.' This clearly states alternatives.

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

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

Annotations already indicate safe, idempotent, read-only behavior. The description adds value by specifying 'newest first' ordering and providing concrete usage examples, though it doesn't add much beyond 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?

Description is concise with three sections: purpose, use cases, and examples. No unnecessary words, front-loaded with important info.

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

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

For a simple list tool with output schema and full annotation coverage, the description is complete. It covers the main functionality, use cases, and parameter usage.

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

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

Schema covers all parameters with descriptions. The description enhances understanding with usage examples for search and pagination, and explains the project_path defaults, thus adding value beyond the schema.

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

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

The description clearly states the tool lists tags of a project, newest first, and differentiates from sibling list tools by specifying its use for release-note generation and checking last shipped version.

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

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

Provides explicit examples for common use cases: default call for last release and using search parameter for filtering. This gives clear guidance on when and how to use the tool.

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

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

The description adds value beyond annotations by specifying that the tool writes to the target branch (destructive), checks merge_status, and returns a cannot_merge status on failure. It aligns with destructiveHint=true and readOnlyHint=false.

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

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

The description is concise at four sentences, front-loading the core purpose. Every sentence contributes essential information (purpose, side effects, preconditions, example, usage guidance) without redundancy.

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

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

Given the tool's moderate complexity (2 parameters, output schema exists), the description covers purpose, behavior, parameter usage, and a key precondition. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, providing full parameter descriptions. The description enhances understanding with an example mapping 'Merge !42' to mr_iid=42, and clarifies the project_path default behavior.

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

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

The description clearly states the tool performs the actual merge of a GitLab MR, using specific verb 'merge' and resource 'MR'. It distinguishes from sibling tools like gitlab_create_merge_request by specifying 'actual merge' and including pre-conditions.

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 advises checking gitlab_get_merge_request first when conflicts are suspected, and explains that the tool checks merge_status before proceeding. It could be more explicit about exact conditions to avoid calling, but the guidance is clear and actionable.

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

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

Discloses progress emission via MCP Context (info log + report_progress) beyond the readOnly/idempotent annotations. Does not mention data freshness or rate limits, but the behavioral context is strong.

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

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

Well-structured with bullet points and examples; concise but includes essential details. Minor wordiness (e.g., 'Great for stand-ups') but overall efficient.

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

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

Explains what the tool returns (success rate %, totals, last-10 statuses, trend indicator) despite having an output schema. Covers use cases and parameter behavior completely for a health-report 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?

All three parameters have schema descriptions (100% coverage). The description adds semantic examples (e.g., ref='master', source='schedule') and clarifies the project_path default from env var, enhancing meaning beyond schema.

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

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

The description clearly states it aggregates success rate over 7 and 30 days with a trend indicator, explicitly differentiating from single-pipeline tools like gitlab_get_pipeline.

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

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

Provides explicit when-to-use (stand-ups, on-call hand-offs) and when-not ('Don't use for a single pipeline — use gitlab_get_pipeline'), with concrete examples for parameter values.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds that it returns counts, providing minor behavioral context beyond the annotations.

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

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

The description is extremely concise: two sentences plus example lines. Every sentence adds value, and the structure is front-loaded with the key purpose. No unnecessary text.

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

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

Given the tool's simplicity, good annotations, and presence of an output schema, the description covers the essential information. It mentions the key returned fields, which suffices. Missing a note about the default project path behavior, but that is covered in the schema.

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

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

Schema coverage is 100% with the parameter's description explaining its default behavior. The tool description does not add additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it returns 'basic metadata about a project: ID, default branch, visibility, counts.' This directly distinguishes it from sibling tools like gitlab_get_pipeline or gitlab_merge_mr, which serve different purposes.

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 includes two examples showing common use cases, which implies when to use the tool. However, it does not explicitly state when not to use it or mention alternatives among siblings, but the examples are sufficient for most scenarios.

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?

Describes behavioral effects: creates new job runs, safe only with failed jobs, no effect if passed. Annotations already indicate non-read-only and non-destructive, but description adds useful context.

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

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

Two sentences plus a bullet example, all essential information front-loaded. No fluff.

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

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

Covers purpose, usage, and behavior well. Does not describe return values, but an output schema exists. Sufficient for 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 coverage is 100% with clear descriptions. The description adds only examples, no extra parameter semantics beyond the schema.

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

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

The description clearly states the tool retries all failed jobs of an existing pipeline. It uses specific verb ('retry') and resource ('pipeline'), and distinguishes from siblings like gitlab_trigger_pipeline.

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

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

Explicitly states when to use (pipeline with failed/canceled jobs) and when not to (successful pipeline, with alternative tool 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?

Description adds context beyond annotations: not idempotent (matches hint), consumes runner minutes, and advises against loops. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false).

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

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

Extremely concise: one sentence for purpose, one for behavioral warning, and bulleted examples. No wasted words.

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

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

With output schema present and good annotations, description is complete. Covers purpose, behavior, cost implications, and alternatives. Examples cover typical usage patterns.

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

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

Schema covers all parameters with descriptions (100% coverage). Description provides examples but does not add significant new semantic meaning beyond what schema provides. Baseline 3 is appropriate.

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

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

Clearly states 'Create a new pipeline on the given ref' with specific verb and resource. Distinguishes from sibling 'gitlab_retry_pipeline' by noting it creates a new pipeline vs. retrying.

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 warns of non-idempotency, runner minutes consumption, and loops. Directs to 'gitlab_retry_pipeline' for retries. Provides concrete examples for common use cases.

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

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

Annotations indicate destructiveHint=true. The description adds crucial context: 'Only provided fields change' and 'Destructive when variables is set: the entire variable set is replaced.' This goes beyond annotations and provides clarity on partial updates and variable replacement behavior.

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

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

The description is concise with 5 sentences, including examples. It opens with the core purpose, follows with behavioral details, and ends with illustrative examples. No wasted words.

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

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

Given the tool's complexity (7 parameters, destructive behavior), the description covers essential aspects: partial update, variable replacement danger, and example usage. Output schema exists, so return values are not needed in description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema: it explains the destructive behavior of variables (schema mentions replacement but description emphasizes full replacement and advises caution) and provides examples showing intended usage of schedule_id, active, and cron. Not all parameters are elaborated, but the key ones are covered.

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

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

The description clearly states 'Update an existing schedule' and specifies partial update behavior. It distinguishes from sibling tools like create_schedule and delete_schedule, as the name and context imply.

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

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

The description provides explicit when/when-not guidance, including a strong warning about variables being destructive. Examples illustrate common use cases (deactivate, change cron) and explicitly advise against passing variables unless replacement is intended.

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