pp_get_promotional_products

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.