Search products

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds a genuinely non-obvious behavioral rule beyond structured data: a multi-word query must match as a phrase in the title, unlike bn_find_cheapest. It stops short of describing result-set size, total counts, or empty-result behavior.

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 tight sentences, front-loaded with purpose, then usage, then routing. Every clause carries information — the phrase-matching caveat and the sibling handoffs are the kind of detail that prevents mis-invocation rather than filler.

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?

With no output schema, the description does name the returned attributes (ids, price, stock, rating), which is the key missing piece an agent needs. It does not cover pagination behavior in general or how to tell when results are exhausted, a minor gap for a 7-parameter 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%, so the baseline is 3 and the schema already documents page/limit/sort/price bounds. The description earns above baseline by explaining query matching semantics (phrase-in-title, Persian or English) and currency units (Toman), which the schema only partially conveys.

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?

States a specific verb and resource ('Search Baneh products by name in Persian or English'), names the fields returned (price in Toman, stock, rating), and explicitly distinguishes itself from siblings bn_find_cheapest and bn_product. An agent can route to this tool without opening any 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?

Gives explicit when-to-use ('Use to find products and their ids') plus two named alternatives with the condition that selects each: bn_find_cheapest for lowest price with order-free word matching, bn_product for a single id. The phrase-match constraint is also flagged as a reason to prefer the sibling.

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