diadoc_fetch_all

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

The annotations already indicate readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat safety. It goes beyond any annotations by describing the automation of pagination and the hard cap (max_items) with a default of 10000 to protect context, which is additional useful behavioral detail. It also transparently states that the response is a JSON wrapper with truncation flag, though some of this is in output schema.

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 extremely efficient: a one-sentence summary up front followed by a compact list of parameter semantics. Every sentence adds value, and the formatting is scannable. It does not waste words on fluff or repeat schema information unnecessarily.

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?

Given the tool's complexity (handling multiple pagination styles) and the availability of an output schema, the description provides a complete picture: what it does, how to use it, parameters, and safety cap. It includes important defaults for max_items and limit)Skip to content. An agent has enough to invoke it correctly without ambiguity.

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?

The schema has 0% description coverage, so the description carries a large burden. It explains operation_id (a read endpoint from the catalog), query/body/path_values (base parameters), items_path (override array path), limit (page size), and max_items (hard cap). This adds meaningful semantics beyond the bare parameter names. However, it could have elaborated on the JSON return structure in more detail, but the output schema exists to cover that.

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 clearly states that the tool auto-paginates a read endpoint and returns all rows, with a verb and resource that distinguishes it from other sibling tools like diadoc_get_raw which likely returns single responses. It also mentions the specific pagination styles, giving concrete detail. However, it does not explicitly contrast with siblings, so a slight deduction.

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 explains the tool's purpose well: use it to fetch all rows from read endpoints, while cursor fields are managed automatically. It does not explicitly state when NOT to use it or name alternatives like diadoc_call_method for pagination control, but the context of auto-pagination is clear. The guidance is implied but not exclusionary.

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