Cancel Pipeline

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

Annotations already declare destructiveHint=true, idempotentHint=true, non-readOnly and openWorld, so the safety profile is covered. The description adds only the invocation mechanism (params_json are passed as keyword args to the named operation) and says nothing about what cancellation does to running jobs, whether it is reversible, or what permissions are needed — the most important behavioral facts for this mutation.

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 verb+resource is front-loaded, but the redundant "(gitlab_graphql_ops)" plus three sentences of family-wide boilerplate that is presumably repeated on every graphql_ops tool crowd out what is specific to cancelling a pipeline. Roughly half the text does not earn its place for this 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 destructive, opaque-payload mutation with no output schema, the description should identify the required pipeline reference and the effect/return of the operation. Instead it gives only generic GraphQL-family mechanics, so an agent still cannot construct a correct call without inspecting the operation elsewhere.

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 params_json. The description usefully explains that entries become keyword arguments to the named operation and that typed-model operations are built from those kwargs, which is more than the schema says. But it never names the actual keys this operation expects (e.g. the pipeline identifier), leaving the agent to guess the payload.

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 line names the specific verb and resource ("Cancel pipeline") and contrasts the tool with the REST gitlab_<domain> family. However, the bulk of the text describes the generic gitlab_graphql_ops mechanism rather than this operation, and it does not distinguish cancel-pipeline from siblings like gitlab_graphql_ops_retry_pipeline or gitlab_cancel_merge_when_pipeline_succeeds.

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 explicitly to prefer this for GraphQL-only capabilities and even lists "pipeline retry/cancel" as one such case, which routes the agent well versus the REST tools. It offers no guidance on when not to use it or how to choose among the other graphql_ops pipeline tools.

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