bar_create_cocktail

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

No annotations are supplied, so the description carries the full burden. It discloses a real, non-obvious content policy (prefer generic categories over specific bottles) but says nothing about mutation semantics such as whether ingredient names auto-create ingredient records, duplicate-name handling, required permissions, or reversibility. The policy guidance is genuinely additive; the write-behavior gaps are not.

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 purpose sentence is front-loaded and the ingredient-policy paragraph is dense but earns its space by encoding a rule an agent would otherwise get wrong. Slightly verbose, but no clear filler.

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 11-parameter write tool with zero annotation coverage, zero schema descriptions, and no parameter-level documentation, the description is too thin: it explains the ingredient-slot policy but leaves eight parameters and all failure/mutation behavior undocumented. An output schema exists, so return values need not be explained.

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 0% across 11 parameters, so the description must compensate and largely does not: tags, images, source, garnish, glass_id, description, cocktail_method_id, and parent_cocktail_id are never mentioned. Only 'ingredients' gets substantive semantic treatment (the generic-vs-specific slot rule), with 'instructions' and an 'optional image' mentioned only in passing.

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 states a specific verb and resource ('Create a new cocktail recipe') plus the content it carries (ingredients, instructions, optional image), which plainly separates it from bar_update_cocktail and bar_create_ingredient. It never names a sibling or an exclusion condition, so it falls short of the 5 bar.

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 second paragraph gives concrete selection guidance for the ingredient slots and names the conditions that override it (brand defines the drink, Erik asks), plus points to the server instructions' 'Generic vs. specific' rule. It gives no guidance on when to create a new cocktail versus updating an existing one, but the context is otherwise clear.

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