Run a workflow

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

Annotations declare openWorldHint and destructiveHint, and the description goes well beyond them: real data is submitted, done rows are skipped, return statuses (done|partial|stopped|needs_repair) are enumerated, and both the needs_repair recovery path and the timeout/busy retry policy (poll run_report, never re-call run_start) are disclosed.

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?

Dense but front-loaded, with the core action first and constraints following. Every sentence carries an instruction or constraint, though the error-handling tail is packed tightly enough that it borders on being a wall of text.

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?

Covers what the tool does, its preconditions, its return shape (status, runId, counts, problem items) despite no output schema, and the downstream recovery flows. Nothing an agent needs to invoke it correctly is missing.

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 0%, so the description must carry the load, and it does for all three parameters: workflow is a saved workflow, params should be read with workflow_get, and repeat should only be true on explicit request. It does not describe the string-map shape of params, so a small gap remains.

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 and resource ('Runs a saved workflow on its input rows'), plus scope qualifiers (without an LLM, submits real data to the site). It is clearly distinguishable from siblings like run_resume and run_report, which are named directly.

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?

Explicit when-to-use ('Call only when the user asked to run this workflow'), explicit when-not ('Never use it to diagnose a breakage or to finish an interrupted run'), and names the alternative (run_resume). Adds the repeat:true precondition as an explicit user-request gate.

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