Upload files

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

The destructiveHint annotation is refined meaningfully: the description discloses that replacements are intercepted by a needs_confirmation/confirm_token handshake rather than silently overwriting, and that the resource type is inferred from the extension unless overridden. It stops short of covering directory-upload edge cases, auth requirements, or batch failure semantics.

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, front-loaded with the core action and scope, followed by the two non-obvious rules (type inference, confirmation gate). Every sentence carries distinct information with no restatement of the title or schema.

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?

With annotations and an output schema already present, the description supplies the one behavioural detail an agent could not infer: the confirmation-token workflow. Remaining gaps are minor — the set of 'allowed local directories' is referenced but not characterised, and multi-asset directory upload outcomes are left to the schema.

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 100%, so all eight parameters (including confirm_token, dry_run, overwrite, and the resource_type enum) are already documented in the schema. The description restates the resource_type default behaviour but adds little interpretation beyond what the schema provides, so the baseline of 3 applies.

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 uses a specific verb ('Upload') with a precise resource boundary: a local file or directory inside allowed directories into a Cloudinary folder. It also states the resource-type inference rule, which distinguishes it from siblings like cloudinary_move, cloudinary_download, and cloudinary_delete that operate on already-stored assets.

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?

Clear context for when this tool applies (pushing local content into Cloudinary) and it explains the two-phase confirmation flow that gates destructive replacement. It does not explicitly compare against siblings such as cloudinary_move (server-side reorganisation) or cloudinary_download, so an agent must infer the boundary itself.

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