search_listings

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

Annotations cover the safety profile, and the description adds substantial behavior the agent could not infer: exactly one site page per call (up to 50 listings), the returned fields (asking prices, links, seller ratings, snippet text, lexical hardware signals), and the crucial caveat that total_found is counted BEFORE local filters. It also flags that price/sort/seller filters are validated against the site's own controls, which explains silent filter degradation.

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?

Dense and front-loaded: category and default city come first, return shape and caveats follow. A few lines are compressed into run-ons ('Includes new/used/unknown') but no sentence is 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, 9 parameters and 0% schema coverage, the description supplies the return-value and filter-caveat information that would otherwise be missing. Remaining gaps are query-syntax expectations, pagination limits beyond `page`, and failure/empty-result behavior for an open-world scraper.

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 carry parameter meaning, and it does for most: city default, price window, sort, seller filter, and especially local_only (filters by listing URL city) and total_found semantics that the schema never explains. It does not clarify `page` behavior or the interplay between `limit` and the stated 'up to 50 listings' cap.

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 Avito's computer-goods category') plus the default scope (Екатеринбург) and category boundary, which implicitly separates it from search_used_parts. It also names the follow-up sibling get_listing, so an agent can place the tool in the workflow without opening a sibling 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 an explicit handoff rule ('Use get_listing to confirm condition and health claims') and explains that local_only/total_found interact in a non-obvious way. It never states when to prefer search_used_parts or compare_listings, so the alternative selection is left to inference.

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