bulk_clone_and_swap

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

The description usefully discloses sequential execution, per-entry independence, failure isolation, and the dry_run default, which is valuable safety context given no annotations are provided. However, it omits the confirm gate ('Must be true to execute') and does not clarify what a dry run returns or that actual persistence requires confirm=true and dry_run=false. This is a notable but not fatal behavioral gap.

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 four short sentences that front-load the core purpose and then add execution semantics, failure isolation, and the dry-run default. There is no filler, and every sentence contributes to an agent's ability to understand and invoke the 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 bulk mutation tool with no annotations and no output schema, the description covers the core algorithm, sequential/independent execution, and the dry-run safety default. The main missing piece is explicit mention of the confirm flag, but the schema already documents that, so the description is reasonably complete for selection and invocation.

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 high (83%), so the baseline is 3. The description adds some algorithmic glue, such as cloning template_recipe_id via scale_recipe and swapping the designated ingredient line with each entry's ingredient_id, but it does not systematically illuminate parameters like confirm or delay_ms beyond what the schema already states.

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 'The copy-and-swap loop' and then spells out the exact per-entry sequence: clone template_recipe_id via scale_recipe, rename it, then replace the designated ingredient line. This clearly distinguishes the tool from siblings like scale_recipe (single clone) and bulk_create_subrecipes (bulk create without swap), so an agent can identify its purpose without ambiguity.

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 clearly frames this as a batch loop over entries, which signals when to use it over single-item operations like scale_recipe. It does not explicitly name alternatives or say 'use this instead of X', but the 'for each entry' construction and the reference to scale_recipe provide enough context for an agent to infer the batch use case.

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