set_import_artwork

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

Annotations only declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description adds genuinely useful behavior beyond that — server-side decoding, path confinement to host-authorized roots, size/type bounds, and the fact that image bytes never enter the model response. It stops short of explaining conflict behavior on expectedRevision mismatch or whether existing artwork is replaced.

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 tight sentences with the action and its constraints front-loaded, and the unusual streaming/no-bytes-in-response detail called out immediately. Slightly dense phrasing ("host-authorized roots", "bounded") but no filler.

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 five-required-parameter mutation with no output schema and zero schema descriptions, the definition covers the file side well but omits the stateful side: what expectedRevision protects against, what the resulting revision is, and what failure looks like. Adequate to attempt the call, not complete enough to call it confidently under concurrency.

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 carry the parameter burden, yet it only illuminates path (local JPEG/PNG within authorized roots) and role (primary vs. backdrop). jobId, profileId, and especially expectedRevision (whose "initial|<uuid>" pattern is an opaque concurrency token) are given no meaning at all, leaving three of five required parameters undocumented in both schema and description.

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 concrete verb (stream) and resource (a bounded local JPEG/PNG) and states the outcome: attaching it as primary or backdrop artwork for an already-completed upload. That implicitly separates it from upload_media (this attaches art to an existing job rather than creating an upload), but no sibling is named, so differentiation is left to inference.

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?

"For your own completed upload" implies a precondition (a finished upload must already exist) and the role enum implies the choice between primary and backdrop. However, there is no explicit when-to-use vs. when-not, no mention of how this interacts with update_import_metadata or upload_media, and no guidance on calling it repeatedly or after a revision conflict.

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