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

Annotations already mark this as destructive, non-idempotent and open-world, so the bar is lower; the description still adds concrete behavior: max 10 files at 20 MB each, the return payload (URL and title), and session economics — every started minute costs credits and the session ends 3 minutes after the last call. It omits what an existing file in the field does when overwritten, which is the main remaining question left by destructiveHint=true.

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 dense sentences with no filler; targeting, file formats, limits, return value and session cost each appear once and in a useful order. The cost warning is placed last where an agent will still see it before committing.

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 no output schema, the description still states what comes back (URL and title), and it covers input formats, size/count caps, and the session lifecycle. Nothing an agent needs in order to call this correctly is missing.

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 100%, so baseline is 3, and the description genuinely adds meaning: it spells out both file-source shapes and the capacity limits that the schema only partly conveys via maxItems. The element parameter's meaning is already fully in the schema, so no further gain is possible there.

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?

A specific verb plus resource — puts files into a file field or the file picker an upload button opens — scoped to the current page of the user's Partiful Cloud Browser. The element-number targeting distinguishes it clearly from sibling tools like cotlet_upload_file (upload to Cotlet) and cotlet_browser_click.

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 two entry modes (an existing file field vs. a picker opened by an upload button) and gives the two accepted file sources, which is the key decision an agent faces. It does not explicitly name cotlet_upload_file as the prerequisite step for {"file_id"} or state when not to use this tool, so it stops short of full routing guidance.

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