Public wine registry and guides: search wines, grapes, regions, appellations. No account.
Scored across 7 tools
Each tool targets a distinct resource or action: registry search vs. single-wine detail, guide listing vs. guide reading, similarity, drink windows, and server metadata. The search-then-get and list-then-read pairings are explicitly cross-referenced, so boundaries are unambiguous.
All tools use snake_case with a verb_noun structure (get_wine, list_guides, read_guide, search_registry, find_similar_wines, get_source_info). The only deviation is drink_window_for, which reads more like a parameterized getter than a clean verb_noun phrase, but it remains readable.
Seven tools is well-scoped for a public wine registry/content server, with each tool covering a distinct facet (search, detail, similarity, drink windows, guides, metadata). No obvious filler or redundancy.
Core registry browsing is covered, but several descriptions point to tools that do not exist in this set (search_bottles, get_photo, suggest_wine_correction), creating dead ends for agents. The user's bottle-collection domain is referenced repeatedly yet has no coverage here.
Sommelier-curated drink windows for a registry wine: per vintage, when it is young, at peak, and in late maturity, with where the vintage stands right now. Call for "when should I drink ", aging questions, or buy-now-drink-later advice. Only sommelier-REVIEWED vintages are returned — an empty result means no curated window exists yet (reason from grape/region/structure yourself, and say it is an estimate).
| Name | Required | Description | Default |
|---|---|---|---|
| vintage | No | One vintage year; omit for all curated vintages of the wine | |
| wine_id | Yes | Registry wine id (from search_registry) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations (readOnlyHint, openWorldHint) by explaining the drink window stages and the meaning of empty results (no curated window exists yet). It provides guidance to reason from grape/region/structure, which is helpful for agent decision-making. No contradictions 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?
The description is a single, well-organized paragraph that front-loads the main purpose, immediately followed by usage scenarios and edge-case behavior. Every sentence is informative and necessary, 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?
Despite the absence of an output schema, the description adequately describes the output format (young, peak, late maturity, current status) and handles the empty-result case. Given the low complexity and strong annotations, the description is complete and leaves no critical 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?
The input schema already has 100% description coverage, with clear explanations for both wine_id and vintage (including that omitting vintage returns all curated vintages). The description reinforces this but does not add new semantic meaning beyond the schema, so baseline score of 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 provides sommelier-curated drink windows for registry wines, detailing per vintage stages (young, peak, late maturity) and current status. It includes example queries like 'when should I drink <wine> <vintage>', making the purpose specific and distinguishable from sibling tools such as find_similar_wines or get_wine.
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 explicitly states when to use the tool: for 'when should I drink' questions, aging queries, or buy-now-drink-later advice. It also clarifies that only sommelier-reviewed vintages are returned and advises how to handle empty results. While it doesn't explicitly say when not to use it, the context and sibling tool list provide sufficient differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Given a registry wine_id (or, on an authenticated connection, one of the user's bottle_ids), returns wines with the closest taste/style profile from the shared registry, using vector similarity over wine embeddings. Call for "more like this", "what else is like my favourite Barolo", or to seed purchase ideas from a wine the user loves. Only wines that have been embedded are searchable — an empty result does not mean nothing similar exists. Ids must be 24-hex Mongo ids from search_registry or search_bottles — a name or slug is not an id. Returns at most 10.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many to return (1-10, default 8; larger values are capped, not rejected) | |
| wine_id | No | Registry wine id (24-hex) from search_registry or a bottle's wine | |
| bottle_id | No | Alternatively: one of the user's bottle ids (24-hex). Needs an authenticated connection — not available on the public endpoint. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the readOnlyHint annotation, such as the vector-similarity mechanism, authentication requirement for bottle_id, the caveat that an empty result does not prove absence of similar wines, and the id format restriction. This gives the agent a clear behavioral model without any contradiction with 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 three sentences that pack essential details: function and inputs, use cases, and critical caveats. It is front-loaded with the primary purpose and avoids repetition or filler, making it efficient for an agent to parse.
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 the tool's modest complexity (3 optional params, read-only, no output schema), the description covers all necessary operational aspects: input origins, authentication, result count cap, and interpretation of empty results. It is sufficiently complete for an agent to invoke the tool correctly without 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?
While the schema already covers all parameters (100% coverage), the description adds important semantics: wine_id vs. bottle_id roles, the need for an authenticated connection for bottle_id, and that ids must be Mongo hex ids from specific sources. This goes beyond the schema's basic descriptions, though limit is only lightly touched ('at most 10').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'returns wines with the closest taste/style profile from the shared registry, using vector similarity over wine embeddings'. It specifies the input types (wine_id or bottle_id) and output (up to 10 similar wines), distinguishing it from sibling tools by focusing on similarity search rather than generic registry lookup.
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 explicitly says when to use the tool: 'Call for "more like this", "what else is like my favourite Barolo", or to seed purchase ideas'. It also provides a clear exclusion: ids must be 24-hex Mongo ids from search_registry/search_bottles, not names/slugs, and notes the limitation about embedded wines, giving practical guidance on interpreting empty results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns what Cellarion is, the version this instance is running, the open-source repository, and the license. Call this when the user asks what Cellarion is, which version they are on, whether it is open source, where to find / contribute to the code — or how to support the project.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations: it specifies the exact returned information (Cellarion, version, repository, license). Annotations already indicate read-only and non-destructive behavior, so the description complements them without contradiction.
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 that front-load the purpose and usage. Every sentence earns its place; no fluff 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?
Given no output schema, description fully covers what the tool returns. Includes common user queries (open source, support). Context of sibling tools (wine-related) makes this independent tool complete.
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?
No parameters exist, so schema description coverage is 100%. The description adds no param info, which is appropriate. Baseline for zero parameters is 4.
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 specific information: what Cellarion is, version, repository, and license. It uses specific verbs and resources, distinguishing it from sibling tools like get_wine or find_similar_wines.
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 explicitly lists when to call the tool (user asks about Cellarion, version, open source, etc.). It lacks explicit when-not-to-use or alternatives, but given the sibling context, the usage is clear and well-guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full registry record for one wine: producer, region, appellation, classification, grapes, community rating, the AI tasting profile when the wine has been enriched, and the registry image (url + credit) when one is published — null means the wine has no public picture yet; to see the picture yourself, call get_photo with the wine_id. Vintage-neutral (bottles carry the vintage). For signed-in callers, pending_correction says whether a correction suggestion is awaiting review on this wine (one is allowed per wine, across all users), which fields it covers and whether it is the caller's own — check it before composing suggest_wine_correction. Call after search_registry when the user wants depth on a specific wine.
| Name | Required | Description | Default |
|---|---|---|---|
| wine_id | Yes | Registry wine id from search_registry or a bottle's wine |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint annotations, the description discloses nullable semantics (image null means no public picture yet), vintage-neutral scoping (bottles carry the vintage), and a subtle constraint that only one correction may be pending per wine across all users plus whether it is the caller's own. That is meaningful behavioral context an agent could not infer from structured fields.
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 content is front-loaded, beginning with what the tool returns and ending with the trigger condition. It is dense and slightly over-packed into long compound clauses, but nearly every clause carries distinct, necessary 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?
There is no output schema, so the description carries the return-shape burden and does so by enumerating the record's fields and their null/absence behavior. Combined with the pending_correction and photo cross-references, an agent has everything needed to call and interpret this tool 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 coverage is 100% and the single parameter is documented as 'Registry wine id from search_registry or a bottle's wine.' The description adds value by establishing that the id is vintage-neutral, clarifying that the same wine_id spans all vintages, which is not derivable from 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 opens with a specific verb+resource ('Full registry record for one wine') and enumerates exactly what the record contains, including the AI tasting profile and registry image. It is immediately distinguishable from siblings like search_registry, which it names as the predecessor step.
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 explicitly states when to call it ('after search_registry when the user wants depth on a specific wine'), routes to get_photo when the caller needs the actual picture, and instructs checking pending_correction before composing suggest_wine_correction. Both the trigger condition and adjacent alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cellarion's published guides and blog articles (cellar management, drink windows, storage, buying) — title, slug, excerpt and tags. Call when the user wants a how-to or background reading; follow with read_guide for the full text.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Filter by tag | |
| limit | No | How many to return (1-20, default 10; larger values are capped, not rejected) | |
| offset | No | Skip this many (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, and the description adds context about the returned fields (title, slug, excerpt, tags) and the relationship to read_guide. This is useful beyond the annotations, though it omits any ordering or pagination behavior (which is partially covered by schema params).
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, front-loaded with the core purpose and followed by usage guidance. No wasted words; every sentence 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?
Despite lacking an output schema, the description enumerates the returned fields, which addresses the main unknown. It also provides follow-up context (read_guide) and the tool is simple enough that no further detail is required.
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 the baseline is 3. The description does not add parameter-specific meaning, but the schema already documents tag, limit, and offset well.
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: lists Cellarion's published guides and articles with metadata fields. It distinguishes itself from sibling read_guide by noting it returns excerpts and pointing to read_guide for full text.
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 use ('when the user wants a how-to or background reading') and names the alternative (read_guide) for full text. This is clear, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full text of one published Cellarion guide or blog article, by slug (from list_guides). Public website content — quote or summarise freely, and link the public_url when pointing the user to it.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Article slug from list_guides |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true; description adds that it is public website content, which reinforces safety and clarifies the nature of the output without contradicting 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 wasted words, front-loaded with the core action, and includes essential tips on usage.
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 tool with one parameter and no output schema, the description fully covers what the tool returns, how to use it, and the expected 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 coverage is 100% for the single parameter 'slug'; the description restates the schema description, adding no new meaning beyond what the schema provides.
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 it reads the full text of a guide/article by slug from list_guides, which is a specific verb+resource and distinguishes it from sibling tools like list_guides.
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 advises to quote or summarise freely and link the public_url, providing clear usage context and telling the agent how to reference the content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches Cellarion's shared wine database (vintage-neutral wines, community data) by name, producer, region or grape. Returns up to 10 matches. Call to identify a wine the user mentions, before recommending, or to check whether a wine exists in the registry. This searches ALL known wines — use search_bottles for what the user owns.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Wine name, producer, appellation or grape |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds that it returns up to 10 matches and searches by specified fields. No contradictions, but some behavioral details like pagination or ordering 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?
The description is four sentences, front-loading the main purpose and then adding usage context. It is relatively concise but could be tightened by merging sentences without losing clarity.
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 search tool with no output schema, the description covers purpose, input semantics, result limit, usage scenarios, and an alternative tool, making it fully informative.
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 a clear parameter name 'query' and description. The tool description restates valid search fields but does not add new semantics beyond the schema, so baseline score of 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 searches the shared wine registry by name, producer, region, or grape, and distinguishes from the sibling tool 'search_bottles' by noting this searches all wines versus user-owned 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 explicitly tells when to use: to identify a wine mentioned, before recommending, or to check existence. It also advises when not to use it (use search_bottles for user-owned wines), providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search 20,000+ wineries worldwide by region, amenities, hours, tasting fees and bookings.
Wine matching, pricing, auctions, exchange, merchant, critic, portfolio, and cellar intelligence.
Wine cellar manager: bottles, racks, drink windows, pairings and a shared wine registry.
Find wines and compare live merchant prices in your region. Fair-deal search, My wine OAuth login.
Add one secure layer between your agents and this server.
