NEVINI Wines

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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), the description discloses that quantities accumulate with existing lines — a key non-idempotency implication — that no order or payment occurs, what is returned (updated cart and checkout_url), and the legal age constraints. This is substantial behavioral context not present in 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 first sentence is front-loaded with the core action and the accumulation rule. The legal/age block is long, and 'The order is only placed once the customer opens the checkout and completes the order' partly restates the earlier 'No order is placed and no payment is taken here', costing some tightness.

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 elaboration, and the description still names them briefly. Combined with the warnings about age restrictions and the checkout handoff, an agent has everything needed to call this 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 cart_id, items, variant_id, quantity bounds and the language enum are already fully documented in the schema. The description's quantity-accumulation note is behavioral rather than parameter-level, so 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?

States a specific verb and resource ('Adds wine variants to an existing cart') and adds the accumulation rule, which clarifies behavior beyond the name. It implicitly distinguishes itself from create_cart by requiring an existing cart, but never names the 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 'an existing cart' implies a prerequisite and routes away from create_cart, and the checkout_url explanation gives downstream context. However, it never explicitly says when to use this versus update_cart (e.g., for changing quantities of existing lines) or create_cart, leaving the agent to infer routing.

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 only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds substantive behavior the schema cannot express — no payment or order is committed, checkout happens on shop.nevini.wine after the customer opens checkout_url, and a legal age gate applies with possible ID check on delivery. This is exactly the kind of consequence-of-calling context the score rewards.

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 operational facts are front-loaded, but the legal block is repetitive: 'No order is placed' is restated as 'The order is only placed once the customer opens the checkout,' and the buyer_is_18_or_older instruction duplicates the schema's own description verbatim in intent. Roughly a third of the text could be compressed 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?

Given an output schema exists, the description need not explain return values, yet it still names the key ones. It covers prerequisites (age confirmation), variant_id sourcing, language default, and the fact that no payment occurs — everything an agent needs to decide to call it and to set preconditions 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 the schema already documents items, quantity range, variant_id source, language default, and the buyer_is_18_or_older confirmation rule. The description reinforces the variant_id provenance and the age-confirmation precondition but adds no syntax or format detail beyond what the schema states.

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 ('Creates a new Shopify cart') and immediately names the return payload (cart_id, items with live prices, subtotal, checkout_url). The word 'new' plus the variant-sourcing hint distinguishes it from the sibling add_to_cart, which operates on an existing cart.

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 the agent to search_wines or get_wine to obtain a variant_id, and clarifies the boundary of the operation: 'No order is placed and no payment is taken here; checkout_url opens the checkout.' It stops short of saying what to do if a cart already exists (use add_to_cart instead), which is the one contextual routing gap.

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=false, and the description adds substantial behavioral context beyond them: no order is placed, no payment is taken, checkout_url opens an external checkout on shop.nevini.wine, and the order is only placed when the customer completes checkout. It also discloses the legal constraint (Dutch Alcohol Act, 18+, ID may be checked on delivery), which no structured field carries.

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 return values are correctly front-loaded, with behavioral and legal context following. There is some redundancy: 'No order is placed and no payment is taken here' is restated later as 'The order is only placed once the customer opens the checkout and completes the order', costing one sentence of economy.

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 already documenting the returned fields, the description covers everything else an agent needs: that this is a non-mutating read, where checkout_url leads, and the age/ID constraints that gate the purchase. Nothing material 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 100%, and the schema itself explains that cart_id must include the '?key=' part and that language controls item names and the checkout. The description adds no parameter-level meaning beyond that, so the baseline of 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?

Opens with a specific verb and resource plus the exact payload: 'Returns the current lines, live prices, subtotal and checkout_url of a cart.' This clearly separates it from the mutating siblings (create_cart, add_to_cart, update_cart), which an agent can distinguish without opening any 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 makes the intent of the tool unambiguous ('No order is placed and no payment is taken here') and explains the role of checkout_url as the hand-off point to the actual checkout. It gives strong context for the inspect-then-checkout flow, but never explicitly says when to prefer this over siblings such as update_cart or add_to_cart, leaving that routing 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds that the result is a pre-aggregated catalog summary (counts, top grapes, selection, price range), but it gives no notes on result size, caching, or freshness.

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 front-loaded sentence that puts the key fact, a catalog overview, first. The enumeration of fields is somewhat long and partly redundant with the output schema, but every clause is still 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?

It is a zero-required-parameter, read-only aggregate tool with full annotations and an output schema, so the description need not explain return values. It is sufficient for correct invocation, with only the 'what this overview contains' clause doing real work.

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 (language) has 100% schema coverage, including the enum values and the Dutch default, so the schema already does the work. The description never mentions language, so it adds nothing beyond the schema; the baseline of 3 fits.

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 uses a specific verb (returns) and resource (an overview of the NEVINI wine catalog), and it enumerates the aggregates it includes. It is clearly distinct from get_wine and search_wines in intent, but it never explicitly names or contrasts 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 usage context is implied: the tool is for getting a high-level summary of the whole catalog rather than a single wine. The description gives no explicit when-to-use guidance, no when-not-to-use guidance, and no pointer to search_wines or get_wine for detail lookups.

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, destructiveHint=false, and openWorldHint=false, so safety behavior is covered structurally. The description adds useful content-scope context but no additional behavioral detail such as caching, freshness, or authorization requirements.

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 definition is a single front-loaded sentence that states purpose first and then enumerates scope. The list is long but each item clarifies what 'store facts' includes, though it could be slightly tighter.

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, rich annotations, and a fully documented single optional parameter, the description provides enough scope to call the tool correctly. The remaining gap is that it does not explicitly state when to prefer it over sibling 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?

Schema description coverage is 100%, and the only parameter (language) is fully documented in the schema with an enum. The description does not mention the language option, so it adds no semantic value beyond the schema, but the baseline is 3 when schema coverage is high.

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 uses a specific verb (returns) and resource (NEVINI store facts) and enumerates the content domains covered. It is clearly distinguishable from cart/catalog/wine siblings, which handle ordering and product data rather than store 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?

The scope implies when the tool is useful (store policies, contact details, shipping, returns, payment), but there is no explicit when-to-use guidance or exclusion. An agent can infer the context, but must do some work to route between this and sibling tools.

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 cover safety (readOnly, idempotent, closed-world), so the bar is lower, and the description nonetheless adds real semantics: food_pairing is null when the text names no dish, default_variant_id is null unless that bottle is purchasable, and on_request sizes cannot be ordered online. These null/edge-case semantics are the kind of detail that prevents misreading results; it stops short of describing price/availability freshness or caching 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?

Front-loaded with the operation and payload, then field-level clarifications. Dense but every clause carries information; the return-field enumeration is somewhat lengthy relative to an existing output schema, but nothing is 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 a two-parameter read tool with a full output schema and rich annotations, the description is sufficient: it explains identifier forms, response language default, and the meaning of the ambiguous variant/availability fields. Only the discovery workflow (how to obtain a slug) is 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 coverage is 100%, so both the 'wine' identifier formats and the 'language' enum are already fully documented in the schema. The description repeats the identifier forms but adds no new meaning about them, so 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?

States a specific verb ('Returns') and resource ('one wine') plus the accepted identifiers, and enumerates the payload (description, grapes, taste notes, bottle variants, related wines). An agent can tell it apart from search_wines (list/query) 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?

The 'returns one wine' framing implies lookup-by-identity usage, but there is no explicit when-to-use guidance, no statement that search_wines should be used first to discover a slug/id, and no mention of alternatives. Usage is inferable 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 readOnly/openWorld=false/idempotent, so the safety profile is covered. The description goes further usefully: results carry live Shopify price and availability, price filters silently exclude wines with no verified price, and the food filter drops wines whose description names no dish — those exclusion behaviors are genuinely valuable. However, return-shape detail largely duplicates the output schema, and pagination/result-count behavior beyond the limit cap is not discussed.

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 matching scope are front-loaded in the first two sentences, and the trailing sentences carry real semantics about nullable/conditional return fields. It is dense but slightly over-long for a search tool, with some repetition of schema content (e.g. 'sparkling' includes Champagne appears in both description and schema).

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 12 optional parameters, no required fields and an available output schema, the description covers everything needed to call it correctly: query scope, filter roles, exclusion side effects of price and food filters, and null semantics for default_variant_id. Nothing an agent needs before invoking it 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 coverage is 100%, so baseline is 3, but the description adds cross-parameter guidance the schema does not spell out — which terms query does and does not match, and which filters to use instead (food, type, price, sort). It also clarifies that type 'sparkling' includes Champagne and explains the meaning of output fields default_variant_id/default_size, though much of the per-parameter detail is echoed 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?

States a specific verb and resource ('Searches the NEVINI wine catalog') plus the full filter scope, and explicitly demarcates it from get_wine for bottle sizes and full descriptions. An agent can distinguish it from get_wine and the cart tools without opening any 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 splits usage: free-text query covers name/winery/grape/region/country/type/vintage while style, budget and dish matching must go through type, country, region, grape, price, sort and food. It also names the alternative (get_wine) for other bottle sizes, all taste notes and the full description, so the routing decision 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 flag the operation as destructive and idempotent, but the description adds real behavioral context: it returns the updated cart and checkout_url, no payment or order is placed, checkout happens on shop.nevini.wine, and age verification may occur on delivery. This goes well beyond what the annotations provide and is consistent with them.

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 key operational sentence is front-loaded and efficient, but the description then repeats the checkout-order idea across two separate sentences and includes multiple sentences of alcohol age policy. That policy is relevant for this store, but the repetition and length keep it from being tight.

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 and annotations covering safety/idempotency, the description supplies the remaining context an agent needs: what the tool returns, that checkout_url is where checkout happens, and the age restrictions for this alcohol seller. Nothing essential to calling it correctly 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?

The schema itself documents all three parameters, including quantity's 0-24 range and the cart_id key requirement, while the description only restates that quantity 0 removes a line. It adds little meaning beyond the schema and does not explain the language parameter or cart_id format, so baseline 3 is appropriate at 67% 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 first sentence names a specific verb and resource: sets quantities of existing cart lines by line_id, with quantity 0 removing a line. This clearly distinguishes it from add_to_cart and create_cart, which handle adding and creating rather than modifying existing lines.

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 'existing cart lines' and the removal behavior for quantity 0, and the description clarifies that no order is placed here. However, it never explicitly names alternatives such as add_to_cart for new lines or create_cart for a new cart, so the agent must infer when to choose this tool over its siblings.

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