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

Annotations already indicate it is not read-only and not destructive, but the description adds key behavioral detail: rotations are added clockwise to the current rotation (cumulative effect) and it returns a new artifact_id. However, it does not clarify whether the artifact is modified in place or a new artifact is created, and the phrase 'new artifact_id' is ambiguous. The description adds value beyond annotations but leaves some behavioral aspects unclear.

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 two sentences, with the core purpose front-loaded. The phrase 'Free.' is an extraneous cost note that does not aid tool invocation, but the overall structure is efficient. No redundant information.

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 tool with two parameters, one being a list of objects, and with no schema descriptions, the description should thoroughly explain the parameter structure. It explains the degrees and the general structure but leaves the 'pages' field ambiguous. It does not mention error handling, empty rotations, or behavior when pages are out of range. Given an output schema exists, return value is covered, but the input semantics are incomplete.

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 coverage is 0%, so the description must explain parameters. It does describe the rotations parameter as a list of {pages, degrees} with degrees limited to 90, 180, or 270, which is helpful. However, it does not specify the format of 'pages' (e.g., individual page numbers, ranges, or arrays) and the schema allows additional properties, so ambiguity remains. artifact_id is self-evident. The description partially compensates for the schema gap but not fully.

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 the action ('Rotate the pages') with a specific resource (pages of artifact_id) and the degree options (90, 180, 270). It distinguishes from siblings like delete_pages, reorder_pages, and extract_pages by naming a distinct operation. The purpose is unambiguous.

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 implies when to use it (when you need to rotate pages) but does not explicitly state alternatives or exclusion criteria. It provides usage details like the rotation list structure, but lacks guidance on when not to use it or how it compares to other page manipulation tools. Usage is implied rather than explicit.

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