Vyhledat akční produkty na Kupi.cz

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

The annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavior beyond that: it discloses the source type (public server-rendered HTML), default date semantics, automatic packaging-term separation, match.confidence/match.quality output fields, and the important caveat that results reflect data location, not stock availability. There is 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?

Five dense sentences are ordered well: search source, default date behavior, query handling, match metadata, and the key limitation. Each sentence earns its place and there is no repeated schema information or 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?

Despite 10 parameters and only 30% schema coverage, the description explains the tool's core behavior, defaults, query nuance, output metadata, and a crucial non-goal (stock confirmation); an output schema exists for return semantics. It falls short only on full parameter guidance and explicit sibling routing, but it is still largely complete for correct high-level use.

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 30%, so the description carries a heavy burden for parameter meaning. It adds some value by explaining that packaging details in the query are separated automatically, but it does not address limit, sortBy, stores, location, onlyOnSale, excludeMembershipOnly, or other parameters. Most parameter semantics remain undocumented in both the schema and the description.

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 names a concrete action ('Vyhledá nabídky') and a precise target ('veřejném server-renderovaném HTML Kupi.cz'), with the title further scoping it to 'akční produkty na Kupi.cz'. This clearly differentiates the tool from offer-lookup and shopping-list comparison siblings even without naming them.

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 provides useful behavioral caveats: it defaults to today's deals, does not present future deals as current, and is not a stock-availability confirmation. However, it never explicitly tells the agent when to choose search_products over get_product_offers or compare_shopping_list; usage is only implied through purpose and caveats.

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