beyond-wine

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

Annotations cover safety (readOnlyHint, destructiveHint=false, openWorldHint). The description adds that the response is a 'profile' plus 'claim previews' and that profiles lack source lists, which is useful context beyond annotations, but it doesn't describe pagination, rate limits, or auth. With annotations carrying the safety profile, this is adequate but not rich.

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?

Four tight sentences, front-loaded with the core action and tool routing. No redundancy. Slightly dense, but every clause serves a distinct routing or behavioral purpose.

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?

No output schema, so the description must explain return values; it does (profile and claim previews, no source lists). Covers the slug-finding prerequisite and downstream claim tools. Missing only the semantics of the 'condensed' 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?

Schema description coverage is 0%, so the description must compensate. It explains the semantic meaning of slug (use search_beverages, never invent) but says nothing about the 'condensed' boolean parameter, leaving one of two parameters undocumented in both the schema and description. Baseline 3 for partial compensation given 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?

States a specific verb (Retrieve) and resource (a published beverage profile with claim previews), and names the sibling tool search_beverages for finding slugs. It's clear what the tool returns, though 'beverage profile' could be more concrete about the domain (e.g., a producer entity with claims).

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: use search_beverages to find the exact slug, never invent it; verify the produced producer against the question; and use get_claim or search_claims with entity_type=beverage for sourced facts. Names alternatives and conditions, including the constraint that profile previews alone don't contain source lists.

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 declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond that. It discloses critical behavioral traits: one claim does not imply no other records, confidence is not proof, 'Below 0.5%' is an upper-bound declaration, 0% vs 0.0% wording difference is not proof of differing thresholds, and alcohol absence cannot be inferred. These are non-obvious, high-value constraints that materially affect how an agent interprets the returned data. This is exactly the kind of context annotations cannot provide.

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 efficiently front-loads purpose and return content. However, the rest is a long list of interpretive warnings that, while valuable, are not clearly prioritized or grouped. The sheer volume of caveats makes it less scannable. It earns its place but could be better structured with bullet points or a clearer separation between core function and interpretation guidelines.

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, one-parameter tool with no output schema and 0% schema coverage, the description is remarkably complete. It explains what is returned, how to obtain the identifier, and provides extensive interpretive guidance about the returned data (provenance, versions, alcohol wording, confidence caveats). An agent has everything needed to call and correctly interpret the tool.

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 the single claim_uid parameter. The description compensates by telling the agent where to get the value ('Copy claim_uid from a profile or claim search'). It does not specify the UID format or error behavior if not found, but it covers the essential semantics of the parameter. With only 1 parameter and 0% coverage, this is strong compensation.

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+resource ('Retrieve a published claim') with details on what is returned (provenance.sources, version history). Distinguishing from get_beverage, get_producer, get_context etc. is implied by the resource name, but there is no explicit sibling routing (e.g., get_context for context, get_entity for entities). It's clear but not maximally differentiated.

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 clear context: 'Copy claim_uid from a profile or claim search' and a use case ('check a source behind a profile claim preview'). This tells the agent when to reach for get_claim rather than search_claims. However, it does not explicitly state when NOT to use it or name alternative tools for adjacent needs (e.g., use get_context when only context is needed).

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 useful context ('token-bounded', bundle composition) but omits default behavior of the include set and the 8000-token ceiling.

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?

A single, front-loaded sentence with no filler. Efficient, though it compresses multiple parameters into one clause rather than giving each distinct treatment.

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 state what is returned (entity summary plus optional claims or graph data), which is the key completeness need for a read tool. Missing only the parameter-level detail that 0% schema coverage leaves undocumented.

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 partially does: 'token-bounded' hints at max_tokens and 'optional claims or graph data' reflects the include enum, but it never names the enum values or the 4000-token default that the schema supplies.

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 (Retrieve) and resource (context bundle for a Beyond Wine topic) with the composition of the bundle spelled out. It is distinguishable from siblings like get_entity or get_graph as the aggregated bundle, though it doesn't explicitly name 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?

Usage is only implied: the description suggests this is the aggregate tool that subsumes entity/claims/graph, but it never says when to prefer it over get_entity, get_claim, or get_graph, nor any prerequisites or exclusions.

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 and open-world retrieval are covered. The description adds useful behavioral context (claim previews, follow-up via get_claim, retain warnings, cite URLs), but does not cover pagination, rate limits, or auth needs. With annotations doing the safety work, this is adequate but not rich.

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?

Three sentences, front-loaded with the core purpose, then usage/provenance notes, then a conceptual clarification. No filler, though the entity-category sentence is slightly tangential to invocation.

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?

No output schema exists, and the description does explain the return shape at a high level (structured data plus claim previews). However, with 0% parameter schema coverage and a complex domain (multiple entity types, provenance linking), it leaves slug format, the condensed flag, and error/empty-result behavior undocumented.

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 for three parameters (slug, entity_type, condensed). It only implies entity_type via the category list and says nothing about slug format or the condensed flag. The gap is significant at 0% 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?

States a specific verb (Retrieve) and resource (published entity profile with structured data and claim previews), which is clearer than the tautological title 'Get entity'. It also distinguishes scope by naming the entity categories (producers, beverages, people, restaurants). It doesn't explicitly contrast with sibling tools like get_producer or get_beverage, but the purpose is unambiguous.

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 clear operational context: follow returned claim_uid with get_claim for provenance, retain confirmation warnings, and cite real returned URLs. It also clarifies the conceptual boundary that profiled entities are independent businesses, not brands. No when-not-to-use exclusions are stated, so it falls short of a 5.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral scope with 'direct relationship neighbors,' indicating non-transitive traversal, but does not disclose depth limits, pagination, or response shape.

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 one efficiently worded sentence with no filler and the key action front-loaded. It could be slightly more informative for a graph traversal operation, but it avoids waste.

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 graph traversal tool with no output schema and 0% parameter description coverage, the single sentence is insufficient. It omits parameter semantics, entity-type constraints, and any indication of what the neighbor results contain.

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 the two required parameters, yet the description never mentions slug or entity_type. It provides no meaning, format, or enum context beyond what the bare schema already shows, so it fails 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 description states a specific verb (Retrieve) and resource (direct relationship neighbors for an entity), which is clear and more specific than a generic get. It does not explicitly differentiate itself from siblings like get_entity or get_producer, so it falls short of a 5.

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 gives no explicit when-to-use guidance, prerequisites, or alternatives. It only implies the tool is for looking up graph neighbors of an entity, leaving selection among the many sibling get/list/search tools 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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that: no note on response size, whether the ontology is static or versioned, or how 'format' changes the output.

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?

One sentence, front-loaded with the verb and resource, with no filler. It is appropriately sized for a simple lookup, though it could have spent the same space on usage guidance instead of a content list.

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 metadata tool with no output schema and no required parameters, the description does list the returned content (entity types, relationship types, semantic scales), which is helpful. It falls short on the format parameter and on when an agent should reach for this tool, leaving it only minimally adequate.

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% and the single 'format' parameter (enum json/json-schema, default json) is never mentioned in the description. The enum values are somewhat self-explanatory, but the tool text gives no hint about what the formats mean or which to choose.

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 (Retrieve) and resource (the Beyond Wine ontology) and enumerates what it contains: entity types, relationship types, semantic scales. This clearly separates it from instance-level siblings like get_entity and get_graph, though it never names those siblings 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?

There is no when-to-use guidance, no mention of prerequisites, and no alternatives offered. An agent must infer from the name alone that this is the schema/metadata tool to call before interpreting data from other 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 declare readOnly, non-destructive, openWorld behavior, so the safety profile is covered. The description adds useful non-obvious behavior: the response embeds the published beverage lineup under data.beverages, which matters because there is no output schema. It does not cover not-found behavior or pagination.

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?

Three short sentences, zero filler, front-loaded with the action and resource. The concrete producer examples and the return-location detail both earn their space.

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 note about data.beverages fills a real gap, and annotations carry the safety profile. Missing details are the meaning of 'condensed' and behavior when the slug does not resolve, which are minor for a simple lookup.

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 parameters. The description only implicitly links 'slug' to producer identity and says nothing about slug format or what 'condensed' changes in the response, so it fails to compensate for the schema 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?

States a specific verb and resource (retrieve a specific producer), gives concrete examples (MURI, AMA Brewery), and names the returned data location (data.beverages). It is clearly distinguishable from search_producers and the other get_* 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?

Explicitly routes the agent: 'Use search_producers first when the producer slug is unknown.' This covers the primary decision point between this tool and its sibling, though it does not discuss other exclusions or preconditions.

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 one genuinely useful behavioral fact not in the annotations — that only 'published' entities are returned — but says nothing about pagination behavior despite exposing page/limit parameters.

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?

A single front-loaded sentence with no filler; the scope qualifier ('published') and the grouping dimension ('by type') appear immediately. Nothing in the sentence is redundant.

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 paginated, parametrised list tool with no output schema and 0% parameter documentation, the description is minimally viable: the purpose is clear enough to invoke, but it omits pagination behaviour, return shape and any hint about ordering or result size.

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 all three parameters rely on the description for meaning. 'By type' loosely explains the required entity_type, but nothing explains the allowed type values beyond the enum, and page/limit semantics and defaults are left entirely to 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 ('List'), a precise resource ('published entity profiles') and the scoping dimension ('by type'). It is distinguishable from sibling get_entity (single fetch) and get_beverage/get_producer, though it never names those alternatives explicitly, so it falls short of a 5.

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 only implied: the required entity_type plus 'by type' signals this is the enumeration entry point, but the description never says when to prefer it over search_beverages/search_producers or get_entity, and gives no prerequisites or exclusions.

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?

Beyond the readOnly/openWorld annotations, it discloses non-obvious query semantics (q matches name, alias, OR producer name) and a real behavioral trap (a combined producer-plus-product phrase may not match), plus the critical warning not to infer nonexistence from an empty result. That is substantive behavioral context the annotations cannot carry.

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 purpose and routing, and nearly every sentence carries actionable content. It is dense and slightly long, but there is little filler to cut.

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 5-param, no-output-schema search tool, it covers matching semantics, empty-result handling, and the downstream verification chain. It stops short of explaining pagination or category filtering, which an agent needs to call the full parameter surface.

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 5 parameters, so the description must compensate. It explains q (matching scope) and producer (must be an exact slug), but says nothing about page, limit, or category, leaving three 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?

States a specific verb and resource ('Find a beverage by name or alias') and immediately differentiates from the sibling search_producers ('Start here for drink names, not search_producers'). An agent can route between the two search tools 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?

Explicitly names alternatives and the conditions that select them: use this for drink names, use search_producers for producers, use the producer param with an exact slug to list a producer's drinks. It also prescribes follow-up chaining (get_beverage, then get_claim) and gives a fallback strategy when results are 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 only cover the safety profile (readOnly, non-destructive, open-world). The description goes well beyond that, disclosing pagination semantics (follow meta.has_more before negative findings), fields to inspect (provenance.sources, requires_independent_confirmation, source-reliability warnings), and explicit interpretation limits ('Confidence is not proof', confidence does not establish measurement).

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 the core filter rule are front-loaded well, but the text runs long and drifts into niche result-interpretation caveats ('0% and 0.0% are different wording', trace-alcohol threshold semantics) that are only marginally about selecting or invoking the tool, making the middle dense and repetitive.

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 6-parameter, 0%-coverage, no-output-schema tool, this covers the important ground: what the result contains (provenance.sources), pagination field (meta.has_more), and the epistemic limits of the returned evidence. An agent has enough to call it and interpret results responsibly.

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 does for the key filters: it explains entity_type/entity_slug pairing, when to use or omit claim_type, and when to omit reliability_class. It leaves page and limit unexplained beyond the generic pagination remark, so it is strong but not complete.

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 published claims') and adds the value-add of returning source provenance. It is clearly distinguishable from get_claim (single-claim retrieval) and from search_beverages/search_producers, though it never names a sibling tool 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?

Gives concrete filter guidance: supply BOTH entity_type and entity_slug for drink/producer questions, omit claim_type and reliability_class unless needed, and treat claim_type as a record format rather than a topic. It does not, however, say when to prefer this tool over get_claim or the other search_* siblings.

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 (readOnly=true, destructive=false, openWorld=true), so the burden is lower; the description adds genuinely useful behavior beyond that: zero-result recovery guidance and the requirement to copy the exact returned slug into get_producer. It doesn't mention pagination behavior or the shape of the result list, which keeps it short of a 5.

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?

Four short sentences, all front-loaded: purpose, disambiguation, failure recovery, then the follow-up call. No filler and no repetition of the 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?

With no output schema, the description correctly substitutes the key return fact (a slug, plus get_producer's data.beverages lineup) so the agent knows what comes back and what to do with it. The gap is the lack of any note on pagination/limits for a 20-param-capable list call.

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% for 8 parameters, so the description must compensate, and it only partly does: it names the facets behind q, country, city, ingredient and technique but never explains region, page, limit, or how q differs from the facet filters. Half the surface area remains undocumented in both schema and text.

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 ('Find producers') and enumerates the searchable facets (name, country, city, ingredient, technique). It explicitly contrasts itself with the sibling search_beverages, so an agent can route between the two 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?

Explicitly states when to use this vs search_beverages ('this searches producers, not beverage names: use search_beverages for a drink'), names get_producer as the downstream consumer, and gives a recovery path for empty results ('try a shorter producer name or remove extra filters'). That is when/when-not/alternatives all present.

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