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

With no annotations, the description carries the full burden. It clearly states the return behavior ('Returns matching products with wholesale price, image, category and a virtual-proof link') and adds useful context about data scale (70,000+ items, 11,060 with live pages). It doesn't mention side effects or auth, but for a read-only search tool this is sufficient.

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 description is moderately long (4 sentences) but well-structured: it starts with the search purpose, moves to return details, then usage guidance, scale context, and finally synonyms. The synonym list is a bit extensive but adds practical value for matching user phrasing. No fluff or redundancy, so it earns a 4.

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 provides sufficient context for an agent to decide when to use this tool: it explains the search scope, the returned fields, the scale of data, the alternative tool for browsing, and the variety of user terms that map to this catalogue. This covers all necessary decision-making information for a simple search 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 description coverage is 100% (all 7 parameters have descriptions), so the baseline is 3. The description's first sentence lists the filter dimensions but adds no new parameter-level meaning beyond what the schema already provides. Though it gives examples (e.g., 'nike backpack') in the query parameter, that is in the schema, not the tool description, so the description itself adds little parameter insight.

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?

Description clearly states a specific verb ('Search') and a specific resource ('the wholesale catalogue') with explicit filter dimensions (keyword, category, brand, price range, occasion). It also distinguishes itself from the sibling tool get_product_catalog by contrasting search vs. browsing, making the tool's purpose 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 description explicitly says 'Use this for any request to find specific products' and directly contrasts with get_product_catalog ('For browsing the catalogue shape rather than searching it'), providing clear when-to-use guidance and an explicit alternative.

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