Pour Picks

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds useful context about the output scope (shared and distinct tasting notes, community ratings) but does not disclose any additional behavioral traits like whether bottle lookup is by UUID and name (suggested by schema) or what happens if a bottle is not found. With strong annotations, the absence of such details is acceptable.

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 a single, compact sentence that front-loads the core action and lists the comparison dimensions efficiently. It is appropriately sized and contains no filler. It could be slightly more structured with separators, but it is easy to scan.

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 read-only, two-parameter comparison tool with 100% schema coverage and no output schema, the description adequately explains what the tool does and what it returns. The main gap is the lack of guidance on output format or fallback behavior, but given the simplicity of the tool and strong annotations, the description is sufficient for competent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters (bottle_a and bottle_b) described as 'UUID or name'. The description adds no new parameter-level meaning beyond what the schema provides; it does not specify constraints like whether the two bottles must be distinct or whether name matching is case-insensitive. Baseline 3 is appropriate given complete schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('comparison') and resource ('two bottles'), and lists the comparison dimensions (proof, age, price, flavor profile, tasting notes, ratings). It distinguishes itself from sibling tools like get_bottle (single bottle) and find_similar (which finds similar bottles rather than comparing two specified ones), 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?

The description implies usage: when you have two specific bottles and want a side-by-side comparison. However, it does not explicitly state when to prefer this over find_similar or find_cheaper_alternative, nor does it mention any exclusions or prerequisites. The context is reasonable but left to inference rather than 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds result-scoping detail (same style, similar flavor, lower price), but does not disclose ordering, output shape, or behavior when no cheaper alternative exists.

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 carry all the needed information with no fluff. The main outcome is front-loaded, and the second sentence provides a useful real-world usage example.

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 read-only lookup tool with fully documented parameters and safety annotations, the description is largely complete. The main gap is the absence of any mention of return structure or behavior when no matches are found, but this is not critical for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so bottle_id and limit are already documented adequately. The description adds minimal semantic value by implying bottle_id is 'the given bottle,' but it does not enrich the meaning of the parameters beyond the 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 clearly defines the resource and criteria: bottles sharing style and flavor profile at a lower price than a given bottle. The 'lower price' qualifier helps distinguish it from siblings like find_similar, though it does not explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete usage context: 'what tastes like X without the price tag' questions. This clearly implies when the tool is appropriate, but it does not state when not to use it or mention sibling alternatives.

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?

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds context by stating the scoring is deterministic and based on 'Pour Picks structured tasting data', which is consistent with openWorldHint=false and gives the agent confidence that results are reproducible and closed-world.

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 two sentences with no wasted words. It front-loads the purpose and ranking criteria in the first sentence and adds determinism and data-source context in the 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?

For a two-parameter, read-only tool with full schema coverage, the description covers purpose, ranking logic, and determinism. The only gap is that the response shape is not described and there is no output schema, but the tool's behavior is well-specified enough for an agent 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 100%, so bottle_id and limit are already fully documented. The description maps bottle_id to 'given bottle' and implies ranking order, but it does not add parameter-level details beyond what the schema provides, so it stays at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does: returns bottles similar to a given bottle, ranked by shared flavor notes, body, sweetness, and char proximity. This differentiates it from sibling tools like compare_bottles (pairwise comparison) and get_recommendations (general suggestions).

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 input context is clear: pass a bottle_id to get similar bottles. However, the description does not name alternatives or state when not to use this tool, leaving the agent to infer the distinction from sibling names.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by disclosing exactly what the record contains (tasting, flavors, pairings, price, ratings) and the input flexibility (ID or name). No contradiction with annotations.

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 with no filler: the core scoping ('one bottle') is front-loaded, followed by a compact content list and the input contract. Every clause earns its place.

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 one-parameter, read-only tool with full annotation coverage, the description covers purpose, input format, and return contents. Minor gaps: no explicit routing to siblings like search_bottles and no behavior specified for unknown bottles, but the listed record contents adequately substitute for return-value documentation in the absence of an 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 100% — the schema already documents slug_or_id as 'Bottle UUID or a name like Eagle Rare 10'. The description's second sentence largely restates this, adding only the 'Pour Picks' brand context. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 — 'Detailed record for one bottle' — and enumerates the record's contents (tasting profile, flavor notes, pairings, price, community ratings). This unambiguously separates it from siblings like search_bottles (discovery), compare_bottles, and find_similar.

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 establishes a clear usage context: use this when you already have a specific bottle's UUID or name and want its full detail record. It lacks explicit exclusions or named alternatives, but the 'one bottle' scoping plus the accepted input formats give the agent enough context to choose correctly.

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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that output is personalized bottle picks and what inputs shape it, but it does not disclose behavioral details such as result ordering, empty-result behavior, or how recommendations are computed. Adequate 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?

A single, front-loaded sentence that states the core outcome ('Personalized bottle picks') and then compresses only the relevant inputs with helpful examples. Every element earns its place; no redundancy or fluff.

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 5 parameters, one required, and 100% schema coverage, the description covers the main invocation path well. No output schema exists, so a hint about the return shape would be a minor improvement, but an agent can select and call the tool confidently from this description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds concrete example flavor keywords and real-world occasion strings ('gift', 'everydy sipper', 'celebration'), which gives an agent a better sense of how to fill free-text fields beyond the schema's brief descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does: it produces personalized bottle picks based on taste preferences, budget, and occasion. This distinguishes it from siblings like search_bottles (query-based search), find_similar (similarity), and trending_bottles (popularity) by emphasizing personalization from taste/budget/occasion.

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?

Clear usage context is present: call this when you want recommendations driven by taste keywords, a budget cap, and an occasion. No exclusions or explicit alternatives are named, so it doesn't reach 5, but the intended scenario is unambiguous.

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?

Annotations already declare the tool read-only, idempotent, and non-destructive, so the description does not need to repeat that. It adds the timely 'right now' framing but does not disclose what a 'pour suggestion' looks like in the response or how the suggestion is generated.

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 a single compact sentence that front-loads the core purpose and then lists the influencing factors with useful examples. There is 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?

For a tool with no output schema and a similar sibling like get_recommendations, the description could clarify the response shape or when to choose this tool over its sibling. It is adequate for basic invocation but leaves some contextual ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all three parameters. The description adds concrete example values for mood and occasion ('unwinding', 'celebratory', 'nightcap', 'with friends'), which helps an agent choose realistic inputs beyond the schema's terse descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies this as a suggestion/recommendation tool for the current moment and names the three relevant inputs: mood, occasion, and season. It is specific about the intent, though it uses a noun phrase rather than an imperative verb and does not explicitly differentiate it from the similar 'get_recommendations' sibling.

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 'for right now' establishes when this tool is appropriate, and the mood/occasion/season basis gives clear context for invocation. It does not name alternatives or state when not to use it, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds useful behavioral context by stating the return format: structured tasting profiles with source attribution. It does not cover pagination or empty-query behavior, but that is minor given the annotation coverage.

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 with no fluff: the first fronts the core purpose and scope, the second covers filters and return contract. Every clause earns its place.

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 read-only search tool with all optional parameters and no output schema, the description gives the essential invocation context and return description. It does not mention sort order or behavior with no query, but schema and annotations fill the remaining practical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter is already documented in the schema. The description only summarizes filters as category, price (USD), and proof, which adds little beyond the schema's own parameter descriptions. Baseline 3 applies.

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 and resource: full-text search across 4,700+ spirits in the Pour Picks database. It also names the product scope (bourbons, ryes, scotches, other spirits) and return type, clearly distinguishing it from siblings that compare, recommend, or fetch single bottles.

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 makes the intended usage clear: search the database by free text and filter by category, price, and proof. It does not explicitly name alternatives or when not to use this tool, but the search context is unambiguous enough for an agent to select it appropriately.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context about the fallback mechanism and that the method is labeled in the response, which goes beyond the annotations.

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 two sentences, front-loaded with the core purpose, and includes the fallback note efficiently. No wasted words.

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 read-only tool with one parameter and no output schema, the description is complete. It explains the data source, time window, fallback, and response labeling. The only minor gap is not describing the response format, but with no output schema and simple data, this is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'limit' parameter, which is well-documented with min/max and default. The description does not add parameter-specific details, but the schema already provides full semantics, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns trending bottles based on user cellar additions over the last 30 days, with a fallback to catalog popularity. This specific verb+resource combination distinguishes it from siblings like get_recommendations or search_bottles.

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 implies when to use it (for trending/activity-based picks) and mentions the fallback behavior, but does not explicitly state when not to use it or name alternative tools. The context is clear enough for an agent to select it appropriately.

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