avito_call_method

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses critical gating behavior: destructive requests are not sent unless both confirm_write and i_understand_this_modifies_data are true, and read/write behaviors are differentiated. It also specifies the success and error envelope, adding real behavioral context that annotations alone do not provide.

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 the core purpose, followed by clear safety rules, a compact argument list, and a return-type statement. The minor repetition of confirmation requirements in both the prose and argument list reinforces important safety conditions without bloating the text.

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 generic catalog dispatcher, the description covers the method catalog source, path/query/body inputs, write/destructive guards, and return envelope. It does not explicitly explain how avito_call_method differs from avito_call_raw or avito_fetch_all, which would make selection more robust, but the core operational details are present.

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?

With 0% schema description coverage, the description must carry the explanatory burden for six parameters. It provides a useful one-line meaning for each parameter, especially explaining operation_id's source and the semantic distinction between confirm_write and i_understand_this_modifies_data. It remains generic for path_values, query, and body, giving no format or example details, but it is sufficient for a flexible dispatcher.

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 'Execute one catalog endpoint by operation_id,' which names a specific verb and resource and clearly identifies the dispatch role of the tool. It implies distinction from siblings like avito_fetch_all and avito_call_raw through 'one' and 'catalog endpoint,' but it does not explicitly contrast itself with those siblings.

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?

It gives practical guidance on when confirmation flags are required: read endpoints run immediately, write endpoints need confirm_write, and destructive endpoints need the extra acknowledgement. However, it does not explicitly state when to choose this tool over avito_call_raw, avito_fetch_all, or other sibling tools; the guidance is about invocation conditions rather than tool selection.

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