search_products

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains the tool's output structure (product cards with pricing, rating, badges, etc.) and the behavior of key parameters, such as sort ordering and min_rating semantics. It does not cover rate limits, error handling, or side effects, but those are less critical for a search operation.

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 organized into a purpose sentence, an output-shape sentence, and parameter semantics with examples. It front-loads the most important information and each sentence earns its place, though it is a little longer than strictly necessary.

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?

An output schema is present, and the description still goes beyond it by explaining card fields and parameter behavior. It covers the ambiguous parameters and connects to list_search_filters. Missing pieces like pagination semantics and no-result behavior are minor and do not block correct invocation.

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 add parameter meaning. It does so for the non-obvious parameters: sort lists all allowed values, min_rating is defined as '4★ & above', brands is exemplified as a JSON array, and extra_facets gets concrete raw-parameter examples. Self-evident parameters like max_price and page 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?

The description opens with 'Search Flipkart and return live product cards' – a specific verb, target marketplace, and output type. This clearly distinguishes it from direct alternatives like amazon_search and from single-product/compare tools like get_product and compare_products. The enumeration of card fields further removes ambiguity.

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 establishes the core use case (searching Flipkart products) and refers to list_search_filters as a source of raw facets, which is a hint at a related workflow. However, it never explicitly states when to prefer this tool over siblings such as get_product, compare_products, or amazon_search, leaving routing to inference.

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