dl_object_revisions

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

Annotations already declare readOnly, idempotent, and non-destructive, but the description adds genuine behavioral context beyond them: it warns that saved/published flags are not a multi-page snapshot and that absence in limited history cannot prove a write did not apply, which prevents false conclusions. It also discloses that results are a bounded, provider-ordered page.

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 front-loaded sentences lead with the verb and waste little, and the pagination caveat is placed after the core action. The phrasing is dense and jargon-heavy, but each sentence carries functional content.

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 4-parameter, 0%-schema-coverage tool with no output schema and no annotations gap, the description covers pagination and continuity semantics well but omits the shape of a returned revision entry and the page_size bounds. An agent knows how to page but not fully what it will receive.

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 coverage the description must carry all four parameters, and it only clarifies entry_id (known entry), rev_ids (known revision IDs), and page_token (opaque continuation). page_size, its default, and the 1-1000 / maxItems bounds are not addressed, and no value formats are given, so the compensation is incomplete.

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 states a specific verb (Read) and resource (a bounded provider-ordered revision page) scoped to a known entry, which is clearly distinct from siblings like dl_object_get or dl_object_diff. An agent can tell this is the paginated history reader without opening any 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?

It gives one concrete usage rule ('Use the returned opaque continuation unchanged') and implicitly frames rev_ids as an optional restriction, so usage is partly implied. However, it never names when to prefer this over dl_object_get, dl_object_diff, or dl_operation_get, and there are no explicit exclusions.

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