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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety profile is known; the description usefully adds that the write is confined to a preference and touches no protected tickets. It does not say whether the call replaces the entire existing preference (overwrite semantics), and idempotentHint=false is left unexplained even though re-sending identical values is a natural agent concern.

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?

Two short sentences, with the positive action front-loaded and the scope guard second; nothing is filler. 'Explicit 3D permission' is compressed to the point of being slightly ambiguous, which keeps it from a 5.

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?

An output schema exists, so return values need no explanation, and with only two required parameters the tool is simple. Still, for a non-idempotent mutation the description should state whether the preference is fully replaced and whether allow3d must be consistent with formatOrder, which it does not.

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 carries more burden than baseline, and it does loosely map both parameters ('format order' → formatOrder, '3D permission' → allow3d). It never explains that formatOrder is an ordered priority list (minItems 1, maxItems 7) or how the separate allow3d flag relates to '3d' appearing inside formatOrder, which is the main ambiguity an agent will hit.

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 gives a specific verb (Set) and two concrete resources (default format order, explicit 3D permission), and no sibling tool covers format preferences, so an agent can place it immediately. It stops short of saying what a 'format order' governs (showtime ranking?), leaving the resource slightly under-defined.

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 clause 'Never books or modifies protected tickets' acts as a useful when-not boundary, steering agents away from using it as a booking tool. However, it names no alternative (e.g. request_booking) and gives no precondition such as an existing plan/subscription.

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