pipeline_pause

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

Even without annotations, the description provides good behavioral context: the pipeline finishes the current step before pausing, meaning it is not instantaneous. It also indicates that the pause is temporary and requires a resume call. The description does not contradict any annotations (none provided). The only missing details are error conditions (e.g., what if the pipeline is not running) or side effects, but for a simple pause action the behavior is adequately transparent.

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 plus a parameter line, efficiently conveying the tool's purpose, behavior, and next steps. It is front-loaded with the key action and uses minimal words. Every sentence serves a purpose (action, detail, follow-up, parameter explanation). No waste.

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 (one required parameter, no output schema, no nested objects), the description covers the essential aspects: what it does, how it behaves, and what comes next. It references the sibling `pipeline_resume` for continuation. It does not mention prerequisites (e.g., pipeline must be running) or error states, which would be helpful but are not critical for a straightforward pause action. Overall, it is fairly complete for its 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?

The description includes a parameter list for `execution_id` with the text 'The pipeline execution ID.', which adds meaning beyond the schema (which has no description). Since schema coverage is 0%, the description partially compensates by naming the parameter and explaining its role. However, it does not provide details like format, how to obtain the ID, or examples. For a single required string parameter, this is acceptable but not exceptional.

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 ('Pause a running pipeline') and provides specific behavior details: it finishes the current step then pauses before the next. It also distinguishes from siblings by explicitly mentioning `pipeline_resume` to continue, and implicitly differentiates from `pipeline_abort` (which stops permanently). The combination of verb ('Pause') and resource ('pipeline') with boundary condition is precise.

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 directly states when to use the tool (to pause a running pipeline) and provides guidance on the next step ('Use `pipeline_resume` to continue'). It does not explicitly list when not to use it or compare to `pipeline_abort`, but the context of siblings and the behavioral description make the appropriate usage clear. A minor improvement would be to state that this is for temporary pauses only.

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