diadoc_fetch_all

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

Annotations already cover the safety profile (readOnlyHint), so the description's job is to add behavior — and it does: it handles offset, last_id, cursor (Ozon v4/v5), page and WB lastChangeDate styles, manages cursor fields itself, and caps results at max_items (default 10000) with a 'truncated' flag. That is substantive context an agent would not get from annotations alone, though it doesn't discuss rate limits or partial-failure behavior mid-pagination.

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?

Front-loads the core behavior in sentence one, then mechanism, then a clean Args list and a compact Returns line — no filler. The Args block slightly restates names the schema already carries, but overall it is tight and well ordered.

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 an output schema present and a Returns line naming {ok, items, total_fetched, pages_fetched, truncated}, return semantics are well covered. For a 7-parameter tool spanning multiple pagination conventions, the description addresses purpose, parameters, and outputs adequately, though deeper guidance on edge cases (e.g., what happens when the endpoint is not paginated) is absent.

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 the burden — and its Args block defines all seven parameters: operation_id (must come from the catalog), query/body/path_values as base params with cursor fields managed, items_path as an override, limit as page size, and max_items as a hard cap. The query/body/path_values group is glossed in a single line, so it isn't fully exhaustive.

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 first sentence states a specific verb+resource+scope: 'Auto-paginate a read endpoint and return every row in one response.' An agent immediately understands this fetches the full result set rather than one page. It does not explicitly name or contrast with sibling tools like diadoc_call_method/diadoc_call_raw, so it stops short of the top band.

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?

Usage is implied: it is for 'a read endpoint from the catalog' when you want all rows, and max_items is framed as protecting context. But there is no explicit when-to-use/when-not guidance and no direction on choosing this over diadoc_call_method or diadoc_call_raw, so the agent must infer the routing.

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