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

Annotations only declare the safety profile (not read-only, open-world, non-idempotent, non-destructive); the description goes well beyond by disclosing that execution is asynchronous, how to observe completion, and non-obvious re-run caching semantics — unchanged nodes keep results, while LLM/API/random-seed nodes regenerate unless locked. The one gap is that it never says what a successful call returns (e.g., a run identifier) for the caller to poll with.

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?

Front-loaded with the action, then dense but purposeful follow-ups; no filler. The final sentence on re-run regeneration and locking is long and nested, making the lock-before-rerun ordering harder to parse than necessary.

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 two-parameter async mutation with no output schema, the description covers invocation, polling, prerequisites, and re-run side effects well. It stops short of stating the return value or how the eventual result is retrieved beyond status polling, which is the only meaningful omission.

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 100%, so baseline is 3, but the description adds provenance the schema lacks: input file URLs must come from upload_file, which a reader of the bare schema would not know. The rest of the inputs contract (node-ID-keyed JSON, text auto-upload) is left to the schema, which is appropriate.

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 verb+resource ("Execute a flow") is unambiguous, and the description immediately distinguishes scope from the nearest sibling: "This runs the flow ONCE; use run_batch for multiple input sets." An agent can select between run_flow, run_batch, preview_flow, and get_flow without opening any schema.

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 an explicit post-call pattern (poll get_flow with view="status" and wait_seconds=20 until completion), a prerequisite for input-bearing flows (file URLs from upload_file), and an explicit exclusion routing multi-input work to run_batch. It also covers the re-run case with a concrete instruction to lock results via update_flow(locked=true) first.

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