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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description goes beyond them by explaining that the server re-loads full current product data by id, that cards carry a link to all matching results, and that ids must be passed through unchanged (i.e. passed-through product objects are reloaded, not trusted verbatim). It does not cover failure modes, such as what happens with an unknown or out-of-stock id, or any limits beyond the schema's maxItems.

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 action first, then the id-sourcing rule, then the optional link parameter. Dense with em-dashes and parentheses but every clause carries information; only the parenthetical about other tools' cards could be trimmed and it still earns its place as a disambiguator.

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?

The tool renders UI rather than returning plain data, and the description makes that rendering behavior and the server-side data reload explicit; an output schema exists so return values need no explanation, and required-parameter count is zero so the agent isn't blocked on missing inputs. Nothing an agent needs in order to call this correctly 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?

Schema description coverage is 100%, so the baseline would be 3, but the description adds real meaning: it explains where `ids` should come from ('each product line shows `id …`' in another tool's results) and what `search_query` actually does (adds a 'see all results' link). It says nothing about the `title` heading or the `products` pass-through alternative, both of which are left to 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?

States a specific verb and concrete result: display a hand-picked product set as interactive product cards in the chat. It also pre-empts confusion by noting that search, price-drop and sale results already render cards on their own, so an agent can distinguish this from search_products and top_price_drops 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?

Explicit about when to use it (a hand-picked subset the agent chose from another tool's output) and when not to (cases that already render cards automatically). It adds a hard constraint — 'Do not invent products' — so the agent knows ids must originate from prior tool results rather than being synthesized.

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