avito_search_ads

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: it returns two streams (35 main + 3 premium) plus details and continuation cursors, and it discloses the constraint that filters/sort must remain unchanged during a continuation. That is meaningful context beyond the annotations, but it omits rate limits or failure 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 sentences, front-loaded with purpose then return shape then the continuation rule. No filler. It is dense but each sentence adds a distinct fact, so only minor trimming is possible.

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?

For a 23-parameter, heavily nested search tool with no output schema, the description explains what is returned (two streams, details, cursors) and the pagination contract, which is the most important omission. But the large low-coverage filter surface (category params, location IDs, boolean flags) is left largely unexplained in both description and schema, so completeness is only adequate.

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 26% across 23 parameters, so the schema does not carry the full burden. The description names the parameter families (texte, catégorie, type, prix, filtres, tri, pagination par curseurs), giving useful mapping, but it does not explain the nested params/listMatch/rangeMatch/singleMatch structure or how cursor fields relate to responses. Partial compensation warrants a 3.

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 (Rechercher) and resource (annonces publiques Avito) with scope ('sans connexion'), which implicitly separates it from account-based siblings like avito_search_my_ads. It also enumerates the main input dimensions, so an agent can tell what it does. It stops short of explicitly naming the sibling it differs from, so not a 5.

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?

'Sans connexion' implies it works without authentication, and the closing sentence gives a real usage rule (filters/sort must stay identical across continuations). However, there is no explicit when-to-use-vs-alternative guidance, e.g. pointing to avito_autocomplete_search for obtaining categoryId or to avito_search_my_ads for private listings. Usage is implied rather than stated.

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