pipeline_run

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

With no annotations provided, the description carries the full disclosure burden. It does disclose a meaningful side effect (reads/writes the GUI session working set) and the unattended behavior, which goes beyond the schema. However, it omits other behavioral traits such as whether the run is blocking, what it returns, or whether it has destructive implications for the project.

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?

Two short paragraphs, front-loaded with the core purpose and the config-override mechanism, then the working-set nuance. No wasted sentences; the length is appropriate for the 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?

An output schema exists so return values are covered there. For a 7-parameter run tool the description covers the config override, working-set side effect, and unattended behavior. Minor gap: no mention of what the run does to project state or how from_step/only_step scope the execution, but overall it is reasonably complete for the 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?

Schema description coverage is 0%, so the description must compensate. It does add meaning for skip_steps_json/config_json (override yaml), use_working_set (working-set sharing), and unattended (Batch mode). But from_step, only_step, and project_path are left entirely to their schema titles; while somewhat intuitive from names, the description does not fully compensate for the zero coverage.

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?

States a specific verb+resource ('Run the production pipeline') which clearly identifies the action. However, it does not differentiate from sibling pipeline tools like pipeline_analyze or pipeline_get_config_tool, so an agent cannot immediately tell when this run tool is the right one among the pipeline_* family.

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?

Gives useful context about when use_working_set matters and notes that omitting unattended leaves Batch mode unchanged. But it never says when to prefer this over pipeline_analyze or other pipeline siblings, and there are no explicit when-not-to-use or alternative pointers.

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