pipeline_resume

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

Annotations already declare a non-read-only, idempotent, non-destructive operation, and the description reinforces the idempotency contract with concrete semantics: a resend of identical content does not create a new revision and returns the prior result. It further discloses that Console runs are not automatically retried unless rerun_upstream is explicitly set, and that an unmonitored running Console yields EXECUTION_UNRESOLVED rather than a false completion — meaningful behavior an agent could not derive from 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 terse purpose line is front-loaded and the per-parameter block is well organized, with zero filler sentences. It is somewhat long and docstring-shaped, but every paragraph carries operational information rather than restating the schema.

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 mutation-style tool with four parameters, no output schema, and no schema descriptions, the definition covers inputs, idempotency, the no-auto-retry rule, and a specific unresolved-execution failure mode. It stops short of saying what a successful return contains (e.g. the new revision identifier) or what prerequisites the target run must satisfy, which keeps it from a 5.

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 0%, so the description must carry the full load and it does: pipeline_path accepts either pipeline-run.json or its parent pipeline_root; updates is restricted to the four named keys per spec §10.1; request_id is the idempotency key; rerun_upstream gates re-execution of Console steps. Every parameter gains meaning beyond the bare JSON types.

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 opening line names a specific verb and resource — resume a pipeline from a stopped stage, with input correction and creation of downstream revisions. It is clear what the tool does, but it never distinguishes itself from the sibling pair pipeline_run and pipeline_status, so an agent must infer the boundary on its own.

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?

Use is implied (a run that stopped at some stage and needs corrected inputs), and the rerun_upstream note hints that this resumes rather than re-executes. However, no sibling is named and there is no explicit when-not or comparison against pipeline_run for a fresh run or pipeline_cancel for abandonment, leaving routing to inference.

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