add_flow_to_scenario

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

With zero annotations, the description carries the full burden and delivers richly: cycle rejection, automatic output capture, the `<camelCase flow name>Output` naming convention with numeric suffixes, array-of-outputs when a target runs multiple times, and the rule that composed-scenario entries never capture output. This far exceeds what any annotation set would typically provide.

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 information density is justified by the tool's complexity, but the whole description is one massive unbroken block of parenthetical asides and nested clauses, making it hard to scan. It is front-loaded with the core purpose, yet would benefit from paragraph breaks per parameter. It earns its length but not its structure.

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 an 8-parameter tool with no output schema and no annotations, it is remarkably complete — covering target selection, dataset resolution, YAML fallback, postprocessing scope, and output capture semantics. The main gap is the required scenarioId parameter, which is never explained, and project is only documented in the schema. Minor omissions against a very high overall bar.

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 only 13%, so the description must compensate, and it does: datasetTokens (comma/space-separated, blank=first/default, multiple = sequential runs), useYaml/yaml (raw fallback, YAML/JSON object or list semantics, yaml ignored unless useYaml true), and postprocess (evaluated per run, receives params plus in-scope names, must return the whole params object). It leaves only scenarioId and project undescribed, which are largely self-evident.

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 description opens with a precise statement of the verb and resource: append a flow OR another scenario to a scenario's composed sequence as a run config. It also differentiates from siblings — explicitly contrasting with live_replay_flow's dataset/params resolution and naming the composeScenarioId alternative. Purpose is unmistakable.

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?

It clearly states when to use flowId (the common case) vs composeScenarioId, and warns that compose is rejected on composition cycles. It also scopes postprocess to live_replay_scenario/live_start_scenario_run. It does not explicitly say 'for immediate execution use live_replay_scenario' as an exclusion, but the references to live tools provide enough routing context.

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