Set owned publication schedule

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

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description adds substantial behavior beyond that: it warns that the date is in 'WEBSITE wall-clock time' and that 'server timezone and actual delayed publication not verified', it states side effects ('Preserves other editor fields and RPMs'), and it adds safety guidance ('Never retry unknown outcomes'). This is rich, non-redundant behavioral disclosure that complements the annotations without contradiction.

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 compact and front-loaded with the core purpose in the first sentence. Every subsequent sentence adds necessary detail (timezone caveat, non-transition behavior, field preservation, confirmation requirement, retry guidance) without fluff. It is well-structured and earns its length.

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 mutation tool with 4 parameters, an output schema present, and rich annotations, the description covers all critical operational aspects: exact date format and timezone, what it does not do, side-effect scope, user confirmation requirement, and retry policy. Nothing an agent needs to invoke it correctly is missing.

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 must compensate. It explains the semantics of publish_at via the date format and timezone note, and implies is_delayed semantics via 'Set/cancel'. It does not explicitly define app_id and version_id, but those are self-evident from the resource context. The description adds meaningful value for the two key parameters, though it could go further in defining is_delayed's boolean meaning.

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 action ('Set/cancel') on a specific resource ('owned version') and explicitly names the fields affected ('is_delayed and publish_at'). It also clarifies scope by saying 'for an owned version' and negates alternatives ('Does not force a status transition or bypass moderation'). This is a clear, distinct purpose that separates it from broader update tools like update_my_app_version.

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 gives context for when to use this tool: it is for scheduling publication on owned versions and requires 'exact user form confirmation'. It also states what it does NOT do ('Does not force a status transition or bypass moderation'), which implies when not to use it. However, it does not explicitly name alternative sibling tools or state 'use this instead of X', so it lacks the explicit routing seen in top-tier examples.

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