search_catalog_offers

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

With no annotations, the description carries the burden and does well: it discloses the default validity-window filtering, the key-tier scoping (self-serve sees only published campaign offers; everyday shelf prices are Salling-only and partner-restricted), and that results carry chainId requiring resolution. Gaps remain around pagination and rate/limit behavior, though limit/cursor exist in the 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?

Four dense sentences, front-loaded with what the tool returns and the default validity behavior, then constraints, then the chainId resolution tip. No filler and nothing repeated from structured fields unnecessarily.

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

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

Given six optional params, no output schema, and no annotations, the description covers the important hidden context: validity defaults, key-tier access limits, and chainId resolution. It omits pagination mechanics and any hint about result shape, which leaves a small but real gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the chain/product/EAN filter trio that the schema already documents, but it does add genuine nuance that include_expired governs whether past-validity offers appear. That is incremental value, not a full semantic expansion.

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 plus resource with scope ('Search catalog offers (promotions and listed products) from Danish retail chains') and states the default validity filter. It does not explicitly distinguish itself from close siblings such as find_cheapest_offers or search_products, so an agent still has to infer which search surface 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?

It sets clear usage context: default excludes expired offers unless include_expired is set, and it tells the agent to resolve chainId names via list_chains. It also excludes everyday shelf prices for self-serve keys, which is a real usage boundary. It stops short of naming an alternative tool by condition (e.g. when to prefer find_cheapest_offers).

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