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

Annotations only say readOnly=false / destructive=false; the description adds substantive behavior: the write counts against storage, metadata is capped at 4 KB and is echoed on every read, and the response's versions field surfaces other sizes of the same picture with an instruction to tell the user. That is context an agent cannot get from the structured fields.

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?

Dense but front-loaded: the source constraint leads, then each enum mode, then the response note and the storage cost. Every clause carries information, and the 'tell the user' imperative is unambiguous.

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 six-parameter, no-output-schema mutation tool this covers sources, modes, cross-references (reference_asset_ids), metadata limits, storage cost and the shape of the answer's versions field. Only the unexplained 'name' parameter keeps it from being complete.

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 load, and it does for most parameters: url vs base64 data: URL for 'data', the three 'as' enum modes and their side effects, the 4 KB metadata cap, and project_id's requirement. The 'name' parameter is never mentioned, leaving one of six undocumented in both places.

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?

States a specific verb and resource ('Adds an image') plus the key scope constraint 'no AI' and the closed set of input sources (url or data). That immediately separates it from generate_image, expand_image and upscale_image in the sibling list.

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?

Explains the mutually exclusive source rule ('ONE source: url ... or data ...') and the conditional dependency (as:"timeline" needs project_id), which is real when-to-use guidance. It does not explicitly name the AI siblings as the alternative, so it falls short of a full routing statement.

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