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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the safety profile is settled. The description still adds real behavioral value: results are pre-filtered to buyable live stock, USD pricing follows product-page sale rules, and cursor pages can come back short after filtering so has_next_page is the traversal signal. That is exactly the non-obvious behavior expected from a live-inventory search.

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, front-loaded with purpose then the two facts that matter (stock filtering, price rules) before the pagination caveat. No filler, though it could have spent a sentence on parameters instead of none.

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 description covers return semantics (buyable-only, has_next_page, cursor) which partially compensates for the absent output schema, and touches pricing. But for a deeply nested two-parameter search with zero schema descriptions, the unexplained price filter units, the country-context effect, and the required ucp-agent profile leave meaningful 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 description coverage is 0%, so the description must carry parameter meaning and it does not. It never explains that price min/max are integers (units ambiguous — cents vs dollars), that filters.sizes and filters.categories accept up to 5 values, that pagination.limit caps at 10, that address_country drives availability/pricing, or that meta.ucp-agent.profile is a required URI. The agent can only learn these by reading the nested 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 opens with a specific verb+resource: "Search FRW's Prism catalog." That is clear on its own, but it never distinguishes itself from the sibling lookup_catalog or explains how a search result differs from get_product, leaving the agent to guess which retrieval tool 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?

The line "Returns only variants confirmed buyable from live stock" implicitly tells the agent this is for in-stock purchasing flows, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., lookup_catalog for direct lookups). 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.