search_products

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

Even with readOnlyHint and idempotentHint already present, the description adds substantial behavioral detail beyond the annotations: pagination at 20 tiles per page, grouping of variants, semantics of total_found counting tiles rather than items, and has_more meaning another page exists. It also discloses the per-item fields returned and the recommendation to confirm finalists with get_product. This is rich, honest behavioral disclosure.

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 front-loaded with a clear purpose and then organized into a scannable list of return values, followed by pagination semantics and tool routing. It is longer than minimal, but each sentence carries information; however, some of the per-item return details may be redundant with the existing output schema, which keeps it from a 5.

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 12 parameters with full schema coverage, a detailed output schema, and rich annotations, the description adds the missing contextual glue: how pages and tiles work, what total_found and has_more mean, that variants are merged, and that get_product should be used for finalist confirmation. This is complete enough for an agent to call the tool correctly without further documentation.

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?

The schema already covers 100% of parameters with individual descriptions, so the baseline is 3. The description does not significantly add parameter-specific semantics; it refers generically to sorting, price window, and filters, which map to sort, price_min, price_max, profit_only, and other schema fields, but without new meaning. The output-focused details (total_found, has_more, per-item fields) are behavioral rather than parameter semantics, so the description earns the baseline but not more.

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 the podrygka.ru catalog like the site' and immediately scopes the function to catalog search with pagination, sorting, price window, and filters. It also names a sibling tool, get_product, as the follow-up for finalizing results, which distinguishes it from other tool operations. This makes the purpose unmistakable even without inspecting the 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?

The description gives clear context: it behaves like the site's search, returns tiles with detailed product info, and explicitly says 'Confirm finalists with get_product,' which routes the agent to the right follow-up. It does not enumerate when to avoid this tool in favor of compare_products or list_stores, but the primary search role and the get_product handoff are clearly conveyed.

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