market_search_products

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description only needs to add value beyond those. It adds useful behavioral nuance: fuzzy search still needs result validation, explicit depots are required, only one zero-based page is returned, and the market://guide preserves alternatives and exact requirements. No contradiction with annotations.

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 concise at three sentences and front-loads the action with 'Search products and facets.' Each sentence contributes a distinct fact, though the 'market://guide' reference is cryptic and unexplained.

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 17 parameters, 4 required fields, nested objects, and only 41% schema coverage, this description is too thin to fully specify the calling contract. It relies heavily on an external market://guide and does not clarify array filter semantics or the relation between product search and facets. The output schema covers return values, but the input behavior remains under-specified.

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 only 41%, and many filter arrays such as brand, main_category, sub_category, and refined_quantity_unit have no descriptions. The description names only refined_volume_weight and order as examples and refers to 'known API filters', which is a pointer rather than an explanation. It adds meaning for keywords ('fuzzy search') and prerequisites, but does not compensate for the large undocumented parameter space.

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 and resource: 'Search products and facets, one zero-based page,' which immediately conveys what the tool does and its pagination scope. It does not explicitly differentiate itself from sibling tools like market_search_by_category or market_get_product, but the constraints and filter examples make its role reasonably clear.

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 gives clear invocation context: combine keywords with known filters, require explicit location and nonempty depots, and follow market://guide for exact requirements and alternatives. It does not name alternative tools or provide when-not-to-use conditions, but it communicates prerequisites and validation cautions effectively.

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