Pause the build queue

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

The description adds meaningful behavior beyond the annotations: running pipelines finish, all other work queues up, the pause is instance-wide, it persists until resume_queue is called, and the operation requires a two-step confirmation flow. These details disclose impact and persistence far beyond the structured hints.

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

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

The description is compact: three sentences that front-load the core action, then give consequences, scope, permissions, and process. Every sentence contributes useful information with no filler or redundancy.

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

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

For a globally destructive-ish admin action, the description covers the key operational facts: what stops, what continues, who can call it, how wide the impact is, how long it lasts, and that a second step is required. The output schema exists and can carry return-value details, so nothing essential is missing for an agent to invoke this 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%: the confirm_token property is already described as a token from a previous call. The description adds the 'Two-step' workflow hint, which mildly reinforces but does not substantially extend what the schema already says. With full schema coverage, 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: 'Stops the server from handing new work to agents.' It names the specific resource (the build queue) and distinguishes itself from siblings like resume_queue and cancel_pipeline by emphasizing instance-wide behavior. The verb is specific and the scope is immediately understandable.

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

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

The description gives clear context: admin-only, instance-wide, stops CI for everybody, and stays paused until resume_queue is called. It explicitly names resume_queue as the counterpart for undoing the action. However, it does not explicitly contrast with alternatives like cancel_pipeline for stopping a single pipeline, so exclusions are mainly implied rather than fully stated.

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