Server Quality Checklist

Tool Scores

• get_bottleA
  3.6/5.0
  Behavior3/5

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

  The annotations already establish this is read-only, idempotent, and non-destructive, so the description does not need to restate that. It adds useful context about the returned record, but it does not cover not-found behavior or exact matching semantics, which would make the behavior fully transparent.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise and well-structured: it opens with the core purpose, lists the key output content, then states the two accepted input forms. There is no filler, and every sentence contributes useful information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  With no output schema available, the description compensates by enumerating what the detailed record contains. For a single-parameter lookup tool, this is nearly complete; only the missing-record behavior is not addressed, which is a minor gap.

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

  Parameters3/5

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

  Schema description coverage is 100% — the parameter already documents that it accepts a UUID or a name like 'Eagle Rare 10'. The description mostly restates this, adding no meaningful new semantics beyond what the schema provides.

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

  Purpose4/5

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

  The description clearly identifies this as retrieving a single bottle's detailed record, naming the resource and its key content: tasting profile, flavor notes, pairings, price, and community ratings. The 'one bottle' wording distinguishes it from search-style siblings, though it does not explicitly name an alternative.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool: when the agent already has a Pour Picks bottle ID or name and needs full details for one bottle. However, it does not explicitly contrast with siblings like search_bottles for broad lookup or find_similar for recommendations.

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

• pour_tonight_suggestionA
  3.7/5.0
  Behavior3/5

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

  Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the suggestion dimensions (mood, occasion, season) but doesn't describe the exact return behavior, randomness, or personalization.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single streamlined sentence that leads with the core proposition and then lists the relevant factors. There is no filler or repetition.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple system with three optional parameters and no nested schemas, the description is adequate and complete enough for a basic agent. The main gap is not mentioning what the suggestion looks like or how it differs from the sibling suggestion tool.

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

  Parameters4/5

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

  The description enriches the schema by providing concrete examples for mood ('unwinding', 'celebratory') and occasion ('nightcap', 'with friends'), which helps specify valid literal values beyond the generic parameter descriptions.

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

  Purpose4/5

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

  The description clearly states the tool's function: a pour suggestion for right now based on mood, occasion, and season. It is purposeful but does not distinguish itself from siblings like get_recommendations or trending_bottles.

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

  Usage Guidelines3/5

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

  The description implies when to use this tool via 'for right now' and gives reasons like mood, occasion, and season, but it does not mention alternatives or explicitly state when not to use it.

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

• get_recommendationsA
  3.8/5.0
  Behavior3/5

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

  The annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds context about inputs but not much about behavior beyond that: no mention of what the tool returns, how recommendations are ranked, or any limits or caveats. It does not contradict annotations, but it also doesn't add significant behavioral precision beyond the obvious read-only nature.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, front-loaded sentence that effectively communicates the tools purpose and key inputs without redundant words. Each example is purposeful and helps clarify intents, making it an efficient, well-structured definition.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the moderate parameter count, rich schema, and annotations, the description is largely sufficient for an agent to call it correctly. It captures the input types and purpose in one sentence. However, it misses minor behavioral details like the default limit (5) or that results are returned as a list of bottles—though these are implied by the schema and the phrase 'bottle picks'. It is still fairly complete for what it is.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents each parameter. The description adds little beyond the schema—it restates taste_preferences with examples and occasion with examples, and repeats that budget is in USD (already in schema's description). While the examples are helpful, they don't substantially move beyond what the schema already says, so a baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb ('personalized bottle picks') and the resource (bottles selected from taste preferences, budget, occasion). This is clearly distinct from sibling tools like search_bottles (which implies searching) or trending_bottles (which implies popularity), and the inputs are provided upfront. It adds specificity beyond the title by naming exactly what kind of recommendations.

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

  Usage Guidelines3/5

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

  The description strongly implies usage: when the agent needs personalized suggestions based on taste, budget, and occasion, this is the tool to call. But it does not explicitly mention when not to use it or recommend alternatives like search_bottles or pour_tonight_suggestion. The use cases are implied through the parameter examples, but there is no explicit 'use when...' or 'if you need... instead'. This is adequate but lacks strong discrimination.

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

• trending_bottlesA
  3.8/5.0
  Behavior4/5

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

  Annotations already mark this as read-only, idempotent, and non-destructive. The description adds useful behavior beyond those annotations: the fallback to catalog popularity when live data is unavailable and the promise that the method used is labeled in the response.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two short sentences carry the full meaning, with the core data source and timeframe stated first. Every sentence contributes: the second sentence is not waste because it discloses important fallback and response-labeling behavior.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple, one-parameter, read-only list tool, the description provides enough to understand what is being returned and what the data represents. It is not a 5 because there is no output schema and the description could have more explicitly described the response as a list of bottles, though that is strongly implied.

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

  Parameters3/5

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

  The only parameter, limit, is already fully described in the schema with min, max, and default behavior, and schema coverage is 100%. The description adds no extra parameter-level guidance, so the baseline 3 applies.

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

  Purpose4/5

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

  The description states the resource (bottles Pour Picks users add to their cellars) and the time window (last 30 days), making the trending purpose clear. It has a slightly awkward phrasing, but it is still distinguishable from siblings like search_bottles and compare_bottles.

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

  Usage Guidelines3/5

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

  The description explains the 30-day live-data window and the fallback to catalog popularity, which gives useful context. However, it does not explicitly say when to prefer this over alternatives such as get_recommendations, find_similar, or pour_tonight_suggestion.

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

• search_bottlesA
  4/5.0
  Behavior4/5

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

  Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: full-text search over a large catalog, filterable results, and a structured tasting-profile return format with source attribution. It does not detail response shape or ordering, but it is a solid addition.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two focused sentences pack the key facts: the target resource, the catalog scope, available filters, and return type. No redundant phrasing or filler; the most distinctive detail (full-text search scope) is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  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 no required parameters and rich schema coverage, the description is mostly complete. It explains what results look like ('structured tasting profiles with source attribution'), which matters because there is no output schema. It could mention ordering or pagination, but the limit parameter in the schema covers the main invocation concern.

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

  Parameters3/5

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

  The schema already documents all 7 parameters with 100% description coverage, so the baseline is 3. The description only mentions the general filter categories—category, price, and proof—without adding new detail beyond what the schema already provides. This is adequate but not compensatory.

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

  Purpose5/5

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

  The description states a specific action ('Full-text search') with a clear resource ('4,700+ ... spirits in the Pour Picks database') and lists the major filters. This clearly distinguishes it from sibling tools like get_bottle or find_similar, which are narrower lookups or recommendations.

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

  Usage Guidelines3/5

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

  The description implies this is the tool for broad catalog searching and filtering, but it never explicitly says when an agent should prefer it over get_bottle, find_similar, or get_recommendations. There are clear search semantics, but no exclusions or alternative tool routing.

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

• compare_bottlesA
  4.2/5.0
  Behavior4/5

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

  Annotations already establish read-only and idempotent behavior. The description adds a concrete behavioral profile by specifying that it produces shared and distinct tasting notes and community ratings, which signals a synthesized comparison rather than a raw record lookup.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  One dense, front-loaded sentence lists all the comparison dimensions without extraneous prose. Every fragment adds useful information for selecting and understanding the tool.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a two-parameter read-only comparison tool with fully documented inputs and clear output dimensions, the description is nearly complete. It lacks explicit details about error handling or exact return shape, but that is not essential given the simple scope and annotations.

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

  Parameters3/5

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

  Schema description coverage is 100%, and both parameters are documented as 'First bottle'/'Second bottle' with UUID or name. The description does not add additional parameter-level detail, so the schema already carries the semantic load.

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

  Purpose5/5

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

  The description states a specific action—'side-by-side comparison of two bottles'—with a clear resource and enumerates the comparison dimensions (proof, age, price, flavor profile, ratings). This directly distinguishes it from sibling tools like get_bottle (single bottle) and find_similar (one-to-many alternatives).

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

  Usage Guidelines4/5

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

  The description makes the intended use clear: comparing exactly two specific bottles. It does not explicitly name alternatives or state when not to use it, but the comparison scope and sibling names provide implied context.

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

• find_cheaper_alternativeA
  4.3/5.0
  Behavior4/5

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

  Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the real behavioral substance: results are constrained to same style, similar flavor profile, and lower price, so an agent knows what it is selecting before calling.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two tightly constructed sentences: first states the functional contract, second gives a relatable use case. There is no filler or repetition of schema metadata.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple, read-only, two-parameter list tool with a 100%-covered schema and safe annotations, this description is sufficient. It tells the agent what is returned conceptually and why the tool exists, without needing to describe return fields.

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

  Parameters3/5

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

  Schema coverage is 100%, so bottle_id (UUID or name) and limit (default 5, max 10) are fully documented there. The description adds no parameter-specific nuance beyond 'the given bottle,' so the baseline 3 is appropriate.

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

  Purpose5/5

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

  States a specific action: identifying bottles in the same style and similar flavor at a lower price than a given bottle. This clearly separates it from siblings like find_similar (no price constraint) and compare_bottles (comparison, not recommendation).

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

  Usage Guidelines4/5

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

  The description gives a concrete use case ('what tastes like X without the price tag'), which is clear guidance for when to call it. It does not explicitly name alternatives or state exclusions, 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.

• find_similarA
  4.3/5.0
  Behavior4/5

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

  Annotations already convey that this is read-only, idempotent, and non-destructive, so the description is not responsible for safety disclosure. It adds valuable behavioral context beyond annotations by stating that scoring is deterministic and explaining exactly which tasting dimensions drive the ranking.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences with zero redundancy. It defines purpose, ranking criteria, scoring type, and data source in a compact, front-loaded structure that an agent can process quickly.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a low-complexity tool with two simple parameters, read-only annotations, and no output schema, the description is sufficiently complete. It tells the agent what input is expected, how results are sorted and ranked, and what data source is involved, leaving little ambiguity for correct selection and invocation.

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

  Parameters3/5

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

  Schema coverage is 100%, and the schema already fully documents bottle_id (UUID or name) and limit (max 15, default 5). The description adds contextual meaning around flavor profile and ranking, but it does not describe parameter-specific behavior beyond what the schema provides, so a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The tool's purpose is immediately clear: it returns bottles similar in flavor to a given bottle, ranked by shared notes and body/sweetness/char proximity. The title 'Find similar bottles' supplies the explicit verb, and the description's criteria distinguish it from siblings like find_cheaper_alternative or compare_bottles.

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

  Usage Guidelines4/5

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

  The description makes the usage condition clear: you need one bottle_id and want a flavor-similar ranked list. It does not explicitly name alternatives or say when not to use it, but the concrete scoring criteria ('shared flavor notes', 'proximity') provide enough context for an agent to select it over generic or price-based sibling tools.

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