Retry Pipeline

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

Annotations already declare the mutation profile: readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds no behavioral detail beyond those annotations—it does not say what gets retried, whether new jobs are created, what permissions are required, or what side effects may occur.

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 opens with the action but then spends most of its length on family-level boilerplate that is not specific to retrying a pipeline. It is not excessively long, but the generic portion does not earn its place in this tool's definition.

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

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

The tool has one opaque parameter and no output schema. The description should explain the required operation-specific keyword arguments and expected result, but it does neither. Given the low schema richness, this leaves an agent without enough information to invoke the tool correctly.

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

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

Schema coverage is 100% for the single params_json field, but the schema itself only documents it as an opaque JSON string. The description says parameters are passed as keyword arguments, which is useful generically, but it never specifies the required keys for retrying a pipeline (project identifier, pipeline ID, etc.). The agent cannot reliably construct params_json from this definition 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 first two words name the action (retry pipeline), but the remaining description is generic boilerplate for the whole gitlab_graphql_ops family. It does not explain what retrying a pipeline entails or clearly distinguish this tool from siblings such as gitlab_graphql_ops_cancel_pipeline, gitlab_run_pipeline, or gitlab_retry_project_job.

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

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

It gives a broad preference rule: use the GraphQL-native tool for GraphQL-only capabilities including pipeline retry/cancel. That is relevant guidance, but it does not explain when to choose this retry tool over the REST retry alternatives or when a full pipeline retry is appropriate versus retrying an individual job.

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