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

Annotations already cover readOnly=false, destructive=false, and openWorld=false; the description adds meaningful context beyond them — cost (free), latency (runs at once), blast radius (writes only the caller's own record), reversibility (undo from this same surface), and the fact that it returns an ordinary result rather than a plan_token. It does not describe limits such as image size/format constraints or rate limits on the upload path.

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 purpose and source options are front-loaded and the sentences are each doing work. The CONFIRMATION block is somewhat redundant, restating "runs immediately" twice and contrasting with plan_token in a way that could be tightened, but it conveys non-obvious policy rather than 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 non-destructive write with annotations, no output schema, and 5 params, the description supplies the return identifier, cost, immediate-execution policy, and both input paths. The notable gaps are the unexplained strength parameter and the semantics of the three kind values, which an agent must guess at call time.

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 carries the load: it explains source_url (public https image) and document_id/upload_token's provenance from the upload flow, and the "either/or" phrasing implies a required-source constraint despite zero required params. However, it never mentions the strength parameter (a 0–1 number) or clarifies the meaning of the kind enum values beyond their bare names, leaving two of five params uninterpreted.

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 opens with a specific verb and resource ("Add a reference image ... to this cabinet's reference library") and scopes it to three kinds (style / composition / product). It also states the concrete return value (reference_id for creative_order.references), which distinguishes it from the upload and creative_* siblings.

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 explicitly routes the caller between two input paths: a public https source_url, or a document_id/upload_token obtained via request_upload_link + get_upload_status. It also states when to run immediately versus when other categories of tools must propose and wait, so the decision to call it is unambiguous.

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