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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description is fully consistent with them while adding context they cannot: the two outcome branches (bytes verified -> creative ready; otherwise placeholder discarded), the idempotency contract, the safety guarantee that a verified ready creative is never deleted, and an explicit non-disclosure guarantee for hash, storage key, provider URL, and tenant id.

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?

Three sentences, each load-bearing: purpose first, then the required matching parameters, then the outcome and safety guarantees. No restatement of the title and no filler, despite the density of information conveyed.

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 no output schema, it covers what the call does, what it needs, what results, and what is deliberately not returned. The only true gap is error/permission behavior (e.g. what happens if the idempotency_key or parameters do not match the original request), which the description does not address.

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 carries the burden. It annotates four of five parameters with real semantics (file_hash as SHA-256, a stable idempotency_key, the matching upload_attempt and folder_id) and ties them to the originating request_upload_v2 call. Only connection_context is unexplained, and its pattern makes it self-evidently plumbing.

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+resource+scope: reconcile or discard one exact tenant-owned pending/error upload. It clearly distinguishes itself from creatives_delete and creatives_reconcile by describing the placeholder lifecycle it targets, so an agent can route between siblings without opening schemas.

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?

Gives the triggering situation ('a failed browser upload does not remain as a permanent library placeholder') and the key prerequisite ('pass the same SHA-256 file_hash, stable idempotency_key, upload_attempt, and folder_id used for creatives_request_upload_v2'). It also implicitly rules out the delete tool by stating it never deletes a verified ready creative, though no sibling is named as the alternative for that case.

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