beyond-wine

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

Annotations only cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint). The description adds substantial behavior beyond that: it cannot place orders or take payments, profile previews do not contain source lists, a null abv means unknown, and catalogue abv is a number without its source qualifier. These are exactly the operational caveats annotations cannot express.

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 text is a ~300-word block that front-loads scope and refusal boilerplate instead of the tool's function, and repeats itself: 'Do not infer alcohol content from ingredients, fermentation, taste...' is restated near the end as 'Do not infer that alcohol is absent from ingredients or production methods.' Substantial material could be compressed without losing guidance.

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 retrieval tool with no output schema, the description covers how to source the slug, what the previews do and do not contain, and how to attach citations — enough for correct invocation and downstream citation. The main gap is that 'condensed' is unexplained and the returned profile structure is only loosely sketched.

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%, so the description must carry parameter meaning. It handles 'slug' well ('find the exact slug with search_beverages; never invent it'), which is genuinely useful invocation guidance, but the 'condensed' parameter is never mentioned, leaving one of two parameters entirely undocumented.

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 does state a specific verb and resource: 'Retrieve a published beverage profile and claim previews.' It also differentiates from siblings by naming search_beverages (to find the slug) and get_claim/search_claims (to source facts). However, the actual purpose statement is buried mid-way through a long policy preamble rather than front-loaded, so an agent must read past scope and refusal rules before learning what the tool returns.

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 when-to-use (individual drink questions, recommendations where declared wording must be checked) and when-not-to-use (excluded categories, purchasing requests, catalogue-wide alcohol guarantees), and names the correct alternatives in each case: search_beverages for the slug, get_claim for source evidence, search_claims with entity_type=beverage. Nothing about routing is left 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?

Annotations already establish read-only, non-destructive, open-world behavior, and the description adds meaningful constraints beyond them: it cannot place orders or take payments, cannot guarantee zero alcohol, and one claim 'does not establish that no other records or sources exist'. It also flags that declarations like 'Below 0.5%' do not prove measurement or lab testing — useful epistemic limits on the returned data.

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 bloated with repeated refusal policy that largely duplicates the domain scope across sentences, and it is not front-loaded — the actual tool purpose appears about two-thirds of the way through. Several sentences ('Do not invent a product or producer') restate the same non-fabrication point.

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-uid read tool with no output schema and only annotations for safety, the description covers the return shape (provenance.sources, version history), the source-attribution requirement, and the limits of what one claim proves. The main gap is that the refusal policy crowds out any concrete detail on the single input parameter.

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?

With a single parameter and 0% schema description coverage, the schema supplies only a minLength on claim_uid. The description compensates partially by telling the agent where the value comes from ('Copy claim_uid from a profile or claim search'), implying it is an opaque identifier, but adds nothing about format, case, or failure behavior on a bad uid.

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 does contain a specific verb+resource — 'Retrieve a published claim with provenance.sources and version history' — but this arrives only after six sentences of domain-scope and refusal policy. Differentiation from siblings is only implicit, via 'Copy claim_uid from a profile or claim search' and 'Use this to check a source behind a profile claim preview', which gestures at search_claims but never names the routing rule.

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?

Offers concrete when-not-to-use guidance: decline excluded-category recommendations, purchasing requests, and catalogue-wide zero-alcohol guarantees 'without a lookup', and explicitly warns that 'an empty search is not how to establish this exclusion'. That is real invocation guidance, but it never directly contrasts get_claim with get_beverage, get_entity, or search_claims for the same lookup.

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/openWorldHint and destructiveHint=false, so the bar is lower. The description adds real behavioral context beyond them: results are token-bounded, the connection cannot place orders or take payments, it cannot guarantee the absence of alcohol, and its catalogue scope is enumerated with explicit exclusions.

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 text runs well over 300 words, and the sentence that says what the tool actually does sits after long stretches of scope and refusal policy that is largely server-wide context. It is badly front-loaded: a reader must wade through exclusions and prohibition language before learning this is a retrieval tool.

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 retrieval tool with no output schema, the description gives a rough shape of the return (entity summary plus optional claims/graph) and the token bound, which is enough to call it. But it never explains what a "topic" token looks like, how to pick include values, or how the bundle relates to the sibling get_* tools, leaving meaningful 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 0%, so the description must carry the parameter burden. It partially does: "token-bounded" maps to max_tokens and "including entity summary and optional claims or graph data" maps to the entity/claims/graph enum for include. The required `topic` parameter is never explained beyond "a Beyond Wine topic," and no defaults or token-limit behavior (100–8000) are mentioned.

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 actual purpose is stated, but it is buried roughly two-thirds of the way in: "Retrieve a token-bounded context bundle for a Beyond Wine topic, including entity summary and optional claims or graph data." The verb and resource are concrete, but the definition never distinguishes get_context from close siblings like get_entity, get_claim, or get_graph, so an agent has to guess which to pick.

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?

There is substantial when-not-to-use guidance (refusals for excluded categories, orders/payments, catalogue-wide 0% guarantees) and one direction to "retrieve its source evidence with get_claim." However, that routing is about domain policy rather than about when to choose this tool over get_entity/get_claim/get_graph, so tool-selection guidance is only implied.

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 a safe read (readOnlyHint, openWorldHint, destructiveHint=false). The description goes well beyond them by disclosing capability boundaries: it cannot place orders or take payments, cannot guarantee zero alcohol, returns structured data plus claim previews, and requires following claim_uid into get_claim for evidence. That is substantive behavioral context an annotation cannot convey.

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 passage is grossly oversized for a fetch tool and front-loads scope policy rather than the operation. It repeats itself ('Preserve declared wording' / 'exact alcohol wording', multiple 'do not infer' variants), so many sentences are duplicative rather than additive.

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 no output schema the description does describe the return shape (structured data and claim previews), but a 3-parameter tool at 0% schema coverage still needs slug format and condensed semantics, which are absent. The extensive guardrail content is useful for domain conduct yet leaves the mechanical calling details thin.

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% and there are three parameters. The description lists four entity kinds (producers, beverages, people, restaurants) that map to part of the entity_type enum but omits ingredient, technique and prepared_ingredient, and says nothing about the slug format or what condensed changes. The description only partially compensates for the total coverage gap.

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 contains a clear verb+resource statement: 'Retrieve a published entity profile with structured data and claim previews,' and identifies what an entity can be (producers, beverages, people, restaurants). However, this core purpose is buried under a long policy preamble, and it never distinguishes this generic fetch from siblings like get_beverage or get_producer, leaving the agent to infer routing.

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 unusually explicit when-to-use and when-not-to-use guidance: refuse excluded categories, purchasing, and catalogue-wide guarantees without a lookup, and use get_claim for provenance. What it lacks is sibling-relative guidance — it never explains why an agent should call get_entity instead of get_beverage/get_producer for the same target.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the connection cannot place orders or take payments, cannot certify zero-alcohol across the catalogue, and empty searches must not be used to establish an exclusion.

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 back-loaded: the one sentence that says what the tool does is last, preceded by several sentences of refusal policy. Much of the content is not about invoking this tool and would be better placed in a shared domain/policy prompt.

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 should explain what 'direct relationship neighbors' actually returns (neighbor entity types, relationship kinds, depth, volume). It never does, and with undocumented parameters on top, an agent cannot predict the response shape before calling.

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% for two required parameters, so the description must compensate and it does not. Neither 'slug' nor 'entity_type' is explained, and the five enum values (producer, beverage, person, restaurant, prepared_ingredient) are never mentioned, leaving the agent to infer the entity model from the schema alone.

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 final sentence states a specific verb and resource: 'Retrieve direct relationship neighbors for an entity profiled in the Beyond Wine knowledge base.' That is clear enough to separate it from pure entity/profile lookups, but it is buried under domain policy text and never explicitly contrasts itself with siblings like get_entity or get_beverage.

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?

There is abundant when-not guidance, but it concerns the domain (decline purchases, refuse scope-guarantee requests, avoid empty searches to prove exclusion) rather than when to call get_graph versus get_entity, get_beverage, or search_beverages. Tool-selection guidance is implied at best.

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 establish readOnlyHint, non-destructive and open-world, so the safety profile is covered. The description adds real boundary context (cannot order, cannot guarantee zero alcohol, don't use empty searches to prove exclusion), but none of it is specific to how get_ontology itself behaves or what it returns.

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 badly front-loaded: the actual purpose appears only in the last sentence, behind lengthy refusal instructions that are peripheral to this tool. Several sentences (purchasing, alcohol-free guarantee, inventing producers) do not earn their place in a get_ontology definition.

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 no output schema, the description does name the four things retrieved, which is adequate for a read-only metadata tool. However, it omits the format parameter's effect on the response and any notion of size/shape of the returned ontology.

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 'format' (enum json/json-schema, default json) has 0% schema description coverage, and the description never mentions it or explains the difference between the two formats. The enum values are fairly self-explanatory, but the description does nothing to compensate for the coverage gap.

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 final sentence gives a concrete verb+resource: retrieve the Beyond Wine ontology, entity types, relationship types, and semantic scales. That distinguishes it from siblings like get_entity, get_graph and get_context, though the actual purpose is buried after a long refusal-policy preamble and the description never says explicitly that this returns schema/model metadata rather than data.

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 bulk of the text is when-NOT-to-use guidance (excluded categories, no order placement, no alcohol-free guarantee), which is largely server-wide policy rather than guidance for when to invoke get_ontology. It never tells the agent when to prefer this over get_context, get_graph or list_entities, so tool-selection guidance is only implied by the last sentence.

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 the safety profile (readOnlyHint, openWorldHint, destructiveHint), and the description adds real behavioral context beyond them: it cannot place orders or take payments, cannot guarantee zero alcohol, and returns the producer's published lineup. It does not describe failure modes when a slug is not found, but its limitations are unusually well disclosed.

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 several hundred words and leads with scope exclusions rather than the tool's function; the actual purpose statement appears only mid-way. Multiple alcohol-wording rules are restated ('Preserve declared wording,' 'Preserve the source's exact alcohol wording'), and much of the policy reads like global system guidance rather than tool-specific instructions.

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 2-parameter read tool with no output schema, it thoroughly covers scope boundaries, refusal behavior, and alcohol-wording caveats, so the agent knows how to interpret results. But it never explains the 'condensed' parameter or slug format, leaving a genuine operational gap for 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 0%, so the description must compensate. It implies 'slug' is a producer identifier by directing the agent to search_producers when the slug is unknown, but 'condensed' is never mentioned and no format, case, or effect of condensed is given. Half the parameters remain semantically undefined.

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 eventually states a specific verb and resource: 'Retrieve a specific producer documented by Beyond Wine,' and adds that the lineup appears under data.beverages. However, this core statement is buried after paragraphs of scope-exclusion policy, so the purpose is clear but not front-loaded or sharply differentiated from get_beverage.

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 routes the agent elsewhere ('Use search_producers first when the producer slug is unknown') and gives strong when-not-to-call guidance for excluded categories, ordering/payment requests, and catalogue-wide guarantees. It lacks explicit guidance on when to prefer get_producer over, say, get_beverage or search_beverages for lineup questions.

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, destructiveHint=false and openWorldHint=true, so safety is covered; the description still adds real behavioral context, notably that a search or lineup abv is a catalogue number, that null means unknown, and that get_claim must be used to inspect source evidence before asserting an alcohol requirement is met. It also states what the connection cannot do (orders, payments, catalogue-wide guarantees). Slightly repetitive phrasing dilutes it.

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?

Not front-loaded: the tool's actual function is buried mid-paragraph behind policy prose, and key instructions are restated ('Preserve declared wording' vs 'Preserve the source's exact alcohol wording'). Large blocks of refusal semantics crowd out the operational information an invoker needs.

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?

Domain and refusal complexity are handled thoroughly, which matters given the open-world annotation and the absent output schema. But for a paginated list tool with 0% schema coverage, the description never explains pagination, defaults, or ordering, so an agent has no basis for advancing pages or bounding result sets.

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% across three parameters. The description only gestures at entity_type ('by type'), leaving the seven enum values and, more importantly, page and limit completely unexplained in prose and schema alike — no pagination or default behavior guidance despite this being a paginated list endpoint.

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 core purpose is stated precisely: 'List published entity profiles in the Beyond Wine knowledge base by type,' a clear verb+resource that reads differently from the get_entity/search_beverages siblings. The problem is placement — it sits after roughly five sentences of refusal policy, so an agent skimming the opening line sees catalogue scope, not a list tool. No explicit sibling contrast, but the list-vs-get-vs-search distinction is inferable.

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?

Unusually explicit about when-to-use and when-not: excluded categories (NA beer, NA spirits, mocktails, dealcoholized wine) should be declined without a lookup, purchasing requests declined without a lookup, and individual drink questions handled via claim wording and get_claim evidence. It names the alternative tool and the condition selecting it, which is exactly what this dimension asks for.

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/openWorldHint/destructiveHint=false, yet the description adds substantial non-obvious behavior: it cannot place orders or take payments, an empty result does not establish nonexistence, abv values are unqualified catalogue numbers and null means unknown, and declared alcohol wording must be preserved and verified via claim evidence. These are exactly the operational caveats an agent cannot get 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 valuable but poorly front-loaded: the actual action ('Find a beverage by name or alias') arrives after a long scope preamble, and the refusal rules are interleaved with search mechanics. There is clear redundancy, e.g. two separate sentences warning against inferring alcohol from ingredients/production methods, so not 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?

For a catalogue tool with no output schema and 0% parameter coverage, the description covers the critical domain semantics, the verification workflow (name/producer check, slug into get_beverage, then get_claim), and the refusals thoroughly. The remaining gap is pagination/limit/category behavior, which is minor relative to what is covered.

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%, so the description must carry the load. It meaningfully explains q (matches name, alias OR producer name; combined producer-plus-product phrases may fail; fallback to a distinctive word) and producer (exact slug to list a lineup), but says nothing about category, page, or limit, leaving three of five parameters undocumented.

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 ('Find a beverage by name or alias') and scopes it precisely to the Beyond Wine no/low-ABV catalogue, listing included and excluded categories. It explicitly differentiates itself from a sibling ('Start here for drink names, not search_producers'), so an agent can route correctly without opening schemas.

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?

Gives explicit when-to-use (drink names, producer slug lineups), when-not-to-use (excluded categories, purchasing requests, catalogue-wide zero-alcohol guarantees), and the correct alternative behaviors for each refusal. It also names the follow-on tools (get_beverage, get_claim) and the fallback path when a query returns empty.

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/non-destructive, and the description goes well beyond them: it discloses that the connection cannot place orders or take payments, cannot guarantee zero alcohol, and that pagination (meta.has_more) must be followed before making negative findings. It also warns against inferring absence from wording differences and against inventing products or producers.

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 valuable but sprawling and repetitive, reading more like a policy prompt than a tool definition. The central purpose sentence appears well after the exclusion catalogue, so the description is not front-loaded. Several refusal-related sentences could be condensed or moved to system-level guidance.

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 no output schema, the description correctly names the return structure pieces an agent needs (provenance.sources, meta.has_more) and explains how to interpret declared alcohol wording. It is fairly complete for a search tool, though page/limit behavior and the exact response shape remain 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 description coverage is 0%, so the description must compensate, and it largely does: it explains that claim_type is a record format (atomic_fact, structured_fact, editorial_claim) NOT a topic, that entity_type must be paired with an exact entity_slug, and that claim_type/reliability_class are optional refinements. It says nothing about page or limit, leaving two of six parameters unexplained.

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 core purpose is stated mid-description: 'Find published claims with their source provenance,' giving a clear verb and resource. However, the description opens with a lengthy domain-scope essay about what Beyond Wine excludes, so the actual function of the tool is buried rather than front-loaded. It differentiates itself from siblings by describing the claim-record domain and provenance focus, but does not explicitly name a sibling alternative.

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 states when to use it (individual drink/producer questions, sourced statements), how to invoke it (supply BOTH entity_type and the exact entity_slug), and when to omit filters (omit claim_type and reliability_class unless needed). It also gives precise when-not guidance: explain scope or decline purchasing/guarantee requests WITHOUT a lookup, since an empty search does not establish exclusion.

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 cover readOnly/openWorld/non-destructive; the description adds substantial behavioral context beyond them: the tool cannot place orders or take payments, cannot guarantee zero alcohol, an empty result is not proof of exclusion, results carry a slug for get_producer, and abv values are catalogue numbers lacking the source's qualifier. It also discloses null-means-unknown semantics and the empty-result recovery path.

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 very long and poorly front-loaded, opening with catalogue scope and refusal policy rather than what the tool does. A large block of alcohol-wording guidance ('0% and 0.0% are different wording...', 'Below 0.5% is an upper-bound declaration...') is really about claim evaluation and belongs with get_claim/search_beverages, not a producer search.

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 no output schema, 0% param coverage and 8 parameters, the description does a lot: it covers scope, routing to siblings, the slug handoff to get_producer, empty-result recovery, and the alcohol-evidence workflow. Gaps remain around the unmentioned region parameter, pagination, and the shape of returned producer records beyond the slug.

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% across 8 parameters, so the description carries the burden. It names five filter fields (name/q, country, city, ingredient, technique), but 'region' is never mentioned despite coexisting with 'country', and page/limit pagination behavior and multi-filter combination logic are unaddressed.

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 gives a specific verb and resource — 'Find producers by name, country, city, ingredient or technique' — and explicitly distinguishes itself from the sibling: 'This searches producers, not beverage names: use search_beverages for a drink.' That is strong differentiation. However, the purpose statement is buried roughly halfway through a long scope/refusal preamble, so the tool's actual function is not front-loaded.

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 states when to search, when not to (excluded categories such as NA beer, spirits, mocktails, dealcoholized wine — 'an empty search is not how to establish this exclusion'), names the alternative tool (search_beverages) and the follow-up tools (get_producer via the returned slug, get_claim for evidence). Refusal conditions for orders/payments and catalogue-wide no-alcohol guarantees are also spelled out.

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