Tryvon

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

Annotations already establish this as a safe, idempotent, non-destructive read, so the bar is lower. The description adds genuinely new behavioral content: how offers are matched into the same product set, that the result is ordered by cheapest total price, and that each entry carries a delivery promise. It omits result limits/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 tight sentences: what it returns, why you'd call it, and which argument to supply. The core behavior is front-loaded and no sentence is 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 annotations covering the safety profile and no output schema, the description does the heavy lifting well by describing the returned list, its ordering, and the delivery information. One gap remains: zero parameters are marked required, yet the description only says to pass one of the two identifiers, leaving the behavior when neither is supplied unspecified.

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 the baseline is 3. The description goes slightly beyond the schema by framing product_key and offer_id as interchangeable ways to address the same product and by explaining the matching basis (barcode or brand + part number) that underlies the key.

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 ('list every shop selling the same item'), plus the matching rule (barcode or brand + part number) and the ordering (cheapest total price first). The 'for one product' scoping implicitly separates it from compare_products (multi-product) and search_products, so an agent can route correctly.

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 context via the two questions it answers ('where is this cheapest', 'who delivers it tomorrow') and guidance on which identifier to pass ('Pass product_key or offer_id'). It stops short of naming alternatives or stating when not to use it, so no explicit exclusion guidance.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real value by disclosing the output shape — differing rows marked, cheapest/best-rated/best-choice highlights, Tryvon score — which is behavioral context the annotations cannot convey. It does not state whether results are cached or sorted.

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 that front-loads the action and scope, then lists the return dimensions. No filler, no repetition of the title.

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 well, enumerating the compared attributes and highlight markers. The only gap is routing guidance against compare_prices and search_products, which the agent would need to select this tool confidently.

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 schema already documents product_keys with its source (productKey from search_products or top_products). The description's '2-4 different products' corroborates the bounds but adds no format or sourcing detail beyond the schema, so baseline 3 is appropriate.

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 (Compare) and resource (products) and enumerates exactly what the comparison surfaces: specifications, rating, lowest price/shop, shop count, delivery. It's clear what the tool does, but it never distinguishes itself from the sibling compare_prices, which an agent could plausibly confuse it with.

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 '2-4 different products' constraint implies usage but no explicit when-to-use or when-not guidance is given, and no alternative (compare_prices, search_products) is named. The agent must infer that this is the multi-attribute comparison path.

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, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds meaningful context by clarifying that nothing is bought and the purchase happens on the shop's site, and it discloses that an affiliate disclosure is included in the response — useful behavioral detail beyond 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?

Two tight sentences; the core purpose is front-loaded, and the clarifying constraint about not making a purchase earns its place by preventing misuse.

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 single-parameter read tool with full annotation coverage, the description covers purpose, safety scope, and return content (link plus affiliate disclosure). No output schema exists, but the description adequately describes what comes back; only pagination/format nuances are absent, which are 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 100% for the single offer_id parameter, and the schema already documents its provenance from compare_prices and search_products. The description adds no additional parameter semantics, 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 ('Get') and resource ('the link where the user can buy the product'), and the scope is clear enough to distinguish it from siblings like compare_prices and search_products. The second clause preempts the obvious confusion about whether the tool performs a purchase.

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?

Implicit routing is present: the schema ties offer_id to compare_prices and cheapestOfferId from search_products, so the agent knows this tool follows price comparison. However, the description itself gives no explicit when-to-use statement or exclusions beyond clarifying that no purchase occurs here.

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, idempotentHint and non-destructive, so safety is covered. The description adds behavior beyond that: the values are aggregated across all shops and the window is a rolling 30-day comparison, which tells the agent what it will actually receive. No output schema exists, so this return-shape disclosure carries real weight.

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, no filler, with the data description front-loaded before the use case. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates the returned metrics, and annotations cover the safety profile, leaving little ambiguity for a simple two-parameter read. Minor gap: nothing about the timezone/granularity of the daily series.

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%, with both parameters documented including the 7-365 range and the source of product_key, so the schema does the heavy lifting. The description's only added nuance is 'all shops together', which is an aggregation note rather than parameter 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?

States a specific resource (lowest daily total price of a product over time) plus the exact aggregates returned: lowest price ever and change versus 30 days ago. This is distinguishable from compare_prices/search_products, which the sibling list shows are lookup tools rather than historical aggregation.

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 frames the use case ('is this a good moment to buy?'), giving clear context for when to call it. It stops short of naming when-not-to-use or pointing to a sibling alternative for other price questions, so it lands below 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, idempotentHint=true, destructiveHint=false and a closed world, so safety is covered; the description goes further by disclosing the aggregate semantics of the response (lowest total price incl. shipping, cheapest shop, shop count, next-day availability). It stops short of auth requirements, rate limits, or empty-result behavior, so it is strong but not exhaustive.

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 tight sentences, front-loaded with what it searches, then what it returns, then the hand-off to the sibling. Every clause carries information; nothing is padding.

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 usefully describes the return shape, and annotations cover the safety profile, so the agent has what it needs for an 8-parameter tool. Minor gaps remain: pagination/limit interaction with the 24 cap and no-result handling are unaddressed.

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

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

Schema description coverage is 100% and each parameter carries its own explanation (shop, sort options, price bounds, delivery days, limit range), so the schema already does the heavy lifting. The description adds no parameter-level syntax or default information beyond it, which is the baseline-3 case.

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 (Search) plus the resource and domain (products and travel eSIM data plans at Dutch partner shops), and further pins the result granularity (one entry per product, not per shop). An agent can distinguish it from compare_prices/compare_products 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?

Explicitly routes the complementary case: 'Use compare_prices with product_key to see every shop for one product,' giving both the alternative tool and the key that selects it. Discovery-vs-drill-down division of labor is unambiguous.

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

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

With readOnlyHint, idempotentHint, and openWorldHint already covered by annotations, the description adds substantial behavioral context: it explains the ranking factors, explicitly states that commission plays no part, lists the return fields, and notes the hasReviews=false flag. This is rich disclosure beyond structured data.

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

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

The description is front-loaded with purpose and structured logically: ranking explanation, trust note, then return details. Every sentence serves a purpose, though the ranking methodology sentence is dense and could be slightly trimmed.

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

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

Given no output schema and rich annotations, the description adequately explains what the tool returns and how ranking works. It omits any routing guidance relative to sibling tools, which is a minor gap for an otherwise complete definition.

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 five parameters are already documented with examples and defaults. The description adds only marginal semantic value, such as relating the query parameter to a 'need', but does not compensate for anything missing.

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 clearly states the tool returns the best products for a need, ranked by a proprietary score. It distinguishes itself from a generic search by emphasizing ranking and specific return fields, but it never names or contrasts with siblings like search_products or compare_products.

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?

Examples such as 'top 5 smartphones' and 'best airfryer under 150 euro' imply the intended use case. However, there is no explicit guidance on when to choose this over search_products or compare_products, nor any exclusions or prerequisites.

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