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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing beyond the operation verb. It does not say whether adds are idempotent, how duplicate ingredient_ids are handled, whether the shelf is appended or replaced, or what permissions are required.

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?

It is a single short sentence with no wasted words and the action is front-loaded. However, the extreme brevity reflects under-specification rather than effective conciseness.

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?

With an output schema present, return values need not be explained, but the combination of zero annotations and 0% parameter coverage leaves the description inadequate for a mutation tool. An agent lacks the mutation semantics and argument details needed to invoke it correctly.

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% and the description explains neither parameter. The meaning of 'ingredient_ids' is partly inferable from its name, but the defaulted user_id and the expected format/behavior of the id array are left entirely unexplained.

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 states a specific verb ('Add') and resource ('ingredients to the shelf'), so the core operation is unambiguous. It does not differentiate from similar siblings such as bar_add_to_shopping_list or bar_remove_from_shelf, but the object ('shelf') does most of that work.

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?

There is no guidance about when to use this tool versus bar_add_to_shopping_list, bar_remove_from_shelf, or bar_get_shelf, nor any prerequisites noted. The agent must infer usage entirely from the name.

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

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

No annotations are provided, so the description carries the full burden. It says 'add' which implies mutation, but doesn't state whether additions are idempotent, whether user_id defaults to a specific user, whether duplicates are allowed, or what the response confirms.

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?

A single short sentence is technically concise but is under-specified rather than efficient. It leaves out required context instead of front-loading useful information.

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?

A mutation tool with no annotations, no output-schema explanation needed (output schema exists), and zero schema parameter coverage. The description does not provide enough for an agent to invoke it correctly, especially regarding the user_id default and array handling.

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%, so the description must compensate for two undocumented parameters. It says 'ingredients' which loosely maps to ingredient_ids, but adds nothing about the user_id default, array semantics, or valid ID ranges.

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?

States a clear verb+resource: 'Add ingredients to the shopping list.' An agent can tell what it does. However, it doesn't distinguish this from the sibling bar_get_shopping_list or explain scope relative to it, so it's vague on differentiation.

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?

No guidance on when to use this vs. bar_get_shopping_list or bar_add_to_shelf. An agent has to infer that this mutates a shopping list while the sibling only reads it. No prerequisites or context given.

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

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

With no annotations, the description carries the burden and does disclose key behavior: hard-disqualified picks are surfaced with explanations only when include_strays=True, and on_shelf_only restricts to on-shelf bottles. The verb 'rank' implies a read-only operation, though read-only/non-mutating status is never stated outright, and nothing is said about result size limits beyond top_n.

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 one-line purpose is front-loaded, followed by the mechanism and then the Args block, so the important information comes first. The 'killer feature' framing is slightly promotional and the Args list restates the schema, but that restatement is justified given 0% schema description coverage.

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?

An output schema exists, so return-value detail is not needed, and the description covers the workflow prerequisite, the filtering options, and the strays behavior. The only material gap is that it never states the operation is read-only/non-mutating, which matters given the absence of annotations.

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%, so the description must compensate, and it does: each of the five parameters is explained, with 'sort' clarified as a 1-based slot index cross-referenced to bar_describe_slots and include_strays explained as surfacing hard-disqualified picks with reasons. A couple of entries ('BA cocktail_id', 'max bottles to return') remain thin, keeping this just below full marks.

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?

States a specific verb and resource ('Rank bottles by fit for a recipe's slot') and immediately differentiates itself from sibling slot tools by naming the workflow it consumes (bar_set_slot_meta, bar_set_band_constraint/bar_set_point_constraint). An agent can tell this apart from bar_describe_slots or bar_get_slot_constraints without opening a schema.

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 gives a clear precondition: the slot must have been declared via bar_set_slot_meta and its constraints set, which tells the agent when this tool is applicable. It does not name an alternative for the reverse question (e.g., bar_uses_for_bottle) or state when not to use it, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the burden and does well: it discloses default exclusions (commodities, uncategorized), the flavor-axis seeding/learning behavior, and per-category applicability rules. It stops short of stating permissions, cost profile in general, or output shape, though an output schema exists to cover returns.

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?

Front-loaded summary sentence, then bullets and an args block that are easy to scan. Slightly verbose and repetitive — the commodity-leaves exclusion is explained twice (once in the purpose and again under image) — but nothing is off-topic.

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 5-param, zero-required audit tool with an output schema, the description covers purpose, scoping, defaults, per-flag effects, and category-specific semantics. An agent has everything needed to invoke it correctly.

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%, so the description must compensate, and it does — all five parameters are explained with rationale and defaults (category as subtree ID with example, check_flavor's speed tradeoff, on_shelf_only, include_uncategorized, include_commodities).

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?

States a specific verb+resource ('audit real bottles for incomplete data') and immediately distinguishes itself from the nearest alternative by naming bar_list_ingredients as the raw structural listing. It also defines scope ('real bottles, not commodity leaves'), so an agent can tell it apart from siblings without opening a schema.

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?

Explicitly routes to bar_list_ingredients for raw listing, states the canonical role as the 'what's incomplete' worklist, and even recommends passing category because it 'makes the flavor scan far cheaper'. Defaults and opt-in flags (include_uncategorized, include_commodities) are stated with their conditions.

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

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.

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

With no annotations, the description carries the full behavioral burden and does disclose a lot: hierarchy placement via parent_ingredient_id, the expectation to fully populate a new bottle, and required follow-up calls (image upload, flavor profile). It omits behavioral traits such as duplicate-name handling, permission/auth needs, and failure modes, which keeps it from a 5.

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 core purpose and the primary create-vs-reuse decision are front-loaded in the first two sentences, with the completeness checklist following as a scannable bulleted list. It is longer than a minimal description but each block (hierarchy, create rule, fill completely, follow-ups) earns its place; some detail could be trimmed without loss.

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 6-parameter mutation tool with no annotations, the description covers the workflow context an agent needs—hierarchy, the create-vs-reuse rule, completeness requirements, and required follow-up tools. The presence of an output schema means return values need no explanation. It is close to complete, with only duplicate/error behavior and the required-vs-optional distinction left unaddressed.

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%, so the description must carry the load, and it meaningfully explains most fields: parent_ingredient_id (hierarchy placement), strength (ABV), description, origin, and images (via the bar_upload_image/bar_upload_image_file workflow). Minor gaps remain: it never echoes the required 'name' field or notes that 'images' is an array of image IDs, and states 'an image' singular against an array parameter.

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+resource ('Create a new ingredient') and the hierarchy detail clarifies the object model. It distinguishes this from the reuse-generic-category path and names complementary siblings (bar_set_flavor_profile, bar_audit_ingredients). It does not explicitly contrast with the close CRUD siblings bar_update_ingredient/bar_delete_ingredient, so it stops short of a 5.

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 gives an explicit when-to-use rule ('Only create a NEW specific bottle when a recipe genuinely needs that brand') and an explicit when-not/alternative ('for ordinary base-spirit slots, reuse the existing generic category'). It also routes the agent to bar_audit_ingredients for the follow-up workflow, so nothing is left to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden. It never states that deletion is irreversible, whether it cascades to shelves, collections, or flavor profiles, or what authorization is required. 'Delete' implies destruction but nothing about consequences is disclosed.

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?

One short, front-loaded sentence with no filler. It is efficient, though the brevity is partly under-specification rather than deliberate compression.

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?

An output schema exists, so return values need not be explained. However, for a destructive one-parameter mutation with no annotations, the description omits irreversibility, side effects on related entities, and error cases (unknown ID/slug), leaving gaps an agent would need to call it safely.

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 0% and the single parameter is titled only 'Id' with no description. The description partially compensates by stating the identifier may be an ID or a slug, which is real information the schema omits. Still, format/validation specifics are left unexplained.

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?

States a specific verb (Delete) and resource (cocktail) with the identifier form, so the agent can distinguish it from bar_delete_ingredient and the update/create siblings. It does not explicitly name those alternatives, but the resource noun is unambiguous.

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?

No when-to-use guidance, no preconditions, and no mention of when a delete is preferable to bar_update_cocktail or to removing items from collections/shelf. The agent gets no routing help beyond the resource name.

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

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

No annotations are provided, so the description carries the full burden. 'Delete' implies a destructive, likely irreversible mutation, but the description says nothing about permission requirements, reversibility, or the effect on related data (cocktails/shelf references). Minimal behavioral context for a destructive tool.

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?

A single efficient sentence with the verb and selector front-loaded. No waste, though it is arguably too terse for a destructive operation.

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?

An output schema exists so return values needn't be explained, and the tool is simple (one param). However, for a destructive mutation with no annotations, the absence of any caveats about irreversibility or permissions leaves a meaningful gap.

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% for the single 'id' parameter. The description adds value by revealing the param accepts either an ID or a slug, which the schema (typed only as an unlabeled string) does not convey. This partially compensates for the coverage gap.

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?

Specific verb (delete) + resource (ingredient), and the 'by ID or slug' phrasing clarifies the target selector. It is distinguishable from siblings like bar_update_ingredient or bar_get_ingredient, though it doesn't explicitly name the destructive counterpart relationship. Clear but no explicit sibling differentiation.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives (e.g., bar_update_ingredient, bar_remove_from_shelf). The agent must infer usage entirely from the name.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a destructive mutation ('Remove') but never states whether the deletion is permanent, whether it errors when the constraint is absent, or whether any permissions/state preconditions apply. 'single' hints that only one constraint is affected, which is the only real behavioral signal.

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?

A single front-loaded sentence with zero filler. It is efficient, though for a three-parameter, un-annotated mutation tool the brevity is arguably under-specification rather than true conciseness.

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 destructive, un-annotated tool with three fully undocumented required parameters, the description is inadequate. The presence of an output schema excuses it from explaining return values, but it still omits preconditions, error behavior, and parameter meaning.

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%, and the description supplies no semantics for cocktail_id, sort, or axis. 'axis' and 'recipe slot' loosely gesture at two of the three parameters, but no formats, valid values, or meaning of 'sort' (slot index? ordering key?) are given, so the description fails to compensate for the coverage gap.

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?

States a specific verb ('Remove') and resource ('a single axis constraint from a recipe slot'), which cleanly separates it from the set/get siblings (bar_set_band_constraint, bar_set_point_constraint, bar_get_slot_constraints). However, it never clarifies how an 'axis constraint' relates to the band/point constraints named by its siblings, leaving the domain model to inference.

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?

No when-to-use guidance, no prerequisites (e.g., does the constraint need to exist, does the slot need to be populated), and no mention of alternatives such as bar_get_slot_constraints for inspection or the set_* tools for modification. The agent is left to guess the workflow position of this tool.

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

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 does disclose the per-line output structure (sort index, ingredient, constraint presence), which tells the agent what the read yields, but it is silent on permissions, side effects, and whether the operation is purely read-only. An output schema exists, so some of the return-value detail is redundant with structured data, keeping this at a middle score.

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?

Front-loaded with the core action in the first sentence, followed by output detail and the routing hint. The second sentence ('Each line shows...') is slightly detailed but earns its place by describing the return shape. No filler or repetition.

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 single-parameter read tool with an output schema, the description covers purpose, output content, and downstream usage well enough for correct invocation. The only real gap is the undefined `cocktail_id` semantics, which the description does not address.

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% for the single `cocktail_id` parameter. The description implies the input selects 'a cocktail's ingredient slots' and that the result includes a `slot_sort` identifier, but it never explicitly explains what `cocktail_id` expects or its format. It partially compensates but leaves the lone parameter under-specified.

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?

States a specific verb and resource ('List a cocktail's ingredient slots') and details exactly what each returned line contains (sort index, current ingredient, constraint flag). It also distinguishes itself from neighbors by naming bar_alternatives_for_slot and the constraint setters as downstream consumers of the slot index it returns.

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?

Gives an explicit workflow cue: 'Use this to find the right `slot_sort` before calling `bar_alternatives_for_slot` or constraint setters.' That routes the agent to the correct sibling and clarifies the tool's role as a lookup step. It does not state any when-not-to-use conditions, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read, but says nothing about whose favorites are returned, whether the list is paginated, or what happens if the user has no favorites. An output schema exists, which lightens the return-value burden, but the authorization/scope behavior remains opaque.

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?

A single short sentence with no filler and the action front-loaded. It avoids padding, but the extreme brevity is under-specification rather than efficient 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?

With an output schema present, return values need not be described, but the tool still leaves key context unstated: the meaning of user_id and its default, and whether this is a per-user or global favorites list. For a 1-parameter tool with zero annotation and zero schema coverage, the description is too thin.

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% for the single user_id parameter, so the schema gives an agent only a name, type, and a suspicious default of 1. The description does not explain that user_id identifies the user whose favorites are fetched, nor what default 1 means (e.g., current user). It adds no meaning beyond the schema and does not compensate for the coverage gap.

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?

States a specific verb and resource ("Get user's favorite cocktails"), which is distinct from siblings like bar_list_cocktails or bar_makeable_cocktails. However, it does not distinguish itself from siblings explicitly, and "favorite" is ambiguous (a curated list vs. per-user favorites) — the presence of a user_id parameter hints at the latter but this is left to inference.

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?

No guidance on when to use this tool versus the many sibling listing tools (bar_list_cocktails, bar_get_collection, bar_search_cocktails). No exclusions, no prerequisites, no mention of whether a user must be authenticated or how favorites are established.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it does a good job: it explains that it loads constrained slots, pits them against in-stock bottles, uses a penalty-vs-threshold cut-off with hard-disqualification, and returns results sorted worst-gap-first. The only unstated traits are the read-only nature and any cost/pagination behavior, which are minor for a clearly analytical 'Find' operation.

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?

Front-loaded with a one-line purpose, followed by a compact mechanics sentence and a clean Args block; nothing is repeated and the ordering (purpose, algorithm, sort order, parameters) puts the most decision-relevant information first.

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?

An output schema exists, so return values need no explanation, and the description still usefully notes the worst-gap-first ordering. It leans heavily on domain jargon (slots, penalty, hard-cap) that a naive agent may not fully grasp, but it is consistent with the rest of the tool family, so the gap is minor.

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 0% and both parameters are only titled ("Threshold", "Cocktail Ids"), yet the Args block compensates fully: it explains cocktail_ids as a restriction with None meaning every constrained slot, and gives threshold both its default and an intuitive operational reading ("roughly two-axis miss or one hard-cap brush"). This adds genuine meaning the JSON schema lacks.

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 opening line states a concrete verb and object ("Find recipe slots where the best in-stock bottle is a stretch") and even labels the concept ("the shopping list"), so the agent knows this is a gap/shopping-list computation over flavor constraints. It does not, however, explicitly disambiguate from the sibling bar_get_shopping_list, so the agent must infer the difference from wording alone.

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?

Usage is heavily implied by the domain framing ("the shopping list") and by the deterministic algorithm described, so an agent can guess it is the analytical gap-finder rather than a plain list. But there is no explicit when-to-use/when-not-to-use statement and no named alternative (e.g. bar_get_shopping_list or bar_alternatives_for_slot) to route between them.

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

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

With no annotations, the description carries the full behavioral burden. 'Get' implies a read, but the description says nothing about error behavior for missing IDs, permissions, or pagination.

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?

A single front-loaded sentence with no wasted words. It states resource and identifier scope immediately.

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?

An output schema exists, so return values need no explanation. For a simple single-param getter the description is adequate, though it omits usage context and any behavioral hints.

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 0% and the schema only labels the field 'Id'. The description's 'by ID or slug' adds genuine meaning by clarifying both accepted identifier forms, compensating for the bare schema.

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 gives a specific verb (Get) and resource (cocktail) with a qualifier (by ID or slug) that separates it from the list/search siblings. However, it does not name an alternative like bar_search_cocktails or bar_list_cocktails to sharpen the boundary.

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?

There is no guidance on when to use this instead of bar_search_cocktails, bar_list_cocktails, or bar_get_collection. The agent must infer usage from the name alone.

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

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

With no annotations, the description carries the full behavioral burden. It implies a read operation ('Get'), which is reasonable, but discloses nothing about permissions, error behavior for invalid ids, or pagination/size limits on the embedded cocktails. For a read tool with zero annotations and no output schema description in the text, this is thin.

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?

Single concise sentence, front-loaded with the verb and resource. No waste, though it is arguably under-specified rather than maximally informative.

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?

Although an output schema exists (reducing the need to explain return values), the description is minimal for a tool in a dense sibling set with an ambiguous, undocumented id parameter and no usage guidance. It does not provide enough context to reliably distinguish it from bar_list_collections or explain what ids are valid.

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% and the single parameter 'id' is undocumented in both schema and description. The description doesn't clarify whether the id is a collection identifier vs. a cocktail id, which matters for sibling disambiguation. Parameter meaning is left implicit.

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?

States a clear verb ('Get') and resource ('specific cocktail collection') and notes it includes its cocktails. This distinguishes it from bar_list_collections (plural) and from bar_get_cocktail, though it doesn't explicitly name those siblings.

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?

No when-to-use or when-not-to-use guidance. Given many sibling tools like bar_list_collections and bar_get_cocktail, the description leaves the agent to infer that this is for fetching a single collection by id, with no exclusions or alternatives stated.

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

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

With no annotations, the description carries the disclosure burden and does well: it reveals that profiles are per-axis integer scores on a category scale (gin: 0-3 across named axes) and that provenance (source enum, confidence, notes) is returned. It does not describe read-only safety or error behavior, but for a read operation the return-shape detail is substantial.

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?

Front-loads the purpose in one sentence, then supplies axis-scale and provenance detail. Efficient and well-ordered, with no filler, though the scale example is slightly verbose for a retrieval 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?

An output schema exists, so return values need not be spelled out, yet the description goes further and characterizes them. For a single-param read tool this is largely complete; the main gap is the absence of usage routing or identifier semantics.

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 0% for the single required ingredient_id, so the description must compensate. It adds only modest meaning by clarifying 'ingredient (specific bottle)', which helps distinguish a specific bottle from a generic ingredient, but adds no identifier format or lookup guidance.

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?

States a specific verb (Return) and resource (flavor profile) plus scope ('recorded for an ingredient (specific bottle)'), which clearly separates it from the write-side sibling bar_set_flavor_profile. It is clear on its own, though it never names an alternative tool to sharpen the contrast.

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?

Usage is implied by the clear read purpose, but there is no explicit when-to-use guidance and no routing to alternatives such as bar_get_ingredient or bar_list_flavor_axes. An agent can infer the intent but gets no exclusions or prerequisite conditions.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It only implies a read operation via the verb 'get' and adds no information about error handling (e.g., missing ID), permissions, or side effects; it merely restates the tool name.

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?

A single, front-loaded sentence with no filler or repetition. It is appropriately sized for a simple retrieval tool, though the phrase 'detailed information' is generic and could be tightened.

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 output schema exists, so the description need not explain return values, and the tool itself is simple (one required parameter). However, with no annotations and 0% schema description coverage, the missing parameter semantics and usage routing leave a gap an agent must fill by inference.

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%, and the description does not mention the required 'id' parameter at all. It does not explain the expected identifier format or where to obtain a valid ID, so the agent receives no semantic guidance beyond the schema's bare property name.

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?

States a clear verb ('Get') and resource ('ingredient') with a scope qualifier ('specific'), so the agent understands this retrieves a single ingredient. It does not differentiate from sibling tools like bar_search_ingredients or bar_list_ingredients, which could also return ingredient information.

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?

No explicit when-to-use guidance, prerequisites, or alternatives are provided. The phrase 'specific ingredient' hints at retrieval by known identifier, but the description never says to use this instead of search or list, leaving the agent to infer from the name and schema.

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

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

No annotations are provided, so the description carries the full behavioral burden. It conveys that this is a retrieval of the user's shelf, but says nothing about read-only safety, default user scoping, empty-shelf behavior, or ordering. For a tool with zero annotation coverage this is thin.

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?

A single tight sentence that front-loads the verb and resource with zero filler. Nothing to trim and nothing buried.

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?

An output schema exists, so return values need not be described, and the core purpose is covered. However, the undocumented user_id default leaves a real gap in how an agent should invoke it, which a single clause could have closed.

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?

There is one parameter (user_id, default 1) at 0% schema description coverage, and the description never mentions it or what omitting it means. The default-1 behavior is a genuine semantic risk that neither the schema nor the description explains.

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?

States a specific verb+resource ('Get ingredients ... on the user's shelf') and clarifies the meaning of 'shelf' with '(what they have available)'. It implicitly contrasts with shelf mutators like bar_add_to_shelf/bar_remove_from_shelf by using 'get', but never names a sibling or scoping rule explicitly.

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 parenthetical hints at when this is useful (checking available ingredients, e.g. before bar_makeable_cocktails), but there is no explicit when-to-use statement or comparison to alternatives like bar_get_shopping_list or bar_search_ingredients. Usage is left to inference.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing: no statement of read-only safety, no ordering, pagination, or per-user scoping behavior. The verb "get" weakly implies a non-mutating call, but that inference is doing all the work.

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?

A single short sentence with zero filler, and the operative verb is front-loaded. It is efficient, though its brevity is partly the source of the missing detail rather than a deliberate tightening.

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 simple one-parameter read tool with an output schema (so return values need no explanation), the description is close to sufficient. It still omits the scoping semantics of user_id and the relationship to bar_add_to_shopping_list, leaving the agent to guess at the surrounding workflow.

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% for the single user_id parameter, and the description only hints at user scoping via the phrase "the user's" — it never explains the parameter, its default of 1, or what happens if it is omitted. This falls short of compensating for the undocumented schema.

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?

"Get the user's shopping list" names a specific verb (get) and resource (shopping list), so the operation is unambiguous. It does not, however, distinguish itself from the sibling bar_add_to_shopping_list or clarify whether it returns full items, quantities, or a summary — differentiation is left to the reader.

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?

No when-to-use guidance is given beyond the implicit read semantics. The description never mentions the related sibling bar_add_to_shopping_list (the natural counterpart), nor any conditions such as empty-list handling or when to prefer other list-style tools in the family.

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

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

No annotations are provided, so the description carries the burden, but 'List' does imply a non-destructive read. It says nothing about permissions, pagination, or whether constraints are returned per slot or flattened. The existence of an output schema covers the return shape, keeping this at a modest 3.

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?

A single front-loaded sentence with no filler; the resource is stated immediately. It is efficient, though its brevity borders on under-specification rather than pure conciseness.

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 is simple (one parameter) and an output schema exists, so return values need not be explained. However, the description never clarifies what a 'flavor constraint' is or how it relates to the sibling set/delete tools, leaving gaps an agent would have to guess at.

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% and the single required parameter cocktail_id is undocumented in the schema. The phrase 'for a cocktail's slots' implies that the argument identifies the cocktail, so the description partially compensates, but it adds no format or validation detail beyond the obvious.

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?

States a specific verb (List) and resource (flavor constraints for a cocktail's slots), which is enough to separate it from the write siblings bar_set_band_constraint, bar_set_point_constraint, and bar_delete_slot_constraint. It does not explicitly name any sibling, so it stops short of 5.

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?

No when-to-use guidance and no alternatives named. The agent must infer from the sibling names that this is the read counterpart to the set/delete constraint tools, and nothing tells it whether bar_describe_slots or bar_get_flavor_profile is the better fit for a related question.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses nothing beyond the purpose. It does not say whether matching is exact or fuzzy, whether results are paginated or capped, or whether an unknown ingredient id errors or returns empty.

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?

A single front-loaded sentence with zero filler, which is appropriate for a one-parameter lookup. It is efficient rather than verbose, though it is arguably under-specified rather than genuinely concise.

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?

An output schema exists, so return values need not be explained, and the operation is simple with one parameter. Still, with no annotations and no usage or matching-behavior notes, an agent lacks enough to call this confidently against its many 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 coverage is 0% and the single parameter is an undescribed 'id'. The description does add one useful disambiguation by stating the id refers to an ingredient (not a cocktail), but it gives no format, name-vs-id, or validation detail.

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?

States a specific verb ('Get') and resource ('cocktails that use a specific ingredient'), which is enough for an agent to know the retrieval is ingredient-driven. It does not differentiate itself from siblings such as bar_search_cocktails or bar_uses_for_bottle, so it stops short of a 5.

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?

There is no when-to-use guidance and no named alternative, despite many plausible siblings (bar_search_cocktails, bar_uses_for_bottle, bar_makeable_cocktails). The agent must infer the use case entirely from the one-line purpose.

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

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

No annotations are provided, so the description carries the burden. It hints at read-only listing via 'browse or audit' and clarifies the missing_image_only audit helper, but does not state safety profile, pagination semantics, or how page/limit interact. It is helpful but not rich.

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?

Front-loads the purpose in one sentence, then a clean bulleted filter list. The bullets largely mirror schema keys, so there is mild redundancy, but each line maps to undocumented behavior or enum values.

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 14-parameter filter tool with no annotations and an output schema, the description supplies the missing filter semantics and sort options. It leaves pagination (page/limit) implicit, a minor gap given the output schema covers returns.

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%, so the description must compensate. It explains the meaning of nearly every filter and even gives sort enum values and ID provenance ('from the matching list_* tools'). It omits only page and limit semantics.

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?

States a specific verb+resource ('List and filter cocktails') and adds a scope note ('browse or audit the collection'). It doesn't explicitly differentiate from siblings like bar_search_cocktails or bar_makeable_cocktails, which an agent must infer.

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?

Says to use it 'to browse or audit the collection,' which distinguishes auditing (via missing_image_only) from browsing, but gives no explicit when-not or contrast with similar siblings such as search_cocktails or makeable_cocktails.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it discloses nothing beyond the verb. It does not state that it is read-only, whether results are paginated or ordered, or whether authentication is required. Low-risk nature is only implied by the word 'List'.

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?

A single front-loaded sentence with zero waste. It is efficient, though arguably terse to the point of under-specification rather than optimally sized.

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?

With zero parameters and an output schema covering return values, the description is nearly sufficient for such a simple tool. The only real gap is the absence of any guidance on ordering, pagination, or how it relates to bar_get_collection.

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?

The tool takes zero parameters, so the schema cannot be improved upon and the baseline for an empty parameter set applies. There is nothing for the description to clarify.

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?

States a specific verb ('List') and resource ('cocktail collections'), so the operation is unambiguous. However it offers no differentiation from the many sibling list/get tools (e.g. bar_get_collection, bar_list_cocktails, bar_list_tags), which share the same naming pattern.

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?

There is no indication of when to use this tool versus bar_get_collection for a single collection or the other list_* siblings. No prerequisites, no context, no exclusions are given.

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

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

No annotations are provided, so the description bears the full behavioral burden. It adds useful domain context (per-category, integer-scored, gin's 7-axis 0–3 system) and 'List' implies a read-only operation, but it does not state permissions, error behavior, or paging. Adequate but not rich for an annotation-free tool.

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?

Three short sentences, front-loaded with the core action and scoping constraint. Every sentence adds value (what it lists, the scoring model, and the intended workflow) with no 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?

An output schema exists, so return values need not be explained. The description covers purpose, usage, and domain model adequately; the only minor gap is the absence of valid category values, which matters because 'category' drives the whole result.

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 0% and the sole parameter 'category' has a default of 'gin'. The description partially compensates by explaining axes are per-category and giving 'gin' as an example value, but does not enumerate valid categories or describe the effect of an unknown category, leaving the parameter partly under-explained.

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?

States a specific verb+resource ('List the flavor axes defined for a category') and immediately clarifies that axes are per-category. An agent can distinguish it from bar_get_flavor_profile (retrieves a profile) and bar_set_flavor_profile without opening either schema.

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?

Explicitly says to use this 'to discover valid axis names before setting profiles or slot constraints,' which routes the agent to the profile/constraint setters. It stops short of naming the specific sibling tools or stating any exclusions, so no explicit when-not guidance.

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

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

No annotations are provided, so the description carries full burden but adds nothing about behavior. It doesn't say this is a read-only enumeration, whether results are paginated, cached, or how large the list might be. An output schema exists, which relieves some burden on return shape, but the description contributes nothing behavioral.

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?

One short sentence, front-loaded with the verb. No waste, though it also could not be shorter without losing meaning.

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 simple zero-param list tool with an output schema, the description is minimally sufficient. It doesn't need to explain return values, but it also adds no routing or behavioral context to help an agent preferring this over related list/search tools.

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?

Zero parameters, so the baseline is 4. Nothing to document and the description correctly implies no filtering arguments.

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?

States a clear verb (list) and resource (glass types), matching the pattern of sibling list tools like bar_list_ingredients and bar_list_methods. It doesn't distinguish itself from siblings beyond the resource name, but the resource is specific enough.

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?

No when-to-use guidance, no mention of alternatives, no context about when an agent should enumerate glass types versus looking one up. Pure statement of purpose.

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

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

No annotations are provided, so the description carries the full burden, and it delivers: it explains filter semantics (recursive category, structural 'leaf' meaning, commodity exclusion) and the output behavior (cocktail counts, 'NO IMAGE' flags). It omits pagination/limit behavior and any auth or rate-limit context, keeping it short of a 5.

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?

Purpose and the sibling-routing guidance are front-loaded, then filters are cleanly bulleted one per parameter. It is long, but the length is justified by 12 undocumented parameters; a few phrasings could still be tightened.

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?

With an output schema present, the description needn't explain return values, yet it still notes the actionable output. All filtering paths an agent needs for a 12-param browse tool are covered; only pagination is unaddressed and that is minor.

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 0%, so the description must compensate and largely does: it documents category (as an ingredient ID, with real examples), name, origin, strength_min/max, all four boolean filters, and the full set of sort enum values. Only page and limit are left undocumented, a minor gap against 10 of 12 params covered.

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?

States a specific verb and resource ('List and filter ingredients') and immediately distinguishes itself from the sibling bar_audit_ingredients, naming the exact scenario each serves. An agent can route between them without opening either schema.

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?

Explicitly says when to prefer the alternative ('incomplete entries' worklist → bar_audit_ingredients) and when to use this one (general browsing/filtering). It also supplies concrete filter combinations, e.g. specific_only + missing_image_only + exclude_commodities for the 'real bottles missing artwork' list.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, yet it says nothing about read-only nature, whether the results are cached or static, or any rate/permission constraints. For a zero-argument lookup the safety profile is implied but not stated.

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?

A single front-loaded sentence with zero wasted words. It is appropriately sized for a trivial list tool, though it is arguably too terse to earn a top score.

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?

With zero parameters and an output schema present, the description does not need to explain return values, so it is close to sufficient. However, with no annotations it leaves the read-only/pure-lookup nature entirely implicit, which is a modest gap.

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?

The tool takes no parameters, so there is nothing for the description to document; the baseline of 4 applies. The schema is empty and fully consistent with the described no-argument call.

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?

States a specific verb ('List') and resource ('cocktail preparation methods'), which disambiguates it from the other list tools like bar_list_glasses and bar_list_ingredients. It doesn't explicitly contrast itself with siblings, but the resource is distinct enough that an agent can tell it apart.

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?

There is no guidance on when to reach for this tool versus bar_get_cocktail or bar_list_cocktails, nor any stated preconditions. The usage is only inferable from the name and the word 'List'.

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

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

No annotations are provided, so the description carries the full burden. It doesn't disclose whether the list is paginated, sorted, cached, or includes count/ordering metadata. 'List all' suggests no pagination, but that is an inference. Output schema exists but the description doesn't hint at its shape.

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?

Single short sentence, front-loaded, zero waste. Could arguably be one word shorter, but it is appropriately sized for a no-arg list operation.

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?

A no-arg list tool with an output schema does not need heavy description. The output schema presumably enumerates the tags, so return semantics are covered. What's missing is any signal about ordering or whether tags are user-scoped vs. system-wide, but for a simple enumeration this is minor.

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?

Zero parameters, so there is nothing to document; baseline 4 applies. Description adds no param context because none is needed.

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?

Specific verb+resource: 'List all cocktail tags.' Clearly states the operation and entity, distinguishing it from siblings like bar_list_ingredients or bar_list_collections. It does not, however, differentiate from other list tools beyond the noun itself.

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?

No when-to-use guidance, no alternatives mentioned, no exclusions. The agent must infer that this tool simply enumerates tags with no filtering. Given 40+ siblings, some routing context would be valuable.

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

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

With no annotations at all, the description carries the full behavioral burden, and it discloses very little. Whether substitution, optional ingredients, or partially-stocked items count as 'makeable', whether results are ranked or limited, and whether any permissions are needed are all unstated. 'Currently on the shelf' hints at state-dependence but never explains it.

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?

A single front-loaded sentence with zero padding; the filtering qualifier arrives immediately after the verb. It is arguably too terse for the behavioral gaps, but as pure conciseness it is efficient.

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?

An output schema exists, so return values need not be described. However, for a state-dependent query tool with an undocumented user scope and no annotations, the description leaves key operational questions (whose shelf, what counts as makeable, result ordering) unanswered.

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?

The single parameter user_id has 0% schema description coverage and the description never mentions it or explains whose shelf is being evaluated. The phrase 'the shelf' is ambiguous precisely because the scope parameter is undocumented in both the schema and the description.

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?

States a specific verb+resource ('Get cocktails') with a clear qualifying scope ('can be made with ingredients currently on the shelf'), which inherently separates it from bar_list_cocktails and bar_search_cocktails. It stops short of naming those siblings explicitly, but the purpose is unambiguous.

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 shelf-constrained framing implies when the tool is appropriate (when the user wants drinks they can actually make right now), but there is no explicit when-to-use/when-not guidance and no reference to the alternatives like bar_list_cocktails or bar_find_gaps. Usage must be inferred from the purpose sentence alone.

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

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

With no annotations, the description carries the full behavioral burden, yet it says nothing about whether removal is destructive or reversible, what happens to IDs not present on the shelf, or any permission requirements. A mutation tool this thin leaves the agent guessing about side effects.

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?

A single short sentence is appropriately front-loaded and free of padding, but its brevity here reflects under-specification rather than discipline. It neither wastes words nor earns them.

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?

An output schema exists, so return values need not be explained, but a two-parameter mutation tool with zero annotation coverage and 0% schema descriptions needs more than one sentence. Key invocation details — required vs optional targeting and removal effects — are missing.

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% and the description only loosely implies that 'ingredient_ids' are the items to remove. It adds no meaning for 'user_id' (including its default of 1), for whether the array is a full replacement or a partial removal, or for ordering/duplicate handling.

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 gives a specific verb ('Remove') and resource ('ingredients from the shelf'), which clearly separates it from the sibling bar_add_to_shelf. It does not, however, name any sibling or scope qualifier, so an agent must infer the pairing from the surrounding tool 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?

There is no indication of when to use this tool versus bar_add_to_shelf, bar_get_shelf, or the shopping-list tools, nor any stated preconditions (e.g. the ingredient must already be on the shelf). Usage is only weakly implied by the shelf context.

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

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

No annotations are provided, so the description carries the full burden. It discloses that results include ingredients, which is useful, but says nothing about matching behavior (substring vs exact), the effect of the default limit, pagination, or error/empty-result handling.

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?

Two sentences, no filler, with the core action stated first. Efficient and front-loaded, though very thin overall.

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?

An output schema exists, so return-shape detail is less critical, but with no annotations and 0% parameter coverage the definition leaves an agent guessing about result volume (limit/pagination) and match semantics. It is under-specified for a search tool in a 40+ tool namespace.

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% and neither parameter has a description. 'By name' loosely conveys what 'query' accepts, but the 'limit' parameter (default 10) is never explained, so the description does not compensate for the schema gap.

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?

States a specific verb (search) and resource (cocktails) plus a scoping constraint ('by name'), which distinguishes it from list-all siblings like bar_list_cocktails. It does not explicitly name or contrast with any sibling, so it falls short of a 5.

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?

There is no when-to-use guidance and no mention of alternatives such as bar_get_cocktail (single lookup) or bar_list_cocktails (browse all). The phrase 'by name' hints at the search axis but the agent gets no explicit routing rule.

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

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

With no annotations, the description carries the full load, and it does explain the filtering behavior of the three flags concretely. It stops short of disclosing matching semantics (case sensitivity, substring vs prefix), result ordering, or how limit behaves, which are the behavioral traits an agent still needs.

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?

Front-loaded purpose sentence followed by scannable bullets, with no filler. Each flag line adds distinct, actionable meaning and the combination tip is a genuine value-add rather than padding.

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?

An output schema exists, so return-value explanation is unnecessary, and the description adequately covers the non-obvious boolean filters for a 5-parameter search tool. Only the limit parameter and query-matching behavior remain unaddressed, a minor gap.

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%, so the description must compensate and largely does: it defines specific_only, missing_image_only, and exclude_commodities precisely, and the opening sentence implies query semantics. The limit parameter is entirely undocumented and matching behavior for query is unspecified, keeping it short of a 5.

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?

States a specific verb and resource ("Search for ingredients by name"), so the core action is unambiguous. However, it never distinguishes itself from close siblings like bar_list_ingredients, bar_get_ingredient, or bar_search_cocktails, leaving the agent to infer the boundary from the name alone.

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 bullet list gives clear context for when each flag matters ("handy for cleanup work") and even recommends a combination for finding bottles needing artwork. But it offers no guidance on when to choose this tool over bar_list_ingredients or bar_get_ingredient, so tool-level selection is left implicit.

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

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

With no annotations, the description carries the full behavioral burden and does add real value by explaining the constraint's downstream semantics (zero penalty inside, graded penalty outside). However, it never discloses mutation behavior such as whether setting a Band overwrites an existing constraint on that axis, or any prerequisites on the slot/cocktail. Output schema covers return values, so that gap is excused.

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 core action is front-loaded, followed by a definition, usage rule, a concrete Negroni example, and a bounds note. It is dense but each element earns its place; the quoted definition and example add real comprehension value without much waste.

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 7-parameter mutation tool with zero annotation and zero schema-description coverage, the description explains the domain concept well but omits mechanical details for several parameters (cocktail_id, sort, out_weight) and any overwrite/idempotency behavior. Output schema exists so return-value explanation is not needed, keeping this at an adequate-but-gapped 3.

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 0%, so the description must compensate, and it meaningfully explains axis (0–3 for gin), lo/hi (inclusive integer bounds), and hard (disqualifying flag). But three of seven parameters — cocktail_id, sort, and especially out_weight — are left entirely undefined in both schema and description, so compensation is only partial.

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?

States a specific verb and resource ('Set a Band constraint on one axis of a recipe slot') and defines what a Band is, so an agent knows the operation precisely. It differentiates conceptually from the sibling bar_set_point_constraint via the hard/graded distinction, but never names that alternative, leaving some sibling routing to inference.

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?

Gives clear when-to-use guidance: 'Use Band for the forgiving axes of a slot — most slots are wide on most axes,' plus the condition for hard=True (axes that truly disqualify). The complementary 'when-not' (use a point constraint instead) is only implied, not stated with the alternative tool named.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses merge-over-existing semantics, the required-first-write case, and the matchability side effect of suggestable_for_classics. It stops short of stating permissions, reversibility, or overwrite/clearing behavior when profile changes an existing axis.

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 front-loaded with the core semantics and the Args section is efficient and scannable. The title line is redundant with the name, but the body sentences each earn their place with dense, non-repetitive information.

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 7-parameter mutation tool with 0% schema coverage and an output schema present, the description supplies all the missing parameter detail, the merge/creation behavior, and the downstream effect on the matcher. An agent has everything needed to invoke it correctly; return-value explanation is unnecessary given the output schema.

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%, so the description must compensate, and it does: it documents every parameter's meaning, the 0–3 integer range for profile axes, the category requirement condition, allowed confidence/source values, and the specific purpose of suggestable_for_classics for novelty bottles.

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 specific verb and resource ('Set or update the flavor profile for an ingredient'), and it distinguishes itself from the read-only sibling bar_get_flavor_profile by clarifying that it writes the profile. An agent can tell exactly what this tool does without opening the schema.

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 explains the partial-update merge behavior and the condition under which 'category' becomes required (no profile yet), and it points to bar_list_flavor_axes for valid axes. It does not explicitly name a competing alternative tool, but the context and prerequisites are clear.

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

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

With no annotations, the description carries the full burden. It helpfully discloses the penalty model ('penalty grows with distance') and that value ranges 0-3 for gin axes, but says nothing about mutation semantics such as whether it overwrites an existing constraint, permissions, or error behavior.

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 action is front-loaded in the first sentence, followed by explanation and a single illustrative example. It is reasonably tight; the example earns its place, though the internal quoting and line breaks are slightly noisy.

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?

An output schema exists, so return values need not be explained. However, for a mutation tool with no annotations, the description omits overwrite/replacement behavior, the role of 'weight', and explicit routing against the band/min/max constraint siblings, leaving an agent under-informed on several call-critical points.

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 0% and there are 5 parameters, yet the description only adds meaning for 'axis' (0-3 for gin) and 'value' (integer). The important 'weight' parameter (which scales the penalty) and 'sort'/'cocktail_id' are left entirely undefined, so it does not compensate for the coverage gap.

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 ('Set a Point constraint on one axis of a recipe slot'), and the body explains the Point concept ('exact-ish target; penalty grows with distance'). This lets an agent distinguish it conceptually from the band-constraint sibling, though it never names that sibling explicitly.

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 gives clear context for when to reach for this tool ('Use Point for the *exposed* axes of a slot') with a concrete worked example (Martinez gin → juniper Point(2)). It does not state when to prefer bar_set_band_constraint or what to avoid, so it stops short of full when/when-not guidance.

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

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

No annotations are provided, so the description carries full burden. It discloses a meaningful semantic: cross-category subs get a small flat penalty so in-category ranks first, and tolerance modes change behavior ('exact' requires a named bottle). However, it doesn't discuss whether this mutates existing slot metadata, idempotency, permissions, or error behavior when required params are missing.

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?

Front-loaded with the core purpose and prerequisite, then a compact Args block. Slightly verbose in restating param names, but each line adds semantic meaning not present in the schema. Well-structured for an 8-param 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?

Given 8 params with 0% schema coverage and an output schema present (so return values needn't be explained), the description covers all parameters, the prerequisite relationship with constraint tools, and the cross-category penalty behavior. Nothing essential for correct invocation is missing.

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%, so the description must compensate and it does: it explains sort as 1-based BA sort index, defines each tolerance value ('exact'=named bottle, 'style'=vector match, 'any'=any in-category), states exact_ingredient_id is required when tolerance='exact', and clarifies also_accept_categories semantics and proof_min/proof_max as US proof range.

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?

States a specific verb+resource ('Declare the category + tolerance for a recipe slot') and distinguishes itself from siblings by naming what it must precede (axis constraints) and pointing to bar_describe_slots for the sort index. An agent can tell it apart from bar_set_point_constraint and bar_set_band_constraint.

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?

Explicitly states 'Required before setting axis constraints', which is a clear prerequisite and sequencing rule. It doesn't say when NOT to use it or fully contrast with the constraint-setting siblings, but the prerequisite and the pointer to bar_describe_slots give solid context.

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

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

With no annotations at all, the description carries the full behavioral burden. It implies a read-only aggregate lookup but says nothing about permissions, whether counts are cheap/cached, freshness of the data, or the shape of the response. It discloses only the general content type.

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?

A single short sentence with the purpose front-loaded and zero filler. Nothing to trim.

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?

An output schema exists, so return values need not be explained, and a zero-param read tool has a low bar. Still, the vague 'etc' leaves the coverage of the statistics unspecified and there is no guidance on when this aggregate view is the right call versus the list tools.

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?

The tool takes zero parameters, so the schema requires no semantic elaboration; baseline is 4. The parenthetical examples add a little meaning about the statistics returned, though 'etc' remains vague.

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?

Names a specific verb ('Get') and resource ('bar statistics') and gives concrete examples of what is returned (total cocktails, ingredients). It is clearly distinct from the sibling list/search/get tools, though the sibling set itself makes it unambiguous rather than the description doing the work.

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?

No statement of when to use this versus alternatives, no prerequisites, no mention of what triggers a stats request. Usage is only implied by the word 'statistics'.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose one meaningful trait: unspecified fields are left unchanged (patch semantics). It omits permissions/authorization, what happens if the id does not exist, and side effects on nested data such as ingredients or parent_cocktail_id, which is thin for a 12-parameter mutation.

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?

Two short sentences, front-loaded with the action, and no filler. Every sentence carries information.

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?

An output schema exists, so return values need no explanation. But for a 12-parameter mutation with zero schema coverage and no annotations, the description is insufficient: it does not clarify whether 'ingredients' replaces or merges existing data, what 'id' expects, or failure behavior.

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 12 parameters, so the description must compensate, and it does not. Nested structures like 'ingredients' (free-form objects) and fields such as 'parent_cocktail_id' or 'cocktail_method_id' get no explanation of semantics or expected values, leaving the agent to guess.

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?

States a specific verb and resource ('Update an existing cocktail'), and the word 'existing' implicitly separates it from bar_create_cocktail and bar_delete_cocktail. It is clear but does not explicitly name or distinguish itself from those siblings.

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?

'Only provide fields you want to change' gives practical guidance on how to invoke it (partial update). However, there is no explicit when-to-use vs alternatives, no prerequisites, and no mention of parallel tools like bar_create_cocktail or bar_update_ingredient.

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

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

No annotations provided, so the description carries full burden. It doesn't state whether this requires auth, whether changes are reversible, what happens on invalid ids, or any mutation semantics beyond the word 'Update'. Very thin behavioral disclosure for a mutation tool.

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?

Two short sentences with no waste, front-loaded with the action and a patch semantics hint. Nothing extraneous.

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?

An output schema exists so return values needn't be described, but for a 7-param mutation tool with 0% schema coverage, no annotations, and no usage guidance, the description is too sparse. Agents lack the info to correctly construct calls (e.g., image id semantics, strength units).

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 7 parameters, so the description must compensate. It only tells the agent to supply fields to change, but never explains what 'id', 'images' (integer array?), 'parent_ingredient_id', or 'strength' mean or expect. The schema titles are bare and provide little help.

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?

Clear verb+resource: 'Update an existing ingredient.' Distinguishable from bar_create_ingredient and bar_delete_ingredient by explicit 'update'/'existing' wording, but no differentiation from bar_update_cocktail beyond the resource name.

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 sentence 'Only provide fields you want to change' gives partial patch-style guidance, but there's no when-to-use direction versus siblings (e.g., when to prefer create vs update, or how it relates to bar_audit_ingredients or bar_set_flavor_profile).

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not disclose whether the tool fetches an external URL, any size/format limits, permission requirements, or whether copyright is mandatory, which matters for a write operation that reaches out to a remote resource.

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?

Two tight sentences with the core action front-loaded and the return value immediately following. No filler or redundancy.

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?

An output schema exists, so explaining return values is not strictly needed (though the ID hint is a nice touch). The gaps are the undocumented copyright parameter and the absence of any behavioral context for a network-fetching write tool.

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%, and the description only hints at image_url ('from a URL'). The second parameter, copyright, is never mentioned, so half the parameters are undocumented in both the schema and the description.

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?

States a specific verb and resource ('Upload an image from a URL') and adds the downstream purpose (obtain an image ID for cocktails/ingredients). It implicitly separates itself from the sibling bar_upload_image_file, but never names that sibling to make the URL-vs-file distinction explicit.

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 conveys when the result is useful ('use when creating cocktails or ingredients'), which implies the workflow context. However, it gives no exclusions or explicit routing to bar_upload_image_file for local files, so the agent must infer the alternative.

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

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

With no annotations, the description carries the burden and does disclose the key behavioral outcome: it returns an image ID for reuse in cocktails or ingredients. However, it says nothing about file size/type validation, whether the upload is durable, or permission requirements for a mutation.

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?

Two tight sentences, no filler, with the action first and the return-value purpose second.

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?

An output schema exists, so the return values need not be explained, and the ID usage note is a nice touch. But with zero annotation coverage and 0% schema descriptions, the definition leaves format constraints, permissions, and the copyright parameter unaddressed for a mutation tool.

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% and the description only implies the file_path parameter through 'local file path'; the copyright parameter is entirely undocumented in both the schema and the description.

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?

Clear verb+resource: uploads an image from a local file path, and it identifies the return value (image ID). It is separable from the sibling bar_upload_image, presumably the non-file variant, but the description never names or contrasts that sibling explicitly.

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 phrase 'from a local file path' implies when to use this over bar_upload_image, which presumably handles remote/other sources, but the condition is never stated outright and no exclusions are given.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful semantics: results are limited to 'constrained' recipes and describe slot-based inclusion. It omits whether the operation is read-only, how results are ordered/paginated, or the effect of top_n, leaving notable behavioral gaps.

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?

Two tight, front-loaded sentences that lead with the core action before the use-case. The clause 'welcome it' is repeated in the second sentence, a minor redundancy, but overall there is little wasted text.

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?

An output schema exists, so return values need no explanation, and the description adequately conveys the tool's intent and the 'declared slot constraints' scoping. The main gap is the undocumented top_n parameter, which an agent cannot interpret from text alone.

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?

'Given a bottle' implicitly maps to ingredient_id, adding a little meaning. But schema coverage is 0% and the description never explains top_n or the default of 10, so with two undocumented parameters it only partially compensates for the schema gap.

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?

It states a specific verb (list) and resource (recipes that welcome a given bottle), scoped by 'declared slot constraints', which is more precise than a generic ingredient lookup. It does not explicitly distinguish itself from close siblings like bar_ingredient_cocktails or bar_alternatives_for_slot, so the distinction is left to inference.

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 sentence gives a clear when-to-use scenario ('when a new bottle arrives... before adding the bottle to your shelf'). However, it names no alternatives or exclusions, so an agent must still guess why to pick this over bar_ingredient_cocktails.

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