Run Recipe

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

Annotations only supply hints; the description adds substantial runtime behavior: ordered execution, stop-at-first-failure with a partial log, fail-fast on missing required vars before any step runs, dryRun preview semantics, and auth dependence on the recipe's own steps. This goes well beyond the generic readOnly/idempotent/destructive hints and gives an agent a realistic model of execution and failure.

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 description is dense but efficiently organized: a first sentence defining the tool, followed by concrete flow examples and the dryRun tip, then labeled paragraphs for Requires, Auth, and Errors. No sentence is filler, and the most important usage guidance is front-loaded. This is appropriately sized for a complex meta-tool.

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 tool with no output schema, the description covers inputs, discovery, auth, and failure behavior. It even states what dryRun returns (a resolved step list) and what failure returns (a partial log). The only notable gap is that it never describes the success return value of a real run beyond implying a log. Given the high complexity and absent output schema, this is a minor omission rather than a fatal one.

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 the baseline is 3. The description still adds relational value between parameters: it explains that dryRun previews resolved steps, that omitting recipeId triggers a listing for the selected goal, and that vars are injected into steps with missing required vars failing fast. This cross-parameter workflow guidance goes beyond the individual parameter descriptions, warranting a 4.

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 first sentence names a specific verb ('Execute') and a specific resource ('a built-in recipe') and defines what a recipe is: 'an ordered sequence of this server's own tool calls.' It also gives concrete examples of flows (B2B bootstrap, broadcast, sources ingest) and contrasts the two modes of operation (run by id vs. list by goal). This clearly separates it from the many individual flow tools in the sibling list.

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?

The description gives clear when-to-use context: execute a built-in recipe for common flows, preview with dryRun, and list recipes by omitting recipeId. It also gives a prerequisite discovery procedure ('call without recipeId first to see the recipes and their required inputs') and an auth prerequisite. It does not explicitly name alternatives like calling the underlying flow tools directly, but the recipe-based framing makes the intended usage unambiguous enough.

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