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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is covered. The description adds a genuinely non-obvious behavioral trait: brand matching is case-sensitive against source data and must not be normalised. It doesn't mention pagination or result-size behavior, but the casing warning is real added value.

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 front-loaded sentences with the core purpose stated first and the casing caveat second. Nearly every clause earns its place, though 'keep the brand as the user wrote it and do not normalise it' restates the same idea twice.

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 3-parameter read tool with no output schema but rich annotations, the description covers the purpose and the trickiest parameter caveat. It omits the unknown valid values for promotion_type (no enums in the schema) and any indication of result ordering or pagination, leaving moderate 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%: 'limit' and 'promotion_type' are described in the schema, but 'brand' is not. The description compensates for the undocumented 'brand' parameter with critical case-sensitivity semantics, which is more than the schema offers. However it says nothing about limit defaults or valid promotion_type values, so it only partially fills the gap.

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

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

The description states a specific verb and resource: 'Every current deal for one brand', with concrete examples (Coca-Cola, Ahold). It implicitly separates itself from pp_get_deals_by_type by scoping to a single brand, but never names or contrasts with its many siblings.

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

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

Usage is implied by the purpose — call it to retrieve deals for one brand — but there is no explicit when-to-use or when-not guidance relative to siblings like pp_get_new_deals, pp_get_popular_deals or pp_get_top_deals. The casing instruction is a usage hint for the parameter rather than tool-selection 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 already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered structurally. The description adds non-obvious behavioral context beyond that: the call is cheap and its typical outcome is a mapping from natural-language terms to slug values, which tells the agent it is a cheap prerequisite lookup rather than a result-producing query.

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 returns and then the usage instruction, with no repetition of the title or schema. The closing clause ('Cheap, and worth it before a search that would otherwise return nothing') is slightly persuasive rather than informational but still carries real decision value.

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

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

No output schema exists, so the description usefully enumerates the fields returned (Dutch display names, product counts, group) and the slug-oriented purpose, which is enough to call it correctly. It stops short of describing the response container or how to map a returned row to a `category` slug value.

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 takes zero parameters and the schema is a closed empty object, so there is nothing parameter-wise to document; the baseline for no-params tools applies. The description correctly implies no input is needed, though it never literally says callers pass nothing.

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 the exact resource returned (unified categories with Dutch display names, product counts and group) and pairs it with a named sibling relationship ('Call this before `pp_search`'), so the agent can distinguish it from the many pp_get_* deal/list tools 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?

Explicit when-to-use: call this before pp_search to translate a user's informal word ('zuivel', 'brood') into a valid `category` slug. It also gives the failure condition it prevents (a search that would otherwise return nothing), which is exactly the routing guidance an agent needs.

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, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds no further behavioral context beyond the parameter mapping — nothing about result volume, ordering, or whether unknown keywords yield empty results versus an 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 purpose and then immediately the parameter mapping. Every clause earns its place; density is high but nothing is padded.

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 a 100% schema coverage, a limit default documented in the schema, and annotations covering safety, the main gap the description had to fill was the keyword-to-internal-name translation, and it does so. The absence of an output schema means return shape is unexplained, but for a simple list tool this is a minor omission.

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 description adds real meaning beyond the schema: it explains that the 'type' input is a promotion keyword like '1+1' or 'korting', and supplies the mapping to the internal names (percentage, multi_buy, one_plus_one, volume, limited, starting) used by promotion_type elsewhere. That translation layer is genuinely useful input guidance, though 'korting' is not tied to a specific internal name.

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 clear resource and filter: 'Deals for one promotion mechanic,' which tells an agent this returns deals scoped to a promotion type. It stops short of differentiating itself from siblings like pp_get_new_deals, pp_get_popular_deals, or pp_get_top_deals, which also return deals under different filters.

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 agent can infer this is the tool to call when it has a promotion keyword such as '1+1' or 'korting' rather than wanting new, popular, or top deals. There is no explicit when-to-use statement, no named alternative, and no exclusion criteria despite a crowded sibling set.

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 open-world, so the safety profile is covered. The description adds genuinely new context: it is cheap, and it is intended as a freshness gate before reporting. It does not describe latency, rate limits, or the exact freshness semantics, keeping it from 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 tight sentences with no filler. The return contents come first, then the operational use case, which is the right front-loading for an agent deciding whether to call it.

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 describing the return value, and it enumerates the four key aggregate fields. For a zero-parameter summary tool, nothing an agent needs to call it correctly 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 tool takes zero parameters, so there is nothing for the description to disambiguate about inputs. Baseline for a no-parameter tool is 4, and the description introduces no misleading parameter behavior.

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 resource ('Aggregate stats') and enumerates exactly what is returned: total products, retailer count, biggest discount, last update. This sets it apart from listing tools like pp_get_top_deals or pp_get_deals_by_type. It stops short of explicitly naming a sibling it replaces, so not quite 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?

It states a concrete situation for calling it: a 'cheap call to check that the data is fresh before reporting anything about this week.' That is real when-to-use guidance tied to a workflow. No exclusions or named alternatives (e.g. pp_health_check) are given, so it falls short of a 5.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the meaningful behavioral detail that counts are scoped to a query when `q` is supplied, but says nothing about the unscoped (no-q) behavior, result volume, 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?

Two sentences, purpose first and usage second, with no filler. The em-dash clause is slightly dense but it carries real routing information (previewing filters, existence checks), so it earns its space.

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

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

All six parameters are optional and there is no output schema, so the description's job is to convey the calling pattern and it does: the primary facet-count result plus the query-scoped variant. It could state what an unfiltered call returns, but nothing critical to correct invocation 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 each of the six parameters is already documented in the schema. The description only elaborates on `q` and `category`, leaving retailer, dietary, private_label and promotion_status to the schema — the baseline 3 for a fully-covered schema 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?

Opens with a concrete noun phrase ('Facet counts per retailer, promotion status and category') that names the resource and the dimensions returned, so the agent knows this is a statistics/facet endpoint rather than a product list. It does not explicitly distinguish itself from nearby siblings such as pp_get_categories or pp_get_deals_summary, which keeps it from a 5.

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

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

The second sentence gives concrete when-to-use guidance: pass `q` (and optionally `category`) for a specific search, to preview what a filter would still return, or to validate that a category exists before searching it. It stops short of naming an alternative tool or stating when NOT to use 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the 30-row cap, a useful behavioral constraint, but it duplicates the schema's maximum:30 and says nothing about ordering, freshness window, or pagination.

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

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

A single short sentence, front-loaded with the key qualifier. It earns its place but is arguably too terse for a tool with 19 siblings, leaving ordering and semantics underspecified.

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 read-only list tool with full annotation coverage and no output schema, the description is minimally adequate. It does not explain the return record shape or the ordering key ('recently started' by what metric), which would help an agent use the results 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% for the single limit parameter, so the schema fully documents it, including the default of 10 and the max of 30. The description adds nothing beyond what structured fields already provide, making the baseline 3 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?

The description names the resource (offers/deals) with a temporal qualifier, 'most recently started,' which gives some sense of the ordering. However it uses 'offers' while the tool and siblings use 'deals,' and it never distinguishes itself from close siblings like pp_get_top_deals or pp_get_popular_deals. An agent would have to guess which 'get deals' variant to pick.

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 use this tool versus the many sibling deal tools (by_type, popular, summary, top, brand). No prerequisites, no exclusions, no alternative routing. The agent is left to 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 cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds useful behavioral detail: it requires a valid partner key and returns 401 when the server lacks one. This auth requirement and failure mode go beyond the structured annotations, though broader return behavior is not described.

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 tightly written sentences with the primary purpose stated first and the prerequisite second. There is no filler or redundant restatement of structured data.

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 zero-parameter, read-only tool with rich annotations and no output schema, the description provides what an agent needs: what it returns, the key prerequisite, and the failure condition. No critical context 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 tool takes zero parameters, so there are no parameter semantics to document. The baseline for zero-param tools is 4, and the description does not need to compensate for any schema coverage gap.

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

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

The description states a specific return payload (rate-limit usage and account info) scoped to the configured API key, which is clear enough for an agent to know what the tool retrieves. It does not explicitly differentiate from any sibling tool, but the resource is distinct enough in context.

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

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

The description gives a prerequisite (requires a valid partner key) and a failure mode (401 without one), which implies the tool should only be called when a partner key is available. However, it does not state when to choose this tool over alternatives or provide broader usage context.

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 behavior, so the safety burden is covered. The description adds real context beyond that: the ranking signal (user clicks) and the hard 30-row cap. It does not describe ordering ties or fields returned, but that is a minor omission.

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 sentence with zero filler, leading with the ranking criterion and ending with the size constraint. Nothing needs to be cut or reordered.

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 is the only source of return-value information; it communicates row count but not the shape of a deal record. Combined with the unaddressed overlap with pp_get_top_deals, it is barely sufficient for a single-parameter read 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 100% and the schema states the 1-30 bounds and the default of 10, so the description has little room to add value. Its phrase 'capped at 30 rows' merely echoes the schema maximum, and it does not explain how limit interacts with the ranking.

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 defines the resource by its ranking criterion ('deals users click most often'), which is more meaningful than a bare restatement of the name. However, it gives no differentiation from pp_get_top_deals, a sibling that sounds functionally identical, so an agent cannot confidently choose between them.

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 statement of prerequisites, and no named alternative. With a near-duplicate sibling (pp_get_top_deals) in the toolset, the absence of routing guidance is a real gap.

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 open-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: a missing forecast still returns HTTP 200 with a null body and the reason in the X-Forecast-Reason header. That is real value beyond the structured fields.

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, each carrying distinct information: what the tool does, the null-not-error contract, and the anti-retry instruction. Front-loaded and free of 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?

No output schema exists, and the description covers the one surprising return case (null forecast plus reason header) that an agent would otherwise mishandle. It does not describe the shape of a successful forecast, which is a minor remaining gap for a read 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 0% and the single parameter has no description in the schema. The description says the forecast is for 'one product', which maps loosely to product_id, but adds no format, ID namespace, or validity detail to compensate for the coverage gap.

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

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

States a specific verb and resource: 'Server-side backtested price forecast for one product'. The domain (price forecasting) is clearly distinct from the deals/products/categories siblings, though the description never names an adjacent tool to differentiate against.

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-vs-alternative guidance, but the description does give one actionable usage rule: a null forecast is not an error and should not be retried. That covers the edge case but leaves the general call context implied.

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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds value beyond them by disclosing the shape of the returned detail (EAN, folder, promo group, dietary labels) for a tool with no output schema, though it says nothing about missing-product or rate-limit 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?

Two sentences, no filler, with the purpose front-loaded and the parameter-provenance note second. 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?

For a one-parameter read tool whose annotations already carry the safety profile and whose only parameter is explained, the description is sufficient to call it correctly. Omitting full return-field enumeration is acceptable given the tool's simplicity.

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

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

Schema description coverage is 0% and the single parameter is documented only as a bare string type, so the description must compensate. It does so by explaining the provenance of product_id ('the product_id field from any search or list result'), which tells the agent where to obtain a valid value, though not its format.

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 (full detail for one product) and enumerates the kind of content returned (EAN, folder, promo group, dietary labels). The singular 'one product' implicitly separates it from the plural list/search siblings such as pp_list_products and pp_search_products_by_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?

The second sentence establishes the precondition for calling it: product_id comes from any search or list result, which routes the agent from the search/list siblings into this detail tool. It stops short of explicitly naming alternatives or a when-not-to-use case, so it does not reach 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description contributes non-obvious behavioral context: the 1000-item page ceiling is expensive in context and rate limit, which is operational knowledge not present in the 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?

Two tightly written sentences, front-loaded with the purpose before the parameter advice; every clause earns its place. Slightly informal phrasing ('a big page is expensive in context and in rate limit') keeps it from being maximally crisp.

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 3-parameter read tool with annotations covering safety, this is largely sufficient. However, with no output schema there is no statement of what a product record contains, how pagination continuation is detected, or whether results are ordered, which a list tool should disclose.

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% (page and page_size have descriptions). The description adds real meaning beyond the schema: it explains that `folder_id` corresponds to the `folder_id` field on a product (i.e., where to obtain it) and warns that a large `page_size` costs context and rate-limit budget. Only `page` remains undocumented.

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

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

States a specific verb+resource (all products) scoped to a single promotional folder, and clarifies the domain term 'actie' as 'folder'. It does not explicitly contrast itself with close siblings such as pp_get_products_by_retailer or pp_list_products, 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 description gives practical sizing advice ('ask for what the question needs') but never states when to choose this tool over pp_get_products_by_retailer, pp_list_products, or pp_get_promotional_products. Usage is implied by the folder scope 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description is freed to add the details annotations cannot: that results are paginated and that the key must be a slug. No rate limits or ordering behavior are disclosed, but the added correctness detail is real.

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, zero filler, front-loaded with what the tool returns before the parameter caveat. 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?

For a simple read-only paginated listing with no output schema, the description covers result scope, identifier format, and pagination. It lacks any indication of ordering or how this fits among the many other product/deal siblings, which 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?

Schema coverage is only 67%, and the required 'retailer' param has no schema description and no enum. The description compensates by enumerating the ten valid slugs and warning it is a slug, not a display name — meaning an agent could construct a valid call without guessing. This is exactly the value the schema omits.

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 with scope: 'Every product from one retailer, paginated.' This is distinguishable from generic siblings like pp_list_products or pp_search_products_by_name because the retailer scoping is explicit. It stops short of naming which sibling to use instead when no retailer filter is wanted.

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 implied by 'from one retailer' — call it when you want everything for a single retailer — but there is no explicit when-to-use/when-not guidance and no alternative sibling is named (e.g., pp_list_products for a cross-retailer listing). Implied 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral trait beyond that: results are returned 'newest first' and unfiltered by default. It says nothing about pagination behavior or result size, so the added value is modest given the annotation coverage.

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 short sentences with zero filler; the scope and sort order are front-loaded, and the routing guidance follows immediately. 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?

For a read-only listing tool backed by four annotations and a fully documented five-parameter schema, the description supplies what an agent needs to select and call it. The only omission is any hint of the result shape, which is not covered by an output schema, but that is a minor gap for a list endpoint.

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 (page, page_size, retailer, min_valid_from, max_valid_from) are already documented in the schema, including date formats. The description adds no parameter-level 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?

The description clearly states the resource and scope: 'Everything currently on offer, newest first,' which tells an agent this is an unfiltered listing of promotional products ordered by recency. It also explicitly distinguishes itself from the sibling pp_list_products for the filtered case. The main verb is implicit rather than stated, keeping it just 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?

It names a concrete alternative and the condition that selects it: use pp_list_products with is_promotional=true when you also need a filter. That is clear when-to-use-routing. However, it ignores the many other deal-oriented siblings (pp_get_new_deals, pp_get_top_deals, pp_get_brand_deals, pp_get_deals_by_type), so an agent must still guess how this differs from those.

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, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral detail beyond that: ordering ('newest first') and the fact that the return is a quantitative availability figure rather than a qualitative status.

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, purpose front-loaded, no wasted preamble. 'Instead of a guess' is slightly colorful but succinctly conveys the tool returns hard numbers, so it largely 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?

For a simple read-only tool with one fully-documented optional parameter and rich annotations, the description covers what it returns (monthly availability, newest first) adequately. Without an output schema there is minor ambiguity about exact return format, but nothing critical to correct invocation 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 'months' parameter is fully documented there, including its default. The description's 'per calendar month' hints at granularity but adds no new parameter meaning, so 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?

States a specific resource and granularity: availability/SLA per calendar month, ordered newest first. It's clearly distinguishable from the deal/product siblings, which are all unrelated domains. The verb is implicit ('get SLA summary') 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?

The scenario 'was the API down last Tuesday?' implies the appropriate usage context. However, there is no explicit when-not guidance and no named alternative sibling, leaving usage 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — the min_savings default of 10%, which is absent from the schema — but says nothing about return format, ordering, or list size 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?

Two sentences, front-loaded with the core purpose and free of filler. The retailer-array sentence partially duplicates the schema text, slightly reducing density but not enough to hurt readability.

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 zero-required-parameter read tool with no output schema and full annotation coverage, the description is adequate: it defines scope, grouping, and the key default. It could say more about what a 'list' contains or how many lists are returned, but nothing essential to 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%, so limit, retailer, and min_savings are already documented in the schema. The description adds the non-schema default value for min_savings and reinforces the array semantics, but the passing syntax it describes is already spelled out in the schema's retailer 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?

States a specific verb+resource ('Top deals grouped per brand') and a clear scope modifier (optionally narrowed to retailers). It is distinguishable from pp_get_new_deals and pp_get_popular_deals by the brand grouping, though it does not explicitly contrast itself with the similarly-named pp_get_brand_deals sibling.

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 actionable tuning guidance ('raise min_savings to cut the noise') and how to scope by retailer, which is usable context. However, it never states when to prefer this over the many sibling deal-listing tools (new_deals, popular_deals, deals_by_type), so alternative selection 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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: it is a diagnostic probe whose meaning depends on other calls failing with 5xx. It does not state what a successful or failed check returns, a minor gap given there is no output 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?

Two short sentences, action first and trigger second, with no filler. 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?

For a parameterless read-only probe the description is nearly sufficient: purpose and trigger are both covered. The one omission is what the result looks like (reachable vs. unreachable signal), which matters slightly because no output schema exists.

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?

Zero parameters, so the baseline is 4; there is nothing for the description to explain. Schema coverage is 100% and the empty object schema is self-evident.

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: 'Check that the PrijsProfeet API is reachable.' This cleanly separates it from all sibling tools, which are data-fetching operations, so an agent can identify it as the diagnostic probe without opening the schema.

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

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

Explicitly names the trigger condition ('when another tool returns 5xx') and the decision it informs ('tell an outage apart from a bad request'). This is a rare case of precise when-to-use routing rather than generic 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 already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: the default sort order, and that promo_group_id returns every participant of one shared action and can be read off a product to expand its group. It does not mention pagination behavior, the one trait annotations leave untouched.

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 paragraphs, front-loaded with the core action and default ordering, followed by routing and then the two non-obvious parameters. No filler sentences.

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 12 optional filter parameters and no output schema, the description covers the non-obvious filters (promo group, validity window) and the default sort. Price, name and page filters are self-documented at 100% coverage, and return values need no explanation without an output schema, so this is nearly complete for a filtering list 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 100%, so the baseline is 3, but the description adds semantics the schema alone does not convey in English: min_valid_from/max_valid_from bound the promotion start date, and promo_group_id is described as a cross-call linking key. That is meaningful added value rather than restatement.

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 ("List products") plus the default ordering ("newest extraction first"), and explicitly names the sibling it is not (pp_search). An agent can distinguish it from the search tool 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 an explicit routing rule: use pp_search when the user named a product, use this tool to enumerate by retailer, folder, promo group or validity window. However, it never acknowledges the overlapping siblings pp_get_products_by_folder, pp_get_products_by_retailer, pp_get_promotional_products, leaving an agent unsure whether those are preferred for the same enumerations.

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?

Goes well beyond annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) by disclosing that the key is never returned, that the response is deliberately identical regardless of prior key existence (anti-enumeration), the 5/hr/IP cap, and the real-world email side effect. Rich, non-obvious disclosure.

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

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

Four tight sentences, each carrying distinct information, with the core purpose front-loaded and the safety caveat last. 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?

With no output schema and full param coverage, the description supplies everything else needed: return behavior (key absent, uniform response), rate limits, and the human-impact caveat. Nothing an agent needs to call this correctly 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 are already documented in the schema. The description adds no syntax or format detail beyond that, so the 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+resource ('request a free API key') and immediately clarifies the mechanism (a link is emailed, not the key). It is trivially distinguishable from all siblings, which are read-only deal/product lookup tools.

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 an explicit precondition: 'Only call it when the user has explicitly asked for it in this conversation,' plus context about the rate cap and the real-world side effect. This is exactly the when-to-use guidance an agent needs for a side-effecting tool.

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, openWorld), and the description layers substantial non-obvious behavior on top: the meaning of each `promotion_status` value, the fact that historical prices can be up to 60 days old and that the lowest row price may be one nobody is charging today, plus the caveat that Lidl and Vomar carry no rows under `private_label` rather than a guessed brand signal. This is real behavioral disclosure, not restatement.

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 front-loaded — purpose and browse semantics come first, then row interpretation, then slug/paging logistics. Each sentence carries actionable content (slug lists, status meanings, paging advice) and there is no filler or restatement of the name.

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 14-parameter, annotation-covered search with no output schema, the description does the heavy lifting on how to interpret a returned row and how to page. It stops short of describing the response shape or its fields beyond price and promotion_status, which is the one gap an agent composing a query could notice.

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 schema already documents every parameter and the baseline would be 3. The description still adds meaning the schema lacks: the full ten-retailer slug list (the schema only shows four), the paging strategy, and the interpretation of `promotion_status` during price comparisons. It loses a point because the status values it describes (`active`, `upcoming`, `shelf`, `historical`) do not match the schema's enum (`active`, `upcoming`, `expired`), which could confuse a caller about valid filter inputs.

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 gives a specific verb and resource ('Search supermarket offers') and scopes it to the 10 named Dutch chains, so the agent immediately knows what the tool does. It does not, however, differentiate itself from overlapping siblings such as pp_get_promotional_products, pp_get_top_deals or pp_search_products_by_name, which an agent must infer from naming alone.

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?

Explicit when-to-use guidance is given for the main knobs: omit `q` or pass `*` to browse the whole catalogue, call `pp_get_categories` first because category slugs are not free text, and keep `page_size` modest and page through instead of asking for 100 rows. It also provides an explicit warning about filtering on `promotion_status` before quoting a best price, which is exactly the kind of conditional guidance that prevents wrong tool output.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine capability context beyond them: fewer filters and no sorting relative to pp_search. It does not describe pagination behavior, but with annotations carrying the safety burden this is a solid addition.

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 short sentences, zero waste, with the core behavior front-loaded and the deprecation-style guidance following immediately.

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 four-parameter read-only search with no output schema, the description covers purpose and routing adequately. It leaves pagination/return shape unstated, which is a minor gap given the schema fields are self-explanatory.

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%, so page, page_size and retailer are already documented in the schema. The description's 'term inside the URL path' adds a hint about how query is used but nothing beyond what the schema provides for the other three parameters. Baseline 3 applies when the schema does most of the work.

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) and resource (products), plus a precise mechanism ('term inside the URL path'). It also names the sibling pp_search and how this differs, so the agent can distinguish it without opening schemas.

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

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

Explicitly routes the agent: 'Prefer `pp_search` for new work,' and characterizes this tool as the older sibling with fewer filters and no sorting. Both the when-to-use and the when-not-to-use conditions are stated.

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