Mr Suppy

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral content by stating what is returned (brands with sales, highest discount, example product), but says nothing about scope limits, rate limits, or data freshness.

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

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

A single, tightly packed sentence with the core result set front-loaded ('welke supplementmerken nú een sale hebben'). No filler, though it compresses return details into one clause.

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 partially compensates by describing the returned fields (brands, highest discount, example product). However, the undocumented 'merk' parameter and the absence of any alternative-tool routing leave the definition only marginally complete for a discovery tool with overlapping 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 description coverage is only 50%: the 'markt' enum is already documented in the schema, while the 'merk' parameter has no description anywhere. The description references the chosen market but adds no meaning beyond the schema and leaves 'merk' entirely 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 description states a specific verb+resource: it returns which supplement brands currently have a sale in a chosen market, including the highest discount and an example product. It is clearly distinguishable in substance, but it does not name or differentiate itself from close siblings like week_deals, verwachte_sales, or beste_in_categorie.

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 explicit when-to-use or when-not-to-use guidance, and no sibling alternative is referenced even though week_deals and verwachte_sales overlap in the sales/deals space. Usage is only implied by the mention of 'de gekozen markt'.

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=false, so the safety profile is covered. The description adds that the result is a ranked ('ranglijst') selection of top products rather than a raw listing, which is useful behavioral context, but it says nothing about ranking criteria, result size, or whether prices/links vary by market.

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 that states the resource first and appends examples; no filler or repetition. It is efficiently sized, though it is arguably too terse to carry usage or output context.

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 should ideally indicate what a ranking entry contains (product, score, price/link per market) and how the market parameter affects results. It conveys the shape of the answer loosely ('ranglijst van de beste producten') but leaves the return contract and the markt/categorie interaction implicit.

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 50%: markt is fully documented in the schema (enum, default, meaning of 'uk'), but categorie has no schema description at all. The description partially compensates by giving three example category values, which helps the agent populate the undocumented required parameter, though it adds no syntax or matching guidance.

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?

Names a specific resource (a ranking of the best products within a category) and gives concrete category examples (eiwitten, creatine, pre-workout), so the agent understands it returns a curated 'best of' list. It does not, however, distinguish itself from catalog/search siblings like search_catalog or lookup_catalog, which an agent could easily confuse with a category-based product query.

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 explicit when-to-use, when-not-to-use, or alternative-tool guidance. With eleven siblings including search_catalog, zoek_producten and lookup_catalog, the description never says why an agent should pick this ranking tool over a plain product lookup for the same category.

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=false, so safety is covered. The description adds real value beyond them: it discloses the failure semantics ('bij een onbekend id een JSON-RPC-fout') and that results carry discount code, partner link and permalink.

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 that packs id format, return contents and error behavior with no filler. It is dense but every clause carries information; the only cost is that the semicolon-joined error note is buried late.

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 needn't be explained, and annotations cover the safety profile. The description still covers the id constraint and the error case, leaving only the absence of sibling routing and the unaddressed markt parameter as minor 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 coverage is 67% and the schema already documents markt and the context/meta fields reasonably well. The description's one genuine addition is the required id format (sp-p-<id> / sp-v-<id>), which the bare 'type: string' does not convey, putting it marginally above the baseline.

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 (fetch one product) plus the id shapes it accepts (sp-p-<id> / sp-v-<id>) and the enriched output form (UCP with discount code, partner link, permalink). The id format alone distinguishes it from the catalogue search siblings, though no sibling is named 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 and no routing against alternatives such as search_catalog, zoek_producten or lookup_catalog. An agent must infer that this is the terminal step after an id has been discovered elsewhere.

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 the safe read-only, non-destructive profile, so the bar is lower. The description adds useful context by naming the return payload (last-verified date and user-vote success rate), but says nothing about permissions, rate limits, or behavior when no code exists.

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 that packs the resource, scope, and return fields without any filler. Well structured for quick scanning.

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 simple lookup with no output schema, the description adequately conveys what is retrieved and what extra metadata accompanies the code. It falls short only on edge-case behavior (e.g., missing codes), which is minor here.

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 only 50% (merk is undocumented in the schema), so the description should compensate, but it merely restates that a brand and a market are involved. It adds no format or semantic detail for merk and nothing beyond the schema's own markt description.

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?

Names a specific resource (kortingscode) with scope (brand + chosen market) and the extra data returned (last-verified date, success rate). It is clearly distinct from the product/sales siblings, though it lacks an explicit verb.

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?

No guidance on when to use this versus alternatives, no prerequisites or exclusions. Usage is only implied by the noun phrase 'voor een merk in de gekozen markt'.

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=false), so the bar is lower; the description adds genuine behavioral context by disclosing that unknown ids are reported rather than rejected, and that each returned variant carries inputs[] echoing the requested id. This error-tolerance detail is not derivable 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?

A single front-loaded sentence with the retrieval action first, followed by format detail and error semantics. Two clauses share one sentence and the embedded parenthetical is dense, 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?

An output schema exists, so return values need not be explained; the description supplies the two things an agent actually needs beyond the schema — accepted id syntax and unknown-id behavior. Market routing and the 20-id batch cap live in the schema, so 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?

The ids array has no description in the schema, and the description compensates by spelling out the accepted id syntaxes (sp-p-<id>, sp-v-<id>, bare post-id), which is real added meaning. The remaining parameters (markt, filters, context, attribution) are already documented in the schema, so 4 is appropriate rather than 5.

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 ("Haal producten op") and resource ("/via hun UCP-id") and even enumerates accepted id formats (sp-p-<id>, sp-v-<id>, bare post-id). The bulk-by-id nature is clear, though it never explicitly contrasts itself with the sibling search_catalog or get_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: it is evident you call this when you already hold ids, but there is no explicit when-to-use/when-not statement and no pointer to search_catalog for text queries or get_product for single fetch. The caller must infer the boundary themselves.

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, openWorldHint=false, so the safety profile is covered; the description adds real behavioral value by disclosing that the data is daily measurements and that it returns min/max/median plus a verdict on whether a 'korting' is genuine. It does not mention rate limits, latency or data-freshness, so it stops 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?

Two sentences, front-loaded with what the tool computes and followed by the parameter-sourcing instruction. Every clause carries information; the parentheticals compactly convey data granularity and ID provenance.

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 return-value burden and does so adequately by naming the statistics returned and the discount verdict. It omits any mention of the dagen window and the shape of the response, which is the only notable gap for a read-only analytics 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 coverage is 75% (markt, product_id and product_key are documented; dagen is not), so the baseline is 3. The description goes beyond the schema by explaining where each ID comes from and that product_id and product_key are interchangeable keys, though it never mentions the dagen parameter, leaving one 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 resource and scope ('Prijsverloop van een product (dagmetingen)') and even summarizes the computed output (laagste/hoogste/mediaan, korting-echtheid). It names sibling tools only as ID sources rather than as alternatives, so it does not fully differentiate itself from the other price/sales siblings, keeping it 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?

Makes the prerequisite explicit: you must first obtain product_id or product_key from zoek_producten, beste_in_categorie or product_oordeel, and states the two are alternatives. No when-not-to-use or alternative-tool routing is given, so 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the verdict is 'onafhankelijk' and enumerates the returned components, which is useful, but says nothing about market-dependent behaviour, freshness of price/reviews, or source of the reviews.

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 sentence with the core purpose front-loaded and no filler. It is appropriately sized, though the trailing enumeration of output components could be trimmed since there is no output schema to disambiguate.

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

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

For a two-parameter read tool with annotations covering safety this is nearly adequate, but with no output schema the description should do more to explain the SupplementScore itself (scale, meaning) and the nature of the reviews/prices returned per market. The essentials to call the tool are present; the essentials to interpret it are 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 50%: markt is fully documented with enum values and a default, while product_id has no schema description at all. The description only implies a single product ('één product') and contributes no meaning about the id or how markt affects output 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 specific verb+resource: an independent quality verdict ('kwaliteitsoordeel') on a single product, and names the payload (SupplementScore, onderbouwing, reviews, actuele prijs). An agent can distinguish it from a raw lookup, though it never explicitly contrasts itself with siblings like get_product or score_methodologie.

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 prerequisites, and no mention of alternatives such as get_product (raw data) or score_methodologie (how the score is computed). The agent must infer from the name that this is the scored, opinionated per-product view.

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=false, so the safety profile is covered. The description adds value by disclosing the payload contents (criteria, letter scale, evidence burden, independent review, dispute procedure), which is meaningful since there is no output schema. It does not cover other behavioral traits such as caching, auth, or versioning.

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 naming the resource and then listing its components after a colon. No wasted words, no preamble, appropriately sized for a no-required-parameter read 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?

With no output schema, the description correctly fills the gap by enumerating the returned content, and the read-only annotations remove the need for behavioral warnings. Only the absence of any usage/routing guidance keeps it from being fully 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?

There is a single parameter (markt) with 100% schema description coverage, including the enum values and the note about UK pricing in pounds. The description says nothing about this parameter, so baseline 3 applies — the schema carries the semantics.

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 resource ('het volledige SupplementScore-scoremodel') and enumerates its components (criteria, letterschaal, bewijslast, review, dispuutprocedure), so an agent can immediately tell this returns the scoring methodology rather than a product or price. It is clearly distinct from every sibling, none of which covers the model itself. It lacks an explicit verb like 'get/retrieve', but the intent 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?

There is no statement of when to call this versus alternatives, no prerequisites, and no exclusions. Usage is only inferable from the fact that it returns the scoring model, but nothing in the text guides the agent on timing or routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds some context about the return payload (price in cents, seller, per-variant discount codes, attribution, partner_url, permalink), but with an output schema present this is largely restating structure rather than disclosing behavior like pagination limits or ranking.

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 compact sentences with the core purpose front-loaded and no filler. Slight density from the enumeration of output fields, but it stays short and readable.

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 has an output schema, so enumerating return fields is not strictly needed, while the genuinely missing piece — how to choose between this and zoek_producten/lookup_catalog — is absent. For a zero-required-param search tool with nested filters, this is minimally viable but leaves the main routing decision to the agent.

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 67%, so most parameters already carry their own documentation (markt values, filters, pagination limits, attribution map). The description only echoes 'prijs in centen' and does not clarify markt/context precedence or cursor behaviour beyond what the schema states. Adequate baseline, no added 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 and resource ('Zoek supplementen in UCP-vorm') and names output contents (prijs in centen, verkoper, discounts.codes). It references sibling zoek_producten only to say it is 'dezelfde bron', which does not actually differentiate the two tools — an agent still cannot tell when this one is preferred.

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. The single sentence 'Dezelfde bron als zoek_producten' creates ambiguity rather than resolving it, since the two siblings should presumably be selected under different conditions but nothing indicates which.

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=false, so the safety profile is covered. The description adds real value by disclosing provenance ('op basis van merk-aankondigingen en onze eigen sale-waarnemingen'), telling the agent these are predictions, not confirmed prices. It still doesn't say how reliable/sparse expected future sales may be.

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 whose key differentiator ('vooruit') appears first. Dense but every clause contributes; the parenthetical '(van/tot, korting)' efficiently lists the returned attributes.

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 return-value burden and does describe the content (announced/expected sales, date range, discount). But it omits how results are structured, whether empty results are common for future periods, and the multi-market scope implied by the markt enum.

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 only 50%: 'markt' is documented in the schema (default nl, enum values), but 'merk' has no description. The phrase 'per merk' gives minimal semantic anchoring for that parameter, so the description partially compensates for the coverage gap but adds no format, multi-value, or filter semantics.

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 resource and scope: forward-looking 'sale-planning vooruit' with announced/expected sales per brand, including period (van/tot) and discount. The 'vooruit' framing implicitly contrasts with the sibling actuele_sales, but the sibling is never named, so the differentiation 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 word 'vooruit' plus 'aangekondigde en verwachte' implies this is the future/upcoming-sales lookup, which points an agent toward when to use it. However there is no explicit when-to-use clause, no exclusion, and no named alternative among the many sales/catalog 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 (readOnlyHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds that deals span supermarket AND online and include old/new price plus discount, which tells the agent what data comes back, but says nothing about freshness, coverage per market, or rate limits.

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 compact sentence with the payload description front-loaded before the market constraint. Nothing is padded, though it is arguably under-specified rather than genuinely concise.

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-only tool with no output schema, the description gives a decent picture of the returned data. However the nl/be restriction contradicts the schema's market enum and the winkel parameter is left entirely unexplained, leaving a real 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 50%, so the description needs to compensate. It mentions market scope only, and does so inconsistently with the enum (nl/be vs six markets), while the 'winkel' parameter is never addressed at all.

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 resource (actuele weekfolder-deals) plus the payload it returns (oude/nieuwe prijs en korting), which is enough to separate it from actuele_sales or verwachte_sales. It is clear but never names a sibling or a comparative condition.

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 only guidance is the scope constraint 'alleen voor markt nl/be', and that constraint conflicts with the schema enum that permits de/fr/es/uk. There is no statement of when to pick this tool over actuele_sales or beste_in_categorie.

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=false, so the safety profile is covered. The description contributes useful output context (price per 100 g/serving, SupplementScore, current discount code), but says nothing about result limits, pagination, auth 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?

A single dense sentence, front-loaded with the action and resource, with the output value proposition appended. Nothing is wasted, though the parenthetical makes it slightly harder to parse.

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 three parameters, no output schema, and a crowded sibling set, the description covers the purpose and return contents but leaves key gaps: no differentiation from search_catalog, no behavior for missing or empty queries, and no note on result size. Adequate but not sufficient for confident selection.

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 only 33%: only markt is documented in the schema, while zoekterm and max_prijs are bare. The description alludes to 'de gekozen markt' but does not explain what zoekterm accepts (name, brand, ingredient?) or how max_prijs filters, so it does not 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?

States a specific verb (zoek) and resource (supplementen) plus a notable scope qualifier: coverage across all shops in the chosen market, including non-Shopify. However, it never distinguishes itself from the sibling search_catalog, leaving the agent to guess which search tool applies.

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 search_catalog, lookup_catalog, beste_in_categorie, or product_oordeel. The 'ook niet-Shopify' phrase hints at breadth of coverage but does not tell the agent when this tool is the right choice.

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