generate_recipe_structure

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

The description discloses that the tool validates all fields and returns a JSON structure, and notes it has an output schema (pointing to structured results). It adds behavioral context about structuring steps apart. With no annotations provided, the description bears the transparency burden; it covers the core behavior but doesn't detail edge cases, error handling, or what happens with invalid input—though having an output schema reduces the burden somewhat.

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 compact—roughly 60 words across three short paragraphs—and opens with the core purpose sentence. The step-formatting guidance earns its place as crucial usage detail. The final instruction about separating ingredient additions from machine actions is valuable but slightly redundant with the steps parameter description in the schema ('Ingredient additions and machine actions must be on separate lines'), creating minor duplication.

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?

The tool has an output schema, reducing the need to describe return values. With 7 parameters at 100% schema coverage, the schema handles parameter documentation. The description adds value on the recipe-structuring guidance and integration workflow with upload_custom_recipe. It's reasonably complete for a generation/validation tool given the rich schema; the main gap is not clarifying how this differs from validate_guided_recipe_structure among siblings.

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 100%, so parameters are well-documented in the schema itself. The description adds meaningful guidance on step formatting ('Ingredient additions and machine actions must be on separate lines') that complements the schema's brief parameter notes. The formatting guidance in the description enhances understanding beyond what the schema alone provides, though it doesn't enumerate each of the 7 parameters individually.

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 clearly states the tool's function: 'Generate and validate a recipe structure ready for upload to Cookidoo.' It uses specific verbs (generate, validate) and identifies a clear resource (recipe structure) and integration with the upload_custom_recipe tool. However, it doesn't explicitly distinguish from the sibling tool validate_guided_recipe_structure, which could cause confusion about which validation tool to use.

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 provides clear guidance on how to structure recipe data, including the explicit instruction to 'Always put weighing/adding ingredients in one step and the subsequent chopping, mixing, cooking, or kneading action in a separate step.' It also notes the tool validates fields before upload. It lacks explicit when-not-to-use guidance or comparison against the sibling validate_guided_recipe_structure, but the integration context with upload_custom_recipe is helpful.

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