Dealio: Belgian deals

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

Annotations already declare readOnly/idempotent/openWorld=false, so safety is covered; the description adds genuinely useful context beyond that, namely that every statement carries a source, that today's lowest promotion is included, and that the tool withholds a verdict. It does not cover pagination or result size, so it falls 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?

Front-loaded with the noun phrase and its contents, then usage, then the no-argument case — a logical order. The middle sentences are dense and run long, but nearly every clause contributes information an agent needs.

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

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

There is no output schema, so the description carries the burden of describing the return value, and it does: models compared with specs and promotions, feature explanations with when-you-need-it guidance, sourced facts, and the list-of-guides fallback. An agent can decide whether to call it and predict the shape of the answer.

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 the baseline is 3; the description goes further by clarifying that the type may be Dutch or English, giving concrete synonyms ('airfryer', 'heteluchtfriteuse'), and explaining the no-argument fallback of returning all guides.

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

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

Opens with a specific verb+resource ('A researched buying guide for a kind of product') and immediately enumerates the contents: compared models with key specs and today's lowest promotion, feature explanations, and sourced facts. It is clearly distinguishable from sibling tools such as get_deal or search_deals, which deal with individual deals rather than guide content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use conditions with real query examples in both Dutch and English ('beste airfryer', 'welke wasmachine kopen'), and states a clear boundary: it does not crown a winner but presents cited test and buyer scores. It also states the behavior when no type is supplied (returns the list of guides).

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/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: provenance ('as read from the stores' own sites'), the fact that 'aangekondigd' campaigns are announced but not yet running, and that each result nests the underlying dealio promotions with their links. It stops short of saying anything about freshness/caching or result ordering.

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 resource and its data source are front-loaded, which is good, but the description is a single ~90-word run-on that re-lists every campaign kind ('1+1, 2e halve prijs', 'no VAT', 'loyalty-card deals') already enumerated in the kind schema. That list is dead weight; trimming it would sharpen the definition without losing information.

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

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

There is no output schema, and the description compensates fully by enumerating the returned fields (store, kind, advantage, applies-to, condition, code, validity, product vs. basket, link, nested promotions). Combined with a complete input schema and read-only annotations, 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 100%, including per-enum-value explanations, so the schema already carries the parameter meaning. The description's 'Filter by store, kind or words' and 'whether it works on products or on the whole basket' merely restate the q/store/kind/reach fields and duplicate the kind vocabulary verbatim from the enum.

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 first sentence names a specific resource (store campaigns / winkelacties at Belgian retailers) and its source (the stores' own sites via dealio.be/acties/). It then explicitly excludes the nearest sibling: 'Not one product's price (that is search_deals).' An agent can distinguish this from search_deals 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 states the exclusion against search_deals and tells the agent it can 'Filter by store, kind or words', with the store filter pointing to list_stores in the schema. It doesn't cover when to prefer get_deal for a single promotion even though it mentions nested promotions 'on dealio that fall under it', so routing is clear but not exhaustive.

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, non-destructive and closed-world, so safety is covered. The description adds only that the full record is returned, saying nothing about unknown-id behavior, error responses, or what 'in full' actually includes.

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 well-front-loaded sentence with no filler; the key constraint (id from a search result) arrives before any qualification.

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 this is close to adequate, but with no output schema the description should at least sketch the return shape or unknown-id behavior; 'in full' is the only hint and it is vague.

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 parameter is documented, so the baseline is 3. The description's note that the id comes from a search result merely restates the schema text rather than adding format or provenance detail.

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 and resource: fetch one promotion (deal) in full by id. The phrase 'by the id a search result gave' implicitly separates it from search_deals, though it never names that sibling and uses 'promotion' rather than the tool's 'deal' terminology.

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?

Clearly signals the prerequisite: use this only when you already have an id produced by a search result, which routes the agent away from list/search tools. It stops short of explicitly naming search_deals as the alternative or saying what to do if no id exists.

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 read-only/idempotent/non-destructive, so the bar is lower, and the description still adds real context: what the response contains (promotions with price, deal, 'until when', link; side ingredients on promotion; remaining non-promo items) and the aggregation behavior when stores is omitted. No contradictions.

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 dense sentences, front-loaded with the resource and the filtering rule, with the store-less mode as a clear trailing clause. It is informative but slightly sprawling; the enumerated return contents 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?

With no output schema, the description does the work of explaining the return payload and the alternate counting mode, which is the key gap it needed to fill for six optional parameters. Ordering of results and use of offset/limit paging are left to the schema only.

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 each parameter already has a description, so the schema carries the load. The description only adds the 'day the user shops' framing and the no-stores interpretation of the stores parameter, which justifies the baseline 3 rather than more.

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 ('meal ideas from the promotions') and immediately scopes it: dishes whose main ingredients are all on promotion at given stores. It is clearly distinct from siblings like search_deals or get_buying_guide because the output is composed dish suggestions, not raw deals.

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 ('dish ideas for a shopping list, not recipes') and documents the no-stores fallback mode. It doesn't name a sibling alternative or state when *not* to reach for this over search_deals, so it stops short of the top band.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful behavioral context by spelling out exactly what is returned: maker specs, test/buyer verdicts with score and source, facts, and today's promotions with links.

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 core operation ('One model from a buying guide in full') and then lists contents. It is information-rich with little waste, though the parenthetical enumeration is slightly crowded.

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 full burden of explaining return contents, and it does so thoroughly by naming specs, evaluations, facts, and promotions with links. An agent has enough to decide whether the returned detail meets its need.

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 schema's model parameter description already gives examples and notes that the id from get_buying_guide is accepted. The description adds no parameter-level detail beyond the schema, so 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: fetch one model from a buying guide, and enumerates its contents. It is clear what the tool returns, though it does not explicitly name get_buying_guide as the alternative for whole-guide retrieval.

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 phrase 'One model from a buying guide' implies this is the detail lookup compared with get_buying_guide, but there is no explicit when-to-use or when-not-to-use guidance. Usage is inferable rather than stated.

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, idempotent, non-destructive, closed-world), so the description earns credit for adding what they don't: results are dealio-written two-to-three-sentence summaries with their own headline, source attribution and article link, ordered newest first. It stops short of stating any rate limits or how paging terminates, but the return-shape disclosure is genuinely additive.

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 resource and content scope before filtering details. The first sentence is a long comma-run that carries a lot at once, but every clause (content types, summary format, ordering) contributes information.

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 specifies what a returned item contains — headline, summary, source, article link, dealio link and named store pages — so an agent knows what it can cite. Pagination semantics are only implied through the schema's offset, which is the main remaining 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 description coverage is 100%, including the store name-or-slug example and the theme enum, so the baseline is 3. The description's only parameter statement ('Filter by store (name or slug) or theme') restates the schema rather than adding semantics for q, limit, or offset.

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 line 'Belgian consumer news ... prices, promotions, store openings and incidents, product recalls, tests, taxes and energy' names the exact resource and content domain, and nothing in the sibling list (deals, campaigns, stores, meal ideas) overlaps with it. An agent can tell instantly this is the news-retrieval tool rather than a pricing or store lookup.

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 closing 'Filter by store (name or slug) or theme' implies how to narrow results and the 'for people who want to save' framing hints at the audience, but there is no explicit when-to-use guidance, no when-not, and no routing to siblings such as search_deals or get_buying_guide when a user actually wants promotions rather than news coverage of them.

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 readOnly, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds useful behavior: unknown ids are reported and left out, and the output is a shareable page URL. One flaw: it says '2 to 30' ids while the schema allows minItems 1, an internal inconsistency that could mislead, though it does not contradict 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 core purpose is front-loaded in the opening clause and the rest is a compact sentence covering ordering, title, id source and edge-case handling. It is slightly run-on with the parenthetical URL example and duplicated range information, but no sentence 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 only two parameters, no output schema and full schema coverage, the description supplies everything an agent needs: what is returned (a list page URL), where the ids come from, the ordering guarantee, and what happens with invalid ids. The only residue is the min-items mismatch, which is a schema/description consistency issue rather than missing context.

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 the baseline is 3, but the description adds value beyond the schema by specifying that ids must come from search_deals, get_deal or get_meal_ideas and that their order is preserved in the output. It reinforces title as optional; the count guidance conflicts slightly with the schema's minItems.

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+resource: it builds one link that opens several promotions together on a dealio.be list page, in the given order, with an optional title. It also clarifies its role relative to siblings by naming search_deals, get_deal and get_meal_ideas as the id sources, so an agent can tell it is an aggregator/builder rather than a lookup.

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 for use: 'for the promotions you propose to the user after one or more searches, so they need not open them one by one', which tells the agent when this is the right call. It also routes id collection to specific sibling tools. There is no explicit 'when not to use' (e.g. a single promotion needing no list link), so it stops short of the top mark.

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 destructiveHint=false, so the safety profile is covered. The description adds useful data-specific context like 'where known' and 'when the store was last fetched,' but does not explain ordering, pagination, or other behavioral details.

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 compact and front-loads the store fields, with a short second sentence for category slugs. The colon-led list is slightly awkward, but no sentence 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 and no parameters, the description carries the burden of explaining return content, and it lists the key store fields plus category slugs. It is largely complete for a simple list tool, though ordering or pagination context is absent.

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 tool has zero parameters, so there are no parameter semantics to document. The baseline for a parameterless tool is 4.

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 establishes that this tool returns store records and enumerates the store fields it includes. It does not distinguish the tool from siblings like get_deal or search_deals, but the resource and scope are still clear.

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 only states what data is returned; it gives no guidance on when to use list_stores versus alternatives such as search_deals or get_deal. Usage is implied by the tool name but not explained.

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 and destructiveHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: the image is 'the same card the site's share button makes', the short link 'counts the click and sends the reader straight to the store's page', and style 'f' only renders when there is a saving. The undefined gap is how the PNG is delivered (returned buffer, URL, or attachment).

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?

Every element mentioned is substantive, but it is delivered as one long comma-spliced sentence with nested parentheticals listing formats and designs, which forces re-reading to separate the returns from the options. Front-loading is present ('One promotion ready to publish elsewhere') but the structure hurts scanability.

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 the return, and it does so thoroughly: image variants, designs, short link behavior, store page, and caption. The one significant omission is whether the card image is returned inline, as a base64 payload, or as a fetchable URL - an agent needs that to actually use the result.

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 the baseline is 3, but the description goes past the enum labels: it names each design in human terms ('Vandaag €x goedkoper' with the price large), maps each size to its channel (feed, story, link preview), and adds a constraint absent from the schema - style f requires a saving - plus the fact that the default style comes from the promotion itself.

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 conveys a specific resource (a shareable promotion card) and enumerates exactly what comes back: a PNG in several formats, a click-counting short link, the store page, and a caption. It is not phrased as a verb+object purpose statement, and it never explicitly contrasts itself with siblings like get_deal, but an agent can tell from the output inventory what the tool is for.

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 closing line 'Use the id from search_deals or get_deal' gives a clear prerequisite and points to the right upstream tools. It says nothing about when not to use it - e.g. whether to call this versus just fetching deal data, or whether repeated calls are expected - so usage is implied rather than fully specified.

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 that this is a read-only, idempotent, non-destructive search. The description adds useful behavioral context by stating that results are best matches and by listing returned fields such as price, discount, validity, and a link. The default-sort phrasing is slightly less precise than the schema's query-dependent default, but overall transparency is good.

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 definition is two sentences, front-loaded with the core action and scope, and every clause contributes useful information. There is no filler or repetition.

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 search tool with nine optional parameters, full schema coverage, and rich annotations, the description provides enough context to use it correctly. It also compensates for the lack of an output schema by naming the key return fields, though it does not mention pagination or the query-dependent default sort.

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 nine parameters are already documented in the input schema. The description adds only high-level meaning such as searching by product, brand, or store and mentions optional filters, without adding syntax or format details 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 gives a clear verb and resource: searching current promotions at Belgian retailers by product, brand, or store. It is easy to distinguish from a single-deal fetch, but it does not explicitly name or contrast with sibling tools such as get_deal or list_stores.

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 implies when to use the tool by stating it searches current promotions with optional filters, but it provides no explicit when-to-use guidance, prerequisites, or alternatives. The schema mentions list_stores for store lookup, but the description itself does not route the agent to sibling tools.

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