Aloha Fungi

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

Annotations only declare the generic hint flags (readOnlyHint=false, destructiveHint=false, idempotentHint=false), while the description adds real behavioral context: signing, no cart/order creation, no payment or authentication, customer-side action required, and a 10-item cap. It does not say whether the link expires or whether repeated calls yield the same link, which is the main remaining gap for a non-idempotent tool.

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, front-loaded with the produced artifact followed by the critical negative scope and the hard limit. Every sentence adds information; nothing is repeated from the title or 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?

The tool's real complexity is the misinterpretation risk of being thought of as a checkout/order action, and the description neutralizes that directly, while the output schema covers the return shape and annotations cover flag hints. An agent has everything needed to call it 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 reported at 0%, so the description carries the burden and does so: it enumerates the item shape (product handle + variant ID + quantity) and the max of 10 items, matching the nested schema and maxItems constraint. It adds no guidance on where the variant ID comes from or what happens if a handle is invalid.

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 artifact: 'Composes a SIGNED LINK to the Aloha Fungi cart from given items'. It also explicitly separates itself from the write-path siblings ('does NOT create a cart or order'), so an agent can distinguish it from place_order/zloz_zamowienie 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?

Gives clear usage context: the output is a link the customer must click to add products and checkout, and no order/payment/login happens here. It does not explicitly name an alternative tool or a when-not condition against place_order, so routing is implied rather than spelled out.

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 annotations it discloses the two behaviors that matter: the result is a link for the CUSTOMER to click, not a completed transaction, and the `items` path is validated against the live catalog (so invalid SKUs surface as errors). That adds real context the annotations don't convey. It does not explain what happens when the goal/preferences match no set, or what the returned link looks like.

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: what it builds, the optional item-form alternative, then the key non-mutation caveat. The most decision-relevant constraints are front-loaded and nothing 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 five-parameter link-generator with no output schema, the definition supplies what an agent needs: required vs optional inputs, the enum vocabularies via schema, catalog validation behavior, and the fact that the return value is a URL rather than an order. Nothing material 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% and four parameters are enums with their own descriptions, so the schema already carries most of the meaning. The description restates the preference names (zestaw, moc, forma) and the SKU:quantity format without adding syntax or constraint detail beyond the schema. Baseline 3 applies since the description adds little param-level value.

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 ("Builds a link"), the resource (the subscription builder at /subskrypcja/zestaw), and the inputs it derives from (goal plus optional preferences). The closing sentence explicitly separates it from a purchase action ("Does NOT create a subscription or pay"), so an agent can distinguish it from zloz_subskrypcje or place_order without opening a 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?

It gives clear usage context: use it to produce a clickable link for the customer, including the alternative path of passing explicit items. The negative guidance ("does NOT create a subscription or pay") effectively steers the agent away from the ordering siblings. It stops short of naming the sibling to use when the customer actually wants to complete checkout, leaving that inference to the agent.

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 readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description adds substantially beyond that — the call is non-mutating in the store (no cart/order created, no payment taken), the customer pays themselves after clicking, and the link is encrypted and signed with live prices/address. It also discloses the 500 PLN hard limit, the 10-item cap, and the shipping-options return path when dostawa is absent, which is exactly the operational context an agent needs before calling.

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 critical constraint (no cart, no payment) is front-loaded, and nearly every sentence carries a distinct rule: the 500 PLN ceiling, the missing-dostawa behavior, the item cap. It loses a point for heavy ALL-CAPS emphasis and for packing three separate constraints into one dense block rather than ordering them by decision importance.

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 still explains what comes back — an encrypted signed one-click link, or live shipping options when dostawa is omitted — plus the error shape above 500 PLN. For a nested-object, 5-parameter write-adjacent tool, nothing an agent needs to call it correctly or predict the response 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 60%, and the description fills the most important gap: "dostawa" is optional and omitting it triggers a live shipping-options response with the cheapest option auto-selected. The 10-item cap and the optional parcel-locker concept are also stated, though "paczkomat" itself is not named in the description and address sub-field meaning is 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?

The description states a concrete verb and resource ("Places a COMPLETE order") plus the concrete artifact it produces ("returns an ENCRYPTED, signed one-click link to /zamowienie-agenta"). It explicitly distinguishes itself from cart-building siblings by stating "This tool does NOT create a cart or order and never pays", so an agent can separate it from compose_cart/zloz_koszyk 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?

It gives explicit conditions: orders above 500 PLN are not supported and the tool returns an error with a link to a regular cart, which routes the agent elsewhere. It also states the conditional path when "dostawa" is omitted (live shipping options are returned and the cheapest is used) and caps items at 10, covering when-to-use and when-not-to-use without 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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: data comes from a live Medusa catalog, the goods are dietary supplements rather than medicines, and the shop makes no diagnostic or health-outcome claims. It stops short of saying what happens when the handle is unknown (empty result versus error).

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

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

Two sentences, front-loaded with the return contract before the catalog context. The second sentence is longer and covers domain positioning, but it earns its place given the supplement/health-claims sensitivity implied by the product domain.

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 one fully documented parameter, a stated output schema, and read-only annotations, the definition supplies everything needed to call it correctly; the return field list is a bonus rather than a gap-filler. 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 description coverage is 100% and the single 'handle' parameter is documented with an example ('reishi'). The description restates the same idea ('po handle produktu') without adding format, casing, or fallback guidance, so the schema carries the load and 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?

The description gives a specific verb and resource ('Zwraca warianty produktu') plus the lookup key ('po handle produktu') and names the returned fields (SKU, cena PLN, dostepnosc), so the agent knows exactly what it gets. It never names a sibling, so it does not explicitly separate itself from search_products/szukaj_produktow or show_product.

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 phrase 'po handle produktu' signals that the tool requires an exact product handle, which implicitly routes name- or keyword-based lookups to search_products. There is no explicit statement of when to use this versus the search siblings, and no exclusions or prerequisites are given.

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 read-only, closed-world safety profile, and the description adds genuinely new behavior: it returns live catalogue data with named fields (tytul, handle, URL, cena od, dostepnosc) plus the list of goals each product serves. It also sets an expectation that this is not an efficacy promise, which is useful framing an agent can carry into its reply.

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 compact sentences, front-loaded with what the tool does and the accepted goals, with the returned fields immediately after. The all-caps emphasis ('CELU', 'ZYWE') is stylistically noisy but costs no real length.

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 one-parameter lookup with no output schema, the description supplies what the schema cannot: the shape of the return payload and its live-catalogue nature. Only the sibling-routing guidance is missing, which is a real but narrow gap.

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

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

Schema coverage is 100% and the enum already lists exactly the six accepted values, so the description's repetition of that list adds little. It does clarify that 'cel' means the customer's stated goal, but that is marginal over the schema's own example 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?

The description gives a specific verb and resource ('Rekomenduje produkty') and narrows scope to a customer goal axis, enumerating the six goals. It is clear what the tool does, but it never differentiates itself from the near-identical sibling 'recommend_products', which an agent is likely to confuse with it.

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 or when-not-to-use guidance and no mention of alternatives such as 'recommend_products', 'search_products' or 'szukaj_produktow'. The closing line about 'po co' framing is positioning, not usage direction, so the agent must infer selection from the name alone.

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 and openWorldHint=false, so safety is covered. The description does add useful behavior beyond that: it names the returned fields (title, handle, URL, price from, availability) and the goals each product serves, which matters because there is no output schema. It stops short of covering ordering, result counts, or empty-result 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?

Three short sentences with the core purpose stated first, followed by return shape and a caveat. The re-listing of all six enum values duplicates the schema and is the one clearly removable element.

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 one-parameter, read-only lookup with no output schema, the description does the necessary work: it explains what comes back, what the goal axis represents, and the health-claim caveat. The missing piece is sibling differentiation, which is the main thing an agent still has to guess.

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

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

Schema coverage is 100% and the single 'cel' parameter is already documented with an enum plus a gloss. The description repeats the enum and adds only light framing ('customer language', the 'why' axis, not a health promise), which is helpful context but not new parameter-level meaning. 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?

The description gives a specific verb and resource ('Recommends products matching a customer GOAL') and enumerates the goal values, so the agent knows exactly what the tool produces. It does not, however, distinguish itself from closely related siblings such as polec_produkty, search_products, or szukaj_produktow, leaving the agent to infer the difference.

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 phrase 'the "why" axis in customer language' suggests this is goal-based discovery rather than keyword search, and 'Not a health promise' hints at a compliance boundary. There is no explicit statement of when to pick this over search_products or polec_produkty, and no 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 and openWorldHint=false, so safety is covered. The description usefully adds the return shape (URL, source, matching text) and a content-policy note that results are GIS-safe and non-diagnostic, but says nothing about result limits, ranking, or empty-result 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?

Three sentences, front-loaded with what is searched and over what corpus, then return fields, then policy. The final GIS-safe sentence is not filler because it tells the agent how to present results, though it could be tightened.

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 read-only search with no output schema, the description is nearly sufficient: corpus, example queries, and return fields are all covered. The remaining gaps are operational details such as result count limits and whether matching is keyword or semantic.

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 at 100% schema coverage, the schema already documents 'pytanie' as a search phrase or question. The example queries give some hints about phrasing (natural-language questions rather than keywords), but no syntax, length, or query-construction guidance 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?

The description names a specific verb ('searches') and an explicit corpus: the Aloha Fungi blog, PDP content, and species guides. Listing the content sources separates it from the product-search siblings, but it never acknowledges the closest-sounding sibling (zapytaj_wiedze / 'ask knowledge'), so the boundary with that tool is left to inference.

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 three example queries imply the intended use (natural-language questions about dosing, benefits, contraindications), which is clear enough context. However, there are no explicit when-to-use/when-not-to-use rules and no named alternative for product lookups or the Q&A-style sibling, so routing depends on the agent's own 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 cover the safety profile (readOnlyHint, openWorldHint=false), yet the description still adds real behavioral context: results are LIVE catalog data including price-from and availability, and the important caveat that with forma/linia the price and availability describe only the matching variant, not the whole product. That variant-scoping warning is exactly the kind of non-obvious behavior an agent needs and cannot get from annotations or schema.

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 core purpose and kept to four sentences, all relevant. Minor redundancy: 'Returns LIVE catalog data (price from, availability)' and 'Prices and availability come from the live catalog' restate the same fact, costing a bit of 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 not be described, and the description correctly focuses on matching scope, liveness of data, and variant-level pricing. Gaps remain around result limits/pagination and whether results are ranked, but for a read-only search tool with a fully documented schema this is close to complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely enriches two parameters: it explains that 'fraza' matches name, Latin name, or common alias (broader than the schema's 'reishi'/'sleep' examples) and that an empty string returns everything, plus it clarifies the forma/linia semantics. The remaining filters (cel, sort, kategoria, rodzaj) are left 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 and resource ('Searches the Aloha Fungi product catalog') and defines the match scope ('name, Latin name, or common alias'), which tells an agent exactly what is being searched. It stops short of naming how it differs from siblings like show_product or recommend_products, so a 4 rather than 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?

Provides one useful usage fact — an empty 'fraza' returns the full catalog — which is really schema/usage behavior. It gives no explicit when-to-use guidance and never says when to prefer show_product, polec_produkty, or search_knowledge over this tool, leaving selection to inference from the names.

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 and openWorldHint=false, so safety is covered and the bar is lower. The description still adds real context beyond them: data provenance ("live Medusa catalog"), currency (PLN), and a domain constraint that the products are dietary supplements rather than medicine, which shapes how an agent should frame answers. It does not say what happens when a handle is unknown.

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, front-loaded with the primary return value and then the secondary educational content. Every sentence carries information; only the terse list of educational sections is slightly clipped.

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 read tool with an output schema, the description is close to complete: it covers provenance, currency, and the domain caveat, and the output schema handles return structure. Minor gaps remain on lookup failure behavior and on explicit routing versus the search siblings.

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

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

Schema coverage is 100% and the single parameter already carries an example ("reishi"), so the baseline is 3. The description clarifies the lookup is handle-based (not SKU or name) and that SKU is an output rather than an input, but it adds no format or matching-rule detail 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?

The description names a specific verb and resource (returns product variants by handle) and enumerates the payload (SKU, price in PLN, availability, plus educational sections). The lookup key ("by product handle") implicitly separates it from the search-style siblings, but no sibling is named, so an agent must infer that search_products/polec_produkty cover non-handle lookups.

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 tool takes a handle, so it is usable when a handle is already known, and the sibling set (search_products, szukaj_produktow, recommend_products) suggests discovery paths. There is no explicit when-to-use, when-not-to-use, or fallback statement for a missing/invalid handle.

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 (readOnlyHint=true, openWorldHint=false), so the description's job is to add context, which it does: results are live catalog data, prices are "cena od", and availability reflects the live catalog. The variant-level caveat — that with forma/linia set, price and availability describe only the matching variant, not the whole product — is real behavioral nuance an agent could not infer from the schema.

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 core scope is front-loaded in the first clause, which is good. However, sentences two and three are redundant: "Zwraca ZYWE dane z katalogu (cena od, dostepnosc)" is immediately restated by "Ceny i dostepnosc pochodza z zywego katalogu", so one sentence does not earn 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?

With 7 parameters at full schema coverage and an output schema present, the description does not need to document fields or return shape, and it correctly focuses on search semantics and the live-pricing caveat. The only material gap is the absence of routing guidance among the many sibling search/show/recommend 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 coverage is 100%, so 3 is the baseline, but the description adds genuine meaning: it explains what the fraza field actually matches against (name, Latin name, PL/EN alias), which the schema only illustrates with an example. The forma/linia sentence also explains the filter's effect on returned price/availability, going beyond the enum labels.

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 and resource ("Szuka produktow w katalogu sklepu Aloha Fungi") and defines the matching surface precisely: nazwa, nazwa lacinska, popularny alias PL/EN. It does not differentiate itself from the sibling search_products or pokaz_produkt, so an agent cannot tell from the text alone which search tool to prefer.

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: search when you have a phrase, optionally narrowed by forma/linia/cel. There is no explicit when-to-use versus show_product (single item lookup) or recommend_products, and no statement of when this tool should not be used. The empty-string-returns-whole-catalog rule lives in the schema, not in the description.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it returns live product data only 'when available in the catalog', always includes a cited source and a disclaimer field, and explicitly frames output as tradition rather than medical advice.

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 dense paragraph that front-loads the core action and follows with output and disclaimer context; every sentence carries information. Minor cost from the capitalized 'TCM TRADITION' emphasis and the slightly run-on final clause, but nothing is wasted.

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 the work of explaining return values: TCM frame mapping, linked mushrooms, cited source, taste/nature/meridian profile, optional live product data, and a disclaimer field. Only the absence of any guidance on ambiguous or empty inputs keeps it from a 5.

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 both enums are documented, so the schema carries the parameter burden. The description adds no format or syntax guidance for 'opis' or 'pora_roku' beyond what the schema already states, so the 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 (translates) and resource (a customer well-being description) and names the output frame precisely (qi, yin/yang, organs, seasons) plus the linked mushrooms with source and profile. An agent can distinguish this from recommend_products or search_knowledge 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 sets a clear boundary ('describes tradition, NOT a diagnosis or a promise of effect'), which implies when the tool is appropriate. However, it never names an alternative or states when to prefer recommend_products, search_knowledge, or the sibling tlumacz_tcm, so 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: it returns live product data when the item is in the catalog, cites sources, and always includes a disclaimer field, plus it explicitly frames output as tradition rather than diagnosis. It does not describe response structure or failure behavior in more detail.

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 core action, then the output contents, then the important caveat about tradition versus diagnosis. It is a single dense paragraph with little waste, though the disclaimer point is repeated in slightly different words.

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 carries the burden of explaining returns, and it does: cited source, taste/nature/meridian profile, live product data, and a disclaimer field. Combined with full schema coverage and read-only annotations, an agent has enough to call it correctly; only sibling disambiguation 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%, so all three parameters (opis, locale, pora_roku) are already documented with examples and defaults. The description adds no syntax, format, or constraint detail beyond the schema, so the 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: translating a client's wellbeing description into the TCM framework (qi, yin/yang, organs, seasons) and mapping mushrooms traditionally associated with it. It also names the output shape (cited source, taste/nature/meridian profile, live product data). It does not, however, distinguish itself from the sibling tcm_translate, which appears to be a near-duplicate name.

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 tool is for interpreting a client's self-described state through TCM. There is no explicit when-to-use versus when-not, and no routing to siblings such as polec_produkty, search_products, or tcm_translate, which an agent would plausibly confuse with this one.

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 and openWorldHint=false, so the safety profile is covered. The description adds real value beyond them: it explains the return shape (matching results with URL, source tag blog/pdp/guide, and the matched text) and states a content policy (GIS-safe, no diagnoses, no promised effects) that an agent needs in order to relay results responsibly.

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 search scope, then the return shape, then the content policy; each sentence carries distinct information. Slightly dense run-on phrasing in the opening sentence, but 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 one-parameter read-only search with no output schema, the description covers purpose, sources, return fields, and content constraints, which is nearly everything an agent needs. Minor gaps remain around result limits, ranking, or empty-result behavior.

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

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

With a single parameter at 100% schema description coverage, the schema already documents "pytanie" fully. The description reinforces that a natural-language phrase or question is expected via its examples, but adds no format, length, or language constraints beyond what the schema states, so the 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?

The description gives a specific verb and resource ("Przeszukuje blog, tresci PDP i przewodniki gatunkow Aloha Fungi po frazie") and enumerates exactly which content corpora are searched. That scope implicitly separates it from the product-oriented siblings (search_products, szukaj_produktow, polec_produkty), though none of them is named directly.

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 three sample queries ("jak dawkowac reishi", "soplowka a pamiec", "przeciwwskazania chaga") show the kind of question this tool is for, so usage is implied fairly well. However, there is no explicit statement of when to prefer this over search_knowledge or the product-search siblings, and no 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 annotations, the description discloses the essential behavior: no cart or order is created, no payment or login occurs, only a link is returned that the customer must click, and there is a 10-item cap. This is exactly the side-effect profile an agent needs for a tool annotated readOnlyHint=false but destructiveHint=false.

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 purpose is front-loaded in the first clause, and the heavy emphasis (caps, repeated negatives) is purposeful for a tool that must not be mistaken for checkout. It is slightly verbose with the capitalized negations, but nothing is genuinely wasteful.

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 tool with annotations and an output schema, the description covers the critical points: what is produced (a link, not a cart), what the agent/kund must do next, and the item cap. Only minor gaps remain, such as link expiry or what happens when the item limit is exceeded.

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 reported as 0%, so the description must carry parameter meaning; it does map the three fields (handle produktu, variantId wariantu, ilosc) and states the 10-item maximum. However, it adds no syntax or sourcing detail — e.g. where variantId comes from or whether quantity limits are per line or per cart — beyond the brief inline schema notes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: it builds a signed cart link ("Sklada PODPISANY LINK do koszyka sklepu Aloha Fungi") from given items. It then explicitly contrasts itself with ordering/payment, which separates it from siblings such as place_order and zloz_zamowienie.

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 a clear context for use (building a cart link from product handle, variantId, quantity) and strong negative guidance — it never creates a cart/order, never pays, never logs the user in, and the client must click the link. It does not name a specific alternative sibling (e.g. place_order or compose_subscription) for the cases it excludes, so it stops short of full when-to-use 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?

Beyond the annotations it discloses two non-obvious traits: SKU quantities are validated against a live catalog (so bad items fail rather than pass through), and the return artifact is a URL the client must click themselves. One tension is left unexplained: readOnlyHint=false implies a non-read-only operation, while the description frames the tool as pure link construction with no state change.

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 compact sentences: what it builds, what inputs it accepts, and what it does not do. The most decision-relevant constraint (returns a link, does not transact) is placed last for emphasis with zero 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?

With no output schema, the description correctly covers the return value ('zwraca link') and who uses it. Minor gaps remain: no mention of link expiry, of what an invalid SKU produces, or of precedence when both items and zestaw/moc/forma are supplied.

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

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

Schema coverage is 100% and all four enums are already documented in the schema, so the schema does the heavy lifting. The description adds framing that zestaw, moc and forma are optional preferences layered on top of the required goal, but nothing about the SKU:quantity format or what happens when validation rejects an item beyond what the schema already 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 concrete verb+resource: builds a link to the subscription configurator at /subskrypcja/zestaw. It explicitly declares the negative scope ('NIE tworzy subskrypcji ani nie płaci'), which separates it from compose_subscription, zloz_zamowienie and place_order without the agent 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 clear this is the path when the outcome is a hand-off link for the client to click, and it explicitly rules out actual subscription creation or payment. It stops short of naming a specific sibling to use instead when the agent does need to create a subscription or order, 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?

Annotations only say it is a non-destructive, non-open-world write; the description adds substantial context beyond that: no cart or shop order is created, no payment ever occurs, the returned link is encrypted and signed, the 500 zl ceiling produces a specific error payload, and the missing-dostawa case returns a live delivery-option list. It also discloses the 10-item cap and the substitution rule (cheapest option chosen) — behavior an agent could not infer from the annotations.

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

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

The most important facts — what is produced and what is explicitly NOT done — are front-loaded, and each sentence carries a distinct constraint. The trailing "Maks. 10 pozycji" merely repeats the schema's maxItems/maximum, a minor redundancy.

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

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

For a mutation-flavored tool with a nested object schema and no output schema, the description covers the success artifact (signed link), the over-limit failure path, and the no-delivery fallback return value, so an agent knows what comes back in every branch. Nothing needed to invoke it correctly 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?

With 60% schema coverage, the description carries real weight: it explains the semantics of the optional "dostawa" parameter (its absence changes the return value and defaults the link to the cheapest option), confirms paczkomat belongs to the order payload, and reiterates the 10-item limit on pozycje. The nested address fields are left to the schema, which documents them adequately.

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 names a specific action (composing a complete order from items, e-mail, address and optional delivery), states the exact artifact returned (an encrypted, signed one-click link to /zamowienie-agenta), and explicitly negates what siblings like zloz_koszyk/compose_cart do ("NIE tworzy koszyka ani zamowienia w sklepie"). An agent can distinguish this from the cart- and order-placing siblings 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?

Clear conditions are given: the customer pays themselves via the link, totals above 500 zl are not supported and yield an error with a plain-cart link, and omitting "dostawa" switches the tool into a delivery-options-returning mode using the cheapest option. It stops short of naming sibling tools for the fallback path (it only says "zwykly koszyk"), so the routing is implied rather than explicit.

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