Workbooks Get Report Version History

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond annotations by explaining pagination: it follows Sigma pagination to the last page, returns entries from every page, and leaves nextPageToken null.

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 main purpose and then adds necessary pagination behavior in a second sentence. It is appropriately sized, though the pagination sentence is slightly jargon-heavy with its reference to 'the keys of Sigma's page'.

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?

The tool has an output schema and rich annotations, so the description need not explain return fields or safety profile. It covers the key non-obvious behavior, automatic pagination, and is nearly complete for a simple read-only lookup, with the main gap being explicit usage guidance relative to sibling version-history tools.

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?

There is a single required parameter, report_id, and the schema has 0% description coverage. The description does not explicitly explain the parameter or its format, but the phrase 'of a report' makes the parameter's purpose inferable, which is minimally adequate for a one-parameter tool.

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 and resource: get the version history of a report, including published versions with who and when. The word 'report' distinguishes it from the sibling workbooks_get_workbook_version_history, so an agent can select it without opening the 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?

Usage is implied by the tool name and purpose, but the description does not explicitly say when to use this instead of related tools such as workbooks_get_workbook_version_history or workbooks_restore_workbook_version. There are no when-not conditions or alternative routing cues.

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