My Wine

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

With no annotations, the description carries the behavioral burden. It discloses that the region is server-provided and NOT user-controllable, which is a meaningful trust/scoping constraint, and implies a read-only fetch. It does not cover error or authentication behavior, but for a zero-parameter read call that is a minor gap.

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 five short sentences, each earning its place: the fetch action, the when-to-call directive, the source/control constraint, the downstream effect, and the return value semantics. It is front-loaded with the essential directive and contains 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?

For a parameterless tool with an output schema, the description is complete. It explains what is returned (region name, currency, price-tier thresholds), why it matters, and how the output should be used with search_offers. Nothing needed to invoke or apply this tool 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 tool has no parameters, so there is no schema detail to compensate for. The description adds context by explaining the data source ('from their profile', 'taken from the server'), which reinforces why no user input is needed and clarifies the source of truth.

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 and resource ('Fetch the user's marketplace region from their profile') and clearly states the tool's role in the workflow. It differentiates itself from the sibling search tools by establishing itself as a prerequisite that scopes offer searches.

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

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

It gives explicit sequencing guidance: 'Call this before questioning' and explains that the result 'determines the currency and scopes every offer search.' This tells the agent exactly when to invoke it relative to search_offers, and no competing sibling serves this purpose.

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

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

With no annotations, the description carries full behavioral burden and does so thoroughly: it discloses that results are real retail listings with price and purchase link, that they must be shown exactly as returned, and it imposes query-construction rules (English keywords, no forbidden tokens, price ranges must keep both bounds). No behavioral surprises are left unstated.

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 long but every sentence is actionable, and it is well-structured: a one-line purpose, a short context paragraph, a bulleted IMPORTANT block, then an Args list. Front-loading the scope and flow makes it 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?

Given a tool with six parameters, zero input-schema descriptions, no annotations, and an output schema that can define return shape, this description is complete: it covers when to call, parameter semantics, sibling dependencies, and exact output-touching behavior. Nothing needed for correct invocation appears to be missing.

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

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

Schema description coverage is 0%, but the Args section fully compensates by explaining every parameter: query must be English keywords, price_min defaults to 0.01, price_currency takes ISO codes, shop_names are exact 'Name (ID)' strings capped at 5, and vintage is an exact year. The description also clarifies required-versus-omitted behavior 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?

Opens with a specific verb+resource statement: 'Search live purchase offers for wine, scoped to the user's marketplace region.' It further differentiates from siblings by stating it is the end of the sommelier flow and always returns retail OFFERS, never abstract products, which distinguishes it from get_user_region and search_shops.

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

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

Explicitly says to call it once preferences are collected, names the sibling flow, and gives sequencing: 'call search_shops FIRST' when shop_names are needed, and maps price tiers to 'thresholds from get_user_region.' This tells an agent when to use the tool and how it relates to the 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 are absent, so the description carries the full behavioral burden. It discloses scoping to the user's marketplace region, a limit of up to 20 results, the output format ('Name (ID)'), and the instruction to pass exact strings into search_offers. This exceeds what most descriptions provide and leaves no ambiguity about behavior.

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

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

The description is efficient and front-loaded. It opens with the purpose, immediately gives usage constraints, then explains the output and how to consume it. Every sentence serves a distinct informational need; no filler or repetition.

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

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

For a single-parameter search tool with an output schema, the description covers everything needed: correct call conditions, the parameter meaning, result count and format, and downstream usage in search_offers. The presence of an output schema handles return structure, so the description's additional context completes the picture.

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

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

Schema coverage is 0%, so the description must document the parameter. It explains 'query' as 'Shop name or partial name the user mentioned,' which adds semantic meaning beyond the schema's type/title. It could be slightly richer (e.g., note case sensitivity or fuzzy matching), but the explanation is sufficient for correct invocation.

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 ('Search') and resource ('wine RETAILERS / STORES by name'), with concrete examples. It explicitly differentiates from siblings by saying producers/châteaux/domaines/wineries/brands go to search_offers, so an agent cannot confuse which tool handles store names.

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?

Provides explicit call conditions: 'Call this ONLY when the user explicitly names a retail store.' It also states when NOT to call it and routes the alternative case to search_offers. This is a model of clear when/when-not guidance with a named alternative.

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