pipeline_run

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

The description discloses behaviors that annotations do not convey: WBPP intermediates are deleted, working files go to <target dir>/working-files, execution is asynchronous, and the run is resumable. It also clarifies that frames dropped via exclude_frames are honored. No contradiction with 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 purpose is front-loaded in the first sentence, and every subsequent sentence adds a distinct fact: engine behavior, native pipeline stages, excluded frames, working files, background execution, and resumability. It is dense but justified by the tool's complexity.

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 description covers the core workflow, engine differences, deletion behavior, background execution, and resumability. However, with 22 parameters and no output schema, it omits the return value or pipeline identifier needed for polling, and it does not state prerequisites like light_group_id or the need for a prior scan_frames/plan.

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 only 32%, so the description needed to compensate for the many undocumented parameters. It adds meaning for engine and resume_id, and hints at working-file behavior, but most parameters (force, min_stars, rejection, drizzle_scale, skip_cosmetic, etc.) remain unexplained in both schema and description.

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?

Opens with a specific purpose: 'One call from raw lights to a master light.' It then differentiates the two engine modes ('wbpp' vs 'native') and describes the full pipeline stages, which clearly separates it from sibling step-by-step tools like calibrate_lights or wbpp_run.

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?

Provides clear usage context: this is the end-to-end pipeline tool, supports two engine choices, runs in the background, requires polling pipeline_status, and can be resumed with resume_id. It does not explicitly state when not to use it versus the individual step tools, so it stops short of full alternative guidance.

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