Create Review Bundle

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the permission scopes accepted, the delegation-token authorization semantics, the confirm=true mutation gate, the 25-media cap, and a warning that the action may share access, notify people, or incur provider charges.

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 core purpose and constraints are front-loaded in the first three sentences, ahead of the permission boilerplate. The block is somewhat long, and the permission/delegation paragraph is dense, but each sentence carries distinct operational 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 mutating, open-world tool with no output schema, the description covers the key agent concerns: what it produces (a shareable link), authorization requirements, the confirm gate, and input limits. Return payload details are not provided, but no output schema exists to reference and the essential outcome is described.

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 100%, so the baseline is 3, but the description adds constraints not spelled out in the schema: media_hashed_ids must belong to the account, media can come from any folder, and there is a hard 25-media limit. It does not explain allow_downloads or the payload/payload_file alternatives, which the schema already covers.

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 names a specific verb and resource ('Creates a review bundle from a set of existing media') and states the concrete output ('a single link that can be shared for review'), so the action is unambiguous. It does not explicitly contrast itself with siblings like list_review_bundles or delete_review_bundle, but the write-vs-read distinction is obvious from the verb.

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 clearly states preconditions: media must already belong to the account, can come from any folder, and the bundle is capped at 25 items. It also flags operational prerequisites (a token with the required permission, delegation token support, and confirm=true). It stops short of explicitly naming alternatives for when not to use this tool.

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